Annotation of docbook2mdoc/docbook2mdoc.1, Revision 1.14
1.14 ! schwarze 1: .\" $Id: docbook2mdoc.1,v 1.13 2019/04/23 15:47:23 schwarze Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2014 Kristaps Dzonsons <kristaps@bsd.lv>
1.11 schwarze 4: .\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
1.1 kristaps 5: .\"
6: .\" Permission to use, copy, modify, and distribute this software for any
7: .\" purpose with or without fee is hereby granted, provided that the above
8: .\" copyright notice and this permission notice appear in all copies.
9: .\"
10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17: .\"
1.14 ! schwarze 18: .Dd $Mdocdate: April 23 2019 $
1.1 kristaps 19: .Dt DOCBOOK2MDOC 1
20: .Os
21: .Sh NAME
22: .Nm docbook2mdoc
1.11 schwarze 23: .Nd convert DocBook to mdoc
1.1 kristaps 24: .Sh SYNOPSIS
1.2 kristaps 25: .Nm docbook2mdoc
1.9 schwarze 26: .Op Fl W
1.12 schwarze 27: .Op Fl T Cm mdoc | tree | lint
1.1 kristaps 28: .Op Ar file
29: .Sh DESCRIPTION
30: The
31: .Nm
1.11 schwarze 32: utility reads DocBook input from a
1.1 kristaps 33: .Ar file
1.11 schwarze 34: and translates it to
1.1 kristaps 35: .Xr mdoc 7
1.6 kristaps 36: and
1.11 schwarze 37: .Xr eqn 7 .
38: If
1.1 kristaps 39: .Ar file
1.11 schwarze 40: is
41: .Sq Cm \-
42: or omitted, standard input is used.
1.8 schwarze 43: .Pp
1.12 schwarze 44: The options are as follows:
45: .Bl -tag -width 2n
46: .It Fl T
47: Select the output mode.
48: The following arguments are supported:
49: .Bl -tag -width 4n
50: .It Cm mdoc
51: Translate the input to
52: .Xr mdoc 7 .
53: This is the default.
54: .It Cm tree
55: Dump a human-readable representation of the parse tree.
56: Each output line shows one tree node.
57: Child nodes are indented with respect to their parent node.
58: The columns are:
59: .Bl -enum -width 2n
60: .It
1.14 ! schwarze 61: An asterisk if the node starts a new text line,
! 62: or a hyphen if the node follows the previous node
1.12 schwarze 63: without intervening whitespace.
64: .It
65: The node type.
66: .It
67: For text nodes, the text contents.
68: For other nodes, the attributes, if any.
69: .El
70: .It Cm lint
71: Do not produce any output, only error messages.
72: Can be combined with
73: .Fl W .
74: .El
1.4 kristaps 75: .It Fl W
1.10 schwarze 76: Report warnings on standard error output, and if any occur, raise the
77: .Sx EXIT STATUS
78: to at least 2.
1.4 kristaps 79: .El
1.2 kristaps 80: .Pp
1.11 schwarze 81: A subset of DocBook 5.1 elements are recognized,
82: as well as some elements from earlier versions.
83: The parser is optimized for robustness even on invalid input,
84: always producing some output on a best-effort basis.
85: Input is not required to be well-formed, nor to adhere to DocBook
86: syntactic or semantic requirements.
87: .Pp
88: Unknown elements are ignored in the sense that they do not affect
89: formatting and only their content is rendered.
90: Unknown attributes are silently discarded.
91: .Pp
92: In addition to DocBook elements, the following constructs are handled:
93: .Bl -tag -width Ds
94: .It Eo <!
95: .Ic DOCTYPE No ...
96: .Eo "[ <!" Ic ENTITY Ar name Qo Ar definition Qc Ec "> ]"
97: .Ec >
98: Internal subset declaration to define an XML entity.
99: .It Eo <!
100: .Ic DOCTYPE No ...
101: .Eo "[ <!" Ic ENTITY Ar name Cm SYSTEM Qo Ar file Qc Ec "> ]"
102: .Ec >
103: Internal subset declaration to define an XML entity using an external
104: .Ar file .
1.13 schwarze 105: .It Eo <!
106: .Ic DOCTYPE No ...
107: .Bo
108: .Eo " <!" Ic ENTITY No % Ar name Cm SYSTEM Qo Ar file Qc Ec >
109: .Pf % Ar name No \&
110: .Bc
111: .Ec >
112: Internal subset declaration to include an external
113: .Ar file
114: that is supposed to contain entity declarations.
1.11 schwarze 115: .It Eo < Ic mml : Ns ... Ec >
116: Elements from the MathML namespace.
117: These are translated to
1.6 kristaps 118: .Xr eqn 7 .
1.11 schwarze 119: .It Eo <
120: .Ic xi : Ns Ic include No ...
121: .Cm href Ns = Ns Qq Ar file
122: .Ec >
123: Include an external DocBook file into the current document.
124: .El
1.1 kristaps 125: .Sh EXIT STATUS
1.10 schwarze 126: The
127: .Nm
128: utility exits with one of the following values:
129: .Bl -tag -width 2n
130: .It 0
131: No error occurred, and if
132: .Fl W
133: was specified, no warning occurred either.
134: .It 2
135: At least one warning occurred, but no error, and
136: .Fl W
137: was specified.
138: .It 3
139: At least one parsing error occurred.
140: .It 5
141: Invalid command line arguments were specified.
142: No input files have been read.
143: .It 6
144: Memory was exhausted.
145: Parsing was aborted immediately.
146: .El
1.1 kristaps 147: .Sh EXAMPLES
148: To pipe a DocBook document
149: .Pa foo.xml
150: through
151: .Xr mandoc 1
152: and a pager:
153: .Pp
1.9 schwarze 154: .Dl $ docbook2mdoc foo.xml | mandoc -l
1.10 schwarze 155: .Sh DIAGNOSTICS
156: Messages displayed by
157: .Nm
158: follow this format:
159: .Pp
160: .D1 Nm : Ar file : Ns Ar line : Ns Ar column : level : message
161: .Pp
162: The first three fields identify the
163: .Ar file
164: name,
165: .Ar line
166: number, and
167: .Ar column
168: number of the input file where the message was triggered.
169: The line and column numbers start at 1.
170: .Pp
171: Message levels have the following meanings:
172: .Bl -tag -width warning
173: .It Sy fatal
174: An operating system error occurred, typically memory exhaustion,
175: and parsing was aborted immediately.
176: .It Sy error
177: Indicates a risk of information loss or severe misformatting,
178: for example caused by unknown elements or missing include files.
179: .It Sy warning
180: Indicates a risk that the information shown or its formatting
181: may mismatch the author's intent in minor ways.
182: For example, mismatched or missing end tags are classified as warnings.
183: .El
1.1 kristaps 184: .Sh SEE ALSO
185: .Xr mandoc 1 ,
1.7 kristaps 186: .Xr eqn 7 ,
1.1 kristaps 187: .Xr mdoc 7
188: .Sh AUTHORS
189: .Nm
190: was written by
1.11 schwarze 191: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
192: and
193: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
1.1 kristaps 194: .Sh CAVEATS
195: The
196: .Nm
197: utility is experimental.
1.11 schwarze 198: Many elements are not recognized yet.
1.2 kristaps 199: .Pp
200: The output
201: .Xr mdoc 7
202: could be much nicer: trailing spaces, superfluous space removal,
203: new-line new-sentence, and other niceties are not used.
CVSweb