Ubuntu Manpage: jw, docbook2dvi, docbook2html, docbook2man, docbook2pdf, docbook2ps, docbook2rtf,

Provided by: docbook-utils_0.6.14-3ubuntu1_all

NAME

       jw,   docbook2dvi,   docbook2html,   docbook2man,  docbook2pdf,  docbook2ps,  docbook2rtf,
       docbook2tex, docbook2texi, docbook2txt - (Jade  Wrapper)  converts  SGML  files  to  other
       formats

SYNOPSIS

       jw [ -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 ]
           [ -V variable[=value] ]
           [ -u | --nochunks ] [ -i section | --include section ]
           [ -w type|list | --warning type|list ]
           [ -e type|list | --error type|list ]
           [ -h | --help ] [ -v | --version ]
           SGML-file

       docbook2dvi SGML-file

       docbook2html SGML-file

       docbook2man SGML-file

       docbook2pdf SGML-file

       docbook2ps SGML-file

       docbook2rtf SGML-file

       docbook2tex SGML-file

       docbook2texi SGML-file

       docbook2txt SGML-file

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:

• the ISO character entities for SGML

• 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. 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/docbook-utils). Similarly, you can use any frontend defined in the frontends/
subdirectory 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 currently
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 docbook2man. Does not
work with other SGML document types than DocBook.

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 catalogs list is
determined like this:

• 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
/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.

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#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.

-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:

-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/docbook-utils/backends
              The various backends

       /usr/share/docbook-utils/frontends
              The various frontends

       /usr/share/perl5/sgmlspl-specs
              The various helper scripts like docbook2man or docbook2texi

AUTHORS