Re: gnotravex man page

[Telsa Gwynne <hobbit aloss ukuu org uk>]

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

A few notes: I believe games should go in section 6, not 1.
The bug address changed to http://bugzilla.gnome.org: but I
believe the BUGS section is for documenting the existence of
known bugs, not for where to report them. It might be worth 
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. 

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]

(I know there's a better way to write 2 to 6 but my brain has
fried.)

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. 

Second, the output of --help on practically any GNOME program: 

GTK options
  --gdk-debug=FLAGS           Gdk debugging flags to set
  --gdk-no-debug=FLAGS        Gdk debugging flags to unset
  --display=DISPLAY           X display to use
  --sync                      Make X calls synchronous
  --no-xshm                   Don't use X shared memory extension
  --name=NAME                 Program name as used by the window manager
  --class=CLASS               Program class as used by the window manager
  --gxid_host=HOST
  --gxid_port=PORT
  --xim-preedit=STYLE
  --xim-status=STYLE
  --gtk-debug=FLAGS           Gtk+ debugging flags to set
  --gtk-no-debug=FLAGS        Gtk+ debugging flags to unset
  --g-fatal-warnings          Make all warnings fatal
  --gtk-module=MODULE         Load an additional Gtk module

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? 

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

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

So we haven't got onto man pages yet because we have been trying to
fill in all the docs which are used by the help system in GNOME:
the stuff where you click the "Help..." button on the toolbar of
any app first. A lot of GNOME users head for that rather than for
a text-based interface with a funny name. Hence we have been 
catching up with those first. 

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

Thank you for the man page. It might be worth popping it as
an attachment into bugzilla (gnome-games/gnotravex) in case it
gets lost on mailing lists: many of the archives strip attachments,
which can be a pain in those "I know it got sent here somewhere"
archive-searching moments... 

Telsa