jw, docbook2dvi, docbook2html, docbook2man, docbook2pdf,
docbook2ps, docbook2rtf, docbook2tex, docbook2texi, doc
book2txt - (Jade Wrapper) converts SGML files to other
formats
SYNOPSIS
jw [ options ...] SGML-file [ [ -f frontend] [ --fron
tend 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 different 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:
· James Clark's DSSSL engine, jade, or an equivalent
parser like OpenJade
· 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. Cur
rent 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/ subdi
rectory of the DocBook-utils distribution directory (usu
ally /usr/share/sgml/docbook/utils-0.6.9). 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] ]
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/doc
book.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 backends is:
dvi Converts to DVI (DeVice Independant files) by call
ing 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 call
ing docbook2man. Does not work with other SGML doc
ument types than DocBook.
pdf Converts to PDF (Portable Document Format) by call
ing 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 replace
ment programs.
tex Converts to TeX by calling Jade or OpenJade.
texi Converts to GNU TeXinfo pages by calling doc
book2texi. 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 cata
logs determined by the script (see option --nostd below)
Do not use the standard SGML Open Catalogs. Normally, the
standard catalogs list is determined like this:
· if the centralized catalog exists, then use it. The cen
tralized 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 fron
tend 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
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 exam
ple, the docbook frontend returns 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 fron
tend. 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
[ [ -s path] [ --sgmlbase path] ]
Allows to use another location for the SGML base direc
tory. 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 sev
eral 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>
Enables or disables the display of given types of warn
ings. 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.9/backends
The various backends
/usr/share/sgml/docbook/utils-0.6.9/frontends
The various frontends
/usr/share/sgml/docbook/utils-0.6.9/helpers
The various helper scripts like docbook2man or
AUTHORS
Eric Bischoff
Author of jw shell script and of a few backends
Jochem Huhmann
Author of the man and texi backends
SEE ALSO
docbook2man-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://sourceware.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.
Man(1) output converted with
man2html