---

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.

• Easy convenient to use language I can typeset directly without any frustration. XML-based ones are definitely a no winner here. LaTeX needs some time to learn, but it is pretty easy to read and work with soon. But all of that is highly subjective of course! Moreover I really hate how links are made in MD/CM!
• Rich formatting features. For example I want to create a bold emphasized URL link – that is impossible in reST. Or link inside preformatted block. Do I need it? Well, actually very often! Too often even I can expect from myself. POD, Markdown are too simple. reST, Asciidoc are much richer, but I always find something not enough to express myself. Tables support are also necessary there.
• Insensitive to indentations and excess spaces. Indentations seems very human friendly and easy to use, but in practice you are very limited in abilities to express yourself. Also it complicates source autogeneration as a rule.
• Ability to use substitution variables. For example I want to set VERSION variable and use a reference to it.
• Ability to use it in docstrings. I doubt anybody tried to use XML/SGML in them. Space sensitive formats are no way there. I mean general ability just to cut some lines from the source code (bordered my some marks) and insert to the documentation source.
• Ability to generate bunch of HTMLs linked together. That can be used for static sites generation. It has to support internal links (references).
• Ability to generate DocBook could be useful and nice. Because it could be converted to formats like Open Document, that could be converted to Office Open XML.
• Ability to generate Info. Talk about that format later.
• Ability to include TeX math. Just nice to know that is there.
• It is not a requirement, but software simplicity is also important. Unfortunately Texinfo is relatively complicated, comparing to trivial POD and rather simple mdoc.

Name	Easy	Convenient	Rich	Noindent	Vars	Docs	HTMLs	DocBook	Info	Math	Simple
troff	no	no	yes	no	?	yes	no	no	no	eqn	no
mdoc	~	no	no	no	no	yes	no	yes	no	no	yes
MD/CM	yes	yes	no	no	no	yes	no	?	no	no	yes
POD	yes	yes	no	no	no	yes	no	yes	yes	no	yes
reST	yes	yes	no	no	no	no	yes	~	~	yes	no
AsciiDoc	yes	yes	no	no	no	no	yes	~?	no	yes	no
LaTeX	~	yes	yes	yes	yes	yes	no	no	no	yes	no
HTML	yes	no	yes	yes	no	~	yes	no	no	~	no
DocBook	yes	no	yes	yes	~	~	yes	yes	no	~	no
Texinfo	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	no

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

Name	Terminal	Links	Plaintext	Index
PDF	no	no	no	no
man	yes	no	no	no
POD	yes	no	yes	no
HTML	yes	yes	no	no
Info	yes	yes	yes	yes

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