docbook2x-man(1)

📦
version 0.8.8 · 3 versions
, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 docbook2x-man — Convert DocBook to man pages 💖

okay bestie, so this is docbook2x-man(1), and it ships with the docbook2X package (that's the manual name, she's fancy like that). Sit down, grab a boba, we're converting DocBook to man pages and it's gonna be so good. 🧚✨

🌸 NAME 🌸

docbook2x-man — Convert DocBook to man pages

🎀 SYNOPSIS 🎀

docbook2x-man [options] xml-document

🦋 DESCRIPTION 🦋

So what does she actually do? docbook2x-man takes the DocBook XML document you hand her and turns it into man pages. By default, those man pages get dropped right into the current directory. No cap. 💅

Here's the tea though: only the refentry content inside your DocBook document gets converted. That's it, that's the whole vibe. (If you wanna convert stuff outside a refentry, you're gonna need stylesheet customization — check the docbook2X package for the deets.)

And plot twist: docbook2x-man is actually a wrapper script running a two-step conversion process behind the scenes. Slide down to the "CONVERSION PROCESS" section if you wanna see how the sausage gets made. 👀

✨ OPTIONS ✨

The options you get here are essentially the union of the options from db2x_xsltproc(1) and db2x_manxml(1). Iconic crossover event, honestly.

Some of the commonly-used ones are listed below:

  • --encoding=encoding — Sets the character encoding of the output. 🫶
  • --string-param parameter=value — Sets a stylesheet parameter (these are the options that affect how the output looks). Peep the "Stylesheet parameters" section below for which parameters you can actually set.
  • --sgml — Accept an SGML source document as input instead of XML.
  • --solinks — Make stub pages for alternate names for an output man page.

🌈 STYLESHEET PARAMETERS 🌈

These are the little knobs that change how your output shows up. Get into it:

  • uppercase-headings — Brief: make headings uppercase?
    • Default setting: 1 (boolean true)
    • Headings in man page content should be or should not be uppercased.
  • manvolnum-cite-numeral-only — Brief: man page section citation should use only the number.
    • Default setting: 1 (boolean true)
    • When citing other man pages, the man-page section is either given as is, or it has the letters stripped from it, citing only the number of the section (e.g. section 3x becomes 3). This option specifies which style you want.
  • quotes-on-literals — Brief: display quotes on literal elements?
    • Default setting: 0 (boolean false)
    • If true, render literal elements with quotes around them.
  • show-comments — Brief: display comment elements?
    • Default setting: 1 (boolean true)
    • If true, comments will be displayed, otherwise they are suppressed. Heads up, "comments" here means the comment element, which will be renamed remark in DocBook V4.0 — it does not mean XML comments (<-- like this -->), because those are unavailable. 🚫
  • function-parens — Brief: generate parentheses after a function?
    • Default setting: 0 (boolean false)
    • If true, the formatting of a <function> element will include generated parenthesis.
  • xref-on-link — Brief: should link generate a cross-reference?
    • Default setting: 1 (boolean true)
    • Man pages cannot render the hypertext links created by link. If this option is set, then the stylesheet renders a cross reference to the target of the link. (This may reduce clutter.) Otherwise, only the content of the link is rendered and the actual link itself is ignored.
  • header-3 — Brief: third header text.
    • Default setting: (blank)
    • Specifies the text of the third header of a man page, typically the date for the man page. If empty, the date content for the refentry is used.
  • header-4 — Brief: fourth header text.
    • Default setting: (blank)
    • Specifies the text of the fourth header of a man page. If empty, the refmiscinfo content for the refentry is used.
  • header-5 — Brief: fifth header text.
    • Default setting: (blank)
    • Specifies the text of the fifth header of a man page. If empty, the 'manual name', that is, the title of the book or reference container, is used.
  • default-manpage-section — Brief: default man page section.
    • Default setting: 1
    • The source document usually indicates the sections that each man page should belong to (with manvolnum in refmeta). In case the source document does not indicate man-page sections, this option specifies the default.
  • custom-localization-file — Brief: URI of XML document containing custom localization data.
    • Default setting: (blank)
    • This parameter specifies the URI of a XML document that describes text translations (and other locale-specific information) that is needed by the stylesheet to process the DocBook document.
    • The text translations pointed to by this parameter always override the default text translations (from the internal parameter localization-file). If a particular translation is not present here, the corresponding default translation is used as a fallback.
    • This parameter is primarily for changing certain punctuation characters used in formatting the source document. The settings for punctuation characters are often specific to the source document, but can also be dependent on the locale.
    • To not use custom text translations, leave this parameter as the empty string.
  • custom-l10n-data — Brief: XML document containing custom localization data.
    • Default setting: document($custom-localization-file)
    • This parameter specifies the XML document that describes text translations (and other locale-specific information) that is needed by the stylesheet to process the DocBook document.
    • This parameter is internal to the stylesheet. To point to an external XML document with a URI or a file name, you should use the custom-localization-file parameter instead.
    • However, inside a custom stylesheet (not on the command-line) this parameter can be set to the XPath expression document(''), which will cause the custom translations directly embedded inside the custom stylesheet to be read.
  • author-othername-in-middle — Brief: is othername in author a middle name?
    • Default setting: 1
    • If true, the othername of an author appears between the firstname and surname. Otherwise, othername is suppressed.

🌟 EXAMPLES 🌟

Real ones, here you go:

$ docbook2x-man --solinks manpages.xml
$ docbook2x-man --solinks --encoding=utf-8//TRANSLIT manpages.xml
$ docbook2x-man --string-param header-4="Free Recode 3.6" document.xml
.fi

🔥 CONVERSION PROCESS 🔥

💜 Converting to man pages

DocBook documents are converted to man pages in two steps:

  1. The DocBook source is converted by a XSLT stylesheet into an intermediate XML format, Man-XML.
    • Man-XML is simpler than DocBook and closer to the man page format; it is intended to make the stylesheets' job easier.
    • The stylesheet for this purpose is in xslt/man/docbook.xsl. For portability, it should always be referred to by the following URI:
http://docbook2x.sourceforge.net/latest/xslt/man/docbook.xsl
  • Run this stylesheet with db2x_xsltproc(1).
  • Customizing. You can also customize the output by creating your own XSLT stylesheet — changing parameters or adding new templates — and importing xslt/man/docbook.xsl.
  1. Man-XML is converted to the actual man pages by db2x_manxml(1).

The docbook2x-man command does both steps automatically, but if any problems occur, you can see the errors more clearly if you do each step separately:

$ db2x_xsltproc -s man mydoc.xml -o mydoc.mxml
$ db2x_manxml mydoc.mxml
.fi

Options to the conversion stylesheet are described in the man-pages stylesheets reference.

Pure XSLT conversion. An alternative to the db2x_manxml Perl script is the XSLT stylesheet in xslt/backend/db2x_manxml.xsl. This stylesheet performs a similar function of converting Man-XML to actual man pages. It is useful if you desire a pure XSLT solution to man-page conversion. Of course, the quality of the conversion using this stylesheet will never be as good as the Perl db2x_manxml, and it runs slower. In particular, the pure XSLT version currently does not support tables in man pages, but its Perl counterpart does.

🌈 Character set conversion

When translating XML to legacy ASCII-based formats with poor support for Unicode, such as man pages and Texinfo, there is always the problem that Unicode characters in the source document also have to be translated somehow.

A straightforward character set conversion from Unicode does not suffice, because the target character set, usually US-ASCII or ISO Latin-1, do not contain common characters such as dashes and directional quotation marks that are widely used in XML documents. But document formatters (man and Texinfo) allow such characters to be entered by a markup escape: for example, \(lq for the left directional quote “. And if a markup-level escape is not available, an ASCII transliteration might be used: for example, using the ASCII less-than sign < for the angle quotation mark ⟨.

So the Unicode character problem can be solved in two steps:

  1. utf8trans(1), a program included in docbook2X, maps Unicode characters to markup-level escapes or transliterations.
    • Since there is not necessarily a fixed, official mapping of Unicode characters, utf8trans can read in user-modifiable character mappings expressed in text files and apply them. (Unlike most character set converters.)
    • In charmaps/man/roff.charmap and charmaps/man/texi.charmap are character maps that may be used for man-page and Texinfo conversion. The programs db2x_manxml(1) and db2x_texixml(1) will apply these character maps, or another character map specified by the user, automatically.
  2. The rest of the Unicode text is converted to some other character set (encoding). For example, a French document with accented characters (such as é) might be converted to ISO Latin 1.

🍓 FILES 🍓

  • /usr/local/share/docbook2X/xslt/man/docbook.xsl
  • /usr/local/share/docbook2X/xslt/backend/db2x_manxml.xsl
  • /usr/local/share/docbook2X/xslt/catalog.xml
  • /usr/local/share/docbook2X/charmaps/roff.charmap
  • /usr/local/share/docbook2X/charmaps/roff.charmap.xml

The above files are distributed and installed by the docbook2X package.

⭐ NOTES ⭐

The docbook2x-man or the docbook2texi command described in this manual page come from the docbook2X package. It should not be confused with the command of the same name from the obsoleted docbook-utils package. Same name, different girl. 💅

⚠️ LIMITATIONS ⚠️

  • okay so this is the part where I have to be real with you bestie 💀 — inside, there's literally one long pipeline of programs that your document gets pushed through, one after another after another. And like… if any segment of that pipeline fails? Even something trivially silly like a mistyped program option? The resulting errors can be difficult to decipher. It's giving cryptic. It's giving unreadable. 😭 So in that case, the move is: try running the components of docbook2X separately, one at a time, and figure out which one's actually being dramatic.

👑 AUTHOR 👑

Steve Cheng <stevecheng@users.sourceforge.net>. That's the icon. That's the main character who built this. 🫶

🌈 SEE ALSO 🌈

The docbook2X manual (it comes in Texinfo or HTML format, pick your fighter ✨) fully describes how to convert DocBook to man pages and Texinfo. Like, the whole thing. Fully. No cap.

Up-to-date information about this program can be found at the docbook2X Web site — http://docbook2x.sourceforge.net/ 🦋

and that's the whole page, bestie!! you read a whole manpage, I'm so proud, that's genuinely iconic of you 💖

this was docbook2X 0.8.8, dated 3 March 2007, and the page you just devoured is docbook2x-man(1). go forth and convert. slay. 💅🎀🌸

📦 where this page comes from