db2html and compiling gnome-utils

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Sat, Aug 19, 2000 at 06:50:29AM +0100 or thereabouts, peter bunney wrote:
> John Fleck <jfleck@inkstain.net> wrote:
> > 
> > Peter - This should not be happening. You should not need db2html
> > (it's a tool that builds html help files out of sgml source, but is
> > normally run by package maintainers when they build the package rather
> > than end users - on your end the html should already be in the package)

I think it should: he's compiling from scratch.
 
> I got the version 1.2.1 tarball from
> ftp://ftp.gnome.org/pub/GNOME/stable/sources/gnome-utils/
> and its the latest version available there
> 
> Output from make........
> 
> make[5]: Entering directory `/usr/src/gnome-utils-1.2.1/gfloppy/doc/C'
> if [ ! -d gfloppy ] ; then cd . && db2html gfloppy.sgml ; fi
> /bin/sh: db2html: command not found
...
> Do I have to go to the pointy end to get a compilable version ?

Naah. 

DocBook is a very rich markup language for technical documentation,
and GNOME's help files are written in it. GNOME's help system likes 
HTML. db2html is "docbook to HTML"...

db2html is a little script that invokes jade. jade is a program which
takes a DocBook file, looks at the version of DocBook, looks at what
the results are supposed be, looks at a stylesheet to see how it should
look, pauses for a long breath, and then turns DocBook into what's
wanted. Or complains at you. (It does that a lot to me :)).

So you have three solutions: 

(1) After ./configure and before make, edit Makefile.am.
    Remove "docs" from the line beginning SUBDIRS.

    It will then compile, miss out the doc-building stage, and 
    everything except for help will work. Not the best solution,
    but quick and dirty and simplest of all.


(2) Install sgml-common, docbook, (cygnus-)stylesheets, and jade.
    This gives you the db2html script to generate docs. Normal docs.

    Unfortunately, we in the documentation folks decided that we would
    use non-normal docs! Specifically, we use Gnome almost-DocBook 
    because messing with the standard let us use PNGs instead of GIFs. 
    (This is good because PNGs are a better thing for a free software
    project to use.) We did this by having a non-standard DTD and an 
    extra stylesheet. Jade doesn't know about these. After you have 
    installed jade and friends, there are two ways to sort this out:

  (a) Change the DTD (the line in angle-brackets) in any file that
      has it at the top. Alter "-//GNOME//DTD V3.1//EN" to
      "-//OASIS//DTD DocBook V3.1//EN". This is the standard DocBook
      DTD and jade knows about it. But it will break all PNG shots
      in the doc, so it will get built with broken graphics links. (Or
      jade will reach 200 errors and bomb out, which is a nuisance.) You
      could remove all the graphics to get rid of that, I expect (by
      removing anything between <figure> and </figure> in the .sgml
      file before compiling it. 

  (b) Simpler: get the GNOME DTD and stylesheets and install them.
      Tarball, rpm and deb are all at 
      http://people.redhat.com/dcm/software.html
      This is simpler and better, and it means it will just whizz 
      through db2html when it gets to that stage of the compile.
      (Well, jade is quite slow, but it will almost whizz.)

One of these _should_ work. I hope :)

Telsa