The Package `docbook-tools'
===========================

    +----------------------------------------------------+
    |                                                    |
    | General documentation on DocBook you'll find here: |
    |                                                    |
    |    http://docbook.sourceforge.net                  |
    |                                                    |
    +----------------------------------------------------+

The package contains:

    db2x.sh       - a script to convert SGML documents conforming to the
                    DocBook DTD 3.0, 3.1, and 4.1 and to DocBook XML DTD
                    4.x.

    suse-both.dsl - a driver file to Norman Walsh's DocBook stylesheets.

Both these files are based on ideas by Mark Galassi.

In addition, gdp-both.dsl the driver file from the GNOME Project is
included.


Requirements
------------

To use all features of `db2x.sh' you've to install the following
packages (on SuSE Linux > 7.2; maybe, the package will still work with
previous releases):

    mktemp

    docbook_3 (was: docbk30)
    docbook_4 (was: docbk_4)
    docbook-dsssl-stylesheets (docbkdsl)
    iso_ent
    jade_dsl
    sp (not required any longer: sp_libs)

The following packages are only needed if you want to produce PostScript
or PDF:

    jadetex

    tetex
    te_kpath
    te_latex
    te_pdf
    te_pscm
    te_mpost
    te_ams


How to use it
-------------

Please, try the --help tableau:

-=-=-=-=-=-=-=-=-=-=-=-=-=- cut here -=-=-=-=-=-=-=-=-=-=-=-=-=-

Usage: db2x.sh [OPTION]... FILE.sgml
Run a DocBook SGML document FILE.sgml through various programs.

If a long option shows an argument as mandatory, then it is mandatory
for the equivalent short option also.  Similarly for optional arguments.

Options:
  --help                  display this help and exit
  -v, --version           output version information and exit

  -x                      trace the shell script

Output formats:
  -d, --dvi               output DVI
  -f, --fot               output FOT
  -h, --html              output HTML
  -m, --mif               output MIF
  --pdf                   output PDF
  -p, --ps, --postscript  output PostScript
  -r, --rtf               output RTF
  -t, --tex               output TeX
  -X, --xml               output XML (DocBook)
      --xencoding VAR     set XML output encoding (default: iso-8859-1)
      --xoptions VAR      add XML output options; e.g., "-xempty -xlower"
                            (default)

HTML:
  --nochunks              don't produce HTML subdocuments; output to stdout

General options:
  -S, --strict            use the SGML declaration coming with the DocBook DTDs
                            (no minimizations are allowed)
  -j, --jade VAR...       set "jade" variables; e.g., "-V %shade-verbatim%"
  -J, --use-jade          use jade instead of openjade
  -c, --catalog FILE      use FILE as the catalog
  -s, --style FILE        use FILE as driver style
  -V, --validate          validate (sloppy); without "--strict" allow
                            minimizations
  -W, --validate-strict   validate (strict); implies "--strict"

Only the last specified output format will be produced.

The script will automatically use FILE.dsl as a driver style if it is found in
the same directory as FILE.sgml.

-=-=-=-=-=-=-=-=-=-=-=-=-=- cut here -=-=-=-=-=-=-=-=-=-=-=-=-=-

For convenience, I do provide the following phony links:

    db2html db2dvi db2fot db2tex db2ps db2pdf db2mif db2rtf db2xml

For compatibility 'dbnochunks' was added.


Examples:
.........

1. If you want to produce HTML output, use `db2html':

      db2html FILE.sgml

   You'll find the HTML files in the subdirectory FILE, ready to put on
   the webserver.

   If you don't want the HTML files being splitted:

      db2html --nochunks FILE.sgml > FILE.html


2. If you want to produce PostScript, use `db2ps':

      db2ps FILE.sgml

   You'll find the PostScript file in the current directory as FILE.ps,
   ready for printing.


3. If you want to convert an SGML DocBook file into a valid XML file,
   use `db2xml':

      db2xml --xoptions "-xcomment" FILE.sgml

   You'll find the XML file in the directory of the SGML file as FILE.XML,
   ready for processiong with XML tools.  If needed, please add the XML
   document type declaration manually; e.g.,

      <?xml version="1.0" encoding="iso-8859-1"?>
      <!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML//EN"
          /usr/share/sgml/db3xml/docbookx.dtd>



Customization
-------------

Customization could be done via the driver file suse-both.dsl; to be
found at /usr/share/sgml/docbook-toys/suse-both.dsl on SuSE Linux.  You
can copy suse-both.dsl into the current directory (as my-style.dsl),
modify the file and use it via the --style switch.
