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 nsgmls_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]
debiandoc2xml [-s script] [shared options]
debiandoc2sgml [-s script] [shared options]
debiandoc2wiki [-O] [-s script] [-m] [shared options]
debiandoc2docbookxml [-s script] [-v] [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, debiandoc2xml, debiandoc2sgml, and
debiandoc2docbookxml.
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.
debiandoc2xml produces a subdirectory basename.xml containing an
DocBook XML representation of the input in a set of .xml files. The
‘top level’ page is named basename.xml/index.xml. (under development)
Multifile XML follows Xinclude specification which requires xsltproc
command to use --xinclude option.
debiandoc2sgml produces a subdirectory basename.new.sgml containing a
Debiandoc SGML representation of the input in a set of .new.sgml files
with reformatted contents and cleanly closed tags. The ‘top level’
page is named basename.new.sgml/index.new.sgml (under development but
quite usable). The use of the -P option is recommended.
debiandoc2wiki produces a text file basename.wiki , part of which may
be used for creation of a Wiki page.
debiandoc2docbookxml produces a DocBook XML file basename.xml via the
Texinfo documentation system. (deprecated)
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 nsgmls(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 nsgmls_options
Pass the indicated options directly on to nsgmls(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.
-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 nsgmls(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, debiandoc2info, or
debiandoc2docbookxml 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
nsgmls(1)’s output format). See the description of the -k option for a
complete overview of the intermediate files.
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 compaact format.
The debiandoc2xml 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.
debiandoc2sgml and the new XHTML feature of debiandoc2html command may
contain some bugs but I think they are quite usable.
The generated Wiki page text created by debiandoc2wiki command is meant
to be used after manual reformatting.
The generated XML code through TeXInfo system by debiandoc2docbookxml
command contains many noise texts and is not proper XML. (Do not use
this)
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/
SP suite (which includes the validating SGML parser nsgmls)
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.)