.\"	$Id: docbook2mdoc.1,v 1.10 2019/04/09 15:23:51 schwarze Exp $
.\"
.\" Copyright (c) 2014 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" 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
.Os
.Sh NAME
.Nm docbook2mdoc
.Nd Convert DocBook refentry to mdoc
.Sh SYNOPSIS
.Nm docbook2mdoc
.Op Fl W
.Op Ar file
.Sh DESCRIPTION
The
.Nm
utility reads
.Ar file
and generates
.Xr mdoc 7
and
.Xr eqn 7
from the <refentry> section of DocBook source, ignoring other sections.
If unspecified or
.Sq Cm \- ,
.Ar file
is taken to be standard input.
.Pp
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.
.El
.Pp
.Nm
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
The
.Nm
utility exits with one of the following values:
.Bl -tag -width 2n
.It 0
No error occurred, and if
.Fl W
was specified, no warning occurred either.
.It 2
At least one warning occurred, but no error, and
.Fl W
was specified.
.It 3
At least one parsing error occurred.
.It 5
Invalid command line arguments were specified.
No input files have been read.
.It 6
Memory was exhausted.
Parsing was aborted immediately.
.El
.Sh EXAMPLES
To pipe a DocBook document
.Pa foo.xml
through
.Xr mandoc 1
and a pager:
.Pp
.Dl $ docbook2mdoc foo.xml | mandoc -l
.Sh DIAGNOSTICS
Messages displayed by
.Nm
follow this format:
.Pp
.D1 Nm : Ar file : Ns Ar line : Ns Ar column : level : message
.Pp
The first three fields identify the
.Ar file
name,
.Ar line
number, and
.Ar column
number of the input file where the message was triggered.
The line and column numbers start at 1.
.Pp
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.
.El
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr eqn 7 ,
.Xr mdoc 7
.Sh AUTHORS
.Nm
was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
.Sh CAVEATS
The
.Nm
utility is experimental.
As such, only a modest subset of the <refentry> domain is accepted.
.Pp
The output
.Xr mdoc 7
could be much nicer: trailing spaces, superfluous space removal,
new-line new-sentence, and other niceties are not used.