debiandoc-sgml
NAME
debiandoc-sgml - overview of the DebianDoc-SGML formatting tools
SYNOPSIS
debiandoc2*
[-h]
[-b basename]
[-s script]
[-c]
[-d declaration]
[-e extension]
[-k]
[-l locale]
[-n nsgmls_options]
[--]
[source]
debiandoc2html
[-L]
[-s script]
[-m]
[-t topname]
[-1]
[shared options]
debiandoc2text [-O] [-s script] [-m] [shared options]
debiandoc2textov [-O] [-s script] [-m] [shared options]
debiandoc2latex [-O] [-s script] [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] [-s script] [-p papersize] [-v] [shared options]
debiandoc2ps [-O] [-s script] [-p papersize] [-v] [-1] [shared options]
debiandoc2pdf [-O] [-s script] [-p papersize] [-v] [shared options]
debiandoc2texinfo [-O] [-s script] [shared options]
debiandoc2info [-s script] [-v] [shared options]
debiandoc2xml [-s script] [-v] [shared options]
debiandoc2sgml [-s script] [-v] [shared options]
debiandoc2docbookxml [-s script] [-v] [shared options]
debiandoc2text [-O] [-s script] [-m] [shared options]
debiandoc2textov [-O] [-s script] [-m] [shared options]
debiandoc2latex [-O] [-s script] [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] [-s script] [-p papersize] [-v] [shared options]
debiandoc2ps [-O] [-s script] [-p papersize] [-v] [-1] [shared options]
debiandoc2pdf [-O] [-s script] [-p papersize] [-v] [shared options]
debiandoc2texinfo [-O] [-s script] [shared options]
debiandoc2info [-s script] [-v] [shared options]
debiandoc2xml [-s script] [-v] [shared options]
debiandoc2sgml [-s script] [-v] [shared options]
debiandoc2docbookxml [-s script] [-v] [shared options]
DESCRIPTION
DebianDoc-SGML is an SGML DTD and a set of formatting tools. These
tools convert
R source ,
an SGML document conforming to the DebianDoc-SGML DTD, into various
output formats.
Each formatting tool
I debiandoc2 foo
directs its output to
B 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
R debiandoc2html ,
R debiandoc2latexdvi ,
R debiandoc2latexps ,
R debiandoc2latexpdf ,
R debiandoc2dvi ,
R debiandoc2ps ,
R debiandoc2pdf ,
R debiandoc2info ,
R debiandoc2xml ,
R debiandoc2sgml ,
and
R debiandoc2docbookxml .
debiandoc2html
produces a subdirectory
B basename .html
containing an HTML representation of the input in a set of
.html
files. The `top level' page is named
B basename .html/index.html.
debiandoc2text
produces a plain ASCII text file
B basename .txt
formatted to a width of 79 columns.
debiandoc2textov
produces an ASCII text file
B 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
B basename .tex
for the LaTeX typesetting system. This can be used to produce
PostScript output and PDF output.
debiandoc2latexdvi
produces a DVI file
B basename .dvi
via the LaTeX typesetting system. This can be used to produce
PostScript output.
debiandoc2latexps
produces a PostScript file
B basename .ps
via the LaTeX typesetting system.
debiandoc2latexpdf
produces a PDF file
B basename .pdf
via LaTeX typesetting system.
debiandoc2dvi
produces a DVI file
B basename .dvi.
Currently this is done via the LaTeX typesetting system. This can be
used to produce PostScript output.
debiandoc2ps
produces a PostScript file
B basename .ps.
Currently this is done via the LaTeX typesetting system.
debiandoc2pdf
produces a PDF file
B basename .pdf.
Currently this is done via the LaTeX typesetting system.
debiandoc2texinfo
produces an input file
B basename .texinfo
for the Texinfo documentation system. This can be used to produce an
Info file.
debiandoc2info
produces an Info file
B basename .info
via the Texinfo documentation system.
debiandoc2xml
produces a subdirectory
B basename .xml
containing an DocBook XML representation of the input in a set of
.xml
files. The `top level' page is named
B basename .xml/index.xml.
(under development) Multifile XML follows Xinclude specification
which requires
xsltproc
command to use
--xinclude
option.
debiandoc2sgml
produces a subdirectory
B 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
B basename .new.sgml/index.new.sgml
(under development). The use of the -P option is recommended.
debiandoc2docbookxml
produces a DocBook XML file
B basename .xml
via the Texinfo documentation system. (deprecated)
SHARED OPTIONS
The following command line options are supported by all formatting
tools:
I -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
B basename . language . extension
with
language
the language part of the locale used to localize the output.
I -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.
I -e extension
Use the indicated
extension
instead of the default one.
I -h
Print the help message on stdout.
I -k
Keep the intermediate files in the directory with the output file(s).
This includes files in
nsgmls(1)'s
output format
B basename .sasp
and
B basename .sasp- foo.
For LaTeX based output this also includes the files
B basename .aux,
B basename .log,
B basename .tex
and
B basename .toc,
and for PostScript output the file
B 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
B basename .dvi,
B basename .pdf
or
B basename .ps
is also an intermediate file.
I -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.
I -n nsgmls_options
Pass the indicated options directly on to
nsgmls(1).
May be used more than once.
I --
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):
I -L
Add <link> tags to the header of the generated HTML file(s).
I -P
Add extra <p> tags to the regenerated SGML file(s) around
<list>, <enumlist>, <taglist>, <example>, ... to work with
Debiandoc SGML syntax.
I -O
Output to standard output instead of to the file
B basename . extension.
This is implied when input is taken from standard input.
I -m
Put the comments in footnote style in the output.
I -s script
Apply the specified script on the intermediate .latex or .texinfo file.
(Or apply the specified script on the generated 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.)
I -p papersize
Produce output in the indicated
R papersize .
See
papersize(5)
for details.
I -t topname
Use the indicated
topname
(without extension) as the name of the `top level' page instead of the
default one.
I -v
Be verbose when invoking secondary processors.
I -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).
I -x
Generate XHTML compliant HTML output.
DIAGNOSTICS
Error messages from the validating SGML parser
nsgmls(1)
indicate something is wrong with
R source .
Make sure
R 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
B 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
I debiandoc2 foo
(unless the
-k
option is used).
NOTES
If
I debiandoc2 foo
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
R debiandoc2latexdvi ,
R debiandoc2latexps ,
R debiandoc2latexpdf ,
R debiandoc2dvi ,
R debiandoc2ps ,
and
R debiandoc2pdf
is not complete.
When
R 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
R debiandoc2xml
and
R debiandoc2sgml
and the new XHTML feature of
R debiandoc2html
command may contain some bugs but I think they are quite usable.
The generated XML code through TeXInfo system by
R debiandoc2docbookxml
command contains many noise texts and is not proper XML.
(Do not use this)
SEE ALSO
R /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)
R /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)
Ian Jackson (original version)
ČLÁNKY DO MAILU