Debian Codegraph @

upstream/fedora-44/man1/linuxdoc.1

raw
1 .\" Process this file with
2 .\" groff -man -Tascii linuxdoc.1
3 .\"
4 .TH LINUXDOC 1 "27 Jul 2000"
5 .SH NAME
6 linuxdoc \- LinuxDoc DTD SGML converter to other output format
7 .SH SYNOPSIS
8 .B linuxdoc
9 .I \fB\--backend=\fP\fIformat\fP
10 .br
11 .I \fB\--papersize=\fP\fIsize\fP
12 .I \fB\--language=\fP\fIlang\fP
13 .I \fB\--charset=\fP\fIchar\fP
14 .I \fB\--style=\fP\fIfile\fP
15 .I \fB\--debug\fP
16 .I \fB\--define\fP\ \fIattribute=value\fP
17 .I \fB\--include\fP\ \fIentity\fP
18 .B "[backend-options...]"
19 .I file(.sgml)\fP
20 .PP
21 or (Old, obsoleted usage)
22 .br
23 .B sgmlxxxx [generic-options...] [backend-options...] \ \ \fIfile(.sgml)\fP
24 .SH DESCRIPTION
25 The
26 .B linuxdoc
27 suite is a collection of text formatters which understands a LinuxDoc DTD
28 SGML source file. Each formatter (or "back-end") renders the source file
29 into a variety of output formats, including HTML, TeX, DVI, PostScript,
30 plain text, and
31 .BR groff (1)
32 source in manual-page format. The linuxdoc suite is provided for backward
33 compatibility, because there are still many useful documents written in
34 LinuxDoc DTD sgml source.
35 .LP
36 The markup language(s) accepted by these formatters is described in the
37 .IR Linuxdoc-Tools " User's " Guide .
38 They are variants of an SGML document type definition originally
39 designed by Matt Welsh for Linux documentation.
40 .SH GENERIC-OPTIONS
41 Most command-line options are accepted by all back-ends. Some
42 back-ends have additional specific options to control rendering to
43 their particular output format. Here are the common options:
44 .IP "--backend=\fIformat\fR, -B
45 Set the backend for specified format. Default is none of the actual
46 format, but just output the usage of this suites.
47 Available formats are: html, info, latex, lyx, rtf, txt, check.
48 .IP "--papersize=\fIsize\fR, -p
49 Set the paper size. Default is ``letter''.
50 You may also specify ``a4'' size (European 297x210mm paper).
51 .IP "--language=\fIlang\fR, -l"
52 Specify the language of the document (this may change which style
53 files are used for formatting by a back end). The default language is
54 English. Run an LinuxDoc-tools command without arguments to see the list
55 of valid language codes.
56 .IP "--charset=\fIchars\fR, -c"
57 Specify the output character encoding. Defaults to ``ascii''
58 selecting the ASCII set; you may specify "latin" to specify the
59 ISO 8859-1 (Latin-1) character set.
60 Also, ``nippon'' and ``euc-kr'' is required to handle the euc-jp and
61 euc-kr encoded sgml file.
62 ``utf-8'' is also accepted, although it is only partially supported.
63 .IP "--style=\fIfile\fR, -S"
64 Include an auxiliary DTD (Document Type Definition) from /usr/share/linuxdoc-tools/dtd.
65 .IP "--tabsize=\fIn\fR, -t"
66 Set the tab spacing assumed for generating the output document. The
67 default tab spacing is 8.
68 .IP "--debug, -d"
69 Don't delete intermediate files (such as .TeX files generated on the
70 way to a .dvi, or .man files deleted on the way to plain text).
71 .IP "--define, -D"
72 Pass attribute/value pairs to be matched against "if" and "unless"
73 conditionals. See the User's Guide for extended discussion of this
74 feature.
75 This conditionalization are handled by sgmlpre command.
76 See sgmlpre(1) as well as the User's Guide.
77 .IP "--include, -i"
78 Pass a \-i option to
79 .BR nsgmls (1).
80 This may be used for conditional inclusion. See the
81 .BR nsgmls (1)
82 manual page for details.
83 .IP "--pass, -P"
84 Pass an option string to the back end. The exact semantics of this
85 option are dependent on the back end and should be explained in the
86 individual manual pages for each.
87 .IP file
88 The SGML source file, named either
89 .I file
90 or
91 .IR file.sgml .
92 .LP
93 Running a back-end with no arguments will cause it to list all its
94 options (Error message about "no filenames given" can be ignored
95 safely in this case). The available back ends include (names in
96 brackets are old & obsoleted form):
97 .IP linuxdoc\ \-B\ html\ (sgml2html)
98 translate to HTML
99 .IP linuxdoc\ \-B\ info\ (sgml2info)
100 translate to GNU info
101 .IP linuxdoc\ \-B\ lyx\ (sgml2lyx)
102 translate to Lyx macros
103 .IP linuxdoc\ \-B\ latex\ (sgml2latex)
104 translate to LaTeX 2e
105 .IP linuxdoc\ \-B\ rtf\ (sgml2rtf)
106 translate to Microsoft Rich Text Format
107 .IP linuxdoc\ \-B\ txt\ (sgml2txt)
108 translate to plain text or Unix manual-page markup
109 .LP
110 There is also a tool
111 .BR linuxdoc -B check
112 (sgmlcheck)
113 available for checking the Linuxdoc DTD SGML syntax of document sources
114 without actually generating a translated version.
115 .SH BACKEND-DRIVERS
116 Here are the description for each backend drivers:
117 .LP
118 ****************************************************
119 .LP
120 .B linuxdoc -B html \fP (sgml2html)
121 converts a LinuxDoc DTD SGML source file to HTML output.
122 Output will appear in the top level file
123 .I file.html
124 and
125 .I file-n.html
126 for each section (default action, but can be changed by option),
127 where
128 .I file
129 is the name of the SGML source file and
130 .I n
131 is the section name.
132 .LP
133 The attribute/value pair "output=html" is set for conditionals.
134 .LP
135 .B linuxdoc -B html
136 accepts the following options:
137 .B [--split
138 .I 0|1|2
139 .B ] [--dosnames] [--imagebuttons]
140 .B [--toc
141 .I 0|1|2
142 .B ]
143 .LP
144 The meanings of them are:
145 .IP "--split, -s"
146 What level to split source documents. 0 = don't split, 1 = split by
147 major sections, 2 = split by subsections.
148 .IP "--toc, -T"
149 What level to generate toc.
150 0 = don't generate toc at all,
151 1 = includes major sections(/chapters/parts),
152 2 = includes subsections.
153 .IP "--dosnames, -h"
154 Use ".htm" rather than ".html" as the extension of html files.
155 .IP "--imagebuttons, -I"
156 Use the "next", "previous", and "contents" arrow image icons included
157 in /usr/share/linuxdoc-tools as navigation buttons.
158 .IP "--footer, -F"
159 Use the specified file as the footer in each resulted html file.
160 Default footer is just plain
161
162 .nh
163 .nf
164 .ad l
165 </BODY>\\n </HTML>\\n
166 .hy
167 .fi
168 .IP "--header, -H"
169 Use the specified file as the top part of the header in each resulted
170 html file. Note this is not the full part of the header.
171 (i.e. the title and the links (next,previous,contents) in the default
172 header are retained. Default is
173
174 .nh
175 .nf
176 .ad l
177 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">\\n
178 <HTML>\\n <HEAD>\\n
179 .hy
180 .fi
181 .IP "--rtldirection, -r"
182 Set right-to-left direction in html file.
183 .LP
184 ****************************************************
185 .LP
186 .B linuxdoc -B info \fP (sgml2info)
187 converts a LinuxDoc DTD SGML source file to GNU info format.
188 Output will appear in
189 .I file.info
190 where
191 .I file
192 is the name of the SGML source file.
193 .LP
194 The attribute/value pair "output=info" is set for conditionals.
195 .LP
196 .B linuxdoc -B info
197 has not backend specific options.
198 .LP
199 ****************************************************
200 .LP
201 .B linuxdoc -B latex \fP (sgml2latex)
202 converts a LinuxDoc DTD SGML source file to LaTeX output, using the
203 .BR nsgmls (1)
204 or
205 .BR onsgmls (1)
206 parser, and the
207 .BR sgmlsasp (1)
208 translator. Using the LaTeX output, and the
209 .BR latex (1)
210 text formatter, you can then create DVI output, and PostScript output
211 using the
212 .BR dvips (1)
213 converter. Output will appear in
214 .I file.tex
215 for LaTeX output,
216 .I file.dvi
217 for DVI output, or
218 .I file.ps
219 for PostScript output,
220 where
221 .I file
222 is the name of the SGML source file.
223 .LP
224 Using the LaTeX output, and the
225 .BR pdflatex (1)
226 text formatter, you can then create a nice PDF output, suitable for
227 viewing with PDF viewers as
228 .BR xpdf (1),
229 .BR acroread (1)
230 or
231 .BR ghostview (1).
232 .LP
233 The attribute/value pair "output=latex2e" is set for conditionals.
234 .LP
235 .B linuxdoc -B latex
236 accepts following backend specific options:
237 .BI [--output= tex | dvi | ps | pdf]
238 .B [--bibtex] [--makeindex]
239 .BI [--pagenumber= n ]
240 .B --quick
241 .BI [--latex= latex | hlatexp | platex | jlatex]
242 .BI [--dvips= dvips | dvi2ps]
243 .BI [--verbosity=n]
244 .LP
245 The meanings of them are:
246 .IP "--output=\fIfmt\fR, -o"
247 Specify the desired output format. The specifier
248 .I fmt
249 may be ``tex'', ``dvi'', ``ps'', or ``pdf''.
250 .PP
251 Note: This version does not overwrite/remove the intermediate
252 files: tex file for dvi output, or tex/dvi files for ps output.
253 This is different behavior from the original SGML-Tools 1.0.9,
254 so you are warned here.
255 .IP "--bibtex, -b"
256 Process the generated TeX with
257 .BR bibtex (1).
258 .IP "--makeindex, -m"
259 Generate a TeX index file suitable for processing with
260 .BR makeindex (1)
261 from and <idx> and <cdx> tags present in the SGML source.
262 .IP "--pagenumber, -n"
263 Set the starting page number in the output DVI or PS file.
264 .IP "--quick, -q"
265 Do only one pass of LaTeX formatting. This is often not sufficient
266 to produce final output (because of references, etc.) but is useful
267 for spotting TeX errors and justification problems.
268 .IP "--pass, -P"
269 The argument of the pass option is inserted just after the LaTeX
270 preamble generated by the document-type tag.
271 Specify the desired output format. The specifier
272 .I fmt
273 may be ``tex'', ``dvi'', ``ps'', or ``pdf''.
274 .IP "--latex=\fIalternate_latex_command\fR, -x"
275 This option is currently for Korean and Japanese.
276 The
277 .I alternate_latex_command
278 can be ``latex'' (default), ``hlatexp'' (for Korean), ``platex''
279 or ``jlatex'' (for Japanese).
280 This option can be used to render Korean document using HLaTeXp,
281 or to render Japanese document using pLaTeX/jLaTeX.
282 If not, HLaTeX should be installed to render Korean document.
283 On the other hand, Japanese document can be rendered with jLaTeX
284 (which is the default when ``\-c nippon'' is specified), so if you
285 already have jLaTeX, you may not need to install the pLaTeX.
286 .IP "--dvips=\fIalternate_dvips_command\fR, -s"
287 This option is currently for Japanese.
288 The
289 .I alternate_dvips_command
290 can be ``dvips'' or ``dvi2ps''. If you don't know this, then
291 you may not need this.
292 .IP "--verbosity, -V"
293 Set verbosity. '0' (default) will show info about LaTeX run only
294 in case of errors. '1' will always show info for last run. '2'
295 will show info for all runs.
296 .LP
297 ****************************************************
298 .LP
299 .B linuxdoc -B lyx \fP (sgml2lyx)
300 converts a LinuxDoc DTD SGML source file to LyX output.
301 Output will appear in
302 .I file.lyx
303 where
304 .I file
305 is the name of the SGML source file.
306 .LP
307 The attribute/value pair "output=lyx" is set for conditionals.
308 .LP
309 .B linuxdoc -B lyx
310 has not backend specific options.
311 .LP
312 ****************************************************
313 .LP
314 .B linuxdoc -B rtf \fP (sgml2rtf)
315 converts a LinuxDoc DTD SGML source file to RTF, the Rich Text Tormat
316 used by the Microsoft Windows help system. Output will appear in the top
317 level file
318 .I file.rtf
319 and
320 .I file-n.rtf
321 for each section, where
322 .I file
323 is the name of the SGML source file. The RTF output is tailored for
324 compilation by the Windows Help Compiler (hc31.exe).
325 .LP
326 The attribute/value pair "output=rtf" is set for conditionals.
327 .LP
328 .B linuxdoc -B rtf
329 accepts
330 .B [--twosplit]
331 as a backend specific option.
332 Following is the meaning of this option:
333 .IP "--twosplit, -2"
334 Splits files both at n. sections and n.m. subsections
335 .LP
336 ****************************************************
337 .LP
338 .B linuxdoc -B txt \fP (sgml2txt)
339 converts a LinuxDoc DTD SGML source file to ASCII, ISO-8859-1, or EUC-JP
340 output. Output will appear in
341 .I file.txt
342 where
343 .I file
344 is the name of the SGML source file.
345 .LP
346 The attribute/value pair "output=txt" is set for conditionals.
347 .LP
348 .B linuxdoc -B txt
349 accepts following backend-options:
350 .B [--manpage] [--filter] [--blanks=\fIn\fB]
351 .LP
352 The meaning of these options are:
353 .IP "--manpage, -m"
354 Outputs a groff source file, suitable for formatting with
355 .B groff -man
356 for man pages
357 .IP "--filter, -f"
358 Remove backspace-overstrikes from the intermediate form generated by
359 \fBgroff\fR(1).
360 .IP "--pass, -P"
361 The argument of the pass option is added to the command-line options
362 handed to
363 .BR groff (1).
364 .IP "--blanks=\fIn\fR, -b"
365 Set the limit of continuous blank lines for generating the output
366 document. The default limit is 3. if 0 (zero) is specified,
367 the result have many continuous blank lines.
368 .LP
369 ****************************************************
370 .LP
371 .B linuxdoc -B check \fP (sgmlcheck)
372 runs an SGML parse on the specified document source. Any errors are
373 reported to standard output. No formatted version of the source is
374 produced.
375 .LP
376 Note that
377 .B linuxdoc -B check
378 preprocesses the LinuxDoc DTD SGML source, doing the conditionalization
379 described by any <#if></#if> and <#unless></#unless> tags.
380 Document sources containing these tags will confuse a standalone SGML parser.
381 .B linuxdoc -B check
382 has no backend-specific options.
383 ****************************************************
384 .SH FILES
385 Many files and executables in /usr/share/linuxdoc-tools and /usr/bin are used.
386 .SH BUGS
387 Maybe some are left. Feel free to send your report to the current maintainer.
388 .SH MAINTAINER
389 This had been maintained by Cees de Groot <[email protected]> in SGML-Tools (v1).
390 Currently maintained by Taketoshi Sano <[email protected]> for Linuxdoc-Tools.