diff options
Diffstat (limited to 'upstream/debian-bookworm/man1/linuxdoc.1')
| -rw-r--r-- | upstream/debian-bookworm/man1/linuxdoc.1 | 388 |
1 files changed, 388 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man1/linuxdoc.1 b/upstream/debian-bookworm/man1/linuxdoc.1 new file mode 100644 index 00000000..af47b664 --- /dev/null +++ b/upstream/debian-bookworm/man1/linuxdoc.1 @@ -0,0 +1,388 @@ +.\" 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 ``a4'' (European 297x210mm paper). +You may also specify ``letter'' size. +.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. +``utf-8'' is also accepted, although it is only partially supported. +.IP "--style=\fIfile\fR, -S" +Include an auxiliary DTD (Document Type Definition) from /usr/share/linuxdoc-tools/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 /usr/share/linuxdoc-tools 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] +.BI [--verbosity=n] +.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. +.IP "--verbosity, -V" +Set verbosity. '0' (default) will show info about LaTeX run only +in case of errors. '1' will always show info for last run. '2' +will show info for all runs. +.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 /usr/share/linuxdoc-tools and /usr/bin 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. |