Re: Template for GNOME man pages.

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Tue, Oct 29, 2002 at 10:17:44AM -0700 or thereabouts, John Fleck wrote:
> > Well, there is the complication that engineers will be writing the 
> > man pages, > and may well be more familiar with nroff than xml. 
> > Although I see and appreciate the magnificence of consistency, 
> > I'm not really convinced that the converter route is needed. Put 
> > it another way, if we create just nroff final man page 
> > files, and not original xml source, will anyone be put out? 
> 
> I think whatever way is easier for the person maintaining the page would be
> best. We've already got a number of man pages in cvs in regular man page
> format rather than DocBook thanks to Jochen Voss, who shipped them back
> upstream after doing them for Debian.
> 
> I'm curious what sort of content the man pages will have, how they will 
> differ in content from our regular documentation, and what their purpose 
> will be? Is it simply an underlying requirement (I believe this is the 
> situation with Debian) that every executable have a man page?

My impression is that man pages are a reference rather than an
introduction. Simple enough :) If you want a tutorial, use 'info'.
If you want an introduction with screenshots, look for GNOME
(or KDE?) help pages from DocBook. 

Things like [], <> and () can mean different things; the reader
is assumed to understand the difference between arguments, operands,
options, uncle Tom Cobleigh and all; the grammar has to be spot-on
so that you can use as few words as possible without leading to
ambiguity, etc. Basically, they're written for programmers and
sysadmins, plus people willing to pore over them with a glossary
(or chapter one of Jon Lasser's "Think UNIX", which explains man
pages very clearly :)) 

I have heard from more than one source (_not_ including #sun on 
irc.gnome.org, where I asked for details on this very issue
recently!) that Linux man pages are particularly abominable.
We don't routinely include a whole pile of sections that other
commercial UNIX man pages do, for example. 

This is really not meant as a slight on the Debian people. I'm
convinced their "no docs, no ship-ee" policy is a wonderful thing:
and also that half the other distros just take the Debian ones
and repackage them. 

But if you go to the FreeBSD website, they have a fabulous collection
of man pages for UNIXen, which gives you some idea of what can be
included. No Solaris ones there, unless I misunderstand Sun OS 
version naming schemes, but plenty of old SunOS ones. One thing
that is often mentioned as missing in Linux man pages is how
stable the interface is which the app or library is using. 

There are indeed man page templates in Bugzilla. An example is
one from Debian (surprise!) in
http://bugzilla.gnome.org/show_bug.cgi?id=52700

(Note that this bug is yet more proof that if I document something,
it dies: my man page never got in. Boo hoo!)

One thing to think about, Pat -- how to include the metadata that
Scrollkeeper wants in a man page. If we can start the ball rolling
on man pages that have scrollkeeper-style metadata, that would
be brilliant.

Telsa