Eric Bischoff
ebisch@cybercable.tm.fr				July 18, 2000

Introduction
------------

The docbook-utils is a set of a few small programs intended to ease
everyday's use of technical documentation software and more generally
use of SGML and XML. They are released under the GPL licence.

Tasks they currently accomplish are:
  - jw: convert SGML files to other formats (HTML, RTF, Postscript, PDF)
  - sgmldiff: detect the differerences in markup between two SGML files

Tasks they might accomplish in the future are:
  - convert legacy formats (linuxdoc, *roff, texinfo, ...) into docbook
  - provide a nice interface to collateindex.pl for easy index generation
  - etc...

The scripts assume that on the user's system the following is installed:
  - James Clark's DSSSL engine, Jade, and associated utilities like nsgmls.
  - a shell and a perl interpreters
  - Sebastian Rahtz's Jadetex set of TeX macros for Jade
  - ISO's SGML entities and other common files
  - OASIS consortium's DocBook DTD
  - Norman Walsh's modular DocBook stylesheets
  - The SGMLS Perl module


Compatibility
-------------

The docbook-utils scripts are inspired by the former scripts from the
DocBook-Tools distribution (hosted by Cygnus sourceware project). The
transition from the former docbook-tools can be ensured through the use
of wrapper scripts.

The following example of a wrapper script is for the KDE project, and can
be easily adapted to meet other needs.
  #!/bin/sh
  if [ -n "`jw --version 2>/dev/null | grep '^docbook-utils'`" ]
  then # docbook-utils
    jw   -c /usr/lib/sgml/kde/kde.cat \
         -d /usr/lib/sgml/kde/stylesheets/kde.dsl#html \
         -o db2html-dir \
         index.docbook
  else # cygnus
    db2html -d /usr/lib/sgml/stylesheets/kde.dsl \
            index.docbook
  fi

Thanks to the standardization effort that has been lead for LSB, we can
hope that those tools are becoming more and more compatible with the
SGML-Tools version 2, or with the packaging of SGML and DocBook done by
many Linux distributions. Any feedback in this area is welcome.

The docbook-utils are now able to run on non-lsb platforms by means of
the same configuration files and scripts than the ones used by
SGML-tools.

Design
------

There is a number of deliberate design choices behind the docbook-utils:

- They are maintained

It means that they should evolve in the future, with the help of the feedback
from their users. It also means that some FTP space and a Web page will be
dedicated to them. There is already a mailing list available:
  docbook-utils@bazar.conectiva.com.br

- They are distributed seperately from the other packages

They will be able to work from a package of their own, thus easing distribution
packager's work and making the whole design much clearer to anyone.

- Full support for alternate stylesheets

Anyone can write new customization stylesheets, for HTML, printout, or
both. But it is not assumed anymore that there is such a customization
stylesheet. The DocBook stylesheets can be used "out of the box".The
old db2ps problems with alternate stylesheets are fixed as well.

- HTML can be generated in any destination directory

HTML will be generated by jw in the current directory as a default, so
there will be no more conflict if the customization stylesheets declare
another target directory. This setting can be overriden through a new
-o command-line output option.

- GNUish syntax for the command-line options

All options will be both in -s short or --long form. GNU style also implies
new --help and --version options.

- Any extension for DocBook files is supported

There is no more restriction to ".sgm" or ".sgml". Someone can use
".dbk" or ".docbook" for instance.

- Modularity:

jw isolates the handling of the output format and of the input format
by means of backend and frontend files. A new backend or a new frontend
are very easy to write.