version 1.4, 2014/04/30 12:54:26 |
version 1.17, 2019/05/02 12:40:42 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2014 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2014 Kristaps Dzonsons <kristaps@bsd.lv> |
|
.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.Os |
.Os |
.Sh NAME |
.Sh NAME |
.Nm docbook2mdoc |
.Nm docbook2mdoc |
.Nd Convert DocBook refentry to mdoc |
.Nd convert DocBook to mdoc |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.Nm docbook2mdoc |
.Nm docbook2mdoc |
|
.Op Fl W |
|
.Op Fl s Ar section |
|
.Op Fl T Cm mdoc | tree | lint |
.Op Ar file |
.Op Ar file |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm |
.Nm |
utility reads |
utility reads DocBook input from a |
.Ar file |
.Ar file |
and |
and translates it to |
generates |
|
.Xr mdoc 7 |
.Xr mdoc 7 |
from the |
and |
.Aq refentry |
.Xr eqn 7 . |
section of DocBook source, ignoring other sections. |
If |
If unspecified or |
|
.Ar \&- , |
|
.Ar file |
.Ar file |
is taken to be standard input. |
is omitted, standard input is used. |
The arguments are as follows: |
.Pp |
.Bl -tag -width Ds |
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 |
.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 |
.El |
.Pp |
.Pp |
.Nm |
A subset of DocBook 5.1 elements are recognized, |
supports only well-formed XML DocBook V4.x until V5.1. |
as well as some elements from earlier versions. |
SGML DocBook documents may be parsed unless they contain SGML-specific |
The parser is optimized for robustness even on invalid input, |
constructs, such as empty end tags |
always producing some output on a best-effort basis. |
.Li </> . |
Input is not required to be well-formed, nor to adhere to DocBook |
The only non-DocBook construct recognised (and discarded) is |
syntactic or semantic requirements. |
.Aq xi:include \(sl . |
.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 <! |
|
.Ic DOCTYPE No ... |
|
.Eo "[ <!" Ic ENTITY Ar name Qo Ar definition Qc Ec "> ]" |
|
.Ec > |
|
Internal subset declaration to define an XML entity. |
|
.It Eo <! |
|
.Ic DOCTYPE No ... |
|
.Eo "[ <!" Ic ENTITY Ar name Cm SYSTEM Qo Ar file Qc Ec "> ]" |
|
.Ec > |
|
Internal subset declaration to define an XML entity using an external |
|
.Ar file . |
|
.It Eo <! |
|
.Ic DOCTYPE No ... |
|
.Bo |
|
.Eo " <!" Ic ENTITY No % Ar name Cm SYSTEM Qo Ar file Qc Ec > |
|
.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 |
.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 |
.Sh EXAMPLES |
To pipe a DocBook document |
To pipe a DocBook document |
.Pa foo.xml |
.Pa foo.xml |
|
|
.Xr mandoc 1 |
.Xr mandoc 1 |
and a pager: |
and a pager: |
.Pp |
.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 |
.Sh SEE ALSO |
.Xr mandoc 1 , |
.Xr mandoc 1 , |
|
.Xr eqn 7 , |
.Xr mdoc 7 |
.Xr mdoc 7 |
.Sh AUTHORS |
.Sh AUTHORS |
.Nm |
.Nm |
was written by |
was written by |
.Ar Kristaps Dzonsons , |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv |
.Mt kristaps@bsd.lv . |
and |
.Sh CAVEATS |
.An Ingo Schwarze Aq Mt schwarze@openbsd.org . |
The |
|
.Nm |
|
utility is experimental. |
|
As such, only a modest subset of the |
|
.Aq 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. |
|