Re: Downloading Gnome Documentation in docbook form

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Tue, May 25, 2004 at 05:36:57AM -0500 or thereabouts, John J. Boyer wrote:
> This is probably a dumb question, but where can I download the Gnome 
> documents, such as the gtk/gnome Programmer's Guide, in docbook form? I'm 
> working on an xml to braille project and need some real documents to chew 
> on. Are the Gnome documents written originally in docbook or SGML?

I was really hoping someone else would answer this, because I shall
get parts wrong. I think the majority of Gnome documentation starts
life as DocBook in Gnome CVS. DocBook began life as an SGML DTD,
then became XML. So some of our really old documents are in SGML 
DocBook (3.0 and 3.1 and so on) and never got converted to XML, but 
the majority are in XML DocBook. They were either converted, or 
they started as XML in the first place.

How much XML do you need? 

Places I would look for lots of it are the Gnome CVS modules
gnome-docu, gnome-devel-docs, gnome-user-docs, and the help/C
directory of any "core" Gnome program, where the user docs for
that program live. 

I'm not sure which Gtk/Gnome Programmer's Guide you mean.
Havoc Pennington wrote Gtk and Gnome Application Development
some years ago. The contents of the book are in the GGAD
module in CVL, but although they're all marked up, it doesn't
look like DocBook to me. 

Matthias Warkus wrote the official Gnome 2 Developer's Guide
recently, and it is published by No Starch press, but I have
no idea whether it is in DocBook, and no idea whether it is
available in digital form. 

Or there are the Gtk tutorials at http://www.gtk.org (which
I can't reach at the moment) and the various documents on 
http://developer.gnome.org/doc/ . I think that the bulk of
the latter are generated by scripts in the website module
of CVS. The scripts use the documents in the rest of CVS,
which are generally in XML DocBook (see first paragraph).

There are also the API reference docs. I am not sure how
these are generated. I think programmers are supposed to 
comment things in CVS with specially-marked up comments,
and then something (gtkdoc) goes through and creates the
documentation from those comments. But I am not very clear
on that side of things.

How much DocBook do you need? If CVS is a problem, I think
lots of people will have lots of CVS checked out. I have quite
a bit of it myself. I expect I can bundle up a collection of
whatever Gnome documents in DocBook I have, and send it by
email or something. 

Looking around on my machine (Fedora Core 1), I see lots
of XML which came with various programs, but it's mainly
user docs. I don't know whether that's what you were looking
for, or whether you specifically wanted developer docs,
which are more likely to use particular elements. 

I hope someone will now correct me and say "you just need
to go here and it's all there"...

Telsa