docbook2man(1)

📦 version 0.8.8, in arch rolling, centos-stream 10, centos-stream 9, fedora 43, fedora 44

💖 docbook2man — the docbook2X girlie 💖

okay so bestie, welcome to docbook2man(1), part of the docbook2X family. buckle up, this one's a whole journey 🦋

✨ NAME ✨

docbook2man — Convert DocBook to man pages 👑

✨ SYNOPSIS ✨

docbook2man [options] xml-document

✨ DESCRIPTION ✨

okay so here's the tea ☕ — docbook2man takes the DocBook XML document you hand it and turns it into man pages. iconic behavior honestly. by default, those man pages get dropped right into the current directory, no cap.

Only the refentry content in the DocBook document is converted. that's the vibe. if you wanna convert stuff outside of a refentry, you're gonna need stylesheet customization — go check the docbook2X package for the details, iykyk. 👀

also, docbook2man is literally just a wrapper script for a two-step conversion process. it's giving project manager energy. the full breakdown lives in the CONVERSION PROCESS section down below 🫶

✨ OPTIONS ✨

the options available are basically the union of the options from db2x_xsltproc(1) and db2x_manxml(1). so yeah, it's a whole collab 💅

some of the most commonly-used ones are listed here:

  • --encoding=encoding — sets the character encoding of the output 🔤
  • --string-param parameter=value — sets a stylesheet parameter (aka the options that change how the output looks). the parameters you can set are in "Stylesheet parameters" below 👇
  • --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 🎀

uppercase-headings

Brief. Make headings uppercase?

Default setting. 1 (boolean true)

basically: should headings in man page content be uppercased, or should they not be? that's it, that's the whole question 💜

manvolnum-cite-numeral-only

Brief. Man page section citation should use only the number

Default setting. 1 (boolean true)

when you're citing other man pages, the man-page section is either given as-is, or it gets the letters stripped off and only cites the number of the section (so like, section 3x becomes 3). this option picks which style you want ✂️

quotes-on-literals

Brief. Display quotes on literal elements?

Default setting. 0 (boolean false)

if it's true, literal elements get rendered with quotes around them 🎀

show-comments

Brief. Display comment elements?

Default setting. 1 (boolean true)

if true, comments get displayed; otherwise they're suppressed, gone, deleted from the narrative 🙈

heads up bestie — "comments" here means the comment element, which gets renamed to remark in DocBook V4.0. it is NOT XML comments (like <!-- this -->), because those are unavailable. don't mix them up, ok? 😭

function-parens

Brief. Generate parentheses after a function?

Default setting. 0 (boolean false)

if true, formatting a <function> element will include generated parenthesis. so it'll have the lil () swag ✨

Brief. Should link generate a cross-reference?

Default setting. 1 (boolean true)

man pages literally cannot render the hypertext links that link creates. so if this option is set, the stylesheet renders a cross reference to the target of the link instead (this may reduce clutter, lowkey a win). otherwise, only the content of the link is rendered and the actual link itself is just… ignored 💀

header-3

Brief. Third header text

Default setting. (blank)

sets the text of the third header of a man page — usually the date for the man page. if it's empty, the date content for the refentry is used 📅

header-4

Brief. Fourth header text

Default setting. (blank)

sets the text of the fourth header of a man page. if it's empty, the refmiscinfo content for the refentry is used 🫶

header-5

Brief. Fifth header text

Default setting. (blank)

sets the text of the fifth header of a man page. if it's 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

so normally the source document says which sections each man page belongs to (with manvolnum in refmeta). but in case the source document doesn't say, 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 an XML document that describes text translations (and other locale-specific info) that the stylesheet needs to process the DocBook document 🌍

the text translations this parameter points to always override the default text translations (from the internal parameter localization-file). and if a particular translation isn't present here, the corresponding default translation is used as a fallback. bestie backup plan fr fr 💖

this parameter is mainly for changing certain punctuation characters used when formatting the source document. those punctuation settings are often specific to the source document, but can also depend on the locale. very situational, very chic ✨

and to not use custom text translations, just 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 info) that the stylesheet needs to process the DocBook document 🌸

this parameter is internal to the stylesheet. so if you wanna point to an external XML document with a URI or a file name, use the custom-localization-file parameter instead, ok? 👀

however, inside a custom stylesheet (not on the command-line!) this paramter can be set to the XPath expression document(''), which causes the custom translations directly embedded inside the custom stylesheet to be read. slay 🎀

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. middle name rights revoked 💀

✨ EXAMPLES ✨

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

✨ CONVERSION PROCESS ✨

🦋 Converting to man pages 🦋

DocBook documents get converted to man pages in two steps. two. not one. the duality of woman 💅

  1. the DocBook source is converted by an XSLT stylesheet into an intermediate XML format, Man-XML.

Man-XML is simpler than DocBook and closer to the man page format; it's intended to make the stylesheets' job easier 🫶

the stylesheet for this purpose lives 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. main character energy honestly 👑

  1. Man-XML is converted to the actual man pages by db2x_manxml(1).

the docbook2man command does both of these 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's 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. the Perl one ate, no cap 🔥

🧚 Character set conversion 🧚

when translating XML to legacy ASCII-based formats with poor support for Unicode — like man pages and Texinfo — there's always the problem that Unicode characters in the source document also have to be translated somehow. the struggle is real 😭

a straightforward character set conversion from Unicode does not suffice, because the target character set (usually US-ASCII or ISO Latin-1) doesn't contain common characters like 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 isn't 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 isn't 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. it's built different 💅)

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. obsessed ✨

  1. 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 🇫🇷

this step is applied after utf8trans character mapping, using the iconv(1) encoding conversion tool. both db2x_manxml(1) and db2x_texixml(1) can call iconv(1) automatically when producing their output 🫶

✨ 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 docbook2man — 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. different girl, same name, do NOT mix them up bestie 💀

💀 LIMITATIONS 💀

  • okay so real talk bestie, under the hood there's one long pipeline of programs that your document gets passed through, one after another 🌈 and if any segment of that pipeline fails — even something trivial, like from mistyped program options — the resulting errors can be difficult to decipher 😭 in that case, try running the components of docbook2X separately. like, break it up, give each one its own moment 💅

👑 AUTHOR 👑

Steve Cheng <stevecheng@users.sourceforge.net>.

🦋 SEE ALSO 🦋

The docbook2X manual (in Texinfo or HTML format) fully describes how to convert DocBook to man pages and Texinfo ✨

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 ate 💅 this one's from docbook2X 0.8.8, dated 3 March 2007, and yeah it's the docbook2man(1) page fr fr 🎀 go convert something iconic ✨💖

📦 where this page comes from