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