docbook2mdoc - convert DocBook to mdoc

---

DOCBOOK2MDOC(1) General Commands Manual DOCBOOK2MDOC(1)

NAME

docbook2mdoc — convert DocBook to mdoc

SYNOPSIS

docbook2mdoc [−W] [−s section] [−T mdoc | tree | lint] [file]

DESCRIPTION

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:

1.

An asterisk if the node starts a new text line, or a hyphen if the node follows the previous node without intervening whitespace.

2.

The node type.

3.

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.

EXIT STATUS

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.

EXAMPLES

To pipe a DocBook document foo.xml through mandoc(1) and a pager:

$ docbook2mdoc foo.xml | mandoc -l

DIAGNOSTICS

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.

SEE ALSO

mandoc(1), eqn(7), mdoc(7)

AUTHORS

docbook2mdoc was written by Kristaps Dzonsons <[email protected]> and
Ingo Schwarze <[email protected]>. GNU May 2, 2019 DOCBOOK2MDOC(1)

---