=================================================================== RCS file: /cvs/docbook2mdoc/docbook2mdoc.1,v retrieving revision 1.8 retrieving revision 1.11 diff -u -p -r1.8 -r1.11 --- docbook2mdoc/docbook2mdoc.1 2017/06/29 12:11:57 1.8 +++ docbook2mdoc/docbook2mdoc.1 2019/04/09 16:57:29 1.11 @@ -1,6 +1,7 @@ -.\" $Id: docbook2mdoc.1,v 1.8 2017/06/29 12:11:57 schwarze Exp $ +.\" $Id: docbook2mdoc.1,v 1.11 2019/04/09 16:57:29 schwarze Exp $ .\" .\" Copyright (c) 2014 Kristaps Dzonsons +.\" Copyright (c) 2019 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -14,49 +15,95 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 29 2017 $ +.Dd $Mdocdate: April 9 2019 $ .Dt DOCBOOK2MDOC 1 .Os .Sh NAME .Nm docbook2mdoc -.Nd Convert DocBook refentry to mdoc +.Nd convert DocBook to mdoc .Sh SYNOPSIS .Nm docbook2mdoc +.Op Fl W .Op Ar file .Sh DESCRIPTION The .Nm -utility reads +utility reads DocBook input from a .Ar file -and -generates +and translates it to .Xr mdoc 7 and -.Xr eqn 7 -from the section of DocBook source, ignoring other sections. -If unspecified or -.Sq Cm \- , +.Xr eqn 7 . +If .Ar file -is taken to be standard input. +is +.Sq Cm \- +or omitted, standard input is used. .Pp The arguments are as follows: .Bl -tag -width Ds .It Fl W -Output non-fatal warning messages. +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 -.Pq which is discarded -and , which is accepted and converted to +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. +.Pp +Unknown elements are ignored in the sense that they do not affect +formatting and only their content is rendered. +Unknown attributes are silently discarded. +.Pp +In addition to DocBook elements, the following constructs are handled: +.Bl -tag -width Ds +.It Eo ]" +.Ec > +Internal subset declaration to define an XML entity. +.It Eo ]" +.Ec > +Internal subset declaration to define an XML entity using an external +.Ar file . +.It Eo < Ic mml : Ns ... Ec > +Elements from the MathML namespace. +These are translated to .Xr eqn 7 . +.It Eo < +.Ic xi : Ns Ic include No ... +.Cm href Ns = Ns Qq Ar file +.Ec > +Include an external DocBook file into the current document. +.El .Sh EXIT STATUS -.Ex -std +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 @@ -64,7 +111,36 @@ through .Xr mandoc 1 and a pager: .Pp -.Dl % docbook2mdoc foo.xml | mandoc | more +.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 , @@ -72,12 +148,14 @@ and a pager: .Sh AUTHORS .Nm was written by -.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +and +.An Ingo Schwarze Aq Mt schwarze@openbsd.org . .Sh CAVEATS The .Nm utility is experimental. -As such, only a modest subset of the domain is accepted. +Many elements are not recognized yet. .Pp The output .Xr mdoc 7