Provided by: debiandoc-sgml_1.2.31-1.1_all bug

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