docbook2man-spec.pl

Name

docbook2man-spec.pl, manpage_makelinks.pl -- convert DocBook documents to man pages

Synopsis

sgmlspl docbook2man-spec.pl

nsgmls [sgml document] |
sgmlspl docbook2man-spec.pl [--section label] [--date date] [--lowercase | --preserve-case] [--cite-numeral-only | --nocite-numeral-only]

manpage_makelinks.pl < {manpage.links}

Description

docbook2man-spec.pl produces man pages from the refentry markup in SGML DocBook documents.

It is implemented as a sgmlspl spec file. sgmlspl reads ESIS such as that produced by nsgmls from standard input. Only the content in refentry is converted.

The converted man pages are written to the current directory. If a particular refentry does not have any refmeta information, then the man page will be written to standard output.

An additional file manpage.links will contains any aliases of the man pages generated. This file is in the format:

man page [tab] alias manpage
The script manpage_makelinks.pl creates alias man pages that include the content of the principal man page using the .so request.

If the DocBook document has any forward references (xrefs to man pages in the same document), then docbook2man-spec.pl may have to be invoked twice to completely resolve them. The manpage.refs file keeps track of these cross references.

Options

--section label

The default man page section to use when the source document does not specify it (using refmeta /manvolnum markup). The default is 1.

--date date

Sets date as the date to use for man pages that do not specify the date (using docinfo /date markup). If this option is not specified, the default date is the current date.

Note: The date must be given as one argument; i.e. shell quoting may have to be used for dates with spaces.

--lowercase

Man page filenames (specified using refentrytitle) will be case-folded to lowercase.

--preserve-case

No case folding is performed on man page filenames; opposite of --lowercase. This is the default.

--cite-numeral-only

If a man page section consists of one or more digits followed by any non-numeric characters, the non-numeric characters are stripped off when citing the man page in a cross reference. This is the default.

--nocite-numeral-only

Disables the behavior of the option --cite-numeral-only, that is, the man page section numbers are cited unaltered in cross references.

Limitations

XML DocBook is not supported at all because of namecase issues.

Always validate the input document. Although some docbook2X tools try to be resiliant against unrecognized markup, the behavior when encountering such markup is undefined.

The docbook2X tools do not support all of DocBook, or may produce wrong output or even die with markup that is claimed to be supported. These are bugs and you should nag the maintainer about them.

This Perl script (and/or the SGMLS module) seems slow. The code is obfuscated.

See Also

docbook2man
docbook2manxml