4 ms·

After having written a fairly popular 400+ page book, and dozens of documentation sets in Markdown (and having worked on a few in other languages), I have to sa

After having written a fairly popular 400+ page book, and dozens of documentation sets in Markdown (and having worked on a few in other languages), I have to say—Markdown is _good enough_. The other syntaxes mentioned will not be mainstream enough to gain critical mass for some time, if at all. Markdown, for many projects, is literally plain text with some added frills for headings, lists, and code blocks. Yes, adding a code snippet inside a table cell inside a list can be a pain-inducing experience (especially until CommonMark settles things down a bit)... but that's about .05% of anything I've ever written, and for those particular instances, I fall back to HTML, which is completely compliant and much less ambiguous. For myself, and for most of the projects I've worked with and maintained, you need documentation to be dead simple in syntax, and requiring a syntax with even less adoption than Markdown is an easy way to cause users who would've otherwise contributed doc fixes and updates behind.

kazinator 11y ago
I wrote a 400+ man page in troff! http://nongnu.org/txr/txr-manpage.pdf http://nongnu.org/txr/txr-manpage.pdf Welcome to the BDSM club. Big Document in Shitty Markup. :)
- dguaraglia 11y ago
  troff! Wow.
  - kazinator 11y ago
    I've never been a "troff" person. Starting around 1990, I was into TeX and LaTeX, and stayed away from troff; my only interaction with it was man pages (mostly as a consumer). This big document is my troff "Magnum Opus". Basically it started as the need to have a man page for a utility/language on Unix-like systems. I don't want to maintain a man page and a whole other reference manual, so I let it grow. And as I let it grow, I wanted to do "reference-manual-like" things in it, like auto-numbered subsections and whatnot, plus halfway usable HTML. (I don't know of any other man page which numbers its sections on the fly like this. Or is even this large, for that matter.)
- jhoechtl 11y ago
  How was your experience? What tools did you use, editor? Was it troff, Plan9 roff, neatroff?
  - kazinator 11y ago
    I use GNU troff (Groff) for maintaining this. And by the way, this is actually installed as a man page on target systems. Most of my struggles were in the area of halfway decent HTML conversion. To that end, I started with a very hacky C program calld man2html, which actually contains a mini-troff implementation, and improved it quite a bit. I cloned that program here: http://www.kylheku.com/cgit/man/log/ http://www.kylheku.com/cgit/man/log/ This had numerous issues, among the main ones being not handling loops and conditionals and so on for complex macros. I still do quite a bit of post-processing on the output of this program, still, to do things like re-arrange its order, add internal hyper-links, and create a Java-scripted table of contents: http://www.nongnu.org/txr/txr-manpage.html http://www.nongnu.org/txr/txr-manpage.html (Almost the same URL as before, s/pdf/html/). That post-processing is done by: http://www.kylheku.com/cgit/txr/tree/genman.txr http://www.kylheku.com/cgit/txr/tree/genman.txr I don't like the approaches you have to take in troff for defining multiple ways of doing the same thing, based on whether it is juxtaposed to something else or followed by whitespace. This is fundamentally broken. For instance if you want foobar such that foo is italic, but bar is regular, you have to use .IR foo bar, rather than the .I macro. I'm sorry, but a markup language should have the scoping/delimiting wherewithal not to have to do stupid things like this. I have a more or less fixed (non-growing) set of such redundant macros in the document and so it doesn't bother me that much any more.
    - groovy2shoes 11y ago
      mandoc works great for producing HTML and PDF output from man(7) and mdoc(7): http://mdocml.bsd.lv/ http://mdocml.bsd.lv/ > I'm sorry, but a markup language should have the scoping/delimiting wherewithal not to have to do stupid things like this. (btw, mdoc has this and is widely supported, having been around for about 2 decades... having discovered it, I'll never write a manpage in man again)
- nils-m-holm 11y ago
  Troff is not that bad, really! I started typesetting my books in Troff (even with my own macro package), then tried TeX and Lout, and I think I'll actually return to Troff, if I should decide to write another book. Simplicity is good! Oh, and I have used homebrew markdown preprocessors to write books (e.g. http://t3x.org/s9fes/edoc.html http://t3x.org/s9fes/edoc.html). Great fun!
galonk 11y ago
With all due respect, a book is nothing like technical documentation. The biggest issue with documentation is that it needs a lot of structure. To do interesting things you need to be able to mark certain passages of text as special (e.g. this term is in the glossary; this block is a method signature), and you need hierarchical structure (e.g. you can't just have bullets points that appear more or less indented, you need some bullet points to be children of other bullet points). That's what Markdown is terrible at.

kazinator 11y ago

I wrote a 400+ man page in troff! http://nongnu.org/txr/txr-manpage.pdf http://nongnu.org/txr/txr-manpage.pdf Welcome to the BDSM club. Big Document in Shitty Markup. :)

dguaraglia 11y ago
troff! Wow.
- kazinator 11y ago
  I've never been a "troff" person. Starting around 1990, I was into TeX and LaTeX, and stayed away from troff; my only interaction with it was man pages (mostly as a consumer). This big document is my troff "Magnum Opus". Basically it started as the need to have a man page for a utility/language on Unix-like systems. I don't want to maintain a man page and a whole other reference manual, so I let it grow. And as I let it grow, I wanted to do "reference-manual-like" things in it, like auto-numbered subsections and whatnot, plus halfway usable HTML. (I don't know of any other man page which numbers its sections on the fly like this. Or is even this large, for that matter.)
jhoechtl 11y ago
How was your experience? What tools did you use, editor? Was it troff, Plan9 roff, neatroff?
- kazinator 11y ago
  I use GNU troff (Groff) for maintaining this. And by the way, this is actually installed as a man page on target systems. Most of my struggles were in the area of halfway decent HTML conversion. To that end, I started with a very hacky C program calld man2html, which actually contains a mini-troff implementation, and improved it quite a bit. I cloned that program here: http://www.kylheku.com/cgit/man/log/ http://www.kylheku.com/cgit/man/log/ This had numerous issues, among the main ones being not handling loops and conditionals and so on for complex macros. I still do quite a bit of post-processing on the output of this program, still, to do things like re-arrange its order, add internal hyper-links, and create a Java-scripted table of contents: http://www.nongnu.org/txr/txr-manpage.html http://www.nongnu.org/txr/txr-manpage.html (Almost the same URL as before, s/pdf/html/). That post-processing is done by: http://www.kylheku.com/cgit/txr/tree/genman.txr http://www.kylheku.com/cgit/txr/tree/genman.txr I don't like the approaches you have to take in troff for defining multiple ways of doing the same thing, based on whether it is juxtaposed to something else or followed by whitespace. This is fundamentally broken. For instance if you want foobar such that foo is italic, but bar is regular, you have to use .IR foo bar, rather than the .I macro. I'm sorry, but a markup language should have the scoping/delimiting wherewithal not to have to do stupid things like this. I have a more or less fixed (non-growing) set of such redundant macros in the document and so it doesn't bother me that much any more.
  - groovy2shoes 11y ago
    mandoc works great for producing HTML and PDF output from man(7) and mdoc(7): http://mdocml.bsd.lv/ http://mdocml.bsd.lv/ > I'm sorry, but a markup language should have the scoping/delimiting wherewithal not to have to do stupid things like this. (btw, mdoc has this and is widely supported, having been around for about 2 decades... having discovered it, I'll never write a manpage in man again)
nils-m-holm 11y ago
Troff is not that bad, really! I started typesetting my books in Troff (even with my own macro package), then tried TeX and Lout, and I think I'll actually return to Troff, if I should decide to write another book. Simplicity is good! Oh, and I have used homebrew markdown preprocessors to write books (e.g. http://t3x.org/s9fes/edoc.html http://t3x.org/s9fes/edoc.html). Great fun!

galonk 11y ago

With all due respect, a book is nothing like technical documentation. The biggest issue with documentation is that it needs a lot of structure. To do interesting things you need to be able to mark certain passages of text as special (e.g. this term is in the glossary; this block is a method signature), and you need hierarchical structure (e.g. you can't just have bullets points that appear more or less indented, you need some bullet points to be children of other bullet points). That's what Markdown is terrible at.