Re: DocBook

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Mon, Oct 16, 2000 at 06:39:12PM +0200 or thereabouts, Germano Rizzo wrote:
> 
> Hi! :)
>     does anyone know where I can learn to write a DocBook? I
> have to write the documentation of an app...
>         Thanx,
>             Mano :)

Documentation for a GNOME app, or just "any old app"? 

You'll need some tools to generate the output of a DocBook file:
these are commonly docbook, jade, stylesheets and sgml-common.
If you want to generate printable output, you'll want jadetex as
well. If you like emacs as an editor, get the psgml package: it's
an SGML-editing mode which is very impressive. Get them from a 
mirror of ftp://sourceware.cygnus.com/pub/docbook-tools/ (there 
are straight tarballs there as well as RPMs) or with apt-get 
docbook or something similar on Debian.  

How to use them? Urm.

The sole printed book I know of is "DocBook: The Definitive Guide"
by Norman Walsh and Leonard Muellner, published by O'Reilly (surprise).
You can read it on the web at http://www.docbook.org. Note that it's
very much a _reference_, not a tutorial. The way everyone I know learned 
DocBook is to find a doc that was almost what you wanted, and start 
tweaking it and see what breaks when you try to validate the results.

There are a bunch of introductions to DocBook. A recent addition
to them is http://www.lst.de/~eric/crash-course/HTML/index.html or
http://www.lst.de/~eric/crash-course/ and it has a very useful section
at the back of sample docs: everything from marking up a list of
information to how to mark up a function in a C library API.
There are also many mailing lists for marking up in DocBook. 

For samples of DocBook, just grab anything out of GNOME CVS :)
(Don't use gnome-applets stuff, though: the docs are put together
in a sane but not-usual way and it will confuse you when you are
starting out.) 

Or there's tons of DocBook docs at http://www.oswg.org (Open 
Source Writers' Group), and I think the LDP is using it increasingly,
too. I really recommend stea^Wborrowing or looking at other docs:
it makes far more sense than staring at an empty file and wondering
"Now what?". 

If it's a GNOME document, there is more! Have a look at the GDP
pages at http://developer.gnome.org/projects/gdp/ for an introduction
to GDP stuff. We complicate matters by using a slightly mucked-with
version of DocBook 3.x, which means you (and potentially anyone
building your app from source, unless you are clever with your 
Makefile, or ship ready-built docs in the app) need the tools to 
cope with it. (Details, packages, and links off the GDP page in
the GDP manual). This problem will go away as we move to DocBook 
4.x which doesn't need our mucky hacks. (KDE's in the same situation: 
both projects wanted to use PNGs instead of GIFs as the images. Blame 
Unisys :)) If you are nice to us, we will convert docs from ASCII 
to DocBook for you. Well. At least once. :) We live over on 
gnome-doc-list gnome org (or docs gnome org is an alias which I think 
goes to the list too) and on the #docs channel on irc.gnome.org where 
we have been known to stay on-topic for minutes at a time. 

If you are documenting the technical side of it, for other hackers,
there are some other useful things, but I don't know how they work
so I'll leave it at that. There's something that turns comments 
into documentation or something (allegedly, at least :)). 

I am going to skip lightly over "How you plug your docs into your
code" because that's beyond my ken. Havoc's book covers it (module
GGAD in CVS), the WROX-published book about GNOME covers it, and 
the one by John Sheets covers it too.

Final thing to remember is that some of the translation teams 
seem to have an on-going "spot new docs and apps and be the first
to translate them" competition: if you see a Norwegian translation
arrive, hold off on a release, because you can bet that Swedish and
Danish are about to jump in too :) The i18n list will probably have 
more to say about this and about "give translators warning before a 
release" :)

Ugh. Long. I hope -some- of that helps. 

Telsa