Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PERLPOD 1" | |
132 | .TH PERLPOD 1 "2002-06-08" "perl v5.8.0" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | perlpod \- the Plain Old Documentation format | |
135 | .SH "DESCRIPTION" | |
136 | .IX Header "DESCRIPTION" | |
137 | Pod is a simple-to-use markup language used for writing documentation | |
138 | for Perl, Perl programs, and Perl modules. | |
139 | .PP | |
140 | Translators are available for converting Pod to various formats | |
141 | like plain text, \s-1HTML\s0, man pages, and more. | |
142 | .PP | |
143 | Pod markup consists of three basic kinds of paragraphs: | |
144 | ordinary, | |
145 | verbatim, and | |
146 | command. | |
147 | .Sh "Ordinary Paragraph" | |
148 | .IX Subsection "Ordinary Paragraph" | |
149 | Most paragraphs in your documentation will be ordinary blocks | |
150 | of text, like this one. You can simply type in your text without | |
151 | any markup whatsoever, and with just a blank line before and | |
152 | after. When it gets formatted, it will undergo minimal formatting, | |
153 | like being rewrapped, probably put into a proportionally spaced | |
154 | font, and maybe even justified. | |
155 | .PP | |
156 | You can use formatting codes in ordinary paragraphs, for \fBbold\fR, | |
157 | \&\fIitalic\fR, \f(CW\*(C`code\-style\*(C'\fR, hyperlinks, and more. Such | |
158 | codes are explained in the "Formatting Codes" | |
159 | section, below. | |
160 | .Sh "Verbatim Paragraph" | |
161 | .IX Subsection "Verbatim Paragraph" | |
162 | Verbatim paragraphs are usually used for presenting a codeblock or | |
163 | other text which does not require any special parsing or formatting, | |
164 | and which shouldn't be wrapped. | |
165 | .PP | |
166 | A verbatim paragraph is distinguished by having its first character | |
167 | be a space or a tab. (And commonly, all its lines begin with spaces | |
168 | and/or tabs.) It should be reproduced exactly, with tabs assumed to | |
169 | be on 8\-column boundaries. There are no special formatting codes, | |
170 | so you can't italicize or anything like that. A \e means \e, and | |
171 | nothing else. | |
172 | .Sh "Command Paragraph" | |
173 | .IX Subsection "Command Paragraph" | |
174 | A command paragraph is used for special treatment of whole chunks | |
175 | of text, usually as headings or parts of lists. | |
176 | .PP | |
177 | All command paragraphs (which are typically only one line long) start | |
178 | with \*(L"=\*(R", followed by an identifier, followed by arbitrary text that | |
179 | the command can use however it pleases. Currently recognized commands | |
180 | are | |
181 | .PP | |
182 | .Vb 12 | |
183 | \& =head1 Heading Text | |
184 | \& =head2 Heading Text | |
185 | \& =head3 Heading Text | |
186 | \& =head4 Heading Text | |
187 | \& =over indentlevel | |
188 | \& =item stuff | |
189 | \& =back | |
190 | \& =cut | |
191 | \& =pod | |
192 | \& =begin format | |
193 | \& =end format | |
194 | \& =for format text... | |
195 | .Ve | |
196 | .PP | |
197 | To explain them each in detail: | |
198 | .ie n .IP """=head1 \f(CIHeading Text\f(CW""" 4 | |
199 | .el .IP "\f(CW=head1 \f(CIHeading Text\f(CW\fR" 4 | |
200 | .IX Item "=head1 Heading Text" | |
201 | .PD 0 | |
202 | .ie n .IP """=head2 \f(CIHeading Text\f(CW""" 4 | |
203 | .el .IP "\f(CW=head2 \f(CIHeading Text\f(CW\fR" 4 | |
204 | .IX Item "=head2 Heading Text" | |
205 | .ie n .IP """=head3 \f(CIHeading Text\f(CW""" 4 | |
206 | .el .IP "\f(CW=head3 \f(CIHeading Text\f(CW\fR" 4 | |
207 | .IX Item "=head3 Heading Text" | |
208 | .ie n .IP """=head4 \f(CIHeading Text\f(CW""" 4 | |
209 | .el .IP "\f(CW=head4 \f(CIHeading Text\f(CW\fR" 4 | |
210 | .IX Item "=head4 Heading Text" | |
211 | .PD | |
212 | Head1 through head4 produce headings, head1 being the highest | |
213 | level. The text in the rest of this paragraph is the content of the | |
214 | heading. For example: | |
215 | .Sp | |
216 | .Vb 1 | |
217 | \& =head2 Object Attributes | |
218 | .Ve | |
219 | .Sp | |
220 | The text \*(L"Object Attributes\*(R" comprises the heading there. (Note that | |
221 | head3 and head4 are recent additions, not supported in older Pod | |
222 | translators.) The text in these heading commands can use | |
223 | formatting codes, as seen here: | |
224 | .Sp | |
225 | .Vb 1 | |
226 | \& =head2 Possible Values for C<$/> | |
227 | .Ve | |
228 | .Sp | |
229 | Such commands are explained in the | |
230 | "Formatting Codes" section, below. | |
231 | .ie n .IP """=over \f(CIindentlevel\f(CW""" 4 | |
232 | .el .IP "\f(CW=over \f(CIindentlevel\f(CW\fR" 4 | |
233 | .IX Item "=over indentlevel" | |
234 | .PD 0 | |
235 | .ie n .IP """=item \f(CIstuff...\f(CW""" 4 | |
236 | .el .IP "\f(CW=item \f(CIstuff...\f(CW\fR" 4 | |
237 | .IX Item "=item stuff..." | |
238 | .ie n .IP """=back""" 4 | |
239 | .el .IP "\f(CW=back\fR" 4 | |
240 | .IX Item "=back" | |
241 | .PD | |
242 | Item, over, and back require a little more explanation: \*(L"=over\*(R" starts | |
243 | a region specifically for the generation of a list using \*(L"=item\*(R" | |
244 | commands, or for indenting (groups of) normal paragraphs. At the end | |
245 | of your list, use \*(L"=back\*(R" to end it. The \fIindentlevel\fR option to | |
246 | \&\*(L"=over\*(R" indicates how far over to indent, generally in ems (where | |
247 | one em is the width of an \*(L"M\*(R" in the document's base font) or roughly | |
248 | comparable units; if there is no \fIindentlevel\fR option, it defaults | |
249 | to four. (And some formatters may just ignore whatever \fIindentlevel\fR | |
250 | you provide.) In the \fIstuff\fR in \f(CW\*(C`=item \f(CIstuff...\f(CW\*(C'\fR, you may | |
251 | use formatting codes, as seen here: | |
252 | .Sp | |
253 | .Vb 1 | |
254 | \& =item Using C<$|> to Control Buffering | |
255 | .Ve | |
256 | .Sp | |
257 | Such commands are explained in the | |
258 | "Formatting Codes" section, below. | |
259 | .Sp | |
260 | Note also that there are some basic rules to using \*(L"=over\*(R" ... | |
261 | \&\*(L"=back\*(R" regions: | |
262 | .RS 4 | |
263 | .IP "\(bu" 4 | |
264 | Don't use \*(L"=item\*(R"s outside of an \*(L"=over\*(R" ... \*(L"=back\*(R" region. | |
265 | .IP "\(bu" 4 | |
266 | The first thing after the \*(L"=over\*(R" command should be an \*(L"=item\*(R", unless | |
267 | there aren't going to be any items at all in this \*(L"=over\*(R" ... \*(L"=back\*(R" | |
268 | region. | |
269 | .IP "\(bu" 4 | |
270 | Don't put "=head\fIn\fR\*(L" commands inside an \*(R"=over\*(L" ... \*(R"=back" region. | |
271 | .IP "\(bu" 4 | |
272 | And perhaps most importantly, keep the items consistent: either use | |
273 | \&\*(L"=item *\*(R" for all of them, to produce bullets; or use \*(L"=item 1.\*(R", | |
274 | \&\*(L"=item 2.\*(R", etc., to produce numbered lists; or use \*(L"=item foo\*(R", | |
275 | \&\*(L"=item bar\*(R", etc. \*(-- namely, things that look nothing like bullets or | |
276 | numbers. | |
277 | .Sp | |
278 | If you start with bullets or numbers, stick with them, as | |
279 | formatters use the first \*(L"=item\*(R" type to decide how to format the | |
280 | list. | |
281 | .RE | |
282 | .RS 4 | |
283 | .RE | |
284 | .ie n .IP """=cut""" 4 | |
285 | .el .IP "\f(CW=cut\fR" 4 | |
286 | .IX Item "=cut" | |
287 | To end a Pod block, use a blank line, | |
288 | then a line beginning with \*(L"=cut\*(R", and a blank | |
289 | line after it. This lets Perl (and the Pod formatter) know that | |
290 | this is where Perl code is resuming. (The blank line before the \*(L"=cut\*(R" | |
291 | is not technically necessary, but many older Pod processors require it.) | |
292 | .ie n .IP """=pod""" 4 | |
293 | .el .IP "\f(CW=pod\fR" 4 | |
294 | .IX Item "=pod" | |
295 | The \*(L"=pod\*(R" command by itself doesn't do much of anything, but it | |
296 | signals to Perl (and Pod formatters) that a Pod block starts here. A | |
297 | Pod block starts with \fIany\fR command paragraph, so a \*(L"=pod\*(R" command is | |
298 | usually used just when you want to start a Pod block with an ordinary | |
299 | paragraph or a verbatim paragraph. For example: | |
300 | .Sp | |
301 | .Vb 1 | |
302 | \& =item stuff() | |
303 | .Ve | |
304 | .Sp | |
305 | .Vb 1 | |
306 | \& This function does stuff. | |
307 | .Ve | |
308 | .Sp | |
309 | .Vb 1 | |
310 | \& =cut | |
311 | .Ve | |
312 | .Sp | |
313 | .Vb 3 | |
314 | \& sub stuff { | |
315 | \& ... | |
316 | \& } | |
317 | .Ve | |
318 | .Sp | |
319 | .Vb 1 | |
320 | \& =pod | |
321 | .Ve | |
322 | .Sp | |
323 | .Vb 1 | |
324 | \& Remember to check its return value, as in: | |
325 | .Ve | |
326 | .Sp | |
327 | .Vb 1 | |
328 | \& stuff() || die "Couldn't do stuff!"; | |
329 | .Ve | |
330 | .Sp | |
331 | .Vb 1 | |
332 | \& =cut | |
333 | .Ve | |
334 | .ie n .IP """=begin \f(CIformatname\f(CW""" 4 | |
335 | .el .IP "\f(CW=begin \f(CIformatname\f(CW\fR" 4 | |
336 | .IX Item "=begin formatname" | |
337 | .PD 0 | |
338 | .ie n .IP """=end \f(CIformatname\f(CW""" 4 | |
339 | .el .IP "\f(CW=end \f(CIformatname\f(CW\fR" 4 | |
340 | .IX Item "=end formatname" | |
341 | .ie n .IP """=for \f(CIformatname\f(CW \f(CItext...\f(CW""" 4 | |
342 | .el .IP "\f(CW=for \f(CIformatname\f(CW \f(CItext...\f(CW\fR" 4 | |
343 | .IX Item "=for formatname text..." | |
344 | .PD | |
345 | For, begin, and end will let you have regions of text/code/data that | |
346 | are not generally interpreted as normal Pod text, but are passed | |
347 | directly to particular formatters, or are otherwise special. A | |
348 | formatter that can use that format will use the region, otherwise it | |
349 | will be completely ignored. | |
350 | .Sp | |
351 | A command "=begin \fIformatname\fR\*(L", some paragraphs, and a | |
352 | command \*(R"=end \fIformatname\fR", mean that the text/data inbetween | |
353 | is meant for formatters that understand the special format | |
354 | called \fIformatname\fR. For example, | |
355 | .Sp | |
356 | .Vb 1 | |
357 | \& =begin html | |
358 | .Ve | |
359 | .Sp | |
360 | .Vb 2 | |
361 | \& <hr> <img src="thang.png"> | |
362 | \& <p> This is a raw HTML paragraph </p> | |
363 | .Ve | |
364 | .Sp | |
365 | .Vb 1 | |
366 | \& =end html | |
367 | .Ve | |
368 | .Sp | |
369 | The command "=for \fIformatname\fR \fItext...\fR" | |
370 | specifies that the remainder of just this paragraph (starting | |
371 | right after \fIformatname\fR) is in that special format. | |
372 | .Sp | |
373 | .Vb 2 | |
374 | \& =for html <hr> <img src="thang.png"> | |
375 | \& <p> This is a raw HTML paragraph </p> | |
376 | .Ve | |
377 | .Sp | |
378 | This means the same thing as the above \*(L"=begin html\*(R" ... \*(L"=end html\*(R" | |
379 | region. | |
380 | .Sp | |
381 | That is, with \*(L"=for\*(R", you can have only one paragraph's worth | |
382 | of text (i.e., the text in \*(L"=foo targetname text...\*(R"), but with | |
383 | \&\*(L"=begin targetname\*(R" ... \*(L"=end targetname\*(R", you can have any amount | |
384 | of stuff inbetween. (Note that there still must be a blank line | |
385 | after the \*(L"=begin\*(R" command and a blank line before the \*(L"=end\*(R" | |
386 | command. | |
387 | .Sp | |
388 | Here are some examples of how to use these: | |
389 | .Sp | |
390 | .Vb 1 | |
391 | \& =begin html | |
392 | .Ve | |
393 | .Sp | |
394 | .Vb 1 | |
395 | \& <br>Figure 1.<br><IMG SRC="figure1.png"><br> | |
396 | .Ve | |
397 | .Sp | |
398 | .Vb 1 | |
399 | \& =end html | |
400 | .Ve | |
401 | .Sp | |
402 | .Vb 1 | |
403 | \& =begin text | |
404 | .Ve | |
405 | .Sp | |
406 | .Vb 4 | |
407 | \& --------------- | |
408 | \& | foo | | |
409 | \& | bar | | |
410 | \& --------------- | |
411 | .Ve | |
412 | .Sp | |
413 | .Vb 1 | |
414 | \& ^^^^ Figure 1. ^^^^ | |
415 | .Ve | |
416 | .Sp | |
417 | .Vb 1 | |
418 | \& =end text | |
419 | .Ve | |
420 | .Sp | |
421 | Some format names that formatters currently are known to accept | |
422 | include \*(L"roff\*(R", \*(L"man\*(R", \*(L"latex\*(R", \*(L"tex\*(R", \*(L"text\*(R", and \*(L"html\*(R". (Some | |
423 | formatters will treat some of these as synonyms.) | |
424 | .Sp | |
425 | A format name of \*(L"comment\*(R" is common for just making notes (presumably | |
426 | to yourself) that won't appear in any formatted version of the Pod | |
427 | document: | |
428 | .Sp | |
429 | .Vb 2 | |
430 | \& =for comment | |
431 | \& Make sure that all the available options are documented! | |
432 | .Ve | |
433 | .Sp | |
434 | Some \fIformatnames\fR will require a leading colon (as in | |
435 | \&\f(CW"=for :formatname"\fR, or | |
436 | \&\f(CW"=begin :formatname" ... "=end :formatname"\fR), | |
437 | to signal that the text is not raw data, but instead \fIis\fR Pod text | |
438 | (i.e., possibly containing formatting codes) that's just not for | |
439 | normal formatting (e.g., may not be a normal-use paragraph, but might | |
440 | be for formatting as a footnote). | |
441 | .PP | |
442 | And don't forget, when using any command, that the command lasts up | |
443 | until the end of its \fIparagraph\fR, not its line. So in the | |
444 | examples below, you can see that every command needs the blank | |
445 | line after it, to end its paragraph. | |
446 | .PP | |
447 | Some examples of lists include: | |
448 | .PP | |
449 | .Vb 1 | |
450 | \& =over | |
451 | .Ve | |
452 | .PP | |
453 | .Vb 1 | |
454 | \& =item * | |
455 | .Ve | |
456 | .PP | |
457 | .Vb 1 | |
458 | \& First item | |
459 | .Ve | |
460 | .PP | |
461 | .Vb 1 | |
462 | \& =item * | |
463 | .Ve | |
464 | .PP | |
465 | .Vb 1 | |
466 | \& Second item | |
467 | .Ve | |
468 | .PP | |
469 | .Vb 1 | |
470 | \& =back | |
471 | .Ve | |
472 | .PP | |
473 | .Vb 1 | |
474 | \& =over | |
475 | .Ve | |
476 | .PP | |
477 | .Vb 1 | |
478 | \& =item Foo() | |
479 | .Ve | |
480 | .PP | |
481 | .Vb 1 | |
482 | \& Description of Foo function | |
483 | .Ve | |
484 | .PP | |
485 | .Vb 1 | |
486 | \& =item Bar() | |
487 | .Ve | |
488 | .PP | |
489 | .Vb 1 | |
490 | \& Description of Bar function | |
491 | .Ve | |
492 | .PP | |
493 | .Vb 1 | |
494 | \& =back | |
495 | .Ve | |
496 | .Sh "Formatting Codes" | |
497 | .IX Subsection "Formatting Codes" | |
498 | In ordinary paragraphs and in some command paragraphs, various | |
499 | formatting codes (a.k.a. \*(L"interior sequences\*(R") can be used: | |
500 | .ie n .IP """I<text>"" \*(-- italic text" 4 | |
501 | .el .IP "\f(CWI<text>\fR \*(-- italic text" 4 | |
502 | .IX Item "I<text> italic text" | |
503 | Used for emphasis ("\f(CW\*(C`be I<careful!>\*(C'\fR\*(L") and parameters | |
504 | (\*(R"\f(CW\*(C`redo I<LABEL>\*(C'\fR") | |
505 | .ie n .IP """B<text>"" \*(-- bold text" 4 | |
506 | .el .IP "\f(CWB<text>\fR \*(-- bold text" 4 | |
507 | .IX Item "B<text> bold text" | |
508 | Used for switches ("\f(CW\*(C`perl's B<\-n> switch\*(C'\fR\*(L"), programs | |
509 | (\*(R"\f(CW\*(C`some systems provide a B<chfn> for that\*(C'\fR\*(L"), | |
510 | emphasis (\*(R"\f(CW\*(C`be B<careful!>\*(C'\fR\*(L"), and so on | |
511 | (\*(R"\f(CW\*(C`and that feature is known as B<autovivification>\*(C'\fR"). | |
512 | .ie n .IP """C<code>"" \*(-- code text" 4 | |
513 | .el .IP "\f(CWC<code>\fR \*(-- code text" 4 | |
514 | .IX Item "C<code> code text" | |
515 | Renders code in a typewriter font, or gives some other indication that | |
516 | this represents program text ("\f(CW\*(C`C<gmtime($^T)>\*(C'\fR\*(L") or some other | |
517 | form of computerese (\*(R"\f(CW\*(C`C<drwxr\-xr\-x>\*(C'\fR"). | |
518 | .ie n .IP """L<name>"" \*(-- a hyperlink" 4 | |
519 | .el .IP "\f(CWL<name>\fR \*(-- a hyperlink" 4 | |
520 | .IX Item "L<name> a hyperlink" | |
521 | There are various syntaxes, listed below. In the syntaxes given, | |
522 | \&\f(CW\*(C`text\*(C'\fR, \f(CW\*(C`name\*(C'\fR, and \f(CW\*(C`section\*(C'\fR cannot contain the characters | |
523 | \&'/' and '|'; and any '<' or '>' should be matched. | |
524 | .RS 4 | |
525 | .IP "\(bu" 4 | |
526 | \&\f(CW\*(C`L<name>\*(C'\fR | |
527 | .Sp | |
528 | Link to a Perl manual page (e.g., \f(CW\*(C`L<Net::Ping>\*(C'\fR). Note | |
529 | that \f(CW\*(C`name\*(C'\fR should not contain spaces. This syntax | |
530 | is also occasionally used for references to \s-1UNIX\s0 man pages, as in | |
531 | \&\f(CW\*(C`L<crontab(5)>\*(C'\fR. | |
532 | .IP "\(bu" 4 | |
533 | \&\f(CW\*(C`L<name/"sec">\*(C'\fR or \f(CW\*(C`L<name/sec>\*(C'\fR | |
534 | .Sp | |
535 | Link to a section in other manual page. E.g., | |
536 | \&\f(CW\*(C`L<perlsyn/"For Loops">\*(C'\fR | |
537 | .IP "\(bu" 4 | |
538 | \&\f(CW\*(C`L</"sec">\*(C'\fR or \f(CW\*(C`L</sec>\*(C'\fR or \f(CW\*(C`L<"sec">\*(C'\fR | |
539 | .Sp | |
540 | Link to a section in this manual page. E.g., | |
541 | \&\f(CW\*(C`L</"Object Methods">\*(C'\fR | |
542 | .RE | |
543 | .RS 4 | |
544 | .Sp | |
545 | A section is started by the named heading or item. For | |
546 | example, \f(CW\*(C`L<perlvar/$.>\*(C'\fR or \f(CW\*(C`L<perlvar/"$.">\*(C'\fR both | |
547 | link to the section started by "\f(CW\*(C`=item $.\*(C'\fR" in perlvar. And | |
548 | \&\f(CW\*(C`L<perlsyn/For Loops>\*(C'\fR or \f(CW\*(C`L<perlsyn/"For Loops">\*(C'\fR | |
549 | both link to the section started by "\f(CW\*(C`=head2 For Loops\*(C'\fR" | |
550 | in perlsyn. | |
551 | .Sp | |
552 | To control what text is used for display, you | |
553 | use "\f(CW\*(C`L<text|...>\*(C'\fR", as in: | |
554 | .IP "\(bu" 4 | |
555 | \&\f(CW\*(C`L<text|name>\*(C'\fR | |
556 | .Sp | |
557 | Link this text to that manual page. E.g., | |
558 | \&\f(CW\*(C`L<Perl Error Messages|perldiag>\*(C'\fR | |
559 | .IP "\(bu" 4 | |
560 | \&\f(CW\*(C`L<text|name/"sec">\*(C'\fR or \f(CW\*(C`L<text|name/sec>\*(C'\fR | |
561 | .Sp | |
562 | Link this text to that section in that manual page. E.g., | |
563 | \&\f(CW\*(C`L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch | |
564 | Statements">\*(C'\fR | |
565 | .IP "\(bu" 4 | |
566 | \&\f(CW\*(C`L<text|/"sec">\*(C'\fR or \f(CW\*(C`L<text|/sec>\*(C'\fR | |
567 | or \f(CW\*(C`L<text|"sec">\*(C'\fR | |
568 | .Sp | |
569 | Link this text to that section in this manual page. E.g., | |
570 | \&\f(CW\*(C`L<the various attributes|/"Member Data">\*(C'\fR | |
571 | .RE | |
572 | .RS 4 | |
573 | .Sp | |
574 | Or you can link to a web page: | |
575 | .IP "\(bu" 4 | |
576 | \&\f(CW\*(C`L<scheme:...>\*(C'\fR | |
577 | .Sp | |
578 | Links to an absolute \s-1URL\s0. For example, | |
579 | \&\f(CW\*(C`L<http://www.perl.org/>\*(C'\fR. But note | |
580 | that there is no corresponding \f(CW\*(C`L<text|scheme:...>\*(C'\fR syntax, for | |
581 | various reasons. | |
582 | .RE | |
583 | .RS 4 | |
584 | .RE | |
585 | .ie n .IP """E<escape>"" \*(-- a character escape" 4 | |
586 | .el .IP "\f(CWE<escape>\fR \*(-- a character escape" 4 | |
587 | .IX Item "E<escape> a character escape" | |
588 | Very similar to \s-1HTML/XML\s0 \f(CW\*(C`&\f(CIfoo\f(CW;\*(C'\fR \*(L"entity references\*(R": | |
589 | .RS 4 | |
590 | .IP "\(bu" 4 | |
591 | \&\f(CW\*(C`E<lt>\*(C'\fR \*(-- a literal < (less than) | |
592 | .IP "\(bu" 4 | |
593 | \&\f(CW\*(C`E<gt>\*(C'\fR \*(-- a literal > (greater than) | |
594 | .IP "\(bu" 4 | |
595 | \&\f(CW\*(C`E<verbar>\*(C'\fR \*(-- a literal | (\fIver\fRtical \fIbar\fR) | |
596 | .IP "\(bu" 4 | |
597 | \&\f(CW\*(C`E<sol>\*(C'\fR = a literal / (\fIsol\fRidus) | |
598 | .Sp | |
599 | The above four are optional except in other formatting codes, | |
600 | notably \f(CW\*(C`L<...>\*(C'\fR, and when preceded by a | |
601 | capital letter. | |
602 | .IP "\(bu" 4 | |
603 | \&\f(CW\*(C`E<htmlname>\*(C'\fR | |
604 | .Sp | |
605 | Some non-numeric \s-1HTML\s0 entity name, such as \f(CW\*(C`E<eacute>\*(C'\fR, | |
606 | meaning the same thing as \f(CW\*(C`é\*(C'\fR in \s-1HTML\s0 \*(-- i.e., a lowercase | |
607 | e with an acute (/\-shaped) accent. | |
608 | .IP "\(bu" 4 | |
609 | \&\f(CW\*(C`E<number>\*(C'\fR | |
610 | .Sp | |
611 | The ASCII/Latin\-1/Unicode character with that number. A | |
612 | leading \*(L"0x\*(R" means that \fInumber\fR is hex, as in | |
613 | \&\f(CW\*(C`E<0x201E>\*(C'\fR. A leading \*(L"0\*(R" means that \fInumber\fR is octal, | |
614 | as in \f(CW\*(C`E<075>\*(C'\fR. Otherwise \fInumber\fR is interpreted as being | |
615 | in decimal, as in \f(CW\*(C`E<181>\*(C'\fR. | |
616 | .Sp | |
617 | Note that older Pod formatters might not recognize octal or | |
618 | hex numeric escapes, and that many formatters cannot reliably | |
619 | render characters above 255. (Some formatters may even have | |
620 | to use compromised renderings of Latin\-1 characters, like | |
621 | rendering \f(CW\*(C`E<eacute>\*(C'\fR as just a plain \*(L"e\*(R".) | |
622 | .RE | |
623 | .RS 4 | |
624 | .RE | |
625 | .ie n .IP """F<filename>"" \*(-- used for filenames" 4 | |
626 | .el .IP "\f(CWF<filename>\fR \*(-- used for filenames" 4 | |
627 | .IX Item "F<filename> used for filenames" | |
628 | Typically displayed in italics. Example: "\f(CW\*(C`F<.cshrc>\*(C'\fR" | |
629 | .ie n .IP """S<text>"" \*(-- text contains non-breaking spaces" 4 | |
630 | .el .IP "\f(CWS<text>\fR \*(-- text contains non-breaking spaces" 4 | |
631 | .IX Item "S<text> text contains non-breaking spaces" | |
632 | This means that the words in \fItext\fR should not be broken | |
633 | across lines. Example: \f(CW\*(C`S<$x\ ?\ $y\ :\ $z>\*(C'\fR. | |
634 | .ie n .IP """X<topic name>"" \*(-- an index entry" 4 | |
635 | .el .IP "\f(CWX<topic name>\fR \*(-- an index entry" 4 | |
636 | .IX Item "X<topic name> an index entry" | |
637 | This is ignored by most formatters, but some may use it for building | |
638 | indexes. It always renders as empty\-string. | |
639 | Example: \f(CW\*(C`X<absolutizing relative URLs>\*(C'\fR | |
640 | .ie n .IP """Z<>"" \*(-- a null (zero\-effect) formatting code" 4 | |
641 | .el .IP "\f(CWZ<>\fR \*(-- a null (zero\-effect) formatting code" 4 | |
642 | .IX Item "Z<> a null (zero-effect) formatting code" | |
643 | This is rarely used. It's one way to get around using an | |
644 | E<...> code sometimes. For example, instead of | |
645 | "\f(CW\*(C`NE<lt>3\*(C'\fR\*(L" (for \*(R"N<3\*(L") you could write | |
646 | \&\*(R"\f(CW\*(C`NZ<><3\*(C'\fR\*(L" (the \*(R"Z<>\*(L" breaks up the \*(R"N\*(L" and | |
647 | the \*(R"<\*(L" so they can't be considered | |
648 | the part of a (fictitious) \*(R"N<...>" code. | |
649 | .PP | |
650 | Most of the time, you will need only a single set of angle brackets to | |
651 | delimit the beginning and end of formatting codes. However, | |
652 | sometimes you will want to put a real right angle bracket (a | |
653 | greater-than sign, '>') inside of a formatting code. This is particularly | |
654 | common when using a formatting code to provide a different font-type for a | |
655 | snippet of code. As with all things in Perl, there is more than | |
656 | one way to do it. One way is to simply escape the closing bracket | |
657 | using an \f(CW\*(C`E\*(C'\fR code: | |
658 | .PP | |
659 | .Vb 1 | |
660 | \& C<$a E<lt>=E<gt> $b> | |
661 | .Ve | |
662 | .PP | |
663 | This will produce: "\f(CW\*(C`$a <=> $b\*(C'\fR" | |
664 | .PP | |
665 | A more readable, and perhaps more \*(L"plain\*(R" way is to use an alternate | |
666 | set of delimiters that doesn't require a single \*(L">\*(R" to be escaped. With | |
667 | the Pod formatters that are standard starting with perl5.5.660, doubled | |
668 | angle brackets (\*(L"<<\*(R" and \*(L">>\*(R") may be used \fIif and only if there is | |
669 | whitespace right after the opening delimiter and whitespace right | |
670 | before the closing delimiter!\fR For example, the following will | |
671 | do the trick: | |
672 | .PP | |
673 | .Vb 1 | |
674 | \& C<< $a <=> $b >> | |
675 | .Ve | |
676 | .PP | |
677 | In fact, you can use as many repeated angle-brackets as you like so | |
678 | long as you have the same number of them in the opening and closing | |
679 | delimiters, and make sure that whitespace immediately follows the last | |
680 | \&'<' of the opening delimiter, and immediately precedes the first '>' | |
681 | of the closing delimiter. (The whitespace is ignored.) So the | |
682 | following will also work: | |
683 | .PP | |
684 | .Vb 2 | |
685 | \& C<<< $a <=> $b >>> | |
686 | \& C<<<< $a <=> $b >>>> | |
687 | .Ve | |
688 | .PP | |
689 | And they all mean exactly the same as this: | |
690 | .PP | |
691 | .Vb 1 | |
692 | \& C<$a E<lt>=E<gt> $b> | |
693 | .Ve | |
694 | .PP | |
695 | As a further example, this means that if you wanted to put these bits of | |
696 | code in \f(CW\*(C`C\*(C'\fR (code) style: | |
697 | .PP | |
698 | .Vb 2 | |
699 | \& open(X, ">>thing.dat") || die $! | |
700 | \& $foo->bar(); | |
701 | .Ve | |
702 | .PP | |
703 | you could do it like so: | |
704 | .PP | |
705 | .Vb 2 | |
706 | \& C<<< open(X, ">>thing.dat") || die $! >>> | |
707 | \& C<< $foo->bar(); >> | |
708 | .Ve | |
709 | .PP | |
710 | which is presumably easier to read than the old way: | |
711 | .PP | |
712 | .Vb 2 | |
713 | \& C<open(X, "E<gt>E<gt>thing.dat") || die $!> | |
714 | \& C<$foo-E<gt>bar(); >> | |
715 | .Ve | |
716 | .PP | |
717 | This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man), | |
718 | and any other pod2xxx or Pod::Xxxx translators that use | |
719 | Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later. | |
720 | .Sh "The Intent" | |
721 | .IX Subsection "The Intent" | |
722 | The intent is simplicity of use, not power of expression. Paragraphs | |
723 | look like paragraphs (block format), so that they stand out | |
724 | visually, and so that I could run them through \f(CW\*(C`fmt\*(C'\fR easily to reformat | |
725 | them (that's F7 in my version of \fBvi\fR, or Esc Q in my version of | |
726 | \&\fBemacs\fR). I wanted the translator to always leave the \f(CW\*(C`'\*(C'\fR and \f(CW\*(C``\*(C'\fR and | |
727 | \&\f(CW\*(C`"\*(C'\fR quotes alone, in verbatim mode, so I could slurp in a | |
728 | working program, shift it over four spaces, and have it print out, er, | |
729 | verbatim. And presumably in a monospace font. | |
730 | .PP | |
731 | The Pod format is not necessarily sufficient for writing a book. Pod | |
732 | is just meant to be an idiot-proof common source for nroff, \s-1HTML\s0, | |
733 | TeX, and other markup languages, as used for online | |
734 | documentation. Translators exist for \fBpod2text\fR, \fBpod2html\fR, | |
735 | \&\fBpod2man\fR (that's for \fInroff\fR\|(1) and \fItroff\fR\|(1)), \fBpod2latex\fR, and | |
736 | \&\fBpod2fm\fR. Various others are available in \s-1CPAN\s0. | |
737 | .Sh "Embedding Pods in Perl Modules" | |
738 | .IX Subsection "Embedding Pods in Perl Modules" | |
739 | You can embed Pod documentation in your Perl modules and scripts. | |
740 | Start your documentation with an empty line, a \*(L"=head1\*(R" command at the | |
741 | beginning, and end it with a \*(L"=cut\*(R" command and an empty line. Perl | |
742 | will ignore the Pod text. See any of the supplied library modules for | |
743 | examples. If you're going to put your Pod at the end of the file, and | |
744 | you're using an _\|_END_\|_ or _\|_DATA_\|_ cut mark, make sure to put an | |
745 | empty line there before the first Pod command. | |
746 | .PP | |
747 | .Vb 1 | |
748 | \& __END__ | |
749 | .Ve | |
750 | .PP | |
751 | .Vb 1 | |
752 | \& =head1 NAME | |
753 | .Ve | |
754 | .PP | |
755 | .Vb 1 | |
756 | \& Time::Local - efficiently compute time from local and GMT time | |
757 | .Ve | |
758 | .PP | |
759 | Without that empty line before the \*(L"=head1\*(R", many translators wouldn't | |
760 | have recognized the \*(L"=head1\*(R" as starting a Pod block. | |
761 | .Sh "Hints for Writing Pod" | |
762 | .IX Subsection "Hints for Writing Pod" | |
763 | .IP "\(bu" 4 | |
764 | The \fBpodchecker\fR command is provided for checking Pod syntax for errors | |
765 | and warnings. For example, it checks for completely blank lines in | |
766 | Pod blocks and for unknown commands and formatting codes. You should | |
767 | still also pass your document through one or more translators and proofread | |
768 | the result, or print out the result and proofread that. Some of the | |
769 | problems found may be bugs in the translators, which you may or may not | |
770 | wish to work around. | |
771 | .IP "\(bu" 4 | |
772 | If you're more familiar with writing in \s-1HTML\s0 than with writing in Pod, you | |
773 | can try your hand at writing documentation in simple \s-1HTML\s0, and converting | |
774 | it to Pod with the experimental Pod::HTML2Pod module, | |
775 | (available in \s-1CPAN\s0), and looking at the resulting code. The experimental | |
776 | Pod::PXML module in \s-1CPAN\s0 might also be useful. | |
777 | .IP "\(bu" 4 | |
778 | Many older Pod translators require the lines before every Pod | |
779 | command and after every Pod command (including \*(L"=cut\*(R"!) to be a blank | |
780 | line. Having something like this: | |
781 | .Sp | |
782 | .Vb 2 | |
783 | \& # - - - - - - - - - - - - | |
784 | \& =item $firecracker->boom() | |
785 | .Ve | |
786 | .Sp | |
787 | .Vb 4 | |
788 | \& This noisily detonates the firecracker object. | |
789 | \& =cut | |
790 | \& sub boom { | |
791 | \& ... | |
792 | .Ve | |
793 | .Sp | |
794 | \&...will make such Pod translators completely fail to see the Pod block | |
795 | at all. | |
796 | .Sp | |
797 | Instead, have it like this: | |
798 | .Sp | |
799 | .Vb 1 | |
800 | \& # - - - - - - - - - - - - | |
801 | .Ve | |
802 | .Sp | |
803 | .Vb 1 | |
804 | \& =item $firecracker->boom() | |
805 | .Ve | |
806 | .Sp | |
807 | .Vb 1 | |
808 | \& This noisily detonates the firecracker object. | |
809 | .Ve | |
810 | .Sp | |
811 | .Vb 1 | |
812 | \& =cut | |
813 | .Ve | |
814 | .Sp | |
815 | .Vb 2 | |
816 | \& sub boom { | |
817 | \& ... | |
818 | .Ve | |
819 | .IP "\(bu" 4 | |
820 | Some older Pod translators require paragraphs (including command | |
821 | paragraphs like \*(L"=head2 Functions\*(R") to be separated by \fIcompletely\fR | |
822 | empty lines. If you have an apparently empty line with some spaces | |
823 | on it, this might not count as a separator for those translators, and | |
824 | that could cause odd formatting. | |
825 | .IP "\(bu" 4 | |
826 | Older translators might add wording around an L<> link, so that | |
827 | \&\f(CW\*(C`L<Foo::Bar>\*(C'\fR may become \*(L"the Foo::Bar manpage\*(R", for example. | |
828 | So you shouldn't write things like \f(CW\*(C`the L<foo> | |
829 | documentation\*(C'\fR, if you want the translated document to read sensibly | |
830 | \&\*(-- instead write \f(CW\*(C`the L<Foo::Bar|Foo::Bar> documentation\*(C'\fR or | |
831 | \&\f(CW\*(C`L<the Foo::Bar documentation|Foo::Bar>\*(C'\fR, to control how the | |
832 | link comes out. | |
833 | .IP "\(bu" 4 | |
834 | Going past the 70th column in a verbatim block might be ungracefully | |
835 | wrapped by some formatters. | |
836 | .SH "SEE ALSO" | |
837 | .IX Header "SEE ALSO" | |
838 | perlpodspec, \*(L"PODs: Embedded Documentation\*(R" in perlsyn, | |
839 | perlnewmod, perldoc, pod2html, pod2man, podchecker. | |
840 | .SH "AUTHOR" | |
841 | .IX Header "AUTHOR" | |
842 | Larry Wall, Sean M. Burke |