debiandoc-sgml - overview of the DebianDoc-SGML formatting tools

debiandoc2* [-h] [-b basename] [-c] [-d declaration] [-e extension] [-k] [-l locale] [-n nsgmls_options] [--] [source]

debiandoc2html [-L] [-m] [-t topname] [-1] [shared options]

debiandoc2text [-O] [-m] [shared options]

debiandoc2textov [-O] [-m] [shared options]

debiandoc2latex [-O] [shared options]

debiandoc2latexdvi [-O] [-s script] [-p papersize] [-v] [shared options]

debiandoc2latexps [-O] [-s script] [-p papersize] [-v] [-1] [shared options]

debiandoc2latexpdf [-O] [-s script] [-p papersize] [-v] [shared options]

debiandoc2dvi [-O] [-p papersize] [-v] [shared options]

debiandoc2ps [-O] [-p papersize] [-v] [-1] [shared options]

debiandoc2pdf [-O] [-p papersize] [-v] [shared options]

debiandoc2texinfo [-O] [shared options]

debiandoc2info [-v] [shared options]

debiandoc2xml [-v] [shared options]

debiandoc2sgml [-v] [shared options]

debiandoc2docbookxml [-v] [shared options]

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 an 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.) Use of-P option recommended.

debiandoc2docbookxml produces a DocBook XML file basename.xml via the Texinfo documentation system. (deprecated)

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. This causes the generated output to be named basename.language.extension with language the language part of the locale used to localize the output.

-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_US.ISO8859-1' is used.

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

The following command line options are supported only by some formatting tools (see the synopsis above for which tool support which option):

-L

Add <link> tags to the header of the generated HTML file(s).

-P

Add extra <p> tags to the regenerated SGML file(s) around <list>, <enumlist>, <taglist>, <example>, ... to work with Debiandoc SGML syntax.

-O

Output to standard output instead of to the file basename.extension. This is implied when input is taken from standard input.

-m

Put the comments in footnote style in the output.

-s script

Apply the specified script on the intermediate generated .tex / .texinfo file. The script is called with parameters [ -l locale ] inputfile outputfile .

This may be useful to support new features, to correct bogus hyphenations, ... (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.)

-p papersize

Produce output in the indicated papersize. See papersize(5) for details.

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

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

-x

Generate XHTML compliant HTML output.

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

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.

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 2 new commands debiandoc2xml and debiandoc2sgml and the new XHTML feature of debiandoc2html command may contain some bugs but I think they are quite usable.

The generated XML code through TeXInfo system by debiandoc2docbookxml command contains many noise texts and is not proper XML. (Do not use this)

/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)

Ardo van Rangelrooij <ardo@debian.org>

Ian Jackson (original version)