.\" Process this file with
.\" groff -man -Tascii linuxdoc.1
.\"
.TH LINUXDOC 1 "27 Jul 2000"
.SH NAME
linuxdoc \- LinuxDoc DTD SGML converter to other output format
.SH SYNOPSIS
.B linuxdoc
.I \fB\--backend=\fP\fIformat\fP
.br
.I \fB\--papersize=\fP\fIsize\fP
.I \fB\--language=\fP\fIlang\fP
.I \fB\--charset=\fP\fIchar\fP
.I \fB\--style=\fP\fIfile\fP
.I \fB\--debug\fP
.I \fB\--define\fP\ \fIattribute=value\fP
.I \fB\--include\fP\ \fIentity\fP
.B "[backend-options...]"
.I file(.sgml)\fP
.PP
or (Old, obsoleted usage)
.br
.B sgmlxxxx [generic-options...] [backend-options...] \ \ \fIfile(.sgml)\fP
.SH DESCRIPTION
The 
.B linuxdoc
suite is a collection of text formatters which understands a LinuxDoc DTD
SGML source file. Each formatter (or "back-end") renders the source file
into a variety of output formats, including HTML, TeX, DVI, PostScript, 
plain text, and
.BR groff (1)
source in manual-page format. The linuxdoc suite is provided for backward
compatibility, because there are still many useful documents written in
LinuxDoc DTD sgml source.
.LP
The markup language(s) accepted by these formatters is described in the
.IR Linuxdoc-Tools " User's " Guide .
They are variants of an SGML document type definition originally
designed by Matt Welsh for Linux documentation.
.SH GENERIC-OPTIONS
Most command-line options are accepted by all back-ends.  Some
back-ends have additional specific options to control rendering to
their particular output format.  Here are the common options:
.IP "--backend=\fIformat\fR, -B
Set the backend for specified format. Default is none of the actual
format, but just output the usage of this suites.
Available formats are: html, info, latex, lyx, rtf, txt, check.
.IP "--papersize=\fIsize\fR, -p
Set the paper size.  Default is ``letter''.
You may also specify ``a4'' size (European 297x210mm paper).
.IP "--language=\fIlang\fR, -l"
Specify the language of the document (this may change which style
files are used for formatting by a back end).  The default language is
English. Run an LinuxDoc-tools command without arguments to see the list
of valid language codes.
.IP "--charset=\fIchars\fR, -c"
Specify the output character encoding.  Defaults to ``ascii''
selecting the ASCII set; you may specify "latin" to specify the
ISO 8859-1 (Latin-1) character set.
Also, ``nippon'' and ``euc-kr'' is required to handle the euc-jp and 
euc-kr encoded sgml file.
.IP "--style=\fIfile\fR, -S"
Include an auxiliary DTD (Document Type Definition) from $LINUXDOCLIB/dtd.
.IP "--tabsize=\fIn\fR, -t"
Set the tab spacing assumed for generating the output document.  The
default tab spacing is 8.
.IP "--debug, -d"
Don't delete intermediate files (such as .TeX files generated on the
way to a .dvi, or .man files deleted on the way to plain text).
.IP "--define, -D"
Pass attribute/value pairs to be matched against "if" and "unless"
conditionals.  See the User's Guide for extended discussion of this 
feature.
This conditionalization are handled by sgmlpre command.
See sgmlpre(1) as well as the User's Guide.
.IP "--include, -i"
Pass a \-i option to 
.BR nsgmls (1).
This may be used for conditional inclusion.  See the
.BR nsgmls (1)
manual page for details.
.IP "--pass, -P"
Pass an option string to the back end.  The exact semantics of this
option are dependent on the back end and should be explained in the
individual manual pages for each.
.IP file
The SGML source file, named either 
.I file
or 
.IR file.sgml .
.LP
Running a back-end with no arguments will cause it to list all its
options (Error message about "no filenames given" can be ignored
safely in this case).  The available back ends include (names in 
brackets are old & obsoleted form):
.IP linuxdoc\ \-B\ html\ (sgml2html)
translate to HTML
.IP linuxdoc\ \-B\ info\ (sgml2info)
translate to GNU info
.IP linuxdoc\ \-B\ lyx\ (sgml2lyx)
translate to Lyx macros
.IP linuxdoc\ \-B\ latex\ (sgml2latex)
translate to LaTeX 2e
.IP linuxdoc\ \-B\ rtf\ (sgml2rtf)
translate to Microsoft Rich Text Format
.IP linuxdoc\ \-B\ txt\ (sgml2txt)
translate to plain text or Unix manual-page markup
.LP
There is also a tool 
.BR linuxdoc -B check
 (sgmlcheck)
available for checking the Linuxdoc DTD SGML syntax of document sources
without actually generating a translated version.
.SH BACKEND-DRIVERS
Here are the description for each backend drivers:
.LP
 ****************************************************
.LP
.B linuxdoc -B html \fP (sgml2html)
converts a LinuxDoc DTD SGML source file to HTML output.
Output will appear in the top level file
.I file.html
and 
.I file-n.html
for each section (default action, but can be changed by option), 
where 
.I file
is the name of the SGML source file and 
.I n
is the section name.
.LP
The attribute/value pair "output=html" is set for conditionals.
.LP
.B linuxdoc -B html
accepts the following options:
.B [--split 
.I 0|1|2
.B ] [--dosnames] [--imagebuttons] 
.B [--toc
.I 0|1|2
.B ]
.LP
The meanings of them are:
.IP "--split, -s"
What level to split source documents.  0 = don't split, 1 = split by
major sections, 2 = split by subsections.
.IP "--toc, -T"
What level to generate toc.
  0 = don't generate toc at all,
  1 = includes major sections(/chapters/parts),
  2 = includes subsections.
.IP "--dosnames, -h"
Use ".htm" rather than ".html" as the extension of 
.IP "--imagebuttons, -I"
Use the "next", "previous", and "contents" arrow image icons included
in $LINUXDOCLIB as navigation buttons.  
.IP "--footer, -F"
Use the specified file as the footer in each resulted html file.
Default footer is just plain

.nh
.nf
.ad l
 </BODY>\\n </HTML>\\n
.hy
.fi
.IP "--header, -H"
Use the specified file as the top part of the header in each resulted
html file. Note this is not the full part of the header.
(i.e. the title and the links (next,previous,contents) in the default
header are retained. Default is 

.nh
.nf
.ad l
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">\\n
 <HTML>\\n <HEAD>\\n
.hy
.fi
.LP
 ****************************************************
.LP
.B linuxdoc -B info \fP (sgml2info)
converts a LinuxDoc DTD SGML source file to GNU info format.
Output will appear in
.I file.info
where 
.I file
is the name of the SGML source file.
.LP
The attribute/value pair "output=info" is set for conditionals.
.LP
.B linuxdoc -B info
has not backend specific options.
.LP
 ****************************************************
.LP
.B linuxdoc -B latex \fP (sgml2latex)
converts a LinuxDoc DTD SGML source file to LaTeX output, using the
.BR nsgmls (1)
or 
.BR onsgmls (1)
parser, and the
.BR sgmlsasp (1)
translator.  Using the LaTeX output, and the
.BR latex (1)
text formatter, you can then create DVI output, and PostScript output
using the 
.BR dvips (1)
converter. Output will appear in
.I file.tex
for LaTeX output, 
.I file.dvi
for DVI output, or
.I file.ps
for PostScript output,
where 
.I file
is the name of the SGML source file.
.LP
Using  the LaTeX output, and the
.BR pdflatex (1)
text formatter, you can then create a nice PDF output, suitable for
viewing with PDF viewers as
.BR xpdf (1),
.BR acroread (1)
or
.BR ghostview (1).
.LP
The attribute/value pair "output=latex2e" is set for conditionals.
.LP
.B linuxdoc -B latex
accepts following backend specific options:
.BI [--output= tex | dvi | ps | pdf]
.B [--bibtex] [--makeindex] 
.BI [--pagenumber= n ]
.B --quick
.BI [--latex= latex | hlatexp | platex | jlatex]
.BI [--dvips= dvips | dvi2ps]
.LP
The meanings of them are:
.IP "--output=\fIfmt\fR, -o"
Specify the desired output format.  The specifier 
.I fmt
may be ``tex'', ``dvi'', ``ps'', or ``pdf''. 
.PP
Note: This version does not overwrite/remove the intermediate
files: tex file for dvi output, or tex/dvi files for ps output.
This is different behavior from the original SGML-Tools 1.0.9, 
so you are warned here.
.IP "--bibtex, -b"
Process the generated TeX with 
.BR bibtex (1).
.IP "--makeindex, -m"
Generate a TeX index file suitable for processing with 
.BR makeindex (1)
from and <idx> and <cdx> tags present in the SGML source.
.IP "--pagenumber, -n"
Set the starting page number in the output DVI or PS file.
.IP "--quick, -q"
Do only one pass of LaTeX formatting.  This is often not sufficient 
to produce final output (because of references, etc.) but is useful
for spotting TeX errors and justification problems.
.IP "--pass, -P"
The argument of the pass option is inserted just after the LaTeX 
preamble generated by the document-type tag.
Specify the desired output format.  The specifier 
.I fmt
may be ``tex'', ``dvi'', ``ps'', or ``pdf''. 
.IP "--latex=\fIalternate_latex_command\fR, -x"
This option is currently for Korean and Japanese.
The
.I alternate_latex_command
can be ``latex'' (default), ``hlatexp'' (for Korean), ``platex''
or ``jlatex'' (for Japanese). 
This option can be used to render Korean document using HLaTeXp,
or to render Japanese document using pLaTeX/jLaTeX.
If not, HLaTeX should be installed to render Korean document.
On the other hand, Japanese document can be rendered with jLaTeX
 (which is the default when ``\-c nippon'' is specified), so if you 
already have jLaTeX, you may not need to install the pLaTeX.
.IP "--dvips=\fIalternate_dvips_command\fR, -s"
This option is currently for Japanese.
The
.I alternate_dvips_command
can be ``dvips'' or ``dvi2ps''.  If you don't know this, then
you may not need this.
.LP
 ****************************************************
.LP
.B linuxdoc -B lyx \fP (sgml2lyx)
converts a LinuxDoc DTD SGML source file to LyX output.
Output will appear in
.I file.lyx
where 
.I file
is the name of the SGML source file.
.LP
The attribute/value pair "output=lyx" is set for conditionals.
.LP
.B linuxdoc -B lyx
has not backend specific options.
.LP
 ****************************************************
.LP
.B linuxdoc -B rtf \fP (sgml2rtf)
converts a LinuxDoc DTD SGML source file to RTF, the Rich Text Tormat 
used by the Microsoft Windows help system. Output will appear in the top 
level file
.I file.rtf
and 
.I file-n.rtf
for each section, where 
.I file
is the name of the SGML source file.  The RTF output is tailored for 
compilation by the Windows Help Compiler (hc31.exe).
.LP
The attribute/value pair "output=rtf" is set for conditionals.
.LP
.B linuxdoc -B rtf
accepts
.B [--twosplit]
as a backend specific option.
Following is the meaning of this option:
.IP "--twosplit, -2"
Splits files both at n. sections and n.m. subsections
.LP
 ****************************************************
.LP
.B linuxdoc -B txt \fP (sgml2txt)
converts a LinuxDoc DTD SGML source file to ASCII, ISO-8859-1, or EUC-JP
output. Output will appear in
.I file.txt
where 
.I file
is the name of the SGML source file.
.LP
The attribute/value pair "output=txt" is set for conditionals.
.LP
.B linuxdoc -B txt
accepts following backend-options:
.B [--manpage] [--filter] [--blanks=\fIn\fB]
.LP
The meaning of these options are:
.IP "--manpage, -m"
Outputs a groff source file, suitable for formatting with 
.B groff -man
for man pages
.IP "--filter, -f"
Remove backspace-overstrikes from the intermediate form generated by
\fBgroff\fR(1).
.IP "--pass, -P"
The argument of the pass option is added to the command-line options
handed to 
.BR groff (1).
.IP "--blanks=\fIn\fR, -b"
Set the limit of continuous blank lines for generating the output 
document.  The default limit is 3. if 0 (zero) is specified,
the result have many continuous blank lines.
.LP
 ****************************************************
.LP
.B linuxdoc -B check \fP (sgmlcheck)
runs an SGML parse on the specified document source.  Any errors are
reported to standard output.  No formatted version of the source is
produced.
.LP
Note that 
.B linuxdoc -B check
preprocesses the LinuxDoc DTD SGML source, doing the conditionalization
described by any <#if></#if> and <#unless></#unless> tags.
Document sources containing these tags will confuse a standalone SGML parser.
.B linuxdoc -B check
has no backend-specific options.
 ****************************************************
.SH FILES
Many files and executables in $LINUXDOCLIB and $LINUXDOCBIN are used. 
.SH BUGS
Maybe some are left.  Feel free to send your report to the current maintainer.
.SH MAINTAINER
This had been maintained by Cees de Groot <cg@cdegroot.com> in SGML-Tools (v1).
Currently maintained by Taketoshi Sano <sano@debian.org> for Linuxdoc-Tools.