table of contents
docbook2x-man(1) | docbook2X | docbook2x-man(1) |
NAME¶
docbook2x-man - Convert DocBook to man pagesSYNOPSIS¶
docbook2x-man
[ options] xml-document
DESCRIPTION¶
docbook2x-man converts the given DocBook XML document into man pages. By default, the man pages will be output to the current directory. Only the refentry content in the DocBook document is converted. (To convert content outside of a refentry, stylesheet customization is required. See the docbook2X package for details.) The docbook2x-man command is a wrapper script for a two-step conversion process. See the section “CONVERSION PROCESS” below for details.OPTIONS¶
The available options are essentially the union of the options from db2x_xsltproc(1) and db2x_manxml(1). Some commonly-used options are listed below:- --encoding=encoding
- Sets the character encoding of the output.
- --string-param parameter=value
- Sets a stylesheet parameter (options that affect how the output looks). See “Stylesheet parameters” below for the parameters that can be 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¶
- uppercase-headings
- Brief. Make headings uppercase?
- manvolnum-cite-numeral-only
- Brief. Man page section citation should use only the
number
- quotes-on-literals
- Brief. Display quotes on literal elements?
- show-comments
- Brief. Display comment elements?
- function-parens
- Brief. Generate parentheses after a function?
- xref-on-link
- Brief. Should link generate a cross-reference?
- header-3
- Brief. Third header text
- header-4
- Brief. Fourth header text
- header-5
- Brief. Fifth header text
- default-manpage-section
- Brief. Default man page section
- custom-localization-file
- Brief. URI of XML document containing custom
localization data
- custom-l10n-data
- Brief. XML document containing custom localization
data
- author-othername-in-middle
- Brief. Is othername in author a middle name?
EXAMPLES¶
$ 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.
http://docbook2x.sourceforge.net/latest/xslt/man/docbook.xsl
- 2.
- Man-XML is converted to the actual man pages by db2x_manxml(1).
$ 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.
- 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.xslNOTES¶
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.LIMITATIONS¶
- •
- Internally there is one long pipeline of programs which your document goes through. If any segment of the pipeline fails (even trivially, like from mistyped program options), the resulting errors can be difficult to decipher — in this case, try running the components of docbook2X separately.
AUTHOR¶
Steve Cheng <stevecheng@users.sourceforge.net>.SEE ALSO¶
db2x_xsltproc(1), db2x_manxml(1), utf8trans(1) 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/⟩ .3 March 2007 | docbook2X 0.8.8 |