Re: Template for GNOME man pages.

On Tue, 29 Oct 2002, Telsa Gwynne wrote:

> 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. 
> 

I think a starting point for them is that all apps that anybody ever will
launch directly and are intended to be shipped by Sun have to have man
pages. 

> 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 :)) 
> 

right, and its pretty useful if you need to figure out how to reliably use 
somthing from a script, including which environment variables you need to
look out for and what files affect the excution/are used.

> 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. 
> 

Something I really like about the BSD man pages is the "first appeared in"
info, and we might want to duplicate it in gnome - so you would know that
while gcnftool-2 was present in gnome 2.0, you would need to have
gnome-2.6 to have a gegltool-2 (just joking).

> 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.

Actually, a potential first questin is if these need to be *roff man pages
or solaris style refentry man pages... 

> 
> Telsa
> 

        Sander

        There are voices in the street,
        And the sound of running feet,
        And they whisper the word --
        Revolution!