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

Author

       Ardo van Rangelrooij <ardo@debian.org>
       Ian Jackson (original version)
       Osamu Aoki (XML converter, UTF-8 updates, etc.)

DebianDoc-SGML Tools                                May 2008                                   DEBIANDOC-SGML(1)

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.

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.

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

Environment

       The  output  from the <date> tag can be overridden by the value of environment variable DEBIANDOC_DATE if
       defined.

Name

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

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.

Shared Options

The following command line options are supported by all formatting tools:

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

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

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

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

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

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

       -sscript
              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 [-llocale]inputfileoutputfile .

              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.

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

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

Synopsis

debiandoc2*[-h][-bbasename][-Xcustom_dir][-sscript][-c][-C][-ddeclaration][-eextension][-k][-llocale][-nonsgmls_options][--][source]debiandoc2html[-L][-Xcustom_dir][-sscript][-m][-ttopname][-1][sharedoptions]debiandoc2text[-O][-Xcustom_dir][-sscript][-m][sharedoptions]debiandoc2textov[-O][-Xcustom_dir][-sscript][-m][sharedoptions]debiandoc2latex[-O][-Xcustom_dir][-sscript][sharedoptions]debiandoc2latexdvi[-O][-Xcustom_dir][-sscript][-ppapersize][-v][sharedoptions]debiandoc2latexps[-O][-Xcustom_dir][-sscript][-ppapersize][-v][-1][sharedoptions]debiandoc2latexpdf[-O][-Xcustom_dir][-sscript][-ppapersize][-v][sharedoptions]debiandoc2dvi[-O][-Xcustom_dir][-sscript][-ppapersize][-v][sharedoptions]debiandoc2ps[-O][-Xcustom_dir][-sscript][-ppapersize][-v][-1][sharedoptions]debiandoc2pdf[-O][-Xcustom_dir][-sscript][-ppapersize][-v][sharedoptions]debiandoc2texinfo[-O][-Xcustom_dir][-sscript][sharedoptions]debiandoc2info[-Xcustom_dir][-sscript][-v][sharedoptions]debiandoc2dbk[-sscript][sharedoptions]debiandoc2wiki[-O][-sscript][-m][sharedoptions]