| 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 |