Annotation of docbook2mdoc/docbook2mdoc.1, Revision 1.11
1.11 ! schwarze 1: .\" $Id: docbook2mdoc.1,v 1.10 2019/04/09 15:23:51 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.1 kristaps 27: .Op Ar file
28: .Sh DESCRIPTION
29: The
30: .Nm
1.11 ! schwarze 31: utility reads DocBook input from a
1.1 kristaps 32: .Ar file
1.11 ! schwarze 33: and translates it to
1.1 kristaps 34: .Xr mdoc 7
1.6 kristaps 35: and
1.11 ! schwarze 36: .Xr eqn 7 .
! 37: If
1.1 kristaps 38: .Ar file
1.11 ! schwarze 39: is
! 40: .Sq Cm \-
! 41: or omitted, standard input is used.
1.8 schwarze 42: .Pp
1.4 kristaps 43: The arguments are as follows:
44: .Bl -tag -width Ds
45: .It Fl W
1.10 schwarze 46: Report warnings on standard error output, and if any occur, raise the
47: .Sx EXIT STATUS
48: to at least 2.
1.4 kristaps 49: .El
1.2 kristaps 50: .Pp
1.11 ! schwarze 51: A subset of DocBook 5.1 elements are recognized,
! 52: as well as some elements from earlier versions.
! 53: The parser is optimized for robustness even on invalid input,
! 54: always producing some output on a best-effort basis.
! 55: Input is not required to be well-formed, nor to adhere to DocBook
! 56: syntactic or semantic requirements.
! 57: .Pp
! 58: Unknown elements are ignored in the sense that they do not affect
! 59: formatting and only their content is rendered.
! 60: Unknown attributes are silently discarded.
! 61: .Pp
! 62: In addition to DocBook elements, the following constructs are handled:
! 63: .Bl -tag -width Ds
! 64: .It Eo <!
! 65: .Ic DOCTYPE No ...
! 66: .Eo "[ <!" Ic ENTITY Ar name Qo Ar definition Qc Ec "> ]"
! 67: .Ec >
! 68: Internal subset declaration to define an XML entity.
! 69: .It Eo <!
! 70: .Ic DOCTYPE No ...
! 71: .Eo "[ <!" Ic ENTITY Ar name Cm SYSTEM Qo Ar file Qc Ec "> ]"
! 72: .Ec >
! 73: Internal subset declaration to define an XML entity using an external
! 74: .Ar file .
! 75: .It Eo < Ic mml : Ns ... Ec >
! 76: Elements from the MathML namespace.
! 77: These are translated to
1.6 kristaps 78: .Xr eqn 7 .
1.11 ! schwarze 79: .It Eo <
! 80: .Ic xi : Ns Ic include No ...
! 81: .Cm href Ns = Ns Qq Ar file
! 82: .Ec >
! 83: Include an external DocBook file into the current document.
! 84: .El
1.1 kristaps 85: .Sh EXIT STATUS
1.10 schwarze 86: The
87: .Nm
88: utility exits with one of the following values:
89: .Bl -tag -width 2n
90: .It 0
91: No error occurred, and if
92: .Fl W
93: was specified, no warning occurred either.
94: .It 2
95: At least one warning occurred, but no error, and
96: .Fl W
97: was specified.
98: .It 3
99: At least one parsing error occurred.
100: .It 5
101: Invalid command line arguments were specified.
102: No input files have been read.
103: .It 6
104: Memory was exhausted.
105: Parsing was aborted immediately.
106: .El
1.1 kristaps 107: .Sh EXAMPLES
108: To pipe a DocBook document
109: .Pa foo.xml
110: through
111: .Xr mandoc 1
112: and a pager:
113: .Pp
1.9 schwarze 114: .Dl $ docbook2mdoc foo.xml | mandoc -l
1.10 schwarze 115: .Sh DIAGNOSTICS
116: Messages displayed by
117: .Nm
118: follow this format:
119: .Pp
120: .D1 Nm : Ar file : Ns Ar line : Ns Ar column : level : message
121: .Pp
122: The first three fields identify the
123: .Ar file
124: name,
125: .Ar line
126: number, and
127: .Ar column
128: number of the input file where the message was triggered.
129: The line and column numbers start at 1.
130: .Pp
131: Message levels have the following meanings:
132: .Bl -tag -width warning
133: .It Sy fatal
134: An operating system error occurred, typically memory exhaustion,
135: and parsing was aborted immediately.
136: .It Sy error
137: Indicates a risk of information loss or severe misformatting,
138: for example caused by unknown elements or missing include files.
139: .It Sy warning
140: Indicates a risk that the information shown or its formatting
141: may mismatch the author's intent in minor ways.
142: For example, mismatched or missing end tags are classified as warnings.
143: .El
1.1 kristaps 144: .Sh SEE ALSO
145: .Xr mandoc 1 ,
1.7 kristaps 146: .Xr eqn 7 ,
1.1 kristaps 147: .Xr mdoc 7
148: .Sh AUTHORS
149: .Nm
150: was written by
1.11 ! schwarze 151: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
! 152: and
! 153: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
1.1 kristaps 154: .Sh CAVEATS
155: The
156: .Nm
157: utility is experimental.
1.11 ! schwarze 158: Many elements are not recognized yet.
1.2 kristaps 159: .Pp
160: The output
161: .Xr mdoc 7
162: could be much nicer: trailing spaces, superfluous space removal,
163: 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