Re: Documentation

[Miguel de Icaza <miguel helixcode com>]

> Here's a novel concept for gnome documentation:
> 
> GNOME NEEDS MAN PAGES.
> 
> Wether anyone likes it or not, man pages are still the #1 source of
> documentation for commands on all Unix platforms, including Linux and
> FreeBSD, though even more so on non-OSS Unix variants.

If you had checked gnome-list, you would have noticed I have been
advocating this for a few weeks.

I even gave an outline on how to do this, but it is something like
this:

	1. Make sure our SGML docs can be loaded with libxml.
	   Amputate or fix if required.

	2. Write a library/subroutine that can take a DocBook SGML
           file and convert it to HTML/Man/whatever.

	3. Write a front-end that talks to Nautilus new help browser
           (using the library above, dont even try to do this now, as
           Nautilus browser is not finished yet).

	4. Write a sgml -> man convertor, and process all the SGML
           files from the GNOME API at distirbution time.

	   This one you can do now.

> I'm not even saying you need to have long, ultra-detailed man pages, but
> they ought to exist.

The text body exists;  We only need the actual conversion to be done.

> Sorry to sound so negative, it's been a shitty day and I'm already
> pissed off. I think you guys are doing a great job.  But I still think
> we need man pages.

You are not being negative, you just have a lot of energy.

What better thing to do, than use this energy to write the above
mentioned stuff.

Look in gnome-libs/devel-docs/{gnome,gnomeui,zvt,libgnorba}/sgml for
the Docbook SGML source that needs to be rendered.

And yes, the stuff there is *designed* to be displayed as a man page;
Solaris even converted all their man pages into SGML and now they ship
an DocbookSGML-aware man command

best wishes,
Miguel.