docbook2mdoc/docbook2mdoc.1 - diff

Return to docbook2mdoc.1 CVS log

Up to [cvsweb.bsd.lv] / docbook2mdoc

Diff for /docbook2mdoc/docbook2mdoc.1 between version 1.10 and 1.13

-version 1.10, 2019/04/09 15:23:51
+version 1.13, 2019/04/23 15:47:23
 Line 1
 Line 1
 Line 1
- .\"     $Id$
+ .\" $Id$
  .\"
  .\" 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
  .\" purpose with or without fee is hereby granted, provided that the above
-Line 19
+Line 20
 Line 19
 Line 20
  .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 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
  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
- is taken to be standard input.
+ is
+ .Sq Cm \-
+ or omitted, standard input is used.
  .Pp
- The arguments are as follows:
+ The options are as follows:
- .Bl -tag -width Ds
+ .Bl -tag -width 2n
+ .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
+ 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
  Report warnings on standard error output, and if any occur, raise the
  .Sx EXIT STATUS
  to at least 2.
  .El
  .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 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
  The
  .Nm
-Line 123  For example, mismatched or missing end tags are classi
+Line 187  For example, mismatched or missing end tags are classi
 Line 123  For example, mismatched or missing end tags are classi
 Line 187  For example, mismatched or missing end tags are classi
  .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 <refentry> domain is accepted.
+ Many elements are not recognized yet.
  .Pp
  The output
  .Xr mdoc 7

CVSweb