Re: DocBook, sgml, whatever...

[Eric Baudais <baudais kkpsi org>]

On Tue, 2002-08-20 at 11:39, Jeremy Jones wrote:
> Eric (et alia),
> 
> Thanks for your reply to my plea for help!
> 
> > It sounds like you have all the tools needed to get DocBook up and
> > working.  Unfortunately you will have to become knowledgeable about
> > DocBook issues if you choose to build from source.
> 
> I was afraid of that :\
> 
> > You can get this <the docbooks, that is> minus the catalog files from docbook.sourceforge.net
> 
> OK...  I've downloaded all the docbook zip files I can find.  What
> versions, in particular, will I absolutely NEED to have installed for a
> clean Gnome 2 build?  I went ahead and got all past/present</future>
> versions of the sgml and xml docbooks, but do I need 'em all?  Are there
> other "unofficial" ones I might need in addition for smooth operation?

To get gtk-doc working all you need is sgml-common, openjade,
docbook-sgml-3.0.0 and docbook-dsssl.  You might need opensp, but I am
not sure.

> > 1) export SGML_CATALOG_FILES=/etc/sgml/catalog
> > 
> > The top level catalog file is /etc/sgml/catalog.  This is the file in
> > which all the other catalog files are referenced.  It does not have to
> > be /etc/sgml/catalog, but this is in reference to my own configuration
> > of Debian unstable.
> > 
> > 2) Make sure you reference all your catalogs from the "super" catalog. 
> > Below is a sample super catalog file which should be put into /etc/sgml/
> > 
> > catalog:
> > 
> > CATALOG /usr/share/sgml/docbook/dsssl-stylesheets/catalog
> > CATALOG /usr/share/sgml/docbook/sgml-dtd-3.0.0/catalog
> > CATALOG /usr/share/sgml/docbook/sgml-dtd-3.1.0/catalog
> > CATALOG /usr/share/sgml/docbook/sgml-dtd-4.0.0/catalog
> > CATALOG /usr/share/sgml/docbook/sgml-dtd-4.1.0/catalog
> > CATALOG /usr/share/sgml/docbook/xml-dtd-4.1.2/catalog
> > 
> > 3) Make sure there is a PUBLIC entry in one of the catalogs listed in
> > your super catalog.  Below is an example:
> > 
> > PUBLIC "-//Davenport//DTD DocBook V3.0//EN" "docbook.dtd"
> > 
> > This entry is made of three parts.  The first part defines the scope of
> > the declaration.  The second part defines the DTD referenced.  The third
> > part defines the file where the DTD is located in your filesystem
> > locally.
> 
> I'll be working on this today...  I'll let you know how it turns out.
> 
> > 
> > After doing these three steps jade should find the DTD.  I do not
> > guarantee any of these steps will work on a crack-laden source only
> > distro.  Nor do I guarantee any of these steps will make gtk-doc, jade,
> > or any other program work correctly.  I do guarantee these steps have a
> > possibility of blowing up your computer and forever destroying any hope
> > of using DocBook in a cyanide laced source distro.
> > 
> 
> Good enough for me!
> 
> > 
> > There are some packagers, notably Garnome, which
> > have chosen not to enable gtk-doc.
> > 
> 
> What are the downsides to this?  Missing help pages and whatnot?

gtk-doc just builds the developer documentation for the libraries in
GNOME.  Since this is prebuilt by the maintainer when the tarball is
made this step is really unnecessary if you are using a tarball. 
However, if you want the developer documentation and are building from
CVS you need to compile with gtk-doc.

Eric Baudais