=================================================================== RCS file: /cvs/docbook2mdoc/docbook2mdoc.1,v retrieving revision 1.4 retrieving revision 1.15 diff -u -p -r1.4 -r1.15 --- docbook2mdoc/docbook2mdoc.1 2014/04/30 12:54:26 1.4 +++ docbook2mdoc/docbook2mdoc.1 2019/05/01 09:02:25 1.15 @@ -1,6 +1,7 @@ -.\" $Id: docbook2mdoc.1,v 1.4 2014/04/30 12:54:26 kristaps Exp $ +.\" $Id: docbook2mdoc.1,v 1.15 2019/05/01 09:02:25 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,45 +15,149 @@ .\" 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 30 2014 $ +.Dd $Mdocdate: May 1 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 Fl s Ar section +.Op Fl T Cm mdoc | tree | lint .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 -from the -.Aq refentry -section of DocBook source, ignoring other sections. -If unspecified or -.Ar \&- , +and +.Xr eqn 7 . +If .Ar file -is taken to be standard input. -The arguments are as follows: -.Bl -tag -width Ds +is +.Sq Cm \- +or omitted, standard input is used. +.Pp +The options are as follows: +.Bl -tag -width 2n +.It Fl s +Specify the manual page +.Ar section +to be used as the second argument of the +.Ic \&Dt +macro. +Defaults to the content of the first +.Eo < Ic manvolnum Ec > +element in the first +.Eo < Ic refmeta Ec > +block, if any, or to +.Qq 1 +otherwise. +.It Fl T +Select the output mode. +The following arguments are supported: +.Bl -tag -width 4n +.It Cm mdoc +Translate the input to +.Xr mdoc 7 . +This is the default. +.It Cm 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: +.Bl -enum -width 2n +.It +An asterisk if the node starts a new text line, +or a hyphen if the node follows the previous node +without intervening whitespace. +.It +The node type. +.It +For text nodes, the text contents. +For other nodes, the attributes, if any. +.El +.It Cm lint +Do not produce any output, only error messages. +Can be combined with +.Fl W . +.El .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. -SGML DocBook documents may be parsed unless they contain SGML-specific -constructs, such as empty end tags -.Li . -The only non-DocBook construct recognised (and discarded) is -.Aq xi:include \(sl . +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 +.Pf % Ar name No \& +.Bc +.Ec > +Internal subset declaration to include an external +.Ar file +that is supposed to contain entity declarations. +.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 @@ -60,22 +165,51 @@ 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 , .Xr mdoc 7 .Sh AUTHORS .Nm was written by -.Ar Kristaps Dzonsons , -.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 -.Aq refentry -domain is accepted. +Many elements are not recognized yet. .Pp The output .Xr mdoc 7