JW(1)JW(1)NAME
jw, docbook2dvi, docbook2html, docbook2man, docbook2pdf, docbook2ps,
docbook2rtf, docbook2tex, docbook2texi, docbook2txt - (Jade Wrapper)
converts SGML files to other formats
SYNOPSISjw [ options ...] SGML-file [ [ -f frontend] [ --frontend frontend]
[ -b backend] [ --backend backend]
[ -c file] [ --cat file]
[ -n] [ --nostd]
[ -d file|default|none] [ --dsl file|default|none]
[ -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] ]
DESCRIPTION
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, docbook2rtf or docbook2ps provide dif‐
ferent ways of calling jw that might be easier to remember.
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 like Open‐
Jade
· 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 PostScript)
· A perl interpreter (for backends that use perl)
· SGMLSpm from CPAN (for backends that use sgmls)
· Lynx HTML browser (for the txt backend)
The jw script is basically called like this:
jw mydoc.sgml
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 /usr/share/sgml/docbook/utils-0.6.8).
Similarly, you can use any frontend defined in the frontends/ subdirec‐
tory to convert from another input format.
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 style sheets.
OPTIONS
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:
docbook
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 cur‐
rently available backends is:
dvi Converts to DVI (DeVice Independant files) by calling Jade or
OpenJade.
html Converts to HTML (HyperText Markup Language) by calling Jade or
OpenJade.
man Converts a refentry to a Unix manual page by calling doc‐
book2man. Does not work with other SGML document types than Doc‐
Book.
pdf Converts to PDF (Portable Document Format) by calling Jade or
OpenJade.
ps Converts to PostScript by calling Jade or OpenJade.
rtf 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.
tex Converts to TeX by calling Jade or OpenJade.
texi Converts to GNU TeXinfo pages by calling docbook2texi. Does not
work with other SGML document types than DocBook.
txt Converts to a bare text file by calling Jade or OpenJade, then
Lynx.
[ [ -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 cat‐
alogs list is determined like this:
· if the centralized catalog exists, then use it. The centralized cata‐
log is a list of all catalogs that might be necessary that usually
resides in /etc/sgml. Its name is provided by the frontend, for exam‐
ple the docbook frontend returns /etc/sgml/sgml-docbook.cat.
· Otherwise, take all the files named catalog from the subdirectories
of the SGML base directory (usually /usr/share/sgml). This option is
useful in conjunction with the --cat option to use only the catalogs
that are specified on the command line.
[ [ -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 replace‐
ment style sheet which is common for both HTML and printout conversion.
By replacing the file name with "default", the default style sheet pro‐
vided with the frontend is used. For example, the docbook frontend
returns ./docbook.dsl#html (or ./docbook.dsl#print) in the SGML base
directory.
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 used.
[ [ -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 is /usr/share/sgml.
[ [ -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 OpenJade.
[ [ -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 this option.
[ [ -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">
]>
<mydoc>
...
<![ %confidential [ Some confidential text... ]]>
...
</mydoc>
[ [ -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
FILES
/etc/sgml/sgml-docbook.cat
Centralized SGML open catalog. This file name might vary if another
frontend than docbook is used.
/usr/share/sgml/docbook/utils-0.6.8/backends
The various backends
/usr/share/sgml/docbook/utils-0.6.8/frontends
The various frontends
/usr/share/sgml/docbook/utils-0.6.8/helpers
The various helper scripts like docbook2man or docbook2texi
AUTHORS
Eric Bischoff
Author of jw shell script and of a few backends
Jochem Huhmann
Author of the man and texi backends
SEE ALSOdocbook2man-spec.pl(1)
perl script to help do the actual conversion to a man page
docbook2texi-spec.pl(1)
perl script to help do the actual conversion to a texinfo page
install-catalog(8)
manage a centralized SGML catalog
nsgmls(1)
a base component of Jade DSSSL engine
http://sourceware.cygnus.com/docbook-tools/ <URL:http://source‐
ware.cygnus.com/docbook-tools/>
the home page of the DocBook tools, a compendium of all tools necessary
to process DocBook files, including the DocBook-utils.
27 April 2001 JW(1)