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