1. I was doing some updates to the Ion home page recently, and needed to make a few screenshots and thumbnails for these. ImageMagick is of course the standard tool for this kind of tasks. It having been a while since I last did any image resizing, obviously I couldn't remember the exact options and parameters to pass to it to do this (and to make it compress PNG better, at which it sucks by default). Since the output of the --help command-line option is quite terse, as it should be, I opened the *nix manual page of the convert command, ImageMagick having had very fine ‘man’ pages.

Now, what did I get? A dummy man page, the immediate reaction to it of course being: “Oh no! Yet another program has fallen to the GNU disease and switched to the piece-of-shit info system?” No. The dummy page had a note instructing to open HTML documentation in /usr/share/doc/. Well, at least the worst Web browser does not suck as much as every single info browser. Maybe there still was some hope of actually finding the information I was looking for, although man pages are so much more convenient.

Well, while info documents also suck, being divided into a zillion tiny nodes from which it is impossible to find anything, especially with the totally worthless browsers, most of the Web sucks even more, and the ImageMagick documentation, while not at the very bottom of the big shitpile, would be eligible for the “most unimaginative abuse of HTML” award of the Web Anti-Usability Engineers' Guild. (This guild is estimated to have a membership rate of about 99% among professional Web Designers.) The big problem: layout with mega-wide HTML tables, containing mega-wide text overflowing the browser window, necessitating constantly adjusting the position of the page to be able to read anything. Tables are for tabular information, not layout! CSS is for layout! Conclusion: ImageMagick sucks, not as much for not having man pages, as for having had them. Thank you very much for making yet another program unusable for me.

2. Admittedly, the *nix man page system, and troff in particular has its limitations, and is not one of the nicest formats to write documentation in, although HTML/XML formats are even less convenient to write in.

An important limitation of the man system is, of course, that it is not so easy for Web Designers to enforce crappy layouts down the user's throat, unlike with amateurish HTML that does not properly use CSS on correctly used semantic tags (which passes for professional in the world of Web Design). Now, a semantic subset of HTML also “safe” for Email, Usenet and RSS feeds, and CSS, could be quite good a choice for electronic dissemination for certain forms of documentation, such as tutorials and other “textbook” material that is often infact preferrable in dead-tree or otherwise portable format. (HTML is quite bad as a source language, though; it is more of a target presentation language.)

Reference documentation – command line parameters, library API reference, and so on – should, however, be accessible through a standard documentation system in a rather standard format, instead of having to look up the information in documents of varying formats at varying locations. On *nix this is the man system. It is easy to find what you're looking for in man pages, because the information you're looking for is usually directly contained on the page you found by running the man command, and the documents have a rather standard and accessible format and layout.

Now, I only said that the man system is the standard, not that it will always be. There is, infact, an attempt to replace it – the GNU info system. It is, unfortunately, crap. As I have already elaborated, all the info browsers suck (pinfo the least), and most of the documents are split out in a cumbersome manner, into a zillion hierarchical levels of small nodes, from which it is impossible to find anything. (Most small documents should be just one page, and even in the biggest documents equivalent to brick-sized books, nothing should be more than two page levels from the “top”.) The pages are also laid out and formatted in a very ugly and unreadable manner (indented paragraphs, for example, seem to diminish legibility on monospaced media), and most info document authors seem to be writing (crappy) textbooks instead of reference documents.

Indeed, the info system is quite unpopular outside GNU projects, and seems to be doomed to fail. I think one essential feature of a good replacement reference documentation system is, that the documentation can be converted into man page(s) (or into the “cat” display format) almost indistinguishable from the prevalent ones, while the new format catches on. Possibly these documents could be HTML, or even TeXinfo, however written and rendered in a more accessible manner.

However, a more serious limitation of the man system is, that it's not designed in such a manner that an arbitrary tool, such as the shell (for completion) or an IDE (Integrated Development Environment, although in case of the present examples, Inexplicably Demented Editor would be more appropriate) could easily extract useful information from the documentation. Thus, I think the direction to take, if one wishes to replace the man system, is a semantic format or formats that can say to any querying program that “these are the command command line parameter that this program accepts”, “this function has such and such parameters”, “this class contains such and such functions”, and so on. Along with some supplementary material, snippets of documentation for such entities can then automatically be rendered by the documentation system into aggregate or individual pages of a rather standard format of the user's choosing. This format or formats would not be for general-purpose documentation (although the actual descriptions could use a subset of one, possibly with similar syntax), but be very specifically tuned to describing the command line parameters of programs, and so on. Of course, with the information being in a format that both humans and programs alike can easily understand, it can easily be included in other works in arbitrary formats. Writing reference documents in a standard format does not have to duplicate work.

There are likely to exist some XML DTDs used by some projects for something like this, but the XML/SGML syntax is too verbose for human consumption, and to actually personally use and encourage to use, I'd want a lighter syntax, preferring something TeX-like as lined out in my essay “TeXnical documents and markup languages”. Obviously there has to be a terminal mode browser for the documentation.

Of course, the man page system has other limitations as well, in its linking and grouping capabilities. Everything lives in a single mess, and different program's and libraries' stuff isn't kept separate. A package can easily clutter the namespace unless care is taken.

3. There's a bit of redundant work in the output of the --help option of programs. This output should tersely, with lesser words than the full manual, document at least the most commonly used options. In principle the information could be obtained from the reference document database as a particular field in the documentation of each option, but this could also make a simple thing a bit too complex. There's, however, one rather trivial aspect of integration in relation to more advanced terminal emulators: the output of the help option should link to a fuller explanation of the parameter.