1LINUXDOC(1) General Commands Manual LINUXDOC(1)
2
6 linuxdoc - LinuxDoc DTD SGML converter to other output format
7
9 linuxdoc --backend=format
10 --papersize=size --language=lang --charset=char --style=file --debug
11 --define attribute=value --include entity [backend-options...]
12 file(.sgml)
13 or (Old, obsoleted usage)
15 sgmlxxxx [generic-options...] [backend-options...] file(.sgml)
16
18 The linuxdoc suite is a collection of text formatters which understands
19 a LinuxDoc DTD SGML source file. Each formatter (or "back-end") renders
20 the source file into a variety of output formats, including HTML, TeX,
21 DVI, PostScript, plain text, and groff(1) source in manual-page format.
22 The linuxdoc suite is provided for backward compatibility, because
23 there are still many useful documents written in LinuxDoc DTD sgml
24 source.
25 The markup language(s) accepted by these formatters is described in the
27 Linuxdoc-Tools User's Guide. They are variants of an SGML document
28 type definition originally designed by Matt Welsh for Linux documenta‐
29 tion.
30
32 Most command-line options are accepted by all back-ends. Some back-
33 ends have additional specific options to control rendering to their
34 particular output format. Here are the common options:
35 --backend=format, -B
37 Set the backend for specified format. Default is none of the ac‐
38 tual format, but just output the usage of this suites. Avail‐
39 able formats are: html, info, latex, lyx, rtf, txt, check.
40 --papersize=size, -p
42 Set the paper size. Default is ``letter''. You may also spec‐
43 ify ``a4'' size (European 297x210mm paper).
44 --language=lang, -l
46 Specify the language of the document (this may change which
47 style files are used for formatting by a back end). The default
48 language is English. Run an LinuxDoc-tools command without argu‐
49 ments to see the list of valid language codes.
50 --charset=chars, -c
52 Specify the output character encoding. Defaults to ``ascii''
53 selecting the ASCII set; you may specify "latin" to specify the
54 ISO 8859-1 (Latin-1) character set. Also, ``nippon'' and ``euc-
55 kr'' is required to handle the euc-jp and euc-kr encoded sgml
56 file. ``utf-8'' is also accepted, although it is only partially
57 supported.
58 --style=file, -S
60 Include an auxiliary DTD (Document Type Definition) from
61 /usr/share/linuxdoc-tools/dtd.
62 --tabsize=n, -t
64 Set the tab spacing assumed for generating the output document.
65 The default tab spacing is 8.
66 --debug, -d
68 Don't delete intermediate files (such as .TeX files generated on
69 the way to a .dvi, or .man files deleted on the way to plain
70 text).
71 --define, -D
73 Pass attribute/value pairs to be matched against "if" and "un‐
74 less" conditionals. See the User's Guide for extended discus‐
75 sion of this feature. This conditionalization are handled by
76 sgmlpre command. See sgmlpre(1) as well as the User's Guide.
77 --include, -i
79 Pass a -i option to nsgmls(1). This may be used for conditional
80 inclusion. See the nsgmls(1) manual page for details.
81 --pass, -P
83 Pass an option string to the back end. The exact semantics of
84 this option are dependent on the back end and should be ex‐
85 plained in the individual manual pages for each.
86 file The SGML source file, named either file or file.sgml.
88 Running a back-end with no arguments will cause it to list all its op‐
90 tions (Error message about "no filenames given" can be ignored safely
91 in this case). The available back ends include (names in brackets are
92 old & obsoleted form):
93 linuxdoc -B html (sgml2html)
95 translate to HTML
96 linuxdoc -B info (sgml2info)
98 translate to GNU info
99 linuxdoc -B lyx (sgml2lyx)
101 translate to Lyx macros
102 linuxdoc -B latex (sgml2latex)
104 translate to LaTeX 2e
105 linuxdoc -B rtf (sgml2rtf)
107 translate to Microsoft Rich Text Format
108 linuxdoc -B txt (sgml2txt)
110 translate to plain text or Unix manual-page markup
111 There is also a tool linuxdoc-Bcheck
113 (sgmlcheck) available for checking the Linuxdoc DTD SGML syntax of
114 document sources without actually generating a translated version.
115
117 Here are the description for each backend drivers:
118 ****************************************************
120 linuxdoc -B html (sgml2html) converts a LinuxDoc DTD SGML source file
122 to HTML output. Output will appear in the top level file file.html and
123 file-n.html for each section (default action, but can be changed by op‐
124 tion), where file is the name of the SGML source file and n is the sec‐
125 tion name.
126 The attribute/value pair "output=html" is set for conditionals.
128 linuxdoc -B html accepts the following options: [--split 0|1|2 ]
130 [--dosnames] [--imagebuttons] [--toc 0|1|2 ]
131 The meanings of them are:
133 --split, -s
135 What level to split source documents. 0 = don't split, 1 =
136 split by major sections, 2 = split by subsections.
137 --toc, -T
139 What level to generate toc.
140 0 = don't generate toc at all,
141 1 = includes major sections(/chapters/parts),
142 2 = includes subsections.
143 --dosnames, -h
145 Use ".htm" rather than ".html" as the extension of
146 --imagebuttons, -I
148 Use the "next", "previous", and "contents" arrow image icons in‐
149 cluded in /usr/share/linuxdoc-tools as navigation buttons.
150 --footer, -F
152 Use the specified file as the footer in each resulted html file.
153 Default footer is just plain
154 </BODY>\n </HTML>\n
156 --header, -H
158 Use the specified file as the top part of the header in each re‐
159 sulted html file. Note this is not the full part of the header.
160 (i.e. the title and the links (next,previous,contents) in the
161 default header are retained. Default is
162 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">\n
164 <HTML>\n <HEAD>\n
165 ****************************************************
167 linuxdoc -B info (sgml2info) converts a LinuxDoc DTD SGML source file
169 to GNU info format. Output will appear in file.info where file is the
170 name of the SGML source file.
171 The attribute/value pair "output=info" is set for conditionals.
173 linuxdoc -B info has not backend specific options.
175 ****************************************************
177 linuxdoc -B latex (sgml2latex) converts a LinuxDoc DTD SGML source
179 file to LaTeX output, using the nsgmls(1) or onsgmls(1) parser, and the
180 sgmlsasp(1) translator. Using the LaTeX output, and the latex(1) text
181 formatter, you can then create DVI output, and PostScript output using
182 the dvips(1) converter. Output will appear in file.tex for LaTeX out‐
183 put, file.dvi for DVI output, or file.ps for PostScript output, where
184 file is the name of the SGML source file.
185 Using the LaTeX output, and the pdflatex(1) text formatter, you can
187 then create a nice PDF output, suitable for viewing with PDF viewers as
188 xpdf(1), acroread(1) or ghostview(1).
189 The attribute/value pair "output=latex2e" is set for conditionals.
191 linuxdoc -B latex accepts following backend specific options: [--out‐
193 put=tex|dvi|ps|pdf] [--bibtex] [--makeindex] [--pagenumber=n] --quick
194 [--latex=latex|hlatexp|platex|jlatex] [--dvips=dvips|dvi2ps] [--ver‐
195 bosity=n]
196 The meanings of them are:
198 --output=fmt, -o
200 Specify the desired output format. The specifier fmt may be
201 ``tex'', ``dvi'', ``ps'', or ``pdf''.
202 Note: This version does not overwrite/remove the intermediate files:
204 tex file for dvi output, or tex/dvi files for ps output. This is dif‐
205 ferent behavior from the original SGML-Tools 1.0.9, so you are warned
206 here.
207 --bibtex, -b
209 Process the generated TeX with bibtex(1).
210 --makeindex, -m
212 Generate a TeX index file suitable for processing with makein‐
213 dex(1) from and <idx> and <cdx> tags present in the SGML source.
214 --pagenumber, -n
216 Set the starting page number in the output DVI or PS file.
217 --quick, -q
219 Do only one pass of LaTeX formatting. This is often not suffi‐
220 cient to produce final output (because of references, etc.) but
221 is useful for spotting TeX errors and justification problems.
222 --pass, -P
224 The argument of the pass option is inserted just after the LaTeX
225 preamble generated by the document-type tag. Specify the de‐
226 sired output format. The specifier fmt may be ``tex'', ``dvi'',
227 ``ps'', or ``pdf''.
228 --latex=alternate_latex_command, -x
230 This option is currently for Korean and Japanese. The alter‐
231 nate_latex_command can be ``latex'' (default), ``hlatexp'' (for
232 Korean), ``platex'' or ``jlatex'' (for Japanese). This option
233 can be used to render Korean document using HLaTeXp, or to ren‐
234 der Japanese document using pLaTeX/jLaTeX. If not, HLaTeX
235 should be installed to render Korean document. On the other
236 hand, Japanese document can be rendered with jLaTeX
237 (which is the default when ``-c nippon'' is specified), so if
238 you already have jLaTeX, you may not need to install the pLaTeX.
239 --dvips=alternate_dvips_command, -s
241 This option is currently for Japanese. The alternate_dvips_com‐
242 mand can be ``dvips'' or ``dvi2ps''. If you don't know this,
243 then you may not need this.
244 --verbosity, -V
246 Set verbosity. '0' (default) will show info about LaTeX run only
247 in case of errors. '1' will always show info for last run. '2'
248 will show info for all runs.
249 ****************************************************
251 linuxdoc -B lyx (sgml2lyx) converts a LinuxDoc DTD SGML source file to
253 LyX output. Output will appear in file.lyx where file is the name of
254 the SGML source file.
255 The attribute/value pair "output=lyx" is set for conditionals.
257 linuxdoc -B lyx has not backend specific options.
259 ****************************************************
261 linuxdoc -B rtf (sgml2rtf) converts a LinuxDoc DTD SGML source file to
263 RTF, the Rich Text Tormat used by the Microsoft Windows help system.
264 Output will appear in the top level file file.rtf and file-n.rtf for
265 each section, where file is the name of the SGML source file. The RTF
266 output is tailored for compilation by the Windows Help Compiler
267 (hc31.exe).
268 The attribute/value pair "output=rtf" is set for conditionals.
270 linuxdoc -B rtf accepts [--twosplit] as a backend specific option.
272 Following is the meaning of this option:
273 --twosplit, -2
275 Splits files both at n. sections and n.m. subsections
276 ****************************************************
278 linuxdoc -B txt (sgml2txt) converts a LinuxDoc DTD SGML source file to
280 ASCII, ISO-8859-1, or EUC-JP output. Output will appear in file.txt
281 where file is the name of the SGML source file.
282 The attribute/value pair "output=txt" is set for conditionals.
284 linuxdoc -B txt accepts following backend-options: [--manpage] [--fil‐
286 ter] [--blanks=n]
287 The meaning of these options are:
289 --manpage, -m
291 Outputs a groff source file, suitable for formatting with groff
292 -man for man pages
293 --filter, -f
295 Remove backspace-overstrikes from the intermediate form generat‐
296 ed by groff(1).
297 --pass, -P
299 The argument of the pass option is added to the command-line op‐
300 tions handed to groff(1).
301 --blanks=n, -b
303 Set the limit of continuous blank lines for generating the out‐
304 put document. The default limit is 3. if 0 (zero) is specified,
305 the result have many continuous blank lines.
306 ****************************************************
308 linuxdoc -B check (sgmlcheck) runs an SGML parse on the specified doc‐
310 ument source. Any errors are reported to standard output. No format‐
311 ted version of the source is produced.
312 Note that linuxdoc -B check preprocesses the LinuxDoc DTD SGML source,
314 doing the conditionalization described by any <#if></#if> and <#un‐
315 less></#unless> tags. Document sources containing these tags will con‐
316 fuse a standalone SGML parser. linuxdoc -B check has no backend-spe‐
317 cific options.
318 ****************************************************
319
321 Many files and executables in /usr/share/linuxdoc-tools and /usr/bin
322 are used.
323
325 Maybe some are left. Feel free to send your report to the current
326 maintainer.
327
329 This had been maintained by Cees de Groot <cg@cdegroot.com> in SGML-
330 Tools (v1). Currently maintained by Taketoshi Sano <sano@debian.org>
331 for Linuxdoc-Tools.
332 27 Jul 2000 LINUXDOC(1)