Why I prefer Texinfo+Info
=> GNU 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
=> 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
  @var{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.
* Ability to automatically generate indices.
* 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 | Indices | Simple
troff    | no   | no         | yes  | no       | ?    | yes  | no    | no      | no   | eqn  | ?       | no
mdoc     | ~    | no         | no   | no       | no   | yes  | no    | yes     | no   | no   | no      | yes
MD/CM    | yes  | yes        | no   | no       | no   | yes  | no    | ?       | no   | no   | no      | ~
POD      | yes  | yes        | no   | no       | no   | yes  | no    | yes     | yes  | no   | no      | yes
reST     | yes  | yes        | no   | no       | no   | no   | yes   | ~       | ~    | yes  | no      | no
AsciiDoc | yes  | yes        | no   | no       | no   | no   | yes   | ~?      | no   | yes  | yes     | no
LaTeX    | ~    | yes        | yes  | yes      | yes  | yes  | no    | no      | no   | yes  | yes     | no
HTML     | yes  | no         | yes  | yes      | no   | ~    | yes   | no      | no   | ~    | no      | no
DocBook  | yes  | no         | yes  | yes      | ~    | ~    | yes   | yes     | no   | ~    | yes     | no
Texinfo  | yes  | 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      | yes   | yes       | no
HTML | yes      | yes   | no        | no
Info | yes      | yes   | yes       | yes