Re: Documentation

[Karl EICHWALDER <ke gnu franken de>]

Nils Barth <nbarth@fas.harvard.edu> writes:

|   IMNSHO, GNOME is about more than just graphics and such (think
|   bonobo/CORBA/Gconf, etc.).

Of course, but the user isn't considered to know this.  And the stable
1.0.xx doesn't have bonobo, "etc.".

|   So: many people (like Derek) like man pages/Texinfo.
|   These are pretty easy to make from DocBook (see below).

Know, they aren't.  Or do you actually want to read the whole users'
guide with man?  Even if manpage are using something like a free format,
they should follow a well defined structure...

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

Yes.  Texinfo is worth all efforts -- and I'm looking forward that one
of the started projects will succeed.

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

Yes.  But if you wish to have good manpages, you'll have the <refentry>
subset of the DocBook DTD.  manpage != users' guide ;)

|   >     help2man gnome-session
|   Er, where can I get `help2man'?

It's an straight forward perl script coming with recent GNU utilities
(file-utils, e.g.); IIRC, an stand alone version was announced at
freshmeat.

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

I've done an RPM for SuSE Linux 6.3 :)  By now available from
ftp://ftp.suse.com/pub/suse/i386/6.3/suse/sgm1/db2x.rpm as "db2x" (version 1.4) 

|   To use this you need the perl modules

Yes, included in SuSE Linux 6.3, directory as above.

|   Put gnome.1 in /usr/man

or /opt/gnome/man/man1 on some Linux distributions.

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

install-info

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

Okay, I'll try to do my best and make RPMs of all needed packages.

-- 
work: ke@suse.de                          |
        : http://www.suse.de/~ke/             |       ------    ,__o
personal: ke@gnu.franken.de                   |      ------   _-\_<,
        : http://www.franken.de/users/gnu/ke/ |     ------   (*)/'(*)