Annotation of pod2mdoc/pod2mdoc.1, Revision 1.16
1.16 ! schwarze 1: .\" $Id: pod2mdoc.1,v 1.15 2015/02/13 15:35:15 schwarze 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.15 schwarze 17: .Dd $Mdocdate: February 13 2015 $
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
1.14 schwarze 53: .Pq Sq \&Dd
1.1 schwarze 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
1.14 schwarze 67: .Pq Sq \&Dt
1.1 schwarze 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
1.14 schwarze 80: .Pq Sq \&Dt
1.1 schwarze 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
1.12 kristaps 103: .It
104: If any number of
105: .Li #include <foo.h>
106: lines are found at the start of a verbatim paragraph, they're rendered
107: with
108: .Sq \&In .
1.16 ! schwarze 109: .It
! 110: Other lines starting with
! 111: .Sq #
! 112: are rendered with
! 113: .Sq \&Fd .
1.7 kristaps 114: .It
115: An initial
116: .Li B<>
117: format code is rendered as
118: .Sq \&Nm .
119: .It
120: Subsequent
121: .Li B<>
122: format codes are rendered as
123: .Sq \&Ar .
124: However, if the leading character of a
125: .Li B<>
126: format code is
127: .Sq - ,
128: it is rendered as
129: .Sq \&Fl .
130: Subsequent space-separated terms without leading hyphens, e.g.,
131: .Li B<-foo bar> ,
132: are rendered as
133: .Sq \&Ar .
134: .It
135: Matching
136: .Li \&[
137: and
138: .Li \&]
139: pairs are rendered as
140: .Sq \&Oo
141: and
142: .Sq \&Oc .
143: .El
144: .Pp
145: Thus, the input
146: .Li B<foo> [B<-bar baz>]
147: is rendered as follows:
148: .Bd -literal
1.14 schwarze 149: \&.Nm foo
1.7 kristaps 150: \&.Oo
151: \&.Fl bar Ar baz
152: \&.Oc
153: .Ed
154: .Pp
1.8 kristaps 155: In the NAME section,
1.7 kristaps 156: .Sq \&Nm
157: and
158: .Sq \&Nd
1.8 kristaps 159: macros are inferred from text leading and trailing the last hyphen
1.7 kristaps 160: followed by a space (there may be any number of hyphens preceding the
161: space).
162: The space may occur on either side of the hyphen.
163: Thus,
164: .Li B<foo> - bar
165: will be rendered as follows:
166: .Bd -literal
167: \&.Nm foo
168: \&.Nd bar
169: .Ed
1.8 kristaps 170: .Pp
171: Multiple names separated by a comma are properly handled.
1.9 kristaps 172: .Pp
173: In any section, the
174: .Li L<>
175: format code is considered a
176: .Sq \&Lk
177: link if beginning with
178: .Li http: ,
179: .Li https: ,
180: .Li ftp: ,
181: .Li sftp: ,
182: .Li smb: ,
183: or
184: .Li afs: .
185: If beginning with
186: .Li mailto: ,
187: it is considered a
188: .Sq \&Mt
189: link.
190: Otherwise, it is considered a
191: .Sq \&Xr
192: manpage in section 3P if containing double-colons or section 1
193: otherwise.
194: The section may be overriden as
195: .Li L<foo(5)> .
1.10 kristaps 196: If only a section appears, such as in
197: .Li </section> ,
198: the link is rendered with
199: .Sq \&Sx .
1.14 schwarze 200: .Pp
201: Words followed by
202: .Qq Pq
203: that match function names listed in the SYNOPSIS section are marked up with
204: .Sq \&Fn .
1.15 schwarze 205: .Pp
206: If the contents of a
207: .Li B<>
208: format code matches a type name mentioned in the SYNOPSIS section,
209: it is rendered as
210: .Sq \&Vt .
211: If it matches a function argument name mentioned there,
212: it is rendered as
213: .Sq \&Fa .
1.1 schwarze 214: .Sh EXIT STATUS
215: .Ex -std
1.6 kristaps 216: .Sh EXAMPLES
217: To pipe a POD document
218: .Pa foo.pod
219: through
220: .Xr mandoc 1
221: and a pager:
222: .Pp
223: .Dl % pod2mdoc foo.pod | mandoc | more
1.1 schwarze 224: .Sh COMPATIBILITY
225: If
226: .Fl s
227: is not specified and the suffix for
228: .Ar file
229: is
230: .Li .pm ,
1.4 kristaps 231: .Nm
1.6 kristaps 232: infers a manual section of 3p, not 3 as stipulated in
1.4 kristaps 233: .Xr perlpod 1 .
1.5 kristaps 234: Furthermore, all links in the format of
235: .Li L<Foo::Bar>
236: are assumed to be in section 3p.
1.4 kristaps 237: .Pp
238: If
239: .Nm
240: encounters an
241: .Li =item
242: without the necessary
243: .Li =over ,
244: it will pretend that a prior
245: .Li =over
246: was invoked.
247: However, it will do so silently and not, as
248: .Xr pod2man 1
249: does, append a POD ERRORS section in the output manpage saying so.
1.1 schwarze 250: .Sh SEE ALSO
1.4 kristaps 251: .Xr perlpod 1 ,
1.6 kristaps 252: .Xr pod2man 1 ,
253: .Xr mdoc 7
1.1 schwarze 254: .Sh AUTHORS
255: .Nm
256: was written by
1.14 schwarze 257: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1.1 schwarze 258: .Sh CAVEATS
1.4 kristaps 259: By way of being a presentational language, POD is not well-represented
260: by
1.1 schwarze 261: .Xr mdoc 7 .
1.11 kristaps 262: Semantic content must be inferred and may be wrong.
1.1 schwarze 263: .Pp
264: .Nm
1.4 kristaps 265: only supports the named
266: .Li E<xxx>
267: escapes.
268: HTML names and numbers are silently discarded.
269: .Pp
270: Although most white-space requests in character encodings are properly
271: carried to output, adjacent character escapes with the specific
1.5 kristaps 272: whitespace sequence
1.4 kristaps 273: .Qq Li "B<2>B< 3>"
274: will cause the second space to be lost.
275: .Pp
276: The
277: .Li S<>
278: escape is discarded.
1.10 kristaps 279: .Pp
280: Unless solely a section link, the text and section parts of
281: .Li L<text|link/section>
282: are discarded.
CVSweb