README

   1 Eric Bischoff
   2 ebisch@cybercable.tm.fr                         July 18, 2000
   3
   4 Introduction
   5 ------------
   6
   7 The docbook-utils is a set of a few small programs intended to ease
   8 everyday's use of technical documentation software and more generally
   9 use of SGML and XML. They are released under the GPL licence.
  10
  11 Tasks they currently accomplish are:
  12   - jw: convert SGML files to other formats (HTML, RTF, Postscript, PDF)
  13   - sgmldiff: detect the differerences in markup between two SGML files
  14
  15 Tasks they might accomplish in the future are:
  16   - convert legacy formats (linuxdoc, *roff, texinfo, ...) into docbook
  17   - provide a nice interface to collateindex.pl for easy index generation
  18   - etc...
  19
  20 The scripts assume that on the user's system the following is installed:
  21   - James Clark's DSSSL engine, Jade, and associated utilities like nsgmls.
  22   - a shell and a perl interpreters
  23   - Sebastian Rahtz's Jadetex set of TeX macros for Jade
  24   - ISO's SGML entities and other common files
  25   - OASIS consortium's DocBook DTD
  26   - Norman Walsh's modular DocBook stylesheets
  27   - The SGMLS Perl module
  28
  29
  30 Compatibility
  31 -------------
  32
  33 The docbook-utils scripts are inspired by the former scripts from the
  34 DocBook-Tools distribution (hosted by Cygnus sourceware project). The
  35 transition from the former docbook-tools can be ensured through the use
  36 of wrapper scripts.
  37
  38 The following example of a wrapper script is for the KDE project, and can
  39 be easily adapted to meet other needs.
  40   #!/bin/sh
  41   if [ -n "`jw --version 2>/dev/null | grep '^docbook-utils'`" ]
  42   then # docbook-utils
  43     jw   -c /usr/lib/sgml/kde/kde.cat \
  44          -d /usr/lib/sgml/kde/stylesheets/kde.dsl#html \
  45          -o db2html-dir \
  46          index.docbook
  47   else # cygnus
  48     db2html -d /usr/lib/sgml/stylesheets/kde.dsl \
  49             index.docbook
  50   fi
  51
  52 Thanks to the standardization effort that has been lead for LSB, we can
  53 hope that those tools are becoming more and more compatible with the
  54 SGML-Tools version 2, or with the packaging of SGML and DocBook done by
  55 many Linux distributions. Any feedback in this area is welcome.
  56
  57 The docbook-utils are now able to run on non-lsb platforms by means of
  58 the same configuration files and scripts than the ones used by
  59 SGML-tools.
  60
  61 Design
  62 ------
  63
  64 There is a number of deliberate design choices behind the docbook-utils:
  65
  66 - They are maintained
  67
  68 It means that they should evolve in the future, with the help of the feedback
  69 from their users. It also means that some FTP space and a Web page will be
  70 dedicated to them. There is already a mailing list available:
  71   docbook-utils@bazar.conectiva.com.br
  72
  73 - They are distributed seperately from the other packages
  74
  75 They will be able to work from a package of their own, thus easing distribution
  76 packager's work and making the whole design much clearer to anyone.
  77
  78 - Full support for alternate stylesheets
  79
  80 Anyone can write new customization stylesheets, for HTML, printout, or
  81 both. But it is not assumed anymore that there is such a customization
  82 stylesheet. The DocBook stylesheets can be used "out of the box".The
  83 old db2ps problems with alternate stylesheets are fixed as well.
  84
  85 - HTML can be generated in any destination directory
  86
  87 HTML will be generated by jw in the current directory as a default, so
  88 there will be no more conflict if the customization stylesheets declare
  89 another target directory. This setting can be overriden through a new
  90 -o command-line output option.
  91
  92 - GNUish syntax for the command-line options
  93
  94 All options will be both in -s short or --long form. GNU style also implies
  95 new --help and --version options.
  96
  97 - Any extension for DocBook files is supported
  98
  99 There is no more restriction to ".sgm" or ".sgml". Someone can use
 100 ".dbk" or ".docbook" for instance.
 101
 102 - Modularity:
 103
 104 jw isolates the handling of the output format and of the input format
 105 by means of backend and frontend files. A new backend or a new frontend
 106 are very easy to write.