Annotation of pod2mdoc/pod2mdoc.1, Revision 1.18
1.18 ! schwarze 1: .\" $Id: pod2mdoc.1,v 1.17 2015/02/14 15:34:39 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.18 ! schwarze 17: .Dd $Mdocdate: February 14 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 .
1.17 schwarze 61: If unspecified or if
62: .Ar date
63: is the literal string
64: .Cm Mdocdate ,
1.1 schwarze 65: .Nm
66: uses the file modification date or the current date if reading from
67: standard input.
1.17 schwarze 68: If
69: .Ar date
70: is the literal string
71: .Cm Mdocdate ,
72: .Nm
73: prepends
74: .Qq $Mdocdate:
75: to the date and appends a dollar sign, producing the format used by
76: .Ox
77: .Xr cvs 1 .
1.1 schwarze 78: .It Fl n Ar title
79: Set the document title
1.14 schwarze 80: .Pq Sq \&Dt
1.1 schwarze 81: to
82: .Ar title .
83: If unspecified,
84: .Nm
85: uses the suffix-stripped filename part of
86: .Ar file
87: as a document title or
88: .Ar STDIN
89: if reading from standard input
90: .Pq you probably don't want that .
91: .It Fl s Ar section
92: Set the document section
1.14 schwarze 93: .Pq Sq \&Dt
1.1 schwarze 94: to
95: .Ar section .
96: If unspecified,
97: .Nm
98: uses
99: .Ar 1
100: or, if the input file suffix is
101: .Li .pm ,
102: uses
103: .Ar 3p .
104: .El
1.7 kristaps 105: .Ss Smarts
106: Since
107: .Xr mdoc 7
108: is semantic and
109: .Xr perlpod 1
110: is not,
111: .Nm
112: tries to figure out semantic context for some terms.
113: Specifically, within each paragraph of the SYNOPSIS section, the
114: following occur:
115: .Bl -bullet
1.12 kristaps 116: .It
117: If any number of
118: .Li #include <foo.h>
119: lines are found at the start of a verbatim paragraph, they're rendered
120: with
121: .Sq \&In .
1.16 schwarze 122: .It
123: Other lines starting with
124: .Sq #
125: are rendered with
126: .Sq \&Fd .
1.7 kristaps 127: .It
1.18 ! schwarze 128: Function declarations are rendered with
! 129: .Sq \&Ft ,
! 130: .Sq \&Fo ,
! 131: and
! 132: .Sq \&Fa .
! 133: .It
1.7 kristaps 134: An initial
135: .Li B<>
136: format code is rendered as
137: .Sq \&Nm .
138: .It
139: Subsequent
140: .Li B<>
141: format codes are rendered as
142: .Sq \&Ar .
143: However, if the leading character of a
144: .Li B<>
145: format code is
146: .Sq - ,
147: it is rendered as
148: .Sq \&Fl .
149: Subsequent space-separated terms without leading hyphens, e.g.,
150: .Li B<-foo bar> ,
151: are rendered as
152: .Sq \&Ar .
153: .It
154: Matching
155: .Li \&[
156: and
157: .Li \&]
158: pairs are rendered as
159: .Sq \&Oo
160: and
161: .Sq \&Oc .
162: .El
163: .Pp
164: Thus, the input
165: .Li B<foo> [B<-bar baz>]
166: is rendered as follows:
167: .Bd -literal
1.14 schwarze 168: \&.Nm foo
1.7 kristaps 169: \&.Oo
170: \&.Fl bar Ar baz
171: \&.Oc
172: .Ed
173: .Pp
1.8 kristaps 174: In the NAME section,
1.7 kristaps 175: .Sq \&Nm
176: and
177: .Sq \&Nd
1.8 kristaps 178: macros are inferred from text leading and trailing the last hyphen
1.7 kristaps 179: followed by a space (there may be any number of hyphens preceding the
180: space).
181: The space may occur on either side of the hyphen.
182: Thus,
183: .Li B<foo> - bar
184: will be rendered as follows:
185: .Bd -literal
186: \&.Nm foo
187: \&.Nd bar
188: .Ed
1.8 kristaps 189: .Pp
190: Multiple names separated by a comma are properly handled.
1.9 kristaps 191: .Pp
192: In any section, the
193: .Li L<>
194: format code is considered a
195: .Sq \&Lk
196: link if beginning with
197: .Li http: ,
198: .Li https: ,
199: .Li ftp: ,
200: .Li sftp: ,
201: .Li smb: ,
202: or
203: .Li afs: .
204: If beginning with
205: .Li mailto: ,
206: it is considered a
207: .Sq \&Mt
208: link.
209: Otherwise, it is considered a
210: .Sq \&Xr
211: manpage in section 3P if containing double-colons or section 1
212: otherwise.
213: The section may be overriden as
214: .Li L<foo(5)> .
1.10 kristaps 215: If only a section appears, such as in
216: .Li </section> ,
217: the link is rendered with
218: .Sq \&Sx .
1.14 schwarze 219: .Pp
220: Words followed by
221: .Qq Pq
222: that match function names listed in the SYNOPSIS section are marked up with
223: .Sq \&Fn .
1.18 ! schwarze 224: If they don't match, they are marked up with
! 225: .Sq \&Xr .
! 226: Words not followed by
! 227: .Qq Pq
! 228: that match preprocessor macros #define'd in the SYNOPSIS section
! 229: are marked up with
! 230: .Sq \&Dv .
1.15 schwarze 231: .Pp
232: If the contents of a
233: .Li B<>
1.18 ! schwarze 234: or
! 235: .Li I<>
1.15 schwarze 236: format code matches a type name mentioned in the SYNOPSIS section,
237: it is rendered as
238: .Sq \&Vt .
239: If it matches a function argument name mentioned there,
240: it is rendered as
241: .Sq \&Fa .
1.1 schwarze 242: .Sh EXIT STATUS
243: .Ex -std
1.6 kristaps 244: .Sh EXAMPLES
245: To pipe a POD document
246: .Pa foo.pod
247: through
248: .Xr mandoc 1
249: and a pager:
250: .Pp
251: .Dl % pod2mdoc foo.pod | mandoc | more
1.1 schwarze 252: .Sh COMPATIBILITY
253: If
254: .Fl s
255: is not specified and the suffix for
256: .Ar file
257: is
258: .Li .pm ,
1.4 kristaps 259: .Nm
1.6 kristaps 260: infers a manual section of 3p, not 3 as stipulated in
1.4 kristaps 261: .Xr perlpod 1 .
1.5 kristaps 262: Furthermore, all links in the format of
263: .Li L<Foo::Bar>
264: are assumed to be in section 3p.
1.4 kristaps 265: .Pp
266: If
267: .Nm
268: encounters an
269: .Li =item
270: without the necessary
271: .Li =over ,
272: it will pretend that a prior
273: .Li =over
274: was invoked.
275: However, it will do so silently and not, as
276: .Xr pod2man 1
277: does, append a POD ERRORS section in the output manpage saying so.
1.1 schwarze 278: .Sh SEE ALSO
1.4 kristaps 279: .Xr perlpod 1 ,
1.6 kristaps 280: .Xr pod2man 1 ,
281: .Xr mdoc 7
1.1 schwarze 282: .Sh AUTHORS
283: .Nm
284: was written by
1.14 schwarze 285: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1.1 schwarze 286: .Sh CAVEATS
1.4 kristaps 287: By way of being a presentational language, POD is not well-represented
288: by
1.1 schwarze 289: .Xr mdoc 7 .
1.11 kristaps 290: Semantic content must be inferred and may be wrong.
1.1 schwarze 291: .Pp
292: .Nm
1.4 kristaps 293: only supports the named
294: .Li E<xxx>
295: escapes.
296: HTML names and numbers are silently discarded.
297: .Pp
298: Although most white-space requests in character encodings are properly
299: carried to output, adjacent character escapes with the specific
1.5 kristaps 300: whitespace sequence
1.4 kristaps 301: .Qq Li "B<2>B< 3>"
302: will cause the second space to be lost.
303: .Pp
304: The
305: .Li S<>
306: escape is discarded.
1.10 kristaps 307: .Pp
308: Unless solely a section link, the text and section parts of
309: .Li L<text|link/section>
310: are discarded.
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