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