Provided by: debiandoc-sgml_1.2.32-2_all 
NAME
debiandoc-sgml - overview of the DebianDoc-SGML formatting tools
SYNOPSIS
debiandoc2* [-h] [-b basename] [-X custom_dir] [-s script] [-c] [-C] [-d declaration]
[-e extension] [-k] [-l locale] [-n onsgmls_options] [--] [source]
debiandoc2html [-L] [-X custom_dir] [-s script] [-m] [-t topname] [-1] [shared options]
debiandoc2text [-O] [-X custom_dir] [-s script] [-m] [shared options]
debiandoc2textov [-O] [-X custom_dir] [-s script] [-m] [shared options]
debiandoc2latex [-O] [-X custom_dir] [-s script] [shared options]
debiandoc2latexdvi [-O] [-X custom_dir] [-s script] [-p papersize] [-v] [shared options]
debiandoc2latexps [-O] [-X custom_dir] [-s script] [-p papersize] [-v] [-1] [shared
options]
debiandoc2latexpdf [-O] [-X custom_dir] [-s script] [-p papersize] [-v] [shared options]
debiandoc2dvi [-O] [-X custom_dir] [-s script] [-p papersize] [-v] [shared options]
debiandoc2ps [-O] [-X custom_dir] [-s script] [-p papersize] [-v] [-1] [shared options]
debiandoc2pdf [-O] [-X custom_dir] [-s script] [-p papersize] [-v] [shared options]
debiandoc2texinfo [-O] [-X custom_dir] [-s script] [shared options]
debiandoc2info [-X custom_dir] [-s script] [-v] [shared options]
debiandoc2dbk [-s script] [shared options]
debiandoc2wiki [-O] [-s script] [-m] [shared options]
DESCRIPTION
DebianDoc-SGML is an SGML DTD and a set of formatting tools. These tools convert source,
an SGML document conforming to the DebianDoc-SGML DTD, into various output formats.
Each formatting tool debiandoc2foo directs its output to basename.extension where basename
is source with any leading directory components and any trailing .sgml removed. If source
is - then the input is taken from the standard input. This option is not available with
debiandoc2html, debiandoc2latexdvi, debiandoc2latexps, debiandoc2latexpdf, debiandoc2dvi,
debiandoc2ps, debiandoc2pdf, debiandoc2info, and debiandoc2dbk.
debiandoc2html produces a subdirectory basename.html containing an HTML representation of
the input in a set of .html files. The `top level' page is named
basename.html/index.html.
debiandoc2text produces a plain ASCII text file basename.txt formatted to a width of 79
columns.
debiandoc2textov produces an ASCII text file basename.tov formatted to a width of 79
columns, with overstrikes for highlighting (using backspaces and repeated characters or
underscores). This is the same ASCII text output style as is generated by troff.
debiandoc2latex produces an input file basename.tex for the LaTeX typesetting system.
This can be used to produce PostScript output and PDF output.
debiandoc2latexdvi produces a DVI file basename.dvi via the LaTeX typesetting system.
This can be used to produce PostScript output.
debiandoc2latexps produces a PostScript file basename.ps via the LaTeX typesetting system.
debiandoc2latexpdf produces a PDF file basename.pdf via LaTeX typesetting system.
debiandoc2dvi produces a DVI file basename.dvi. Currently this is done via the LaTeX
typesetting system. This can be used to produce PostScript output.
debiandoc2ps produces a PostScript file basename.ps. Currently this is done via the LaTeX
typesetting system.
debiandoc2pdf produces a PDF file basename.pdf. Currently this is done via the LaTeX
typesetting system.
debiandoc2texinfo produces an input file basename.texinfo for the Texinfo documentation
system. This can be used to produce an Info file.
debiandoc2info produces an Info file basename.info via the Texinfo documentation system.
debiandoc2dbk produces a subdirectory basename.dbk containing an DocBook XML
representation of the input in a set of .dbk files. The `top level' page is named
basename.dbk/index.dbk. If -1 option is used, it produces a basename.dbk file instead in
the same directory without creating a subdirectory.
debiandoc2wiki produces a text file basename.wiki , part of which may be used for creation
of a Wiki page.
SHARED OPTIONS
The following command line options are supported by all formatting tools:
-b basename
Use the indicated basename instead of the default one. If applied to
debiandoc2html and given with one or more directory components, the indicated
basename is interpreted as basename/prefix with basename now consisting of the
given directory components. The resulting basename is used as described above.
The prefix is used as prefix of the set of .html files containing the HTML
representation of the input, including the `top level' page.
-c Turn on content-negotiation with encoding suffix. This causes the generated output
to be named basename.language[.encoding].extension based on the -l option argument.
The optional encoding exists only when -l option argument explicitly contains
encoding.
-C Turn on content-negotiation without encoding suffix. This causes the generated
output to be named basename.language.extension based only on the language part of
-l option argument. (Good for UTF-8 locale such as 'fr.UTF-8'.)
-d declaration
Use the indicated SGML declaration instead of the default (
/usr/share/sgml/debiandoc/dtd/sgml/1.0/debiandoc.dcl ). If given without any
leading directory components, declaration is assumed to be in one of the
declaration directories in the SGML search paths.
-e extension
Use the indicated extension instead of the default one.
-h Print the help message on stdout.
-k Keep the intermediate files in the directory with the output file(s). This
includes files in onsgmls(1)'s output format basename.sasp and basename.sasp-foo.
For LaTeX based output this also includes the files basename.aux, basename.log,
basename.tex and basename.toc, and for PostScript output the file basename.dvi as
well. Further, if the -O option and/or the -c option and/or the -e option(s)
are/is used to generate a DVI, a PDF or a PS file, respectively basename.dvi,
basename.pdf or basename.ps is also an intermediate file.
-l locale
Use the indicated locale to localize the generated output. If this option is not
used or an unsupported locale is indicated, the locale 'en' which is alias of
'en_US.ISO8859-1' is used. For generic English UTF-8, use 'en.UTF-8' instead.
These will be used as a part of file name when -c or -C options are used. For
HTML, content negotiation part of file name is generated by changing the locale
value such as 'pt_BR' to a lower case one 'pt-br'. The locale value such as 'pt-
br' are also accepted as an alias for pt_BR' to make build scripts cleaner. This
will make non-HTML output to use the same suffix as HTML. See
/usr/share/perl5/DebianDoc_SGML/Locale/Alias.pm for exact locale names accepted
(left side values).
-n onsgmls_options
Pass the indicated options directly on to onsgmls(1). May be used more than once.
-- Separates options from the source in case the latter begins with a hyphen.
SPECIFIC OPTIONS
The following command line options are supported only by some formatting tools (see the
synopsis above for which tool support which option):
-1 Generate one page for HTML output. Generate 1 page per page (default) for
PostScript output (as this is the default now the option is deprecated and will
likely be removed in the future).
-L Do not add <link> tags to the header of the generated HTML file(s).
-m Put the comments in footnote style in the output.
-O Output to standard output instead of to the file basename.extension. This is
implied when input is taken from standard input.
-p papersize
Produce output in the indicated papersize. See papersize(5) for details.
-P Add extra <p> tags to the regenerated SGML file(s) around <list>, <enumlist>,
<taglist>, <example>, ... to work with Debiandoc SGML syntax.
-s script
Apply the specified script on the intermediate .latex or .texinfo file before
making further processing. (Or apply the specified script on the generated file)
The script is called with its argument set to [ -l locale ] inputfile outputfile .
Currently, the default value for this script hook for .tex file is set to
/usr/share/debiandoc-sgml/fixlatex which fixes Chinese Big5 encoding issues.
-S Use <sect1>, <sect2>, <sect3>, ... instead of default <section> for DocBook XML
conversion.
-t topname
Use the indicated topname (without extension) as the name of the `top level' page
instead of the default one.
-v Be verbose when invoking secondary processors such as latex or makeinfo.
-x Generate XHTML compliant HTML output.
-X custom_dir.
You can change the locale dependent data directory from the default
/usr/share/perl5/DebianDoc_SGML/Locale/ to custom_dir directory by setting this
option.
This may be used as a hook for user to add new locale support or to change LaTeX
header definition created by the debiandoc-sgml package without having root access
to the system.
DIAGNOSTICS
Error messages from the validating SGML parser onsgmls(1) indicate something is wrong with
source. Make sure source conforms to the DebianDoc-SGML DTD.
Error messages from saspconvert (an internally used script of the DebianDoc-SGML package)
indicates a problem with the package itself. Please report them to the package maintainer
via Debian's bug reporting system.
If debiandoc2latexdvi, debiandoc2latexps, debiandoc2latexpdf, debiandoc2dvi, debiandoc2ps,
debiandoc2pdf, or debiandoc2info encounter an error when calling their secondary
processors, they issue an appropriate error message and indicate to use the -v option to
see the output generated by these secondary processors (which can be a lot!). The latter
three also indicate to check the log file basename.log.
If an error occurred, none of the already generated intermediate files are removed. They
are removed in the next successful conversion of the same source by the same debiandoc2foo
(unless the -k option is used).
NOTES
If debiandoc2foo is about to overwrite an already existing intermediate file, it issues an
appropriate warning message (except for files in onsgmls(1)'s output format). See the
description of the -k option for a complete overview of the intermediate files.
ENVIRONMENT
The output from the <date> tag can be overridden by the value of environment variable
DEBIANDOC_DATE if defined.
BUGS
There should be a program to convert the overstrikes generated by debiandoc2textov from
using backspaces to using carriage returns.
The paper size support in debiandoc2latexdvi, debiandoc2latexps, debiandoc2latexpdf,
debiandoc2dvi, debiandoc2ps, and debiandoc2pdf is not complete.
When debiandoc2html is invoked with -x option to produce XHTML compliant code, the index
format control features of <enumlist> will not work and it produces <enumlist> in the
compact format.
The debiandoc2dbk command creates usable DocBook XML file. This is meant to be used as a
tool to transform existing DebianDoc SGML document to DocBook XML document.
The new XHTML feature of debiandoc2html command may contain some bugs but improves XML
conformance of HTML output.
The generated Wiki page text created by debiandoc2wiki command is meant to be used after
manual reformatting.
SEE ALSO
/usr/share/doc/debiandoc-sgml-doc/
DebianDoc-SGML documentation in SGML (= source), HTML, PDF and plain text format
(currently only the SGML DTD is described)
/usr/share/doc/sp/
OpenSP suite (which includes the validating SGML parser onsgmls) documentation in
HTML format
basename(1)
AUTHOR
Ardo van Rangelrooij <ardo@debian.org>
Ian Jackson (original version)
Osamu Aoki (XML converter, UTF-8 updates, etc.)