| 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>. |