Man Linux: Main Page and Category List

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