version 1.10, 2019/04/09 15:23:51 |
version 1.11, 2019/04/09 16:57:29 |
|
|
.\" $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 W |
|
|
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm |
.Nm |
utility reads |
utility reads DocBook input from a |
.Ar file |
.Ar file |
and generates |
and translates it to |
.Xr mdoc 7 |
.Xr mdoc 7 |
and |
and |
.Xr eqn 7 |
.Xr eqn 7 . |
from the <refentry> section of DocBook source, ignoring other sections. |
If |
If unspecified or |
|
.Sq Cm \- , |
|
.Ar file |
.Ar file |
is taken to be standard input. |
is |
|
.Sq Cm \- |
|
or omitted, standard input is used. |
.Pp |
.Pp |
The arguments are as follows: |
The arguments are as follows: |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
Line 47 Report warnings on standard error output, and if any o |
|
Line 48 Report warnings on standard error output, and if any o |
|
to at least 2. |
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. |
Some earlier DocBook constructs are accepted as well. |
The parser is optimized for robustness even on invalid input, |
SGML DocBook documents may be parsed unless they contain SGML-specific |
always producing some output on a best-effort basis. |
constructs, such as empty end tags |
Input is not required to be well-formed, nor to adhere to DocBook |
.Li </> . |
syntactic or semantic requirements. |
The only non-DocBook constructs recognised are <xi:include\ /> |
.Pp |
.Pq which is discarded |
Unknown elements are ignored in the sense that they do not affect |
and <mml:*>, which is accepted and converted to |
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 mml : Ns ... Ec > |
|
Elements from the MathML namespace. |
|
These are translated to |
.Xr eqn 7 . |
.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 |
The |
The |
.Nm |
.Nm |
Line 123 For example, mismatched or missing end tags are classi |
|
Line 148 For example, mismatched or missing end tags are classi |
|
.Sh AUTHORS |
.Sh AUTHORS |
.Nm |
.Nm |
was written by |
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 |
.Sh CAVEATS |
The |
The |
.Nm |
.Nm |
utility is experimental. |
utility is experimental. |
As such, only a modest subset of the <refentry> domain is accepted. |
Many elements are not recognized yet. |
.Pp |
.Pp |
The output |
The output |
.Xr mdoc 7 |
.Xr mdoc 7 |