LINUXDOC(1)

📦
version 0.9.86 · 7 versions
, in arch rolling, debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

okay so this is the LINUXDOC(1) page from the General Commands Manual, and it's literally about linuxdoc — LinuxDoc DTD SGML converter to other output format. That's the whole main character energy right there. 💅

🌸 SYNOPSIS 🌸

bestie, here's the whole synopsis, no cap:

       linuxdoc --backend=format
       [--papersize=size] [--language=lang] [--charset=char] [--style=file]
       [--debug] [--define attribute=value] [--include entity] [backend-
       options...]  file(.sgml)

       or (Old, obsoleted usage)
       sgmlxxxx [generic-options...] [backend-options...]   file(.sgml)

periodt. The old obsoleted usage is still there if you're feeling nostalgic, but it's giving legacy. 🙈

💖 DESCRIPTION 💖

okay so the linuxdoc suite is a collection of text formatters which understands a LinuxDoc DTD SGML source file. Each formatter (or "back-end") renders the source file into a variety of output formats, including HTML, TeX, DVI, PostScript, plain text, and groff(1) source in manual-page format. The linuxdoc suite is provided for backward compatibility, because there are still many useful documents written in LinuxDoc DTD sgml source. obsessed. ✨

The markup language(s) accepted by these formatters is described in the Linuxdoc-Tools User's Guide. They are variants of an SGML document type definition originally designed by Matt Welsh for Linux documentation. iykyk. 🦋

🎀 GENERIC-OPTIONS 🎀

Most command-line options are accepted by all back-ends. Some back-ends have additional specific options to control rendering to their particular output format. Here are the common options:

  • --backend=format, -B — Set the backend for specified format. Default is none of the actual format, but just output the usage of this suites. Available formats are: html, info, latex, lyx, rtf, txt, check. slay. 💅
  • --papersize=size, -p — Set the paper size. Default is a4 (European 297x210mm paper). You may also specify letter size. vibe check passed. 🎀
  • --language=lang, -l — Specify the language of the document (this may change which style files are used for formatting by a back end). The default language is English. Run an LinuxDoc-tools command without arguments to see the list of valid language codes. fr fr. 🌍
  • --charset=chars, -c — Specify the output character encoding. Defaults to ascii selecting the ASCII set; you may specify "latin" to specify the ISO 8859-1 (Latin-1) character set. Also, nippon and euc-kr is required to handle the euc-jp and euc-kr encoded sgml file. utf-8 is also accepted, although it is only partially supported. the way that utf-8 is only partially supported? noted. 😭
  • --style=file, -S — Include an auxiliary DTD (Document Type Definition) from /usr/share/linuxdoc-tools/dtd. iconic path. ✨
  • --tabsize=n, -t — Set the tab spacing assumed for generating the output document. The default tab spacing is 8. lowkey important. 🫶
  • --debug, -d — Don't delete intermediate files (such as .TeX files generated on the way to a .dvi, or .man files deleted on the way to plain text). bestie, this is your bestie when you need to see the messy middle. 💖
  • --define, -D — Pass attribute/value pairs to be matched against "if" and "unless" conditionals. See the User's Guide for extended discussion of this feature. This conditionalization are handled by sgmlpre command. See sgmlpre(1) as well as the User's Guide. iykyk. 🧚
  • --include, -i — Pass a -i option to nsgmls(1). This may be used for conditional inclusion. See the nsgmls(1) manual page for details. conditional inclusion is giving main character energy. 🌈
  • --pass, -P — Pass an option string to the back end. The exact semantics of this option are dependent on the back end and should be explained in the individual manual pages for each. ngl, very back-end-specific. 💀
  • file — The SGML source file with .sgml extension, named either file or file.sgml. It must use the linuxdoc DTD. Other DTDs are not supported. no cap, only linuxdoc DTD. 🍓

Running a back-end with no arguments will cause it to list all its options (Error message about "no filenames given" can be ignored safely in this case). The available back ends include (names in brackets are old & obsoleted form):

  • linuxdoc -B html (sgml2html) — translate to HTML
  • linuxdoc -B info (sgml2info) — translate to GNU info
  • linuxdoc -B lyx (sgml2lyx) — translate to Lyx macros
  • linuxdoc -B latex (sgml2latex) — translate to LaTeX 2e
  • linuxdoc -B rtf (sgml2rtf) — translate to Microsoft Rich Text Format
  • linuxdoc -B txt (sgml2txt) — translate to plain text or Unix manual-page markup

There is also a tool linuxdoc-Bcheck (sgmlcheck) available for checking the Linuxdoc DTD SGML syntax of document sources without actually generating a translated version. periodt. 💅

✨ BACKEND-DRIVERS ✨

okay bestie, here's the tea on every single backend driver, one by one. no skipping, no skimming, we're doing all of them 💅

🌸 linuxdoc -B html (sgml2html)

converts a LinuxDoc DTD SGML source file to HTML output. Output will appear in the top level file file.html and file-n.html for each section (default action, but can be changed by option), where file is the name of the SGML source file and n is the section name.

The attribute/value pair output=html is set for conditionals.

linuxdoc -B html accepts the following options: [--split 0|1|2 ] [--dosnames] [--imagebuttons] [--toc 0|1|2 ]

The meanings of them are:

  • --split, -s — what level to split source documents. 0 = don't split, 1 = split by major sections, 2 = split by subsections.
  • --toc, -T — what level to generate toc.
    • 0 = don't generate toc at all,
    • 1 = includes major sections(/chapters/parts),
    • 2 = includes subsections.
  • --dosnames, -h — use .htm rather than .html as the extension of html files.
  • --imagebuttons, -I — use the "next", "previous", and "contents" arrow image icons included in /usr/share/linuxdoc-tools as navigation buttons.
  • --footer, -F — use the specified file as the footer in each resulted html file. Default footer is just plain
</BODY>\n </HTML>\n
  • --header, -H — use the specified file as the top part of the header in each resulted html file. Note that this is not the full part of the header, i.e., the title and the links (next,previous,contents) in the default header are retained. Default is
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">\n
<HTML>\n <HEAD>\n
  • --rtldirection, -r — set right-to-left direction in html file.

🦋 linuxdoc -B info (sgml2info)

converts a LinuxDoc DTD SGML source file to GNU info format. Output will appear in file.info where file is the name of the SGML source file.

The attribute/value pair output=info is set for conditionals.

linuxdoc -B info has not backend specific options. (iconic, honestly — no extra flags to memorize, we love a low-maintenance queen)

💜 linuxdoc -B latex (sgml2latex)

converts a LinuxDoc DTD SGML source file to LaTeX output, using the nsgmls(1) or onsgmls(1) parser, and the sgmlsasp(1) translator. Using the LaTeX output, and the latex(1) text formatter, you can then create DVI output, and PostScript output using the dvips(1) converter. Output will appear in file.tex for LaTeX output, file.dvi for DVI output, or file.ps for PostScript output, where file is the name of the SGML source file.

Using the LaTeX output, and the pdflatex(1) text formatter, you can then create a nice PDF output, suitable for viewing with PDF viewers as xpdf(1), acroread(1) or ghostview(1). ✨

The attribute/value pair output=latex2e is set for conditionals.

linuxdoc -B latex accepts following backend specific options: [--output=tex|dvi|ps|pdf] [--bibtex] [--makeindex] [--pagenumber=n] --quick [--latex=latex|hlatexp|platex|jlatex] [--dvips=dvips|dvi2ps] [--verbosity=n]

The meanings of them are:

  • --output=fmt, -o — specify the desired output format. The specifier fmt may be tex'', dvi'', ps'', or pdf''.
⚠️ Note: This version does not overwrite/remove the intermediate files: tex file for dvi output, or tex/dvi files for ps output. This is different behavior from the original SGML-Tools 1.0.9, so you are warned here. (no cap, consider yourself warned 💀)
  • --bibtex, -b — process the generated TeX with bibtex(1).
  • --makeindex, -m — generate a TeX index file suitable for processing with makeindex(1) from and <idx> and <cdx> tags present in the SGML source.
  • --pagenumber, -n — set the starting page number in the output DVI or PS file.
  • --quick, -q — do only one pass of LaTeX formatting. This is often not sufficient to produce final output (because of references, etc.) but is useful for spotting TeX errors and justification problems.
  • --pass, -P — the argument of the pass option is inserted just after the LaTeX preamble generated by the document-type tag. Specify the desired output format. The specifier fmt may be tex'', dvi'', ps'', or pdf''.
  • --latex=alternate_latex_command, -x — this option is currently for Korean and Japanese. The alternate_latex_command can be latex'' (default), hlatexp'' (for Korean), platex'' or jlatex'' (for Japanese). This option can be used to render Korean document using HLaTeXp, or to render Japanese document using pLaTeX/jLaTeX. If not, HLaTeX should be installed to render Korean document. On the other hand, Japanese document can be rendered with jLaTeX (which is the default when ``-c nippon'' is specified), so if you already have jLaTeX, you may not need to install the pLaTeX.
  • --dvips=alternate_dvips_command, -s — this option is currently for Japanese. The alternate_dvips_command can be dvips'' or dvi2ps''. If you don't know this, then you may not need this.
  • --verbosity, -V — set verbosity. '0' (default) will show info about LaTeX run only in case of errors. '1' will always show info for last run. '2' will show info for all runs.

🎀 linuxdoc -B lyx (sgml2lyx)

converts a LinuxDoc DTD SGML source file to LyX output. Output will appear in file.lyx where file is the name of the SGML source file.

The attribute/value pair output=lyx is set for conditionals.

linuxdoc -B lyx has not backend specific options. (again, zero extra flags, the way that she just works 🫶)

🌈 linuxdoc -B rtf (sgml2rtf)

converts a LinuxDoc DTD SGML source file to RTF, the Rich Text Tormat used by the Microsoft Windows help system. Output will appear in the top level file file.rtf and file-n.rtf for each section, where file is the name of the SGML source file. The RTF output is tailored for compilation by the Windows Help Compiler (hc31.exe).

The attribute/value pair output=rtf is set for conditionals.

linuxdoc -B rtf accepts [--twosplit] as a backend specific option. Following is the meaning of this option:

  • --twosplit, -2 — splits files both at n. sections and n.m. subsections

🍓 linuxdoc -B txt (sgml2txt)

converts a LinuxDoc DTD SGML source file to ASCII, ISO-8859-1, or EUC-JP output. Output will appear in file.txt where file is the name of the SGML source file.

The attribute/value pair output=txt is set for conditionals.

linuxdoc -B txt accepts following backend-options: [--manpage] [--filter] [--blanks=n]

The meaning of these options are:

  • --manpage, -m — outputs a groff source file, suitable for formatting with groff -man for man pages
  • --filter, -f — remove backspace-overstrikes from the intermediate form generated by groff(1).
  • --pass, -P — the argument of the pass option is added to the command-line options handed to groff(1).
  • --blanks=n, -b — set the limit of continuous blank lines for generating the output document. The default limit is 3. If 0 (zero) is specified, the result have many continuous blank lines.

🧚 linuxdoc -B check (sgmlcheck)

runs an SGML parse on the specified document source. Any errors are reported to standard output. No formatted version of the source is produced.

Note that linuxdoc -B check preprocesses the LinuxDoc DTD SGML source, doing the conditionalization described by any <#if></#if> and <#unless></#unless> tags. Document sources containing these tags will confuse a standalone SGML parser. linuxdoc -B check has no backend-specific options.

🌟 FILES 🌟

Many files and executables in /usr/share/linuxdoc-tools and /usr/bin are used.

💀 BUGS 💀

Maybe some are left. Feel free to send your report to the current maintainer. (if you find one, pls tell her, she wants to know 🙈)

👑 MAINTAINER 👑

This has been maintained by Cees de Groot <cg@cdegroot.com> in SGML-Tools (v1) and Taketoshi Sano <sano@debian.org> for Linuxdoc-Tools. Currently maintained by Agustin Martin <agustin6martin AT gmail com>.

and that's the whole page, bestie 💖 this one's dated 2025-04-02 and it's LINUXDOC(1) — go forth and convert some SGML, you absolute icon ⭐

📦 where this page comes from