Plaintext certainly seems more attractive the more docs I write. Over the years, with both work and personal projects, I've used every format from:
- Notepad
- Microsoft Word
- PDF
- Twiki
- Various proprietary WSYWIG that compiles to HTML
- JIRA
- Raw HTML
- Markdown (several flavors)
With nearly every kind of migration, there are numerous pain points. The "raw" formats are a nightmare to edit and update, and the compiled ones require several hours of changing syntax, image locations, etc.
I've been getting so tired of having to re-do stuff on different platforms that more of my docs are starting as Plaintext and then written in pseudocode markup for areas that I know will change on every platform (e.g. generating a table of contents, image tags, etc).
Having just coded an entire website from scratch that was basically just documentation, Markdown comes remarkably close to doing what I want, except when the common format fails to meet my needs, which forces me to then have to switch to a specific flavor of Markdown in order to get something as basic as tables.
The docs of mine that seem most resilient to platform shifts (other than plaintext) are the ones that are written in or compiled to longstanding formats like LaTeX or HTML.
So perhaps my takeaway is, write in something readable that compiles to something widely available. That will provide the least headache.
If you're interested in adding LaTeX to that list, you might like to try Overleaf [1] -- it's an online collaborative LaTeX editor we built to try to lower the learning curve (I'm one of the founders).
It includes a rich text mode for easier collaboration with non-LaTeX users [2], and you can also write in Markdown if you like :) [3].
Feedback always appreciated if you do give it a try, thanks.
Thank you so much for Overleaf, as a new user, its great!
I really like how easy it is to experiment with the LaTeX formatting (something I wasnt super familiar with) and immediately see the output.
I had someone send me their resume template on overleaf and it was super easy to get a similar product with my personal touch.
The only feedback I would have is it was a little awkward to do folders within folders (this was a few months ago) and I had to ken the "hey put a path separator in the name" before I got it.
I just use markdown for what it's good at and 'drop' to HTML for the stuff I can't do in 'plain' markdown.
Python has a lovely library for it and combined with jinja you can get a hell of a long way in a couple of hundred lines of python as a static site generator.
> Having just coded an entire website from scratch that was basically just documentation, Markdown comes remarkably close to doing what I want, except when the common format fails to meet my needs, which forces me to then have to switch to a specific flavor of Markdown in order to get something as basic as tables.
I just did essentially the same, in reStructuredText.
The battle is so lost that I don't even bother fighting it, but there are many nice things about reST: you have to explicitly escape html to get it passed through as html (feature/bug), tables are easy, especially the list tables, I'm used to it (feature? bug?), ...
hmm..... having seen a bunch of demos of almost-compiling LaTeX produced by neural networks, I wonder if there's a good space for building seq2seq document format converters...
(also makes me wonder what style transfer from latex to markdown would look like; automatically convert your years-in-the-making research project into a snarky blog post!)
Ulysses (and probably Quiver too) can just give you a "pretty view" of your existing folder structure, and since it's all plaintext/MD you can work with your data on Windows/Linux just fine, and there's nothing keeping someone from makes similar apps on the other OSes.
I used to use OneNote for everything, until I moved to Macs... Not only there was no Mac version at first, OneNote STILL doesn't let you import old local notebooks into the Mac version.
With Ulysses/Quiver at least I know that what I write on the Mac will still be readable on Windows/Linux..
>With nearly every kind of migration, there are numerous pain points. The "raw" formats are a nightmare to edit and update, and the compiled ones require several hours of changing syntax, image locations, etc.
And plain text is itself a nightmare to parse and do anything beyond reading it as a block.
I'd argue that it's hard to parse because it's so open-ended. E.g. Markdown is only one example of how to structure textual data in plain-text with additional "syntax".
Imagine it wasn't decided on Markdown. E.g.: I don't use markdown when making plain-text notes. I make it all hierarchical and indent using "- ". I.e. headings are top-level, sub-headings are indented by one, and so on. Eventually, you realize that all things can be represented as just lists of nested lists. No need for some arbitrary "heading" type, just nest it all based on the concept.
Uh, "plain text" is not a pair of words that I would use to describe "structured data" at all. I don't even know what someone would intend to mean in such a situation.
If someone told me they needed me to parse a "plain text" file, to me it sounds like they'd want me to provide some statistics on an unstructured text blob.
Free form text does have properties, such as byte length, character count, word count, line count, sentence count, paragraph count, and so on. Most of which is simply variations on whitespace delimiters.
But an individual plain text file... all on its own? Could be a shell script? Could be a newspaper clipping? Could be a dictionary file? Could be an array of XYZ vertices, edges and faces? Could be all of the above, and an email signature at the end?
Someone tells me: "here have this plain text object," and I presume it is a monolithic blob of ASCII, if I'm lucky, and maybe it's War and Peace or Moby Dick expressed in emoji if I'm not.
>Uh, "plain text" is not a pair of words that I would use to describe "structured data" at all. I don't even know what someone would intend to mean in such a situation.
Well, most would agree markdown is a plain text format for example, but it's not totally unstructured.
Still it's a bitch to parse compared to something like JSON.
I'm building course notes right now for a college class using markdown & MathML/LaTeX, that i'll be hosting on Github pages for the students to browse. It's by far the best balance that I've come across yet.
Asciidoc/Asciidoctor is non-ambiguous (unlike Markdown), works with different workflows and unlike org mode you can use different editors, easy to learn (unlike LaTeX). ReStructured text is the second closest but there you have to have Python in order for it to be useful, so Asciidoc is the only one plausible universal text markup as I see it.
I like reStructuredText, but the format is grating compared to markdown. The two things I do the most are sectioning and links. Inline links are ok in rst, but I prefer markdown. Sectioning though is awful. I hate having to hold the damn == or -- or ~~ down and getting the length right. It's easier to parse when you read the plaintext, but makes me loath writing it. Most the time I deal with md or rst, they end up formatted anyway, which is the point IMO.
Personally I don't think sectioning is that bad, a little annoying when working with other people that don't do it, though...
foo
======================
... the easy and built-in extensibility is a huge plus though, as is Sphinx and the pretty good output writers for many formats. Sphinx btw. works with Markdown, too.
Quite possibly my biggest annoyance with rST/Sphinx is the hanging toctree issue, and poor support for multi-format images/figures.
The 100 % offline search in Sphinx is somewhat of a mixed bag and doesn't always give good results, though it's fine for reference works.
- Notepad
- Microsoft Word
- PDF
- Twiki
- Various proprietary WSYWIG that compiles to HTML
- JIRA
- Raw HTML
- Markdown (several flavors)
With nearly every kind of migration, there are numerous pain points. The "raw" formats are a nightmare to edit and update, and the compiled ones require several hours of changing syntax, image locations, etc.
I've been getting so tired of having to re-do stuff on different platforms that more of my docs are starting as Plaintext and then written in pseudocode markup for areas that I know will change on every platform (e.g. generating a table of contents, image tags, etc).
Having just coded an entire website from scratch that was basically just documentation, Markdown comes remarkably close to doing what I want, except when the common format fails to meet my needs, which forces me to then have to switch to a specific flavor of Markdown in order to get something as basic as tables.
The docs of mine that seem most resilient to platform shifts (other than plaintext) are the ones that are written in or compiled to longstanding formats like LaTeX or HTML.
So perhaps my takeaway is, write in something readable that compiles to something widely available. That will provide the least headache.