doc/man/jw.1

   1 .\" This manpage has been automatically generated by docbook2man
   2 .\" from a DocBook document.  This tool can be found at:
   3 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
   4 .\" Please send any bug reports, improvements, comments, patches,
   5 .\" etc. to Steve Cheng <steve@ggi-project.org>.
   6 .TH "JW" "1" "11 February 2004" "" ""
   7
   8 .SH NAME
   9 jw, docbook2dvi, docbook2html, docbook2man, docbook2pdf, docbook2ps, docbook2rtf, docbook2tex, docbook2texi, docbook2txt \- (Jade Wrapper) converts SGML files to other formats
  10 .SH SYNOPSIS
  11
  12 \fBjw\fR [ \fB-f
  13 \fIfrontend\fB\fR | \fB--frontend
  14 \fIfrontend\fB\fR ]
  15     [ \fB-b
  16 \fIbackend\fB\fR | \fB--backend \fIbackend\fB\fR ]
  17     [ \fB-c \fIfile\fB\fR | \fB--cat \fIfile\fB\fR ]
  18     [ \fB-n\fR | \fB--nostd\fR ]
  19     [ \fB-d
  20 \fIfile\fB|default|none\fR | \fB--dsl
  21 \fIfile\fB|default|none\fR ]
  22     [ \fB-l \fIfile\fB\fR | \fB--dcl \fIfile\fB\fR ]
  23     [ \fB-s \fIpath\fB\fR | \fB--sgmlbase \fIpath\fB\fR ]
  24     [ \fB-p \fIprogram\fB\fR | \fB--parser \fIprogram\fB\fR ]
  25     [ \fB-o \fIdirectory\fB\fR | \fB--output \fIdirectory\fB\fR ]
  26     [ \fB-V
  27 \fIvariable\fB[=\fIvalue\fB]\fR ]
  28     [ \fB-u\fR | \fB--nochunks\fR ] [ \fB-i \fIsection\fB\fR | \fB--include \fIsection\fB\fR ]
  29     [ \fB-w \fItype\fB|list\fR | \fB--warning \fItype\fB|list\fR ]
  30     [ \fB-e \fItype\fB|list\fR | \fB--error \fItype\fB|list\fR ]
  31     [ \fB-h\fR | \fB--help\fR ] [ \fB-v\fR | \fB--version\fR ]
  32     \fB\fISGML-file\fB\fR
  33
  34
  35 \fBdocbook2dvi\fR \fB\fISGML-file\fB\fR
  36
  37
  38 \fBdocbook2html\fR \fB\fISGML-file\fB\fR
  39
  40
  41 \fBdocbook2man\fR \fB\fISGML-file\fB\fR
  42
  43
  44 \fBdocbook2pdf\fR \fB\fISGML-file\fB\fR
  45
  46
  47 \fBdocbook2ps\fR \fB\fISGML-file\fB\fR
  48
  49
  50 \fBdocbook2rtf\fR \fB\fISGML-file\fB\fR
  51
  52
  53 \fBdocbook2tex\fR \fB\fISGML-file\fB\fR
  54
  55
  56 \fBdocbook2texi\fR \fB\fISGML-file\fB\fR
  57
  58
  59 \fBdocbook2txt\fR \fB\fISGML-file\fB\fR
  60
  61 .SH "DESCRIPTION"
  62 .PP
  63 The \fBjw\fR shell script allows to
  64 convert a DocBook file (or some other SGML-based format) to
  65 other formats (including HTML, RTF, PS and PDF) with
  66 an easy-to-understand syntax. It hides most of Jade's
  67 or OpenJade complexity and adds comfortable features.
  68 .PP
  69 Other scripts like \fBdocbook2html\fR,
  70 \fBdocbook2rtf\fR or
  71 \fBdocbook2ps\fR provide different ways of
  72 calling \fBjw\fR that might be easier to
  73 remember.
  74 .PP
  75 For the moment, jw does not handle XML, but only SGML.
  76 .PP
  77 This utility assumes that several other components are
  78 installed. The list includes:
  79 .TP 0.2i
  80 \(bu
  81 the ISO character entities for SGML
  82 .TP 0.2i
  83 \(bu
  84 James Clark's DSSSL engine, jade, or an equivalent parser
  85 like OpenJade
  86 .TP 0.2i
  87 \(bu
  88 the DocBook DTD from the OASIS consortium
  89 .TP 0.2i
  90 \(bu
  91 Norman Walsh's DocBook modular style sheets (or some other
  92 set of DSSSL style sheets)
  93 .TP 0.2i
  94 \(bu
  95 Sebastian Rahtz's jadetex set of TeX macros for jade
  96 (for backends intended to "printing" formats like PDF, RTF or
  97 PostScript)
  98 .TP 0.2i
  99 \(bu
 100 A perl interpreter (for backends that use perl)
 101 .TP 0.2i
 102 \(bu
 103 SGMLSpm from CPAN (for backends that use sgmls)
 104 .TP 0.2i
 105 \(bu
 106 Lynx HTML browser (for the \fItxt\fR
 107 backend)
 108 .PP
 109 The jw script is basically called like this:
 110
 111 .nf
 112 jw mydoc.sgml
 113 .fi
 114 .PP
 115 where \fImydoc.sgml\fR is a SGML file.
 116 .PP
 117 The command line above uses default options: it converts
 118 from DocBook (the default frontend) to HTML (the default backend),
 119 does not put the result in a subdirectory (unless specified
 120 otherwise in the style sheets), etc.
 121 .PP
 122 In this example, the "mydoc" file name as well as the ".sgml"
 123 extension can be replaced by anything else. Current extensions
 124 for SGML DocBook files include ".sgml", ".sgm", ".docbook", and
 125 ".db". The processed file \fImydoc.sgml\fR can
 126 be in any other directory than the current one.
 127 .PP
 128 Here we have chosen to generate HTML output. In fact we can
 129 use any of the backends stored in the \fIbackends/\fR
 130 subdirectory of the DocBook-utils distribution directory (usually
 131 \fI/usr/share/sgml/docbook/utils-0.6.14\fR).
 132 Similarly, you can use any frontend defined in the
 133 \fIfrontends/\fR subdirectory to convert from another
 134 input format.
 135 .PP
 136 This sample command creates one or many HTML files with
 137 arbitrary file names in the current directory. This default behavior
 138 can be changed through command line options and/or customization
 139 style sheets.
 140 .SH "OPTIONS"
 141 .PP
 142 The following options apply to the conversion script:
 143 .TP
 144 \fB   -f \fIfrontend\fB | --frontend \fIfrontend\fB  \fR
 145 Allows to specify another frontend than default \fIdocbook\fR\&.
 146 The list of currently available frontends is:
 147 .RS
 148 .TP
 149 \fB\fIdocbook\fB\fR
 150 Converts docbook with Norman Walsh's
 151 style sheets. This frontend searches in the
 152 subdirectories of the base SGML directory for a
 153 file named \fIhtml/docbook.dsl\fR or
 154 \fIprint/docbook.dsl\fR (depending on the
 155 backend's type: html or print).
 156 .RE
 157 .TP
 158 \fB   -b \fIbackend\fB | --backend \fIbackend\fB  \fR
 159 Allows to specify another backend than default
 160 \fIHTML\fR\&. The list of currently available
 161 backends is:
 162 .RS
 163 .TP
 164 \fB\fIdvi\fB\fR
 165 Converts to DVI (DeVice Independant
 166 files) by calling \fBJade\fR or
 167 \fBOpenJade\fR\&.
 168 .TP
 169 \fB\fIhtml\fB\fR
 170 Converts to HTML (HyperText Markup
 171 Language) by calling \fBJade\fR
 172 or \fBOpenJade\fR\&.
 173 .TP
 174 \fB\fIman\fB\fR
 175 Converts a refentry to a Unix manual page
 176 by calling docbook2man. Does not work with other SGML
 177 document types than DocBook.
 178 .TP
 179 \fB\fIpdf\fB\fR
 180 Converts to PDF (Portable Document
 181 Format) by calling \fBJade\fR or
 182 \fBOpenJade\fR\&.
 183 .TP
 184 \fB\fIps\fB\fR
 185 Converts to PostScript by
 186 calling \fBJade\fR or
 187 \fBOpenJade\fR\&.
 188 .TP
 189 \fB\fIrtf\fB\fR
 190 Converts to RTF (Rich Text Format)
 191 by calling \fBJade\fR or
 192 \fBOpenJade\fR\&. The resulting file can
 193 then be inported into \fBMS Word\fR
 194 or one of its Linux replacement programs.
 195 .TP
 196 \fB\fItex\fB\fR
 197 Converts to TeX by calling \fBJade\fR or
 198 \fBOpenJade\fR\&.
 199 .TP
 200 \fB\fItexi\fB\fR
 201 Converts to GNU TeXinfo pages by calling
 202 docbook2texi. Does not work with other SGML document types
 203 than DocBook.
 204 .TP
 205 \fB\fItxt\fB\fR
 206 Converts to a bare text file
 207 by calling \fBJade\fR
 208 or \fBOpenJade\fR, then
 209 \fBLynx\fR\&.
 210 .RE
 211 .TP
 212 \fB   -c \fIfile\fB | --cat \fIfile\fB  \fR
 213 Allows to use an extra SGML Open Catalog that will list
 214 other files like customization style sheets, adaptations to the
 215 DocBook Document Type Definition, special character entities,
 216 etc. This catalog is added to the list of catalogs determined
 217 by the script (see option \fB--nostd\fR below)
 218 .TP
 219 \fB   -n | --nostd  \fR
 220 Do not use the standard SGML Open Catalogs. Normally,
 221 the standard catalogs list is determined like this:
 222 .RS
 223 .TP 0.2i
 224 \(bu
 225 if the centralized catalog exists, then
 226 use it. The centralized catalog is a list of all
 227 catalogs that might be necessary that usually
 228 resides in \fI/etc/sgml\fR\&. Its
 229 name is provided by the frontend, for example
 230 the \fIdocbook\fR frontend returns
 231 \fI/etc/sgml/sgml-docbook.cat\fR\&.
 232 .TP 0.2i
 233 \(bu
 234 Otherwise, take all the files
 235 named \fIcatalog\fR from the
 236 subdirectories of the SGML base directory (usually
 237 \fI/usr/share/sgml\fR).
 238 .RE
 239 This option is useful in conjunction with the
 240 \fB--cat\fR option to use only the catalogs that
 241 are specified on the command line.
 242 .TP
 243 \fB   -d \fIfile\fB|default|none | --dsl \fIfile\fB|default|none  \fR
 244 Allows to use a customized style sheet instead
 245 of the default one.
 246
 247 A "target" starting with a hash mark "#" can be appended
 248 to the file name. As a result, only the corresponding part
 249 of the style sheet is executed (the "style specification" whose
 250 "identificator" is equal to the target's name). A common use of this
 251 mechanism is to define "#html" and "#print" targets to trigger
 252 the corresponding part  of a replacement style sheet which is
 253 common for both HTML and printout conversion.
 254
 255 By replacing the file name with "default", the default
 256 style sheet provided with the frontend is used. For example, the
 257 \fIdocbook\fR frontend returns
 258 \fI\&./docbook.dsl#html\fR (or
 259 \fI\&./docbook.dsl#print\fR) in the SGML base
 260 directory.
 261
 262 By replacing the file name with "none", no replacement
 263 style sheet is used, not even the default style sheet. The style
 264 sheet which is used is also determined by the frontend. For
 265 example, the \fIdocbook\fR frontend returns
 266 Norman Walsh's \fIhtml/docbook.dsl\fR (or
 267 \fIprint/docbook.dsl\fR) found somewhere below
 268 the SGML base directory.
 269
 270 If no --dsl option is specified, then "--dsl default" is
 271 used.
 272 .TP
 273 \fB   -l \fIfile\fB | --dcl \fIfile\fB  \fR
 274 Allows to use a customized SGML declaration instead
 275 of the default one. The file name of the default SGML
 276 declaration is not set for SGML files, and is set to
 277 \fIxml.dcl\fR in the SGML base directory
 278 for XML files.
 279 .TP
 280 \fB   -s \fIpath\fB | --sgmlbase \fIpath\fB  \fR
 281 Allows to use another location for the SGML base
 282 directory. This is the directory below which all SGML DTDs,
 283 style sheets, entities, etc are installed. The default value
 284 is \fI/usr/share/sgml\fR\&.
 285 .TP
 286 \fB   -p \fIprogram\fB | --parser \fIprogram\fB  \fR
 287 Specify the parser to use (\fBJade\fR
 288 or \fBOpenJade\fR) if several
 289 are installed. If this option is not specified,
 290 the script first tries to use Jade, then it tries
 291 \fBOpenJade\fR\&.
 292 .TP
 293 \fB   -o \fIdirectory\fB | --output \fIdirectory\fB  \fR
 294 Set output directory where all the resulting files will
 295 be stored. If the style sheets define a subdirectory where to
 296 store the resulting files too, the subdirectory defined by the
 297 style sheets will be placed below the subdirectory defined by
 298 this option.
 299 .TP
 300 \fB   -V \fIvariable\fB=[\fIvalue\fB]  \fR
 301 Set a variable (to a value, if one is specified).
 302 .TP
 303 \fB   -u | --nochunks  \fR
 304 Output only one big file. This option is useful only
 305 when generating HTML, because the output can be split into
 306 several files. This option overrides the setting that may be
 307 done in the style sheets.
 308 .TP
 309 \fB   -i \fIsection\fB | --include \fIsection\fB  \fR
 310 Declare a SGML marked section as "include". A SGML marked
 311 section is a kind of conditional part of a document. If it is
 312 declared "ignore", it will be left ignored, otherwise it will
 313 be processed. An example of such a marked section would be:
 314 .PP
 315 .PP
 316
 317 .nf
 318             <DOCTYPE mydoc [
 319               <!ENTITY % confidential "ignore">
 320             ]>
 321             <mydoc>
 322               ...
 323               <![ %confidential [ Some confidential text... ]]>
 324               ...
 325             </mydoc>
 326
 327 .fi
 328 .TP
 329 \fB   -w \fItype\fB|list | --warning \fItype\fB|list  \fR
 330 Enables or disables the display of given types of warnings.
 331 Several -w options might be entered on the command line.
 332 Warning types that start with "no-" disable the corresponding
 333 warnings, the other types enable them.
 334
 335 If the warning type is replaced with "list", then
 336 a list of allowed warning types is displayed.
 337 .TP
 338 \fB   -e \fItype\fB|list | --error \fItype\fB|list  \fR
 339 Disables given types of errors.
 340 Several -e options might be entered on the command line.
 341 All error types start with "no-".
 342
 343 If the error type is replaced with "list", then
 344 a list of allowed error types is displayed.
 345 .TP
 346 \fB   -h | --help  \fR
 347 Print a short help message and exit
 348 .TP
 349 \fB   -v | --version  \fR
 350 Print the version identifier and exit
 351 .SH "FILES"
 352 .TP
 353 \fB\fI/etc/sgml/sgml-docbook.cat\fB\fR
 354 Centralized SGML open catalog. This file name might
 355 vary if another frontend than \fIdocbook\fR
 356 is used.
 357 .TP
 358 \fB\fI/usr/share/sgml/docbook/utils-0.6.14/backends\fB\fR
 359 The various backends
 360 .TP
 361 \fB\fI/usr/share/sgml/docbook/utils-0.6.14/frontends\fB\fR
 362 The various frontends
 363 .TP
 364 \fB\fI/usr/share/sgml/docbook/utils-0.6.14/helpers\fB\fR
 365 The various helper scripts like docbook2man or docbook2texi
 366 .SH "AUTHORS"
 367 .PP
 368 Eric Bischoff (jw shell script and a few backends),
 369 Jochem Huhmann (the \fIman\fR and
 370 \fItexi\fR backends)
 371 .SH "SEE ALSO"
 372 .PP
 373 \fBdocbook2man-spec.pl\fR(1),
 374 \fBdocbook2texi-spec.pl\fR(1),
 375 \fBinstall-catalog\fR(8),
 376 \fBnsgmls\fR(1), docbook-utils
 377 homepage <URL:http://sources.redhat.com/docbook-tools/>\&.