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

[Mark Galassi <rosalia cygnus com>]

    csmall> May I suggest we go the same way as GNU.  They have man
    csmall> pages for all their programs but they are usually quite

That's quite incorrect.  Some GNU programs have man pages by chance,
and the GNU coding standards discourage spending time on maintaining
them: take a look at the documentation part of the GNU coding
standards -- it's quite explicit.  And in practice most GNU programs
don't have man pages, especially the recent ones.  Do you find man
pages for automake or gettext?

But we can probably do better than the GNU standards recommend:
DocBook allows man page information to be embedded in your DocBook
document (via the <refentry> tag), and we should use that mechanism.
You can then process the DocBook file and get a man page source as
output!

I have not yet explored <refentry> in my DocBook tutorial
(http://nis-www.lanl.gov/~rosalia/mydocs/), but I will eventually add
something about it, and in that I will recommend how Cygnus and GNOME
docs can produce man pages without maintaining a separate man page
document.