Annotation of docbook2mdoc/docbook2mdoc.1, Revision 1.12
1.12 ! schwarze 1: .\" $Id: docbook2mdoc.1,v 1.11 2019/04/09 16:57:29 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.11 schwarze 18: .Dd $Mdocdate: April 9 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 .
104: .It Eo < Ic mml : Ns ... Ec >
105: Elements from the MathML namespace.
106: These are translated to
1.6 kristaps 107: .Xr eqn 7 .
1.11 schwarze 108: .It Eo <
109: .Ic xi : Ns Ic include No ...
110: .Cm href Ns = Ns Qq Ar file
111: .Ec >
112: Include an external DocBook file into the current document.
113: .El
1.1 kristaps 114: .Sh EXIT STATUS
1.10 schwarze 115: The
116: .Nm
117: utility exits with one of the following values:
118: .Bl -tag -width 2n
119: .It 0
120: No error occurred, and if
121: .Fl W
122: was specified, no warning occurred either.
123: .It 2
124: At least one warning occurred, but no error, and
125: .Fl W
126: was specified.
127: .It 3
128: At least one parsing error occurred.
129: .It 5
130: Invalid command line arguments were specified.
131: No input files have been read.
132: .It 6
133: Memory was exhausted.
134: Parsing was aborted immediately.
135: .El
1.1 kristaps 136: .Sh EXAMPLES
137: To pipe a DocBook document
138: .Pa foo.xml
139: through
140: .Xr mandoc 1
141: and a pager:
142: .Pp
1.9 schwarze 143: .Dl $ docbook2mdoc foo.xml | mandoc -l
1.10 schwarze 144: .Sh DIAGNOSTICS
145: Messages displayed by
146: .Nm
147: follow this format:
148: .Pp
149: .D1 Nm : Ar file : Ns Ar line : Ns Ar column : level : message
150: .Pp
151: The first three fields identify the
152: .Ar file
153: name,
154: .Ar line
155: number, and
156: .Ar column
157: number of the input file where the message was triggered.
158: The line and column numbers start at 1.
159: .Pp
160: Message levels have the following meanings:
161: .Bl -tag -width warning
162: .It Sy fatal
163: An operating system error occurred, typically memory exhaustion,
164: and parsing was aborted immediately.
165: .It Sy error
166: Indicates a risk of information loss or severe misformatting,
167: for example caused by unknown elements or missing include files.
168: .It Sy warning
169: Indicates a risk that the information shown or its formatting
170: may mismatch the author's intent in minor ways.
171: For example, mismatched or missing end tags are classified as warnings.
172: .El
1.1 kristaps 173: .Sh SEE ALSO
174: .Xr mandoc 1 ,
1.7 kristaps 175: .Xr eqn 7 ,
1.1 kristaps 176: .Xr mdoc 7
177: .Sh AUTHORS
178: .Nm
179: was written by
1.11 schwarze 180: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
181: and
182: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
1.1 kristaps 183: .Sh CAVEATS
184: The
185: .Nm
186: utility is experimental.
1.11 schwarze 187: Many elements are not recognized yet.
1.2 kristaps 188: .Pp
189: The output
190: .Xr mdoc 7
191: could be much nicer: trailing spaces, superfluous space removal,
192: 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