Re: gnotravex man page

[Jan Schaumann <jschauma netmeister org>]

Telsa Gwynne <hobbit aloss ukuu org uk> wrote:
> [For docs-list specific stuff, people might want to trim the  Cc:
> line]
> 
> On Sat, Aug 25, 2001 at 01:57:46PM -0400 or thereabouts, Jan Schaumann wrote:
> > I maintain a project called "The Missing Man Pages Project", and
> > somebody reported that your software package "gnotravex" is lacking a
> > man-page.  You can find it attached; feel free to change and
> > redistribute the pages to your liking.
> 
> Thanks very much. GNOME tends to write its documentation in DocBook,
> which can be converted into a variety of formats: text, PDF, PS, 
> HTML... and allegedly man pages, although I have never managed this.

As it so happens, I also just started a project to deal with exactly
this problem:  http://mama.sourceforge.net

In fact, I wrote all the man-pages as DocBook RefEntry's and used the
newly creted ''makeman.pl''
(http://mama.sourceforge.net/perl/current/doc/html) to convert them to
roff sources.

> A few notes: I believe games should go in section 6, not 1.

Good point, I will change this on my copies for the ``Missing Man Pages
Project''.

> adding the location of the scorefile into a FILES section. 
> That seems to be /var/lib/games/gnotravex.AxA.scores, where
> A is the grid size. Well, it does on RH. Something tells me
> it will be in a different place on SuSE. Whatever localstatedir 
> is on SUSE, I expect. 

On debian it's /var/lib/games/gnotravexAxA.scores

> And finally, all those options. Shouldn't they go in the 
> synopsis at the top? If not the GTK+ options, at least the 
> gnotravex-specific ones? 
> 
>     gnotravex [-x window-x-coordinate] [-y window-y-coordinate] 
>               [-s|--size 2|3|4|5|6]

Yes, maybe.  I used a template which simply specifiec "OPTIONS".  I
dunno.  I'd say one can argue for either way.

> It has raised a couple of questions in my mind to throw at the
> docs list: 
> 
> I haven't thought about this before, but do man pages have to go 
> under a licence, or is the practice just to include them under the
> licence for the code in the tarball? I'm just trying to imagine
> man pages under the FDL with all the boilerplate at start and
> end :) It's quite a size in the help pages we currently have. 

I believe they should be public domain.  But that's just my opinion.
IIRC, it's common to place the documentation of a package under a
similar license as the package itself; that is FDL for GPL would
probably be appropriate.

The ones that I wrote are public domain, so do whatever you feel like
doing with it ;-)

> Second, the output of --help on practically any GNOME program: 
[...] 
> Are these documented somewhere? I presume the GTK+ hackers know
> how to use them. But what on earth is gxid, for example? It's
> not mentioned in man -k and it's not in the GTK+ FAQ. Are these
> things that all hackers "just know", or what? 

If anybody knows, please email me.

> In addition, I just tested the final ones, and there is a typo: 
> 
> gnotravex options
>   -x=ARG
>   -y=ARG
>   -s, --size=SIZE             Size of board (2-6)
> 
> Put the equals sign in, and they won't work for the single-letter
> option. 
> 
> [hobbit aloss ~]$ gnotravex -s=4
> Error on option -s=4: unknown option.
> Run 'gnotravex --help' to see a full list of available command line options.
> 
> "gnotravex -s 4", "gnotravex --size 4" and "gnotravex --size=4" do 
> all work though. Argh. Confusion reigns :) 

I'll change it to "-s SIZE, --size=SIZE" in the mang page on my machine,
then.

> > To learn more about "The Missing Man Pages Project", please visit
> > http://www.netmeister.org/misc/m2p2/index.html
> 
> I agree that man pages are vital, and there are one or two pages I
> feel GNOME must have in man format. But in general, GNOME's docs
> are in DocBook rendered to HTML, on the expectation that if you're 
> running GNOME then you have a graphical environment.

You can find some of the man-pages I wrote in sgml format at
http://www.netmeister.org/misc/m2p2/sgml/

> Of the docs
> I think we should have in a non-graphical form, I think "man gnome"
> (which used to exist, it fell out of the tarballs back in 1.1 days:
> must dig it out and put it back in!) and "man gdm" are the most 
> pressing. gdm needs it because that's one thing you can find yourself 
> trying to set up without the luxury of X actually running correctly. 

I do believe, though, that every executable should have a man-page.  If
only for the sake of "apropos", "whatis" etc.  With the pages installed
on my machine now when I type "apropos GNOME", I get a nice list of
GNOME applications.

Also, sometimes I come across a binary that I have no idea what it does
(and the name doesn't help necessarily).  If I don't have X running (for
example, I'm logged in remotely), I can't even try it out.  Man pages
are vital.

> Also, I have to be honest. In the past I've tried to mark up
> stuff in DocBook to turn into man pages, and I had trouble. I
> know John Fleck is looking at this again, and I have every
> confidence that he will succeed :) 

Again, see http://mama.sourceforge.net -- maybe it'll be helpful for
you.

Thanks for your detailed comments - it's nice to get feedback.
-Jan

-- 
Jan Schaumann 
http://www.netmeister.org