Updated: 11 February 2004
jw, docbook2dvi, docbook2html, docbook2man, docbook2pdf, docbook2ps, docbook2rtf, docbook2tex, docbook2texi, docbook2txt - (Jade Wrapper) converts SGML files to other formats
jw [ -f
frontend | --frontend
backend | --backend backend ]
[ -c file | --cat file ]
[ -n | --nostd ]
file|default|none | --dsl
[ -l file | --dcl file ]
[ -s path | --sgmlbase path ]
[ -p program | --parser program ]
[ -o directory | --output directory ]
[ -u | --nochunks ] [ -i section | --include section ]
[ -w type|list | --warning type|list ]
[ -e type|list | --error type|list ]
[ -h | --help ] [ -v | --version ]
The jw shell script allows to
convert a DocBook file (or some other SGML-based format) to
other formats (including HTML, RTF, PS and PDF) with
an easy-to-understand syntax. It hides most of Jade's
or OpenJade complexity and adds comfortable features.
Other scripts like docbook2html,
docbook2ps provide different ways of
calling jw that might be easier to
For the moment, jw does not handle XML, but only SGML.
This utility assumes that several other components are
installed. The list includes:
the ISO character entities for SGML
James Clark's DSSSL engine, jade, or an equivalent parser
the DocBook DTD from the OASIS consortium
Norman Walsh's DocBook modular style sheets (or some other
set of DSSSL style sheets)
Sebastian Rahtz's jadetex set of TeX macros for jade
(for backends intended to "printing" formats like PDF, RTF or
A perl interpreter (for backends that use perl)
SGMLSpm from CPAN (for backends that use sgmls)
Lynx HTML browser (for the txt
The jw script is basically called like this:
where mydoc.sgml is a SGML file.
The command line above uses default options: it converts
from DocBook (the default frontend) to HTML (the default backend),
does not put the result in a subdirectory (unless specified
otherwise in the style sheets), etc.
In this example, the "mydoc" file name as well as the ".sgml"
extension can be replaced by anything else. Current extensions
for SGML DocBook files include ".sgml", ".sgm", ".docbook", and
".db". The processed file mydoc.sgml can
be in any other directory than the current one.
Here we have chosen to generate HTML output. In fact we can
use any of the backends stored in the backends/
subdirectory of the DocBook-utils distribution directory (usually
Similarly, you can use any frontend defined in the
frontends/ subdirectory to convert from another
This sample command creates one or many HTML files with
arbitrary file names in the current directory. This default behavior
can be changed through command line options and/or customization
The following options apply to the conversion script:
- -f frontend | --frontend frontend
Allows to specify another frontend than default docbook.
The list of currently available frontends is:
Converts docbook with Norman Walsh's
style sheets. This frontend searches in the
subdirectories of the base SGML directory for a
file named html/docbook.dsl or
print/docbook.dsl (depending on the
backend's type: html or print).
- -b backend | --backend backend
Allows to specify another backend than default
HTML. The list of currently available
Converts to DVI (DeVice Independant
files) by calling Jade or
Converts to HTML (HyperText Markup
Language) by calling Jade
Converts a refentry to a Unix manual page
by calling docbook2man. Does not work with other SGML
document types than DocBook.
Converts to PDF (Portable Document
Format) by calling Jade or
Converts to PostScript by
calling Jade or
Converts to RTF (Rich Text Format)
by calling Jade or
OpenJade. The resulting file can
then be inported into MS Word
or one of its Linux replacement programs.
Note - The original picture must be
present when RTF document is viewed, because
the RTF documents created by OpenJade
includes pictures by reference.
Converts to TeX by calling Jade or
Converts to GNU TeXinfo pages by calling
docbook2texi. Does not work with other SGML document types
Converts to a bare text file
by calling Jade
or OpenJade, then
- -c file | --cat file
Allows to use an extra SGML Open Catalog that will list
other files like customization style sheets, adaptations to the
DocBook Document Type Definition, special character entities,
etc. This catalog is added to the list of catalogs determined
by the script (see option --nostd below)
- -n | --nostd
Do not use the standard SGML Open Catalogs. Normally,
the standard catalogs list is determined like this:
This option is useful in conjunction with the
--cat option to use only the catalogs that
are specified on the command line.
if the centralized catalog exists, then
use it. The centralized catalog is a list of all
catalogs that might be necessary that usually
resides in /etc/sgml. Its
name is provided by the frontend, for example
the docbook frontend returns
Otherwise, take all the files
named catalog from the
subdirectories of the SGML base directory (usually
- -d file|default|none | --dsl file|default|none
Allows to use a customized style sheet instead
of the default one.
A "target" starting with a hash mark "#" can be appended
to the file name. As a result, only the corresponding part
of the style sheet is executed (the "style specification" whose
"identificator" is equal to the target's name). A common use of this
mechanism is to define "#html" and "#print" targets to trigger
the corresponding part of a replacement style sheet which is
common for both HTML and printout conversion.
By replacing the file name with "default", the default
style sheet provided with the frontend is used. For example, the
docbook frontend returns
./docbook.dsl#print) in the SGML base
By replacing the file name with "none", no replacement
style sheet is used, not even the default style sheet. The style
sheet which is used is also determined by the frontend. For
example, the docbook frontend returns
Norman Walsh's html/docbook.dsl (or
print/docbook.dsl) found somewhere below
the SGML base directory.
If no --dsl option is specified, then "--dsl default" is
- -l file | --dcl file
Allows to use a customized SGML declaration instead
of the default one. The file name of the default SGML
declaration is not set for SGML files, and is set to
xml.dcl in the SGML base directory
for XML files.
- -s path | --sgmlbase path
Allows to use another location for the SGML base
directory. This is the directory below which all SGML DTDs,
style sheets, entities, etc are installed. The default value
- -p program | --parser program
Specify the parser to use (Jade
or OpenJade) if several
are installed. If this option is not specified,
the script first tries to use Jade, then it tries
- -o directory | --output directory
Set output directory where all the resulting files will
be stored. If the style sheets define a subdirectory where to
store the resulting files too, the subdirectory defined by the
style sheets will be placed below the subdirectory defined by
- -V variable=[value]
Set a variable (to a value, if one is specified).
- -u | --nochunks
Output only one big file. This option is useful only
when generating HTML, because the output can be split into
several files. This option overrides the setting that may be
done in the style sheets.
- -i section | --include section
Declare a SGML marked section as "include". A SGML marked
section is a kind of conditional part of a document. If it is
declared "ignore", it will be left ignored, otherwise it will
be processed. An example of such a marked section would be:
<DOCTYPE mydoc [
<!ENTITY % confidential "ignore">
<![ %confidential [ Some confidential text... ]]>
- -w type|list | --warning type|list
Enables or disables the display of given types of warnings.
Several -w options might be entered on the command line.
Warning types that start with "no-" disable the corresponding
warnings, the other types enable them.
If the warning type is replaced with "list", then
a list of allowed warning types is displayed.
- -e type|list | --error type|list
Disables given types of errors.
Several -e options might be entered on the command line.
All error types start with "no-".
If the error type is replaced with "list", then
a list of allowed error types is displayed.
- -h | --help
Print a short help message and exit
- -v | --version
Print the version identifier and exit
Centralized SGML open catalog. This file name might
vary if another frontend than docbook
The various backends
The various frontends
The various helper scripts like docbook2man or docbook2texi
Eric Bischoff (jw shell script and a few backends),
Jochem Huhmann (the man and