Debian Codegraph @

upstream/debian-unstable/man1/linuxdoc.1

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