Annotation of pod2mdoc/pod2mdoc.1, Revision 1.7
1.7 ! kristaps 1: .\" $Id: pod2mdoc.1,v 1.6 2014/03/24 01:43:42 kristaps Exp $
1.1 schwarze 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.6 kristaps 17: .Dd $Mdocdate: March 24 2014 $
1.1 schwarze 18: .Dt POD2MDOC 1
19: .Os
20: .Sh NAME
21: .Nm pod2mdoc
22: .Nd Convert POD data to mdoc input
23: .Sh SYNOPSIS
24: .Nm pod2man
25: .Op Fl chloqruv
26: .Op Fl d Ar date
27: .Op Fl n Ar title
28: .Op Fl s Ar section
29: .Op Ar file
30: .Sh DESCRIPTION
31: The
32: .Nm
33: utility reads
34: .Ar file
35: and
36: generates
37: .Xr mdoc 7
38: input from
39: .Xr perlpod 1
40: source.
41: If unspecified or
42: .Ar \&- ,
43: .Ar file
44: is taken to be standard input.
45: Its arguments are as follows:
46: .Bl -tag -width Ds
47: .It Fl chloqruv
48: For compatibility with
49: .Xr pod2man 1 .
50: Ignored.
51: .It Fl d Ar date
52: Set the document date
53: .Pq Sq Dd
54: to
55: .Ar date
56: .Po
57: preferrably in
58: .Qq Month Day, Year
59: format
60: .Pc .
61: If unspecified,
62: .Nm
63: uses the file modification date or the current date if reading from
64: standard input.
65: .It Fl n Ar title
66: Set the document title
67: .Pq Sq Dt
68: to
69: .Ar title .
70: If unspecified,
71: .Nm
72: uses the suffix-stripped filename part of
73: .Ar file
74: as a document title or
75: .Ar STDIN
76: if reading from standard input
77: .Pq you probably don't want that .
78: .It Fl s Ar section
79: Set the document section
80: .Pq Sq Dt
81: to
82: .Ar section .
83: If unspecified,
84: .Nm
85: uses
86: .Ar 1
87: or, if the input file suffix is
88: .Li .pm ,
89: uses
90: .Ar 3p .
91: .El
1.7 ! kristaps 92: .Ss Smarts
! 93: Since
! 94: .Xr mdoc 7
! 95: is semantic and
! 96: .Xr perlpod 1
! 97: is not,
! 98: .Nm
! 99: tries to figure out semantic context for some terms.
! 100: Specifically, within each paragraph of the SYNOPSIS section, the
! 101: following occur:
! 102: .Bl -bullet
! 103: .It
! 104: An initial
! 105: .Li B<>
! 106: format code is rendered as
! 107: .Sq \&Nm .
! 108: .It
! 109: Subsequent
! 110: .Li B<>
! 111: format codes are rendered as
! 112: .Sq \&Ar .
! 113: However, if the leading character of a
! 114: .Li B<>
! 115: format code is
! 116: .Sq - ,
! 117: it is rendered as
! 118: .Sq \&Fl .
! 119: Subsequent space-separated terms without leading hyphens, e.g.,
! 120: .Li B<-foo bar> ,
! 121: are rendered as
! 122: .Sq \&Ar .
! 123: .It
! 124: Matching
! 125: .Li \&[
! 126: and
! 127: .Li \&]
! 128: pairs are rendered as
! 129: .Sq \&Oo
! 130: and
! 131: .Sq \&Oc .
! 132: .El
! 133: .Pp
! 134: Thus, the input
! 135: .Li B<foo> [B<-bar baz>]
! 136: is rendered as follows:
! 137: .Bd -literal
! 138: \&.Nm foo
! 139: \&.Oo
! 140: \&.Fl bar Ar baz
! 141: \&.Oc
! 142: .Ed
! 143: .Pp
! 144: In the NAME section, an
! 145: .Sq \&Nm
! 146: and
! 147: .Sq \&Nd
! 148: macro are inferred from text leading and trailing the last hyphen
! 149: followed by a space (there may be any number of hyphens preceding the
! 150: space).
! 151: The space may occur on either side of the hyphen.
! 152: Thus,
! 153: .Li B<foo> - bar
! 154: will be rendered as follows:
! 155: .Bd -literal
! 156: \&.Nm foo
! 157: \&.Nd bar
! 158: .Ed
1.1 schwarze 159: .Sh EXIT STATUS
160: .Ex -std
1.6 kristaps 161: .Sh EXAMPLES
162: To pipe a POD document
163: .Pa foo.pod
164: through
165: .Xr mandoc 1
166: and a pager:
167: .Pp
168: .Dl % pod2mdoc foo.pod | mandoc | more
1.1 schwarze 169: .Sh COMPATIBILITY
170: If
171: .Fl s
172: is not specified and the suffix for
173: .Ar file
174: is
175: .Li .pm ,
1.4 kristaps 176: .Nm
1.6 kristaps 177: infers a manual section of 3p, not 3 as stipulated in
1.4 kristaps 178: .Xr perlpod 1 .
1.5 kristaps 179: Furthermore, all links in the format of
180: .Li L<Foo::Bar>
181: are assumed to be in section 3p.
1.4 kristaps 182: .Pp
183: If
184: .Nm
185: encounters an
186: .Li =item
187: without the necessary
188: .Li =over ,
189: it will pretend that a prior
190: .Li =over
191: was invoked.
192: However, it will do so silently and not, as
193: .Xr pod2man 1
194: does, append a POD ERRORS section in the output manpage saying so.
1.1 schwarze 195: .Sh SEE ALSO
1.4 kristaps 196: .Xr perlpod 1 ,
1.6 kristaps 197: .Xr pod2man 1 ,
198: .Xr mdoc 7
1.1 schwarze 199: .Sh AUTHORS
200: .Nm
201: was written by
202: .Ar Kristaps Dzonsons ,
203: .Mt kristaps@bsd.lv .
204: .Sh CAVEATS
1.4 kristaps 205: By way of being a presentational language, POD is not well-represented
206: by
1.1 schwarze 207: .Xr mdoc 7 .
208: Semantic content will be necessarily lost.
209: .Pp
210: .Nm
1.4 kristaps 211: only supports the named
212: .Li E<xxx>
213: escapes.
214: HTML names and numbers are silently discarded.
215: .Pp
216: Although most white-space requests in character encodings are properly
217: carried to output, adjacent character escapes with the specific
1.5 kristaps 218: whitespace sequence
1.4 kristaps 219: .Qq Li "B<2>B< 3>"
220: will cause the second space to be lost.
221: .Pp
222: The
223: .Li S<>
224: escape is discarded.
1.5 kristaps 225: .Pp
226: Lastly, only the
227: .Li L<Perl::Manpage>
228: and
229: .Li L<manpage(1)>
230: links are understood and properly rendered as
231: .Sq \&Xr .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to pod2mdoc.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / pod2mdoc