Annotation of docbook2mdoc/docbook2mdoc.1, Revision 1.10
1.10 ! schwarze 1: .\" $Id: docbook2mdoc.1,v 1.9 2019/03/17 13:53:42 schwarze Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2014 Kristaps Dzonsons <kristaps@bsd.lv>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
1.10 ! schwarze 17: .Dd $Mdocdate: March 17 2019 $
1.1 kristaps 18: .Dt DOCBOOK2MDOC 1
19: .Os
20: .Sh NAME
21: .Nm docbook2mdoc
22: .Nd Convert DocBook refentry to mdoc
23: .Sh SYNOPSIS
1.2 kristaps 24: .Nm docbook2mdoc
1.9 schwarze 25: .Op Fl W
1.1 kristaps 26: .Op Ar file
27: .Sh DESCRIPTION
28: The
29: .Nm
30: utility reads
31: .Ar file
1.9 schwarze 32: and generates
1.1 kristaps 33: .Xr mdoc 7
1.6 kristaps 34: and
35: .Xr eqn 7
1.8 schwarze 36: from the <refentry> section of DocBook source, ignoring other sections.
1.1 kristaps 37: If unspecified or
1.8 schwarze 38: .Sq Cm \- ,
1.1 kristaps 39: .Ar file
40: is taken to be standard input.
1.8 schwarze 41: .Pp
1.4 kristaps 42: The arguments are as follows:
43: .Bl -tag -width Ds
44: .It Fl W
1.10 ! schwarze 45: Report warnings on standard error output, and if any occur, raise the
! 46: .Sx EXIT STATUS
! 47: to at least 2.
1.4 kristaps 48: .El
1.2 kristaps 49: .Pp
50: .Nm
51: supports only well-formed XML DocBook V4.x until V5.1.
1.5 kristaps 52: Some earlier DocBook constructs are accepted as well.
1.2 kristaps 53: SGML DocBook documents may be parsed unless they contain SGML-specific
54: constructs, such as empty end tags
55: .Li </> .
1.8 schwarze 56: The only non-DocBook constructs recognised are <xi:include\ />
1.6 kristaps 57: .Pq which is discarded
1.8 schwarze 58: and <mml:*>, which is accepted and converted to
1.6 kristaps 59: .Xr eqn 7 .
1.1 kristaps 60: .Sh EXIT STATUS
1.10 ! schwarze 61: The
! 62: .Nm
! 63: utility exits with one of the following values:
! 64: .Bl -tag -width 2n
! 65: .It 0
! 66: No error occurred, and if
! 67: .Fl W
! 68: was specified, no warning occurred either.
! 69: .It 2
! 70: At least one warning occurred, but no error, and
! 71: .Fl W
! 72: was specified.
! 73: .It 3
! 74: At least one parsing error occurred.
! 75: .It 5
! 76: Invalid command line arguments were specified.
! 77: No input files have been read.
! 78: .It 6
! 79: Memory was exhausted.
! 80: Parsing was aborted immediately.
! 81: .El
1.1 kristaps 82: .Sh EXAMPLES
83: To pipe a DocBook document
84: .Pa foo.xml
85: through
86: .Xr mandoc 1
87: and a pager:
88: .Pp
1.9 schwarze 89: .Dl $ docbook2mdoc foo.xml | mandoc -l
1.10 ! schwarze 90: .Sh DIAGNOSTICS
! 91: Messages displayed by
! 92: .Nm
! 93: follow this format:
! 94: .Pp
! 95: .D1 Nm : Ar file : Ns Ar line : Ns Ar column : level : message
! 96: .Pp
! 97: The first three fields identify the
! 98: .Ar file
! 99: name,
! 100: .Ar line
! 101: number, and
! 102: .Ar column
! 103: number of the input file where the message was triggered.
! 104: The line and column numbers start at 1.
! 105: .Pp
! 106: Message levels have the following meanings:
! 107: .Bl -tag -width warning
! 108: .It Sy fatal
! 109: An operating system error occurred, typically memory exhaustion,
! 110: and parsing was aborted immediately.
! 111: .It Sy error
! 112: Indicates a risk of information loss or severe misformatting,
! 113: for example caused by unknown elements or missing include files.
! 114: .It Sy warning
! 115: Indicates a risk that the information shown or its formatting
! 116: may mismatch the author's intent in minor ways.
! 117: For example, mismatched or missing end tags are classified as warnings.
! 118: .El
1.1 kristaps 119: .Sh SEE ALSO
120: .Xr mandoc 1 ,
1.7 kristaps 121: .Xr eqn 7 ,
1.1 kristaps 122: .Xr mdoc 7
123: .Sh AUTHORS
124: .Nm
125: was written by
1.8 schwarze 126: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1.1 kristaps 127: .Sh CAVEATS
128: The
129: .Nm
130: utility is experimental.
1.8 schwarze 131: As such, only a modest subset of the <refentry> domain is accepted.
1.2 kristaps 132: .Pp
133: The output
134: .Xr mdoc 7
135: could be much nicer: trailing spaces, superfluous space removal,
136: new-line new-sentence, and other niceties are not used.
CVSweb