7 ms·

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

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.

tangue 9y ago
Did you try org files ? Even if you're not into Emacs it might worth the try reading your needs
- gyrgtyn 9y ago
  Pollen seems really cool.
- JoshMnem 9y ago
  Org mode format is great. Pandoc works with all of those formats, including org mode. http://pandoc.org/ http://pandoc.org/
dom0 9y ago
restructuredtext?
- marcosdumay 9y ago
  I'm going to second that. RestructuredText is very powerful, and has an official specification. Basically what Markdown is missing. Yet, it is plain text and easy to parse.
  - ferdterguson 9y ago
    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.
    - dom0 9y ago
      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.
coldtea 9y ago
>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.
- gkya 9y ago
  How is it harder to parse than a PDF or a docx?
  - coldtea 9y ago
    I mean compared to structured file formats like JSON, YAML, TOML, XML and whatever (including binary such). Obviously it's not harder to parse than a PDF.
    - overdunk 9y ago
      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.
      - coldtea 9y ago
        >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.
k__ 9y ago
AsciiDoc seems the way to go then. It's like DocBook with Markdown like syntax
- type0 9y ago
  Btw, AsciiDoc could be used with gitbook-cli. It's not Sphinx but still powerful enough for all kinds of documentation.
jdcarter 9y ago
I've found that Pandoc [1] is a wonderful converter if you want to write in a future-proof format (like markdown) but also generate nice PDFs. [1]: http://pandoc.org/ http://pandoc.org/
a3n 9y ago
> 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?), ...
JohnHammersley 9y ago
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. [1] https://www.overleaf.com https://www.overleaf.com [2] https://www.overleaf.com/blog/81 https://www.overleaf.com/blog/81 [3] https://www.overleaf.com/blog/501 https://www.overleaf.com/blog/501
- hobs 9y ago
  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.
  - JohnHammersley 9y ago
    Thanks for the feedback - great to hear you've been finding it useful and yes, improving the file tree is definitely on our list. Good luck with your future projects!
- karthikb 9y ago
  Overleaf was invaluable while I wrote my thesis. Thank you!
  - JohnHammersley 9y ago
    Congratulations on your thesis -- it's a lot of work, and I'm glad Overleaf helped :)
foobarian 9y ago
I've been writing daily notes in the same text file since 1996. Fascinating to look back through old entries. Format is dirt simple: date alone on a line is the only special element. The main thing I really miss is the ability to scribble drawings inline.
Razengan 9y ago
Plaintext / basic Markdown with an "organizer" like Ulysses [0] or Quiver [1] can serve just about all needs. [0] https://www.ulyssesapp.com https://www.ulyssesapp.com [1] http://happenapps.com/#quiver http://happenapps.com/#quiver
- NoahTheDuke 9y ago
  No Windows or Linux? Okay.
  - Razengan 9y ago
    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..
noir_lord 9y ago
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.
sdenton4 9y ago
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...
- sdenton4 9y ago
  (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!)
thearn4 9y ago
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.
dheera 9y ago
obligatory xkcd: https://xkcd.com/927/ https://xkcd.com/927/
edoceo 9y ago
Asciidoc
- rubidium 9y ago
  what, recommending just one more format to learn? I don't think that's what the parent post is looking for : )
  - type0 9y ago
    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.
    - edoceo 9y ago
      I couldn't have said it better.
rubidium 9y ago
That's.... pretty much my exact experience (oh, I get to add multiple years of latex use). Html or plaintext is all I trust now. A nice editor on top of it and I'm good. If you have to do larger document writing, I recommend Madcap Flare.
- deleted 9y ago
  [deleted]

tangue 9y ago

Did you try org files ? Even if you're not into Emacs it might worth the try reading your needs

gyrgtyn 9y ago
Pollen seems really cool.
JoshMnem 9y ago
Org mode format is great. Pandoc works with all of those formats, including org mode. http://pandoc.org/ http://pandoc.org/

dom0 9y ago

restructuredtext?

marcosdumay 9y ago
I'm going to second that. RestructuredText is very powerful, and has an official specification. Basically what Markdown is missing. Yet, it is plain text and easy to parse.
- ferdterguson 9y ago
  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.
  - dom0 9y ago
    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.

coldtea 9y ago

>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.

gkya 9y ago
How is it harder to parse than a PDF or a docx?
- coldtea 9y ago
  I mean compared to structured file formats like JSON, YAML, TOML, XML and whatever (including binary such). Obviously it's not harder to parse than a PDF.
  - overdunk 9y ago
    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.
    - coldtea 9y ago
      >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.

k__ 9y ago

AsciiDoc seems the way to go then. It's like DocBook with Markdown like syntax

type0 9y ago
Btw, AsciiDoc could be used with gitbook-cli. It's not Sphinx but still powerful enough for all kinds of documentation.

jdcarter 9y ago

I've found that Pandoc [1] is a wonderful converter if you want to write in a future-proof format (like markdown) but also generate nice PDFs. [1]: http://pandoc.org/ http://pandoc.org/

a3n 9y ago

> 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?), ...

JohnHammersley 9y ago

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. [1] https://www.overleaf.com https://www.overleaf.com [2] https://www.overleaf.com/blog/81 https://www.overleaf.com/blog/81 [3] https://www.overleaf.com/blog/501 https://www.overleaf.com/blog/501

hobs 9y ago
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.
- JohnHammersley 9y ago
  Thanks for the feedback - great to hear you've been finding it useful and yes, improving the file tree is definitely on our list. Good luck with your future projects!
karthikb 9y ago
Overleaf was invaluable while I wrote my thesis. Thank you!
- JohnHammersley 9y ago
  Congratulations on your thesis -- it's a lot of work, and I'm glad Overleaf helped :)

foobarian 9y ago

I've been writing daily notes in the same text file since 1996. Fascinating to look back through old entries. Format is dirt simple: date alone on a line is the only special element. The main thing I really miss is the ability to scribble drawings inline.

Razengan 9y ago

Plaintext / basic Markdown with an "organizer" like Ulysses [0] or Quiver [1] can serve just about all needs. [0] https://www.ulyssesapp.com https://www.ulyssesapp.com [1] http://happenapps.com/#quiver http://happenapps.com/#quiver

NoahTheDuke 9y ago
No Windows or Linux? Okay.
- Razengan 9y ago
  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..

noir_lord 9y ago

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.

sdenton4 9y ago

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...

sdenton4 9y ago
(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!)

thearn4 9y ago

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.

dheera 9y ago

obligatory xkcd: https://xkcd.com/927/ https://xkcd.com/927/

edoceo 9y ago

Asciidoc

rubidium 9y ago
what, recommending just one more format to learn? I don't think that's what the parent post is looking for : )
- type0 9y ago
  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.
  - edoceo 9y ago
    I couldn't have said it better.

rubidium 9y ago

That's.... pretty much my exact experience (oh, I get to add multiple years of latex use). Html or plaintext is all I trust now. A nice editor on top of it and I'm good. If you have to do larger document writing, I recommend Madcap Flare.

deleted 9y ago
[deleted]