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:

    : 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 <kristaps@bsd.lv> and Ingo Schwarze <schwarze@openbsd.org>.