DEBIANDOC-SGML(1)

okay bestie, welcome to DEBIANDOC-SGML(1) from the DebianDoc-SGML Tools section of the manual 💅 this is the whole vibe of the DebianDoc-SGML formatting squad, and yes we're gonna go through every single option together, no skipping, no cap 🫶

---

✨ NAME ✨

debiandoc-sgml — the whole overview of the DebianDoc-SGML formatting tools, like the group chat of the whole toolset 🎀

---

🌈 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 💖

so like. DebianDoc-SGML is an SGML DTD and a lil family of formatting tools. these tools take your source — an SGML document that conforms to the DebianDoc-SGML DTD — and convert it into whatever output format you're feeling that day. it's giving versatile 👑

Every formatting tool debiandoc2foo sends its output to basename.extension, where basename is source with all the leading directory components stripped off and any trailing .sgml yeeted into the void. If source is -, then the input comes from standard input 📥. BUT — that - thing is not available with debiandoc2html, debiandoc2latexdvi, debiandoc2latexps, debiandoc2latexpdf, debiandoc2dvi, debiandoc2ps, debiandoc2pdf, debiandoc2info, and debiandoc2dbk. so don't even try it with those ones bestie 💀

• debiandoc2html — makes a whole subdirectory basename.html stuffed with an HTML representation of your input, spread across a set of .html files. the top level page is named basename.html/index.html. main character of the subdirectory fr ✨
• debiandoc2text — produces a plain ASCII text file basename.txt, formatted to a width of 79 columns. neat and tidy 🎀
• debiandoc2textov — produces an ASCII text file basename.tov, also formatted to a width of 79 columns, but with overstrikes for highlighting (using backspaces and repeated characters or underscores). it's the exact same ASCII text output style that troff generates. retro but make it fashion 💅
• debiandoc2latex — produces an input file basename.tex for the LaTeX typesetting system. you can use this to produce PostScript output and PDF output, two for the price of one 🌈
• debiandoc2latexdvi — produces a DVI file basename.dvi via the LaTeX typesetting system. 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. 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. 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 a DocBook XML representation of your input in a set of .dbk files. the top level page is named basename.dbk/index.dbk. and if you use the -1 option, it instead produces a basename.dbk file in the same directory, without creating a subdirectory. plot twist 👀
• debiandoc2wiki — produces a text file basename.wiki, part of which may be used for creation of a Wiki page 🌐

---

🌸 SHARED OPTIONS 🌸

these command line options are supported by ALL the formatting tools, so they're basically the friend group everyone shares 🫶

• -b basename — use the basename you gave instead of the default one. if you use this with debiandoc2html and hand it one or more directory components, the basename you gave gets interpreted as basename/prefix, where basename now consists of the directory components you provided. the resulting basename gets used exactly as described above. and the prefix? it becomes the prefix of the set of .html files holding the HTML representation of your input, top level page included 👑
• -c — turns on content-negotiation with encoding suffix. this makes the generated output get named basename.language[.encoding].extension, based on the -l option argument. the optional encoding part only shows up when the -l option argument explicitly contains encoding. specifics matter bestie 💅
• -C — turns on content-negotiation without encoding suffix. this makes the generated output get named basename.language.extension, based only on the language part of the -l option argument. (good for UTF-8 locales such as fr.UTF-8.) 🌈
• -d declaration — use the declaration you gave instead of the default one (/usr/share/sgml/debiandoc/dtd/sgml/1.0/debiandoc.dcl). if you give it without any leading directory components, the declaration is assumed to live in one of the declaration directories in the SGML search paths 🔍
• -e extension — use the extension you gave instead of the default one 🎀
• -h — print the help message on stdout 📢
• -k — keep the intermediate files in the directory alongside 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, plus for PostScript output the file basename.dvi as well. and 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, then respectively basename.dvi, basename.pdf or basename.ps is also an intermediate file. it's a whole collection, obsessed 🗂️
• -l locale — use the locale you gave to localize the generated output. if you don't use this option, or you point at an unsupported locale, the locale en — which is an alias of en_US.ISO8859-1 — gets used. for generic English UTF-8, use en.UTF-8 instead. these get used as a part of the file name when the -c or -C options are used. for HTML, the content negotiation part of the file name is generated by changing the locale value, such as turning pt_BR into a lower case one, pt-br. locale values such as pt-br are also accepted as an alias for pt_BR' to make build scripts cleaner. this makes non-HTML output use the same suffix as HTML. see /usr/share/perl5/DebianDoc_SGML/Locale/Alias.pm for the exact locale names accepted (left side values) 📖
• -n onsgmls_options — pass the onsgmls_options you gave directly on to onsgmls(1). may be used more than once, so go off 🔥
• -- — separates options from the source, in case the source begins with a hyphen. saving you from chaos, one dash at a time 🛟

---

💅 SPECIFIC OPTIONS 💅

these command line options are only supported by some of the formatting tools (peep the synopsis above to see which tool supports which option) 👀

• -1 — generate one page for HTML output. for PostScript output, generate 1 page per page (default).

bestie, heads up: since 1 page per page is the default now, this option is deprecated and will likely be removed in the future. it's giving legacy 💀

• -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 papersize you gave. 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 script you gave on the intermediate .latex or .texinfo file before making further processing. (or apply the script you gave on the generated file.)

the script gets 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 the default <section> for DocBook XML conversion 🔀
• -t topname — use the topname you gave (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. it will tell you everything 🗣️
• -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 the custom_dir directory by setting this option.

this may be used as a hook for a user to add new locale support, or to change the LaTeX header definition created by the debiandoc-sgml package, without having root access to the system. no sudo needed, we love that for you 🫶

---

😭 DIAGNOSTICS 😭

error messages coming out of the validating SGML parser onsgmls(1) mean something is wrong with your source. make sure source conforms to the DebianDoc-SGML DTD, bestie, or it's gonna keep yelling at you 📣

error messages coming out of saspconvert (an internally used script of the DebianDoc-SGML package) mean there's a problem with the package itself. please report those to the package maintainer via Debian's bug reporting system — that one's not your fault, it's a them problem 🐛

if debiandoc2latexdvi, debiandoc2latexps, debiandoc2latexpdf, debiandoc2dvi, debiandoc2ps, debiandoc2pdf, or debiandoc2info hit an error while calling their secondary processors, they issue an appropriate error message and tell you to use the -v option to see the output generated by those secondary processors (and omg, it can be a LOT!). the latter three also tell you to check the log file basename.log 📜

if an error occurred, none of the already generated intermediate files get removed. they get removed on the next successful conversion of the same source by the same debiandoc2foo (unless you're using the -k option). so they just kinda... linger. iconic but messy 💀

---

🎀 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 🌸

okay so there's literally one (1) environment variable in this whole situation and it's kind of a big deal if you care about dates, which — same.

• DEBIANDOC_DATE — if you set this, it overrides whatever the <date> tag would have spat out. like, the tag says one thing, the env var says another, and the env var WINS. periodt. if it's not defined, <date> just does its own thing, no drama. 💅

---

💀 BUGS 💀

bestie. sit down. we're doing the bugs section and it's giving "group project where everyone submitted their part separately." ngl it's a lot but it's all real so let's go one by one 🫶

• someone should really write a program that converts the overstrikes that debiandoc2textov generates from using backspaces to using carriage returns. like, that program does not exist yet. it's a whole missing thing. 😭
• the paper size support in debiandoc2latexdvi, debiandoc2latexps, debiandoc2latexpdf, debiandoc2dvi, debiandoc2ps, and debiandoc2pdf is not complete. all six of them. incomplete. that's the vibe. 🎀
• when debiandoc2html gets invoked with the -x option to produce XHTML compliant code, the index format control features of <enumlist> will not work, and it just produces <enumlist> in the compact format instead. so like, you asked for index format control and the answer was no. 🙈
• debiandoc2dbk creates a usable DocBook XML file. to be clear, this is meant to be used as a tool to transform an existing DebianDoc SGML document into a DocBook XML document. that's its whole job description. 💖
• the new XHTML feature of debiandoc2html may contain some bugs, but it improves XML conformance of HTML output. so like, tradeoffs, bestie. tradeoffs. ⭐
• the generated Wiki page text created by debiandoc2wiki is meant to be used after manual reformatting. so don't just yeet it at a wiki and expect magic. you gotta touch it up first. 💅

not me listing six whole commands with incomplete paper size support 😭 anyway it's documented, that's what counts

---

👑 SEE ALSO 👑

the required reading, the syllabus, the "you'll want these open in other tabs" section:

• /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) — yeah just, basename. it's there. iconic. 💜

---

🦋 AUTHOR 🦋

the legends themselves, no cap:

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

---

and that's a wrap on the whole page, bestie!! this one came from the DebianDoc-SGML Tools, dated May 2008, and it lives at DEBIANDOC-SGML(1). go forth, read your SGML, validate your docs, and remember — <date> listens to DEBIANDOC_DATE first. mwah 💋🌸