JW(1)

📦

version 0.6.15 · 5 versions

0.6.15 · fedora 43 (latest)
0.6.14 · centos-stream 10, centos-stream 9
0.6.15 · fedora 44
0.6.14 · ubuntu resolute, ubuntu stonking
0.6.14 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

jw(1) — the Jade Wrapper 💅✨

okay bestie, sit DOWN, because this one's a whole vibe. the manual name is jw (that's section 1, the user commands girlies), and honestly? it's giving "tiny script, massive glow-up." 💖

also answering to: docbook2dvi, docbook2html, docbook2man, docbook2pdf, docbook2ps, docbook2rtf, docbook2tex, docbook2texi, docbook2txt — and the collective noun for all of that is Jade Wrapper. it converts SGML files to other formats. no cap. 🦋

✨ 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 🌸

so the jw shell script is that girl who converts a DocBook file (or honestly any other SGML-based format) into other formats — HTML, RTF, PS, PDF, all of them — using a syntax that actually makes sense. she hides most of Jade's or OpenJade complexity and adds comfortable features on top. it's giving translator-with-benefits. 💅

her little siblings — docbook2html, docbook2rtf, docbook2ps and friends — are just different ways of calling jw, and they exist because sometimes your brain wants a command name it can actually remember. iconic behavior, honestly.

heads up bestie: for the moment, jw does not handle XML, only SGML. don't come for her about it. 😭

this utility assumes a bunch of other components are already 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. that's it. that's the whole summoning ritual. 🕯️✨

the command line above uses default options: it converts from DocBook (the default frontend) to HTML (the default backend), and it does not put the result in a subdirectory (unless the style sheets say otherwise), etc.

in this example, the "mydoc" file name as well as the ".sgml" extension can be replaced by literally anything else. current extensions for SGML DocBook files include ".sgml", ".sgm", ".docbook", and ".db". and the processed file mydoc.sgml can live in any other directory than the current one — she'll find it. 🧚

here we chose 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.15). similarly, you can use any frontend defined in the frontends/ subdirectory to convert from another input format. mix and match, bestie, it's a whole wardrobe. 🎀

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 — lets you specify another frontend than the 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 — lets you specify another backend than the 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 imported 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 — lets you 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. 🫶

-d file|default|none, --dsl file|default|none — lets you 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#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 — lets you 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 — lets you 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. bestie tries Jade first. loyalty. 💜
-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. (yes, nested. it's nesting hours. 🪆)
-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">
]>
<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.15 /backends — the various backends
/usr/share/sgml/docbook/utils-0.6.15 /frontends — the various frontends
/usr/share/sgml/docbook/utils-0.6.15 /helpers — the various helper scripts like docbook2man or docbook2texi

👑 AUTHORS 👑

Eric Bischoff (jw shell script and a few backends), Jochem Huhmann (the man and texi backends)

✨ SEE ALSO ✨

okay bestie, when you're done vibing with jw and you want the whole DocBook cinematic universe, here's the friend group 🫶

docbook2man-spec.pl(1) — the perl spec situation for man page output, lowkey the sibling energy
docbook2texi-spec.pl(1) — same vibe but it's giving Texinfo instead
install-catalog(8) — for when your catalog needs to be installed, main character admin behavior 👑
nsgmls(1) — the SGML parser doing the heavy lifting behind the scenes, fr fr
and obviously the docbook-utils homepage — <URL:http://sources.redhat.com/docbook-tools/> — go read it, iykyk 💖

and that's the whole page, no cap 🎀 this was the JW(1) manual, straight from the 23 July 2025 drop ✨ go forth and slay your documentation, bestie 💅🌸

📦 where this page comes from

fedora 43: docbook-utils 0.6.15-3.fc43 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms