.\" $Id: docbook2mdoc.1,v 1.10 2019/04/09 15:23:51 schwarze Exp $
.\" Copyright (c) 2014 Kristaps Dzonsons <email@example.com>
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.Dd $Mdocdate: April 9 2019 $
.Dt DOCBOOK2MDOC 1
.Nd Convert DocBook refentry to mdoc
.Op Fl W
.Op Ar file
.Xr mdoc 7
.Xr eqn 7
from the <refentry> section of DocBook source, ignoring other sections.
If unspecified or
.Sq Cm \- ,
is taken to be standard input.
The arguments are as follows:
.Bl -tag -width Ds
.It Fl W
Report warnings on standard error output, and if any occur, raise the
.Sx EXIT STATUS
to at least 2.
supports only well-formed XML DocBook V4.x until V5.1.
Some earlier DocBook constructs are accepted as well.
SGML DocBook documents may be parsed unless they contain SGML-specific
constructs, such as empty end tags
.Li </> .
The only non-DocBook constructs recognised are <xi:include\ />
.Pq which is discarded
and <mml:*>, which is accepted and converted to
.Xr eqn 7 .
.Sh EXIT STATUS
utility exits with one of the following values:
.Bl -tag -width 2n
No error occurred, and if
was specified, no warning occurred either.
At least one warning occurred, but no error, and
At least one parsing error occurred.
Invalid command line arguments were specified.
No input files have been read.
Memory was exhausted.
Parsing was aborted immediately.
To pipe a DocBook document
.Xr mandoc 1
and a pager:
.Dl $ docbook2mdoc foo.xml | mandoc -l
Messages displayed by
follow this format:
.D1 Nm : Ar file : Ns Ar line : Ns Ar column : level : message
The first three fields identify the
number of the input file where the message was triggered.
The line and column numbers start at 1.
Message levels have the following meanings:
.Bl -tag -width warning
.It Sy fatal
An operating system error occurred, typically memory exhaustion,
and parsing was aborted immediately.
.It Sy error
Indicates a risk of information loss or severe misformatting,
for example caused by unknown elements or missing include files.
.It Sy 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.
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr eqn 7 ,
.Xr mdoc 7
was written by
.An Kristaps Dzonsons Aq Mt firstname.lastname@example.org .
utility is experimental.
As such, only a modest subset of the <refentry> domain is accepted.
.Xr mdoc 7
could be much nicer: trailing spaces, superfluous space removal,
new-line new-sentence, and other niceties are not used.