docbook2mdoc —
convert DocBook to mdoc
docbook2mdoc |
[ -W
]
[-s
section
]
[-T
mdoc |
tree |
lint
]
[file ] |
The
docbook2mdoc utility reads DocBook input
from a
file and translates it to
mdoc(7) and
eqn(7).
If
file is omitted, standard input is used.
The options are as follows:
-
-
-s- Specify the manual page section to be
used as the second argument of the
Dt
macro. Defaults to the content of the first
<manvolnum> element in the first
<refmeta> block, if any, or to
“1” otherwise.
-
-
-T- Select the output mode. The following arguments are supported:
-
-
mdoc- Translate the input to mdoc(7). This is
the default.
-
-
tree- Dump a human-readable representation of the parse tree. Each output
line shows one tree node. Child nodes are indented with respect to
their parent node. The columns are:
- An asterisk if the node starts a new text line, or a hyphen if the
node follows the previous node without intervening
whitespace.
- The node type.
- For text nodes, the text contents. For other nodes, the
attributes, if any.
-
-
lint- Do not produce any output, only error messages. Can be combined with
-W.
-
-
-W- Report warnings on standard error output, and if any occur, raise the
EXIT STATUS to at least
2.
A subset of DocBook 5.1 elements are recognized, as well as some elements from
earlier versions. The parser is optimized for robustness even on invalid
input, always producing some output on a best-effort basis. Input is not
required to be well-formed, nor to adhere to DocBook syntactic or semantic
requirements.
Unknown elements are ignored in the sense that they do not affect formatting and
only their content is rendered. Unknown attributes are silently discarded.
In addition to DocBook elements, the following constructs are handled:
-
-
- <!
DOCTYPE
... [ <!ENTITY
name
“definition”> ]>
- Internal subset declaration to define an XML entity.
-
-
- <!
DOCTYPE
... [ <!ENTITY
name
SYSTEM
“file”> ]>
- Internal subset declaration to define an XML entity using an external
file.
-
-
- <!
DOCTYPE
... [ <!ENTITY
% name
SYSTEM
“file”>
%name ]>
- Internal subset declaration to include an external
file that is supposed to contain entity
declarations.
-
-
- <
mml:...>
- Elements from the MathML namespace. These are translated to
eqn(7).
-
-
- <
xi:include
...
href=“file”>
- Include an external DocBook file into the current document.
The
docbook2mdoc utility exits with one of
the following values:
-
-
- 0
- No error occurred, and if
-W was
specified, no warning occurred either.
-
-
- 2
- At least one warning occurred, but no error, and
-W was specified.
-
-
- 3
- At least one parsing error occurred.
-
-
- 5
- Invalid command line arguments were specified. No input files have been
read.
-
-
- 6
- Memory was exhausted. Parsing was aborted immediately.
To pipe a DocBook document
foo.xml through
mandoc(1) and a pager:
$ docbook2mdoc foo.xml | mandoc
-l
Messages displayed by
docbook2mdoc follow
this format:
docbook2mdoc:
file:line:column:
level:
message
The first three fields identify the
file name,
line number, and
column number of the input file where the
message was triggered. The line and column numbers start at 1.
Message levels have the following meanings:
-
-
- fatal
- An operating system error occurred, typically memory exhaustion, and
parsing was aborted immediately.
-
-
- error
- Indicates a risk of information loss or severe misformatting, for example
caused by unknown elements or missing include files.
-
-
- warning
- Indicates a risk that the information shown or its formatting may mismatch
the author's intent in minor ways. For example, mismatched or missing end
tags are classified as warnings.
mandoc(1),
eqn(7),
mdoc(7)
docbook2mdoc was written by
Kristaps Dzonsons
<
kristaps@bsd.lv>
and
Ingo Schwarze
<
schwarze@openbsd.org>.