Re: DocBook, sgml, whatever...

[Eric Baudais <baudais kkpsi org>]

On Thu, 2002-08-15 at 16:13, Jeremy Jones wrote:
> Hello alls,
> 
> Forgive me for sounding either stupid or a little frustrated...  I'm
> more than likely both.
> 
> I use a linux distro called CRUX -- not a big-time distribution, just
> ships with the basics.  It uses a simple packaging system for software
> management -- basically a script that downloads source, passes configure
> options, and builds .tar.gz files.  There's no dependency checking, or
> anything like that.  I've been working for over a month on building a
> collection of Gnome 2 ports for crux.  I now have a reasonably
> well-assembeled collection.  The only thing that's still giving me
> trouble is docbook.  This docbook stuff has caused me more grief than
> anything else.

It is great you want to port GNOME 2 to your favorite distro. :)

> All I want to do is install Gnome 2 without using that
> --enable-gtk-doc=no configure option on every other package.  I _DO NOT_
> want to become an expert on sgml, xml, or docbook-dtd stuff.  However, I
> have found no simple, task-oriented documentation on how to get the
> docbook/sgml prerequisites for gnome 2 setup properly.  I have installed
> docbook-sgml-3.0.0, 3.1.0, 4.0.0, and 4.1.0; docbook-xml-4.1.2;
> sgmltools-lite; docbook-dsssl; docbook-xsl; sgml-common; gtk-doc;
> openjade; and opensp.  

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.

> Openjade, opensp, sgmltools-lite, and gtk-doc are latest releases. 
> Docbook things are mostly stolen from RedHat RPMS.  I've verified (to
> the best of my meager abilities) that my catalogs are set up properly.
> 
> So, here's what happens when, for instance I try to compile GConf w/out
> the dreaded --enable-gtk-doc=no option:
> 
> <moving along just fine... then...>
> *** Building HTML ***
> rm -rf ./html 
> mkdir ./html
> cd ./html && gtkdoc-mkhtml gconf ../gconf.sgml
> jade:../gconf.sgml:1:59:W: cannot generate system identifier for public
> text "-//Davenport//DTD DocBook V3.0//EN"

This is a catalog problem.  This error message is telling you jade
cannot find the DTD specified in the DTD directive in the SGML file.

> jade:../gconf.sgml:14:0:E: reference to entity "BOOK" for which no
> system identifier could be generated 
> jade:../gconf.sgml:1:0: entity was defined here
> jade:../gconf.sgml:14:0:E: DTD did not contain element declaration for
> document type name
> jade:../gconf.sgml:15:9:E: there is no attribute "ID"
> jade:../gconf.sgml:15:16:E: element "BOOK" undefined
> jade:../gconf.sgml:16:11:E: element "BOOKINFO" undefined
> jade:../gconf.sgml:17:16:E: element "AUTHORGROUP" undefined
> jade:../gconf.sgml:18:13:E: element "AUTHOR" undefined
> jade:../gconf.sgml:19:11:E: element "FIRSTNAME" undefined
> jade:../gconf.sgml:20:9:E: element "SURNAME" undefined
> jade:../gconf.sgml:21:13:E: element "AFFILIATION" undefined
> <...etc...until...>
> /usr/bin/gtkdoc-mkhtml: index.sgml: No such file or directory

The rest of the above errors are a result of jade not finding the DTD
correctly.
 
> Yes, I've looked through my (hediously opaque) chain of catalog files,
> and I do have things that say "-//Davenport/DTD DocBook V3.0//EN" and so
> on.  
> 
> I guess what I'd really like is one of two things:
> 
> either 1) A simple .tar file with a working set of docbook dtd stuff. 
> Something that people compiling from source don't need to worry about,
> that'll chuck all the necessary files and catalogs in the right
> directories, and let them move on to working with gnome.

You can get this minus the catalog files from docbook.sourceforge.net

> or 2) A set of instructions like:  "download such-and-such from
> so-and-so and extract it in /this/directory/; next, download
> this-other-thing from some-other-place and extract it in
> /another/directory..."

This I will try to help you with.

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.

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.

> Does anyone know if either of my two prayers have been answered already?
> 
> Or should I shut up and deal with the --enable-gtk-doc=no thing...

That is your choice.  There are some packagers, notably Garnome, which
have chosen not to enable gtk-doc.

Eric Baudais