Next: , Previous: , Up: Articles  


Why I prefer Texinfo+Info

I had many years experience with various (mainly software) documentation formats, including Plain Old Documentation (POD), reStructured Text (reST) + Sphinx, DocBook, AsciiDoc, Vimwiki, LaTeX, mdoc, troff and of course HTML. But only GNU Texinfo and its corresponding Info format is my choice for documentation and static websites generation. Previously I used reST everywhere, but since then I know many of its disadvantages and limitations (like available, but rather bad export to Texinfo/Info and TeX).

Remark about Markdown format (MD): there is no such format, stop suggesting it! There are only many vaguely incompatible dialects and implementations. You can always be sure that your .md won’t work with another implementation. Only very tiny subset of features are guaranteed to work reliably. I heard about CommonMark (CM), but do not see its widespread usage at all.

I will overview the source format (that is intended to by writeable) and target format (readable one). There will be neither Vimwiki nor Org-mode, because they are editor-locked, however both of them could be perfect candidates in most cases too.

What do I want from source format? Easiness, convenience, rich features, machine friendliness and HTML output at least.

NameEasyConvenientRichNoindentVarsDocsHTMLsDocBookInfoMathSimple
troffnonoyesno?yesnononoeqnno
mdoc~nonononoyesnoyesnonoyes
MD/CMyesyesnononoyesno?nonoyes
PODyesyesnononoyesnoyesyesnoyes
reSTyesyesnonononoyes~~yesno
AsciiDocyesyesnonononoyes~?noyesno
LaTeX~yesyesyesyesyesnononoyesno
HTMLyesnoyesyesno~yesnono~no
DocBookyesnoyesyes~~yesyesno~no
Texinfoyesyesyesyesyesyesyesyesyesyesno

What do I expect from target format? Ability to read it in terminal (PDF looses). Internal links (man and POD loose). man and HTML are viewable only with specialized software. Built-in indexing/searching ability exists only in GNU Info (however you can use external software like recoll).

NameTerminalLinksPlaintextIndex
PDFnononono
manyesnonono
PODyesnoyesno
HTMLyesyesnono
Infoyesyesyesyes

Next: Why I won’t use Let’s Encrypt, Previous: Сравнение JPEG XL, Up: Articles