I wanted to write the user manual for a small personal project that I have been working on in my free time. I wanted the user manual for the project to be available in both HTML as well as PDF and also look good in either case. I considered both GNU Texinfo as well as DocBook for this purpose, but settled for Texinfo simply because it is installed by default on almost all Linux systems and since GCC and many other Free Software projects use it for their documentation. This way, I can easily contribute to the GCC/GCJ documentation without having to learn a new documentation system, should I wake up one morning with the sudden urge to do so.
Texinfo proved very simple to learn and produces fairly good looking HTML and PDF files (although some people prefer texi2html to "makeinfo --html" for HTML output). It can also output DocBook XML files, though I don't know how good the output is since I don't know the DocBook system yet. I am very happy with the tool so far. I haven't learnt a whole lot of Texinfo yet, but since when has that stopped me from making a fool of myself?
There are still some warts that I see with the Texinfo system though:
-
Info is a nice format/tool and I use it a lot under Linux, but you have to go through so many unnecessary hoops in Texinfo to properly support it. Why do you have to explicitly declare nodes and menus? Why can't Texinfo automatically derive these from the chapters and sections in the document in case they haven't been specified explicitly?
-
Creating an index and bibliography is unnecessarily painful. LaTeX has a far better support for these things via auxiliary tools.
-
As with TeX/LaTeX, inserting images is so painful. It could be one of the reasons why so many Free Software manuals do not bother to include figures at all.
-
Texinfo ostensibly focusses on content rather than presentation, but many presentation-related tags and conventions creep in.
-
Support for mathematical symbols is rather weak. Things look good only in the TeX output. The HTML output should be using MathML instead of just showing the text as-is. I don't particularly like MathML since it makes writing even simple things so tedious (TeX is so much better at this), but it's still a standard, as unfortunate as that situation might be.
-
A lot of things work well only for English documents and it does not seem well-suited to writing documents in other languages. As an aside, I personally cringe when I have to write tags spelt assuming American English (as with HTML, Java, etc.) not British English.
These rants aside, I am still sticking with Texinfo for the documentation for my little projects, though for "paper-like" stuff, I'm going to prefer LaTeX.
Miscellaneous
Steve Yegge is now on Blogger for those of you who can't seem to have enough of his rants.
Ranjit Madampath pointed me to a rather hilarious entry on Frameworks in the Joel on Software discussion group.
Planet Scheme used to be available as planet-scheme.yi.org, but it seems to be dead now. I used to like reading the aggregated weblogs of a lot of smart Scheme hackers, the weblog of José Antonio Ortega Ruiz in particular.