--- name: "debiandoc-sgml" section: "1" platform: "linux" package: "debiandoc-sgml" version: "1.2.32-2.1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/debiandoc-sgml" --- # debiandoc-sgml(1) overview of the DebianDoc-SGML formatting tools ## 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 **debiandoc2***foo* 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)](/onsgmls/1.md)'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)](/onsgmls/1.md). 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 \ 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)](/papersize/5.md) for details. - **-P** Add extra \ tags to the regenerated SGML file(s) around \, \, \, \, ... 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 \, \, \, ... instead of default \ 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)](/onsgmls/1.md) 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 **debiandoc2***foo* (unless the **-k** option is used). ## NOTES If **debiandoc2***foo* is about to overwrite an already existing intermediate file, it issues an appropriate warning message (except for files in [**onsgmls**(1)](/onsgmls/1.md)'s output format). See the description of the **-k** option for a complete overview of the intermediate files. ## ENVIRONMENT The output from the \ 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 \ will not work and it produces \ 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)](/basename/1.md) ## AUTHOR Ardo van Rangelrooij \\ Ian Jackson (original version)\ Osamu Aoki (XML converter, UTF-8 updates, etc.)