Re: Documentation

[Nils Barth <nbarth fas harvard edu>]

Thus spake Karl EICHWALDER:
> Nils Barth <nbarth@fas.harvard.edu> writes:
> 
> |   Agreed.
> 
> Disagreed.  GNOME is about graphics and GUI -- AFAIK, `man' isn't
> able to deal with pictures.  Go figure ;-)

IMNSHO, GNOME is about more than just graphics and such (think
bonobo/CORBA/Gconf, etc.).
However, proper DocBook should have some kind of ALT text for
pictures, so this shouldn't be too much of a problem (and if we really
wanted to, we could use a graphics-to-ASCII converter ;-)

So: many people (like Derek) like man pages/Texinfo.
These are pretty easy to make from DocBook (see below).
Thus, I think we should try to support man pages and Texinfo when
practical/not too much work, which will hopefully be all the time.

I haven't played with docbook2X too much, but it seems that the only
concern is that it requires DocBook XML, which isn't an official
standard yet, though: there is an unofficial DocBook XML DTD, and I
think DocBook 5.0 will be XML.

> |   Fortunately, man pages are (theoretically) easy to make for GNOME,
> |   since we document in DocBook. Thus, all you need to do is feed your
> |   documentation through a DocBook -> Man (or TeXinfo, or whatever)
> |   convert and ta-da! Man pages!
> 
> In practice, you've to prepare the SGML/XML source files to produce
> manpages; have a look at Norman Walsh's book (p. 44 s.) -- if you don't
> want to buy it, it's available at ww.docbook.org and/or www.nwalsh.com
> (sorry. I'm not online to check it).

Really?
docbook2X seems to work fine on any DocBook.
Are you referring to <refentry>?
AFAIK, this is -based- on UNIX man pages, but you certainly don't need
to write your whole DocBook documentation as <refentry>s, as one can
see by considering the examples in docbook2X.

> |   However, I haven't had any luck with docbook2X or DocBook-to-man
> |   (though I haven't tried very hard) -- I'm guessing that this hurdle is
> |   why there aren't more GNOME man pages.
> 
> I didn't try these tools.  For quick results I'd try
> 
>     help2man gnome-session
Er, where can I get `help2man'?

Incidentally, I got docbook2X working -- I just need to get a few perl
modules. Here's instructions/a HOW-TO:
------------------------------------------------------------
Making man/info from DocBook.
(1) You need to use DocBook XML, as docbook2X doesn't like DocBook SGML.
(2) Get docbook2X (from: http://shell.ipoline.com/~elmert/hacks/docbook2X/ )
There is a DEB package, but no RPM, and it doesn't come with an
install script :P -- though you can use it in place.

To use this you need the perl modules
XML::DOM and XML::Parser
Get these by going to:
http://search.cpan.org/
If you're not familiar with perl, to install these modules:
gunzip module.tar.gz
tar xf module.tar
cd module
perl Makefile.PL # this is the only change, as opposed to ./configure
make
su
make install

(3) Make the files
docbook2man gnome.xml > gnome.1
docbook2texi gnome.xml > gnome.texi
makeinfo gnome.texi # produces gnome.info

Put gnome.1 in /usr/man
Put gnome.info in /usr/info, and edit /usr/dir to put a reference to
it, something like:
* GNOME: (gnome).    The GNU Network Object Model Environment.
 (I don't know a good way to automatically do this -- any Texinfo
experts out there?)
Oh, and set correct permissions, of course.

The above is somewhat incomplete, but should work for simple files.
Additions anyone?
------------------------------------------------------------

> |   That said, I agree that we should have man pages and TeXinfo if
> |   possible.
> 
> Wrong spelling: It's spelled "Texinfo".

oops -- thanks!

So. . .man and Texinfo aren't that bad to create, so we should do it
when possible, to support all the Dereks out there.

-- 
  -nils