Re: man pages and GNOME docs [was Re: gtt suggestions]

[Tom Tromey <tromey creche cygnus com>]

>> Info pages (unfortunately) seem to require constant maintenance and
>> hassle, and the GNU utilities don't automatically add them to the
>> system repository.

Miguel> Recent info distributions include the install-info program
Miguel> that takes care of updating the dir file.

Miguel> Agreed, the dir file is not a particularly good idea.

I don't know that I agree (or disagree either, if that makes sense).
The problem it tries to solve is fundamentally difficult.

FWIW, the GNU info dir stuff was hurt because for many years there was
no install-info program.  If this had been available earlier, maybe
the situation would be better now.  It is improving, though this may
be largely imperceptible.


But the basic problem is figuring out a smart way to construct a
central directory out of things which are maintained and distributed
separately.  This can be done through convention (which is what GNU
does, though that fact is not widely publicized, even among GNU
developers), but it requires a lot of coordination.

Unix man pages completely punt this issue, leaving a flat namespace.
This is fine until you install Tcl and get its "open" man page instead
of the one you really wanted (e.g.).


Another, perhaps more far-fetched, example is that of extracting
documentation from program text.  I think one reason this is not done
more often is that naive attempts at doing this assume that all the
structure should be extracted from the source itself -- whereas to get
readable docs you have to order the extracted pieces according to some
external and predetermined scheme.  (Does this make sense?  I base
this analysis on an earlier project of mine where we did run into
these problems.)


This is a problem we are going to have to address somehow.  There are
plenty of possibilities (e.g., use a directory tree instead of a dir
file, and have the reader construct the TOC on the fly).

Tom