Hacker News new | past | comments | ask | show | jobs | submit login

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.




I wrote a 400+ man page in troff!

http://nongnu.org/txr/txr-manpage.pdf

Welcome to the BDSM club.

Big Document in Shitty Markup.

:)


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). Great fun!


How was your experience? What tools did you use, editor? Was it troff, Plan9 roff, neatroff?


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/

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

(Almost the same URL as before, s/pdf/html/).

That post-processing is done by:

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.


mandoc works great for producing HTML and PDF output from man(7) and mdoc(7): 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)


This "mandoc" naming of a project that was previously called "mdocml" is terribly confusing.

"mandoc" is the name of a newer troff/nroff macro package for writing man pages which replaced one called "man". (nroff -man versus nroff -mandoc).

The renamed "mandoc" project provides a processor which understands a "mdoc" language, a set of macros used on BSD Unixes. It's not a full processor for the roff language. The mdoc language has macros that resemble mandoc, like .SH, .TH and others.

In the TXR man-page-like reference manual, I'm using real roff macros (some of which output mandoc macros as their target, in the original sense of mandoc).

I don't think these macros could run in under the mandoc system, where you have to use a canned repertoire of macros.

For instance, I have a macro like this.

   .coNP Functions @, boundp @, fboundp and @ mboundp
This parses its arguments. Any word preceded by @, is typeset in a typewriter font, immediately followed by a comma. A word preceded by @ is typeset typewriter, not followed by a comma. Other material is in the regular font.

Another complicated thing:

   .mets (replace-list < list < item-sequence >> [ from <> [ to ]])
IN this syntax "< word" means typeset word as a meta-identifier. "<< word1 word2" means, typeset word as a meta-identifier, immediately juxtaposed with word2 (no whitespace) which is ordinary. >> word1 word2 reverses the relationship, and <> w1 w2 w3 means w1 and w2 are ordinary , surrounding meta-syntax w2 without space.

When you render this with a man reader, the macro puts out angle-bracket notation, exactly like this:

   (replace-list <list> <item-sequence> [<from> [<to>]])
in the paragraphs which describe this, this notation is consistently used. In HTML and PDF output, these angle-bracket notation is replaced by italics.


Ah, I didn't realize you were making full use of roff. I don't think mandoc (mdocml) supports that; you're correct in saying that it's a canned version of man/mdoc.

It has served me well, though :)


troff! Wow.


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


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.




Join us for AI Startup School this June 16-17 in San Francisco!

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: