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