1JW(1)                                                                    JW(1)
2
3
4

NAME

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

SYNOPSIS

11       jw [ -f frontend | --frontend frontend ]
12           [ -b backend | --backend backend ]
13           [ -c file | --cat file ]
14           [ -n | --nostd ]
15           [ -d file|default|none | --dsl file|default|none ]
16           [ -l file | --dcl file ]
17           [ -s path | --sgmlbase path ]
18           [ -p program | --parser program ]
19           [ -o directory | --output directory ]
20           [ -V variable[=value] ]
21           [ -u | --nochunks ] [ -i section | --include section ]
22           [ -w type|list | --warning type|list ]
23           [ -e type|list | --error type|list ]
24           [ -h | --help ] [ -v | --version ]
25           SGML-file
26
27
28       docbook2dvi SGML-file
29
30
31       docbook2html SGML-file
32
33
34       docbook2man SGML-file
35
36
37       docbook2pdf SGML-file
38
39
40       docbook2ps SGML-file
41
42
43       docbook2rtf SGML-file
44
45
46       docbook2tex SGML-file
47
48
49       docbook2texi SGML-file
50
51
52       docbook2txt SGML-file
53
54

DESCRIPTION

56       The  jw  shell  script  allows to convert a DocBook file (or some other
57       SGML-based format) to other formats (including HTML, RTF, PS  and  PDF)
58       with  an easy-to-understand syntax. It hides most of Jade's or OpenJade
59       complexity and adds comfortable features.
60
61       Other scripts like docbook2html, docbook2rtf or docbook2ps provide dif‐
62       ferent ways of calling jw that might be easier to remember.
63
64       For the moment, jw does not handle XML, but only SGML.
65
66       This  utility  assumes that several other components are installed. The
67       list includes:
68
69       · the ISO character entities for SGML
70
71       · James Clark's DSSSL engine, jade, or an equivalent parser like  Open‐
72         Jade
73
74       · the DocBook DTD from the OASIS consortium
75
76       · Norman  Walsh's  DocBook  modular  style sheets (or some other set of
77         DSSSL style sheets)
78
79       · Sebastian Rahtz's jadetex set of TeX macros for  jade  (for  backends
80         intended to "printing" formats like PDF, RTF or PostScript)
81
82       · A perl interpreter (for backends that use perl)
83
84       · SGMLSpm from CPAN (for backends that use sgmls)
85
86       · Lynx HTML browser (for the txt backend)
87
88       The jw script is basically called like this:
89
90       jw mydoc.sgml
91
92       where mydoc.sgml is a SGML file.
93
94       The  command  line above uses default options: it converts from DocBook
95       (the default frontend) to HTML (the default backend), does not put  the
96       result  in  a  subdirectory  (unless  specified  otherwise in the style
97       sheets), etc.
98
99       In this example, the "mydoc" file name as well as the ".sgml" extension
100       can  be  replaced by anything else. Current extensions for SGML DocBook
101       files include ".sgml", ".sgm", ".docbook",  and  ".db".  The  processed
102       file mydoc.sgml can be in any other directory than the current one.
103
104       Here  we have chosen to generate HTML output. In fact we can use any of
105       the backends stored in the backends/ subdirectory of the  DocBook-utils
106       distribution  directory (usually /usr/share/sgml/docbook/utils-0.6.14).
107       Similarly, you can use any frontend defined in the frontends/ subdirec‐
108       tory to convert from another input format.
109
110       This  sample command creates one or many HTML files with arbitrary file
111       names in the current directory. This default behavior  can  be  changed
112       through command line options and/or customization style sheets.
113

OPTIONS

115       The following options apply to the conversion script:
116
117          -f frontend | --frontend frontend
118              Allows  to  specify  another frontend than default docbook.  The
119              list of currently available frontends is:
120
121              docbook
122                     Converts docbook with Norman Walsh's style  sheets.  This
123                     frontend  searches in the subdirectories of the base SGML
124                     directory for a file named html/docbook.dsl or print/doc‐
125                     book.dsl  (depending  on  the  backend's  type:  html  or
126                     print).
127
128          -b backend | --backend backend
129              Allows to specify another backend than default HTML. The list of
130              currently available backends is:
131
132              dvi    Converts  to  DVI  (DeVice  Independant files) by calling
133                     Jade or OpenJade.
134
135              html   Converts to HTML (HyperText Markup Language)  by  calling
136                     Jade or OpenJade.
137
138              man    Converts a refentry to a Unix manual page by calling doc‐
139                     book2man. Does not work with other  SGML  document  types
140                     than DocBook.
141
142              pdf    Converts  to  PDF  (Portable  Document Format) by calling
143                     Jade or OpenJade.
144
145              ps     Converts to PostScript by calling Jade or OpenJade.
146
147              rtf    Converts to RTF (Rich Text Format)  by  calling  Jade  or
148                     OpenJade. The resulting file can then be inported into MS
149                     Word or one of its Linux replacement programs.
150
151                     Note - The original picture must be present when RTF doc‐
152                     ument  is  viewed,  because  the RTF documents created by
153                     OpenJade includes pictures by reference.
154
155              tex    Converts to TeX by calling Jade or OpenJade.
156
157              texi   Converts to GNU TeXinfo pages  by  calling  docbook2texi.
158                     Does  not  work  with other SGML document types than Doc‐
159                     Book.
160
161              txt    Converts to a bare text file by calling Jade or OpenJade,
162                     then Lynx.
163
164          -c file | --cat file
165              Allows  to  use  an extra SGML Open Catalog that will list other
166              files like customization style sheets, adaptations to  the  Doc‐
167              Book  Document Type Definition, special character entities, etc.
168              This catalog is added to the list of catalogs determined by  the
169              script (see option --nostd below)
170
171          -n | --nostd
172              Do  not use the standard SGML Open Catalogs. Normally, the stan‐
173              dard catalogs list is determined like this:
174
175              · if the centralized catalog exists, then use it.  The  central‐
176                ized catalog is a list of all catalogs that might be necessary
177                that usually resides in /etc/sgml. Its name is provided by the
178                frontend,   for   example   the   docbook   frontend   returns
179                /etc/sgml/sgml-docbook.cat.
180
181              · Otherwise, take all the files named catalog from the subdirec‐
182                tories of the SGML base directory (usually /usr/share/sgml).
183       This  option is useful in conjunction with the --cat option to use only
184       the catalogs that are specified on the command line.
185
186          -d file|default|none | --dsl file|default|none
187              Allows to use a customized style sheet instead  of  the  default
188              one.
189
190              A  "target" starting with a hash mark "#" can be appended to the
191              file name. As a result, only the corresponding part of the style
192              sheet  is executed (the "style specification" whose "identifica‐
193              tor" is equal to the target's name). A common use of this mecha‐
194              nism  is  to  define "#html" and "#print" targets to trigger the
195              corresponding part  of a replacement style sheet which is common
196              for both HTML and printout conversion.
197
198              By  replacing  the  file  name with "default", the default style
199              sheet provided with the frontend is used. For example, the  doc‐
200              book    frontend    returns    ./docbook.dsl#html   (or   ./doc‐
201              book.dsl#print) in the SGML base directory.
202
203              By replacing the file name with  "none",  no  replacement  style
204              sheet is used, not even the default style sheet. The style sheet
205              which is used is also determined by the frontend.  For  example,
206              the docbook frontend returns Norman Walsh's html/docbook.dsl (or
207              print/docbook.dsl) found somewhere below the  SGML  base  direc‐
208              tory.
209
210              If no --dsl option is specified, then "--dsl default" is used.
211
212          -l file | --dcl file
213              Allows  to  use  a  customized  SGML  declaration instead of the
214              default one. The file name of the default  SGML  declaration  is
215              not  set  for SGML files, and is set to xml.dcl in the SGML base
216              directory for XML files.
217
218          -s path | --sgmlbase path
219              Allows to use another location for the SGML base directory. This
220              is  the directory below which all SGML DTDs, style sheets, enti‐
221              ties, etc are installed. The default value is /usr/share/sgml.
222
223          -p program | --parser program
224              Specify the parser to use (Jade  or  OpenJade)  if  several  are
225              installed.  If  this  option  is not specified, the script first
226              tries to use Jade, then it tries OpenJade.
227
228          -o directory | --output directory
229              Set output directory where  all  the  resulting  files  will  be
230              stored. If the style sheets define a subdirectory where to store
231              the resulting files too, the subdirectory defined by  the  style
232              sheets  will  be  placed  below the subdirectory defined by this
233              option.
234
235          -V variable=[value]
236              Set a variable (to a value, if one is specified).
237
238          -u | --nochunks
239              Output only one big file. This option is useful only when gener‐
240              ating  HTML, because the output can be split into several files.
241              This option overrides the setting that may be done in the  style
242              sheets.
243
244          -i section | --include section
245              Declare  a  SGML marked section as "include". A SGML marked sec‐
246              tion is a kind of conditional part  of  a  document.  If  it  is
247              declared "ignore", it will be left ignored, otherwise it will be
248              processed. An example of such a marked section would be:
249
250                   <DOCTYPE mydoc [
251                     <!ENTITY % confidential "ignore">
252                   ]>
253                   <mydoc>
254                     ...
255                     <![ %confidential [ Some confidential text... ]]>
256                     ...
257                   </mydoc>
258
259
260          -w type|list | --warning type|list
261              Enables or disables the display  of  given  types  of  warnings.
262              Several  -w options might be entered on the command line.  Warn‐
263              ing types that start with "no-" disable the corresponding  warn‐
264              ings, the other types enable them.
265
266              If  the  warning  type  is  replaced with "list", then a list of
267              allowed warning types is displayed.
268
269          -e type|list | --error type|list
270              Disables given types of errors.  Several  -e  options  might  be
271              entered on the command line.  All error types start with "no-".
272
273              If  the  error  type  is  replaced  with  "list", then a list of
274              allowed error types is displayed.
275
276          -h | --help
277              Print a short help message and exit
278
279          -v | --version
280              Print the version identifier and exit
281

FILES

283       /etc/sgml/sgml-docbook.cat
284              Centralized SGML open catalog. This  file  name  might  vary  if
285              another frontend than docbook is used.
286
287       /usr/share/sgml/docbook/utils-0.6.14/backends
288              The various backends
289
290       /usr/share/sgml/docbook/utils-0.6.14/frontends
291              The various frontends
292
293       /usr/share/sgml/docbook/utils-0.6.14/helpers
294              The various helper scripts like docbook2man or docbook2texi
295

AUTHORS

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

SEE ALSO

301       docbook2man-spec.pl(1),  docbook2texi-spec.pl(1),   install-catalog(8),
302       nsgmls(1),  docbook-utils  homepage <URL:http://sources.redhat.com/doc
303       book-tools/>.
304
305
306
307                               11 February 2004                          JW(1)
Impressum