| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "PERLPODSPEC 1" |
| 58 |
.TH PERLPODSPEC 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
perlpodspec \- Plain Old Documentation: format specification and notes |
| 65 |
.SH DESCRIPTION |
| 66 |
.IX Header "DESCRIPTION" |
| 67 |
This document is detailed notes on the Pod markup language. Most |
| 68 |
people will only have to read perlpod to know how to write |
| 69 |
in Pod, but this document may answer some incidental questions to do |
| 70 |
with parsing and rendering Pod. |
| 71 |
.PP |
| 72 |
In this document, "must" / "must not", "should" / |
| 73 |
"should not", and "may" have their conventional (cf. RFC 2119) |
| 74 |
meanings: "X must do Y" means that if X doesn't do Y, it's against |
| 75 |
this specification, and should really be fixed. "X should do Y" |
| 76 |
means that it's recommended, but X may fail to do Y, if there's a |
| 77 |
good reason. "X may do Y" is merely a note that X can do Y at |
| 78 |
will (although it is up to the reader to detect any connotation of |
| 79 |
"and I think it would be \fInice\fR if X did Y" versus "it wouldn't |
| 80 |
really \fIbother\fR me if X did Y"). |
| 81 |
.PP |
| 82 |
Notably, when I say "the parser should do Y", the |
| 83 |
parser may fail to do Y, if the calling application explicitly |
| 84 |
requests that the parser \fInot\fR do Y. I often phrase this as |
| 85 |
"the parser should, by default, do Y." This doesn't \fIrequire\fR |
| 86 |
the parser to provide an option for turning off whatever |
| 87 |
feature Y is (like expanding tabs in verbatim paragraphs), although |
| 88 |
it implicates that such an option \fImay\fR be provided. |
| 89 |
.SH "Pod Definitions" |
| 90 |
.IX Header "Pod Definitions" |
| 91 |
Pod is embedded in files, typically Perl source files, although you |
| 92 |
can write a file that's nothing but Pod. |
| 93 |
.PP |
| 94 |
A \fBline\fR in a file consists of zero or more non-newline characters, |
| 95 |
terminated by either a newline or the end of the file. |
| 96 |
.PP |
| 97 |
A \fBnewline sequence\fR is usually a platform-dependent concept, but |
| 98 |
Pod parsers should understand it to mean any of CR (ASCII 13), LF |
| 99 |
(ASCII 10), or a CRLF (ASCII 13 followed immediately by ASCII 10), in |
| 100 |
addition to any other system-specific meaning. The first CR/CRLF/LF |
| 101 |
sequence in the file may be used as the basis for identifying the |
| 102 |
newline sequence for parsing the rest of the file. |
| 103 |
.PP |
| 104 |
A \fBblank line\fR is a line consisting entirely of zero or more spaces |
| 105 |
(ASCII 32) or tabs (ASCII 9), and terminated by a newline or end-of-file. |
| 106 |
A \fBnon-blank line\fR is a line containing one or more characters other |
| 107 |
than space or tab (and terminated by a newline or end-of-file). |
| 108 |
.PP |
| 109 |
(\fINote:\fR Many older Pod parsers did not accept a line consisting of |
| 110 |
spaces/tabs and then a newline as a blank line. The only lines they |
| 111 |
considered blank were lines consisting of \fIno characters at all\fR, |
| 112 |
terminated by a newline.) |
| 113 |
.PP |
| 114 |
\&\fBWhitespace\fR is used in this document as a blanket term for spaces, |
| 115 |
tabs, and newline sequences. (By itself, this term usually refers |
| 116 |
to literal whitespace. That is, sequences of whitespace characters |
| 117 |
in Pod source, as opposed to "E<32>", which is a formatting |
| 118 |
code that \fIdenotes\fR a whitespace character.) |
| 119 |
.PP |
| 120 |
A \fBPod parser\fR is a module meant for parsing Pod (regardless of |
| 121 |
whether this involves calling callbacks or building a parse tree or |
| 122 |
directly formatting it). A \fBPod formatter\fR (or \fBPod translator\fR) |
| 123 |
is a module or program that converts Pod to some other format (HTML, |
| 124 |
plaintext, TeX, PostScript, RTF). A \fBPod processor\fR might be a |
| 125 |
formatter or translator, or might be a program that does something |
| 126 |
else with the Pod (like counting words, scanning for index points, |
| 127 |
etc.). |
| 128 |
.PP |
| 129 |
Pod content is contained in \fBPod blocks\fR. A Pod block starts with a |
| 130 |
line that matches \f(CW\*(C`m/\eA=[a\-zA\-Z]/\*(C'\fR, and continues up to the next line |
| 131 |
that matches \f(CW\*(C`m/\eA=cut/\*(C'\fR or up to the end of the file if there is |
| 132 |
no \f(CW\*(C`m/\eA=cut/\*(C'\fR line. |
| 133 |
.PP |
| 134 |
Note that a parser is not expected to distinguish between something that |
| 135 |
looks like pod, but is in a quoted string, such as a here document. |
| 136 |
.PP |
| 137 |
Within a Pod block, there are \fBPod paragraphs\fR. A Pod paragraph |
| 138 |
consists of non-blank lines of text, separated by one or more blank |
| 139 |
lines. |
| 140 |
.PP |
| 141 |
For purposes of Pod processing, there are four types of paragraphs in |
| 142 |
a Pod block: |
| 143 |
.IP \(bu 4 |
| 144 |
A command paragraph (also called a "directive"). The first line of |
| 145 |
this paragraph must match \f(CW\*(C`m/\eA=[a\-zA\-Z]/\*(C'\fR. Command paragraphs are |
| 146 |
typically one line, as in: |
| 147 |
.Sp |
| 148 |
.Vb 1 |
| 149 |
\& =head1 NOTES |
| 150 |
\& |
| 151 |
\& =item * |
| 152 |
.Ve |
| 153 |
.Sp |
| 154 |
But they may span several (non-blank) lines: |
| 155 |
.Sp |
| 156 |
.Vb 3 |
| 157 |
\& =for comment |
| 158 |
\& Hm, I wonder what it would look like if |
| 159 |
\& you tried to write a BNF for Pod from this. |
| 160 |
\& |
| 161 |
\& =head3 Dr. Strangelove, or: How I Learned to |
| 162 |
\& Stop Worrying and Love the Bomb |
| 163 |
.Ve |
| 164 |
.Sp |
| 165 |
\&\fISome\fR command paragraphs allow formatting codes in their content |
| 166 |
(i.e., after the part that matches \f(CW\*(C`m/\eA=[a\-zA\-Z]\eS*\es*/\*(C'\fR), as in: |
| 167 |
.Sp |
| 168 |
.Vb 1 |
| 169 |
\& =head1 Did You Remember to C<use strict;>? |
| 170 |
.Ve |
| 171 |
.Sp |
| 172 |
In other words, the Pod processing handler for "head1" will apply the |
| 173 |
same processing to "Did You Remember to C<use strict;>?" that it |
| 174 |
would to an ordinary paragraph (i.e., formatting codes like |
| 175 |
"C<...>") are parsed and presumably formatted appropriately, and |
| 176 |
whitespace in the form of literal spaces and/or tabs is not |
| 177 |
significant. |
| 178 |
.IP \(bu 4 |
| 179 |
A \fBverbatim paragraph\fR. The first line of this paragraph must be a |
| 180 |
literal space or tab, and this paragraph must not be inside a "=begin |
| 181 |
\&\fIidentifier\fR", ... "=end \fIidentifier\fR" sequence unless |
| 182 |
"\fIidentifier\fR" begins with a colon (":"). That is, if a paragraph |
| 183 |
starts with a literal space or tab, but \fIis\fR inside a |
| 184 |
"=begin \fIidentifier\fR", ... "=end \fIidentifier\fR" region, then it's |
| 185 |
a data paragraph, unless "\fIidentifier\fR" begins with a colon. |
| 186 |
.Sp |
| 187 |
Whitespace \fIis\fR significant in verbatim paragraphs (although, in |
| 188 |
processing, tabs are probably expanded). |
| 189 |
.IP \(bu 4 |
| 190 |
An \fBordinary paragraph\fR. A paragraph is an ordinary paragraph |
| 191 |
if its first line matches neither \f(CW\*(C`m/\eA=[a\-zA\-Z]/\*(C'\fR nor |
| 192 |
\&\f(CW\*(C`m/\eA[ \et]/\*(C'\fR, \fIand\fR if it's not inside a "=begin \fIidentifier\fR", |
| 193 |
\&... "=end \fIidentifier\fR" sequence unless "\fIidentifier\fR" begins with |
| 194 |
a colon (":"). |
| 195 |
.IP \(bu 4 |
| 196 |
A \fBdata paragraph\fR. This is a paragraph that \fIis\fR inside a "=begin |
| 197 |
\&\fIidentifier\fR" ... "=end \fIidentifier\fR" sequence where |
| 198 |
"\fIidentifier\fR" does \fInot\fR begin with a literal colon (":"). In |
| 199 |
some sense, a data paragraph is not part of Pod at all (i.e., |
| 200 |
effectively it's "out-of-band"), since it's not subject to most kinds |
| 201 |
of Pod parsing; but it is specified here, since Pod |
| 202 |
parsers need to be able to call an event for it, or store it in some |
| 203 |
form in a parse tree, or at least just parse \fIaround\fR it. |
| 204 |
.PP |
| 205 |
For example: consider the following paragraphs: |
| 206 |
.PP |
| 207 |
.Vb 1 |
| 208 |
\& # <\- that\*(Aqs the 0th column |
| 209 |
\& |
| 210 |
\& =head1 Foo |
| 211 |
\& |
| 212 |
\& Stuff |
| 213 |
\& |
| 214 |
\& $foo\->bar |
| 215 |
\& |
| 216 |
\& =cut |
| 217 |
.Ve |
| 218 |
.PP |
| 219 |
Here, "=head1 Foo" and "=cut" are command paragraphs because the first |
| 220 |
line of each matches \f(CW\*(C`m/\eA=[a\-zA\-Z]/\*(C'\fR. "\fI[space][space]\fR\f(CW$foo\fR\->bar" |
| 221 |
is a verbatim paragraph, because its first line starts with a literal |
| 222 |
whitespace character (and there's no "=begin"..."=end" region around). |
| 223 |
.PP |
| 224 |
The "=begin \fIidentifier\fR" ... "=end \fIidentifier\fR" commands stop |
| 225 |
paragraphs that they surround from being parsed as ordinary or verbatim |
| 226 |
paragraphs, if \fIidentifier\fR doesn't begin with a colon. This |
| 227 |
is discussed in detail in the section |
| 228 |
"About Data Paragraphs and "=begin/=end" Regions". |
| 229 |
.SH "Pod Commands" |
| 230 |
.IX Header "Pod Commands" |
| 231 |
This section is intended to supplement and clarify the discussion in |
| 232 |
"Command Paragraph" in perlpod. These are the currently recognized |
| 233 |
Pod commands: |
| 234 |
.IP """=head1"", ""=head2"", ""=head3"", ""=head4"", ""=head5"", ""=head6""" 4 |
| 235 |
.IX Item """=head1"", ""=head2"", ""=head3"", ""=head4"", ""=head5"", ""=head6""" |
| 236 |
This command indicates that the text in the remainder of the paragraph |
| 237 |
is a heading. That text may contain formatting codes. Examples: |
| 238 |
.Sp |
| 239 |
.Vb 1 |
| 240 |
\& =head1 Object Attributes |
| 241 |
\& |
| 242 |
\& =head3 What B<Not> to Do! |
| 243 |
.Ve |
| 244 |
.Sp |
| 245 |
Both \f(CW\*(C`=head5\*(C'\fR and \f(CW\*(C`=head6\*(C'\fR were added in 2020 and might not be |
| 246 |
supported on all Pod parsers. Pod::Simple 3.41 was released on October |
| 247 |
2020 and supports both of these providing support for all |
| 248 |
Pod::Simple\-based Pod parsers. |
| 249 |
.IP """=pod""" 4 |
| 250 |
.IX Item """=pod""" |
| 251 |
This command indicates that this paragraph begins a Pod block. (If we |
| 252 |
are already in the middle of a Pod block, this command has no effect at |
| 253 |
all.) If there is any text in this command paragraph after "=pod", |
| 254 |
it must be ignored. Examples: |
| 255 |
.Sp |
| 256 |
.Vb 1 |
| 257 |
\& =pod |
| 258 |
\& |
| 259 |
\& This is a plain Pod paragraph. |
| 260 |
\& |
| 261 |
\& =pod This text is ignored. |
| 262 |
.Ve |
| 263 |
.IP """=cut""" 4 |
| 264 |
.IX Item """=cut""" |
| 265 |
This command indicates that this line is the end of this previously |
| 266 |
started Pod block. If there is any text after "=cut" on the line, it must be |
| 267 |
ignored. Examples: |
| 268 |
.Sp |
| 269 |
.Vb 1 |
| 270 |
\& =cut |
| 271 |
\& |
| 272 |
\& =cut The documentation ends here. |
| 273 |
\& |
| 274 |
\& =cut |
| 275 |
\& # This is the first line of program text. |
| 276 |
\& sub foo { # This is the second. |
| 277 |
.Ve |
| 278 |
.Sp |
| 279 |
It is an error to try to \fIstart\fR a Pod block with a "=cut" command. In |
| 280 |
that case, the Pod processor must halt parsing of the input file, and |
| 281 |
must by default emit a warning. |
| 282 |
.IP """=over""" 4 |
| 283 |
.IX Item """=over""" |
| 284 |
This command indicates that this is the start of a list/indent |
| 285 |
region. If there is any text following the "=over", it must consist |
| 286 |
of only a nonzero positive numeral. The semantics of this numeral is |
| 287 |
explained in the "About =over...=back Regions" section, further |
| 288 |
below. Formatting codes are not expanded. Examples: |
| 289 |
.Sp |
| 290 |
.Vb 1 |
| 291 |
\& =over 3 |
| 292 |
\& |
| 293 |
\& =over 3.5 |
| 294 |
\& |
| 295 |
\& =over |
| 296 |
.Ve |
| 297 |
.IP """=item""" 4 |
| 298 |
.IX Item """=item""" |
| 299 |
This command indicates that an item in a list begins here. Formatting |
| 300 |
codes are processed. The semantics of the (optional) text in the |
| 301 |
remainder of this paragraph are |
| 302 |
explained in the "About =over...=back Regions" section, further |
| 303 |
below. Examples: |
| 304 |
.Sp |
| 305 |
.Vb 1 |
| 306 |
\& =item |
| 307 |
\& |
| 308 |
\& =item * |
| 309 |
\& |
| 310 |
\& =item * |
| 311 |
\& |
| 312 |
\& =item 14 |
| 313 |
\& |
| 314 |
\& =item 3. |
| 315 |
\& |
| 316 |
\& =item C<< $thing\->stuff(I<dodad>) >> |
| 317 |
\& |
| 318 |
\& =item For transporting us beyond seas to be tried for pretended |
| 319 |
\& offenses |
| 320 |
\& |
| 321 |
\& =item He is at this time transporting large armies of foreign |
| 322 |
\& mercenaries to complete the works of death, desolation and |
| 323 |
\& tyranny, already begun with circumstances of cruelty and perfidy |
| 324 |
\& scarcely paralleled in the most barbarous ages, and totally |
| 325 |
\& unworthy the head of a civilized nation. |
| 326 |
.Ve |
| 327 |
.IP """=back""" 4 |
| 328 |
.IX Item """=back""" |
| 329 |
This command indicates that this is the end of the region begun |
| 330 |
by the most recent "=over" command. It permits no text after the |
| 331 |
"=back" command. |
| 332 |
.IP """=begin formatname""" 4 |
| 333 |
.IX Item """=begin formatname""" |
| 334 |
.PD 0 |
| 335 |
.IP """=begin formatname parameter""" 4 |
| 336 |
.IX Item """=begin formatname parameter""" |
| 337 |
.PD |
| 338 |
This marks the following paragraphs (until the matching "=end |
| 339 |
formatname") as being for some special kind of processing. Unless |
| 340 |
"formatname" begins with a colon, the contained non-command |
| 341 |
paragraphs are data paragraphs. But if "formatname" \fIdoes\fR begin |
| 342 |
with a colon, then non-command paragraphs are ordinary paragraphs |
| 343 |
or data paragraphs. This is discussed in detail in the section |
| 344 |
"About Data Paragraphs and "=begin/=end" Regions". |
| 345 |
.Sp |
| 346 |
It is advised that formatnames match the regexp |
| 347 |
\&\f(CW\*(C`m/\eA:?[\-a\-zA\-Z0\-9_]+\ez/\*(C'\fR. Everything following whitespace after the |
| 348 |
formatname is a parameter that may be used by the formatter when dealing |
| 349 |
with this region. This parameter must not be repeated in the "=end" |
| 350 |
paragraph. Implementors should anticipate future expansion in the |
| 351 |
semantics and syntax of the first parameter to "=begin"/"=end"/"=for". |
| 352 |
.IP """=end formatname""" 4 |
| 353 |
.IX Item """=end formatname""" |
| 354 |
This marks the end of the region opened by the matching |
| 355 |
"=begin formatname" region. If "formatname" is not the formatname |
| 356 |
of the most recent open "=begin formatname" region, then this |
| 357 |
is an error, and must generate an error message. This |
| 358 |
is discussed in detail in the section |
| 359 |
"About Data Paragraphs and "=begin/=end" Regions". |
| 360 |
.IP """=for formatname text...""" 4 |
| 361 |
.IX Item """=for formatname text...""" |
| 362 |
This is synonymous with: |
| 363 |
.Sp |
| 364 |
.Vb 1 |
| 365 |
\& =begin formatname |
| 366 |
\& |
| 367 |
\& text... |
| 368 |
\& |
| 369 |
\& =end formatname |
| 370 |
.Ve |
| 371 |
.Sp |
| 372 |
That is, it creates a region consisting of a single paragraph; that |
| 373 |
paragraph is to be treated as a normal paragraph if "formatname" |
| 374 |
begins with a ":"; if "formatname" \fIdoesn't\fR begin with a colon, |
| 375 |
then "text..." will constitute a data paragraph. There is no way |
| 376 |
to use "=for formatname text..." to express "text..." as a verbatim |
| 377 |
paragraph. |
| 378 |
.IP """=encoding encodingname""" 4 |
| 379 |
.IX Item """=encoding encodingname""" |
| 380 |
This command, which should occur early in the document (at least |
| 381 |
before any non-US-ASCII data!), declares that this document is |
| 382 |
encoded in the encoding \fIencodingname\fR, which must be |
| 383 |
an encoding name that Encode recognizes. (Encode's list |
| 384 |
of supported encodings, in Encode::Supported, is useful here.) |
| 385 |
If the Pod parser cannot decode the declared encoding, it |
| 386 |
should emit a warning and may abort parsing the document |
| 387 |
altogether. |
| 388 |
.Sp |
| 389 |
A document having more than one "=encoding" line should be |
| 390 |
considered an error. Pod processors may silently tolerate this if |
| 391 |
the not-first "=encoding" lines are just duplicates of the |
| 392 |
first one (e.g., if there's a "=encoding utf8" line, and later on |
| 393 |
another "=encoding utf8" line). But Pod processors should complain if |
| 394 |
there are contradictory "=encoding" lines in the same document |
| 395 |
(e.g., if there is a "=encoding utf8" early in the document and |
| 396 |
"=encoding big5" later). Pod processors that recognize BOMs |
| 397 |
may also complain if they see an "=encoding" line |
| 398 |
that contradicts the BOM (e.g., if a document with a UTF\-16LE |
| 399 |
BOM has an "=encoding shiftjis" line). |
| 400 |
.PP |
| 401 |
If a Pod processor sees any command other than the ones listed |
| 402 |
above (like "=head", or "=haed1", or "=stuff", or "=cuttlefish", |
| 403 |
or "=w123"), that processor must by default treat this as an |
| 404 |
error. It must not process the paragraph beginning with that |
| 405 |
command, must by default warn of this as an error, and may |
| 406 |
abort the parse. A Pod parser may allow a way for particular |
| 407 |
applications to add to the above list of known commands, and to |
| 408 |
stipulate, for each additional command, whether formatting |
| 409 |
codes should be processed. |
| 410 |
.PP |
| 411 |
Future versions of this specification may add additional |
| 412 |
commands. |
| 413 |
.SH "Pod Formatting Codes" |
| 414 |
.IX Header "Pod Formatting Codes" |
| 415 |
(Note that in previous drafts of this document and of perlpod, |
| 416 |
formatting codes were referred to as "interior sequences", and |
| 417 |
this term may still be found in the documentation for Pod parsers, |
| 418 |
and in error messages from Pod processors.) |
| 419 |
.PP |
| 420 |
There are two syntaxes for formatting codes: |
| 421 |
.IP \(bu 4 |
| 422 |
A formatting code starts with a capital letter (just US-ASCII [A\-Z]) |
| 423 |
followed by a "<", any number of characters, and ending with the first |
| 424 |
matching ">". Examples: |
| 425 |
.Sp |
| 426 |
.Vb 1 |
| 427 |
\& That\*(Aqs what I<you> think! |
| 428 |
\& |
| 429 |
\& What\*(Aqs C<CORE::dump()> for? |
| 430 |
\& |
| 431 |
\& X<C<chmod> and C<unlink()> Under Different Operating Systems> |
| 432 |
.Ve |
| 433 |
.IP \(bu 4 |
| 434 |
A formatting code starts with a capital letter (just US-ASCII [A\-Z]) |
| 435 |
followed by two or more "<"'s, one or more whitespace characters, |
| 436 |
any number of characters, one or more whitespace characters, |
| 437 |
and ending with the first matching sequence of two or more ">"'s, where |
| 438 |
the number of ">"'s equals the number of "<"'s in the opening of this |
| 439 |
formatting code. Examples: |
| 440 |
.Sp |
| 441 |
.Vb 1 |
| 442 |
\& That\*(Aqs what I<< you >> think! |
| 443 |
\& |
| 444 |
\& C<<< open(X, ">>thing.dat") || die $! >>> |
| 445 |
\& |
| 446 |
\& B<< $foo\->bar(); >> |
| 447 |
.Ve |
| 448 |
.Sp |
| 449 |
With this syntax, the whitespace character(s) after the "C<<<" |
| 450 |
and before the ">>>" (or whatever letter) are \fInot\fR renderable. They |
| 451 |
do not signify whitespace, are merely part of the formatting codes |
| 452 |
themselves. That is, these are all synonymous: |
| 453 |
.Sp |
| 454 |
.Vb 7 |
| 455 |
\& C<thing> |
| 456 |
\& C<< thing >> |
| 457 |
\& C<< thing >> |
| 458 |
\& C<<< thing >>> |
| 459 |
\& C<<<< |
| 460 |
\& thing |
| 461 |
\& >>>> |
| 462 |
.Ve |
| 463 |
.Sp |
| 464 |
and so on. |
| 465 |
.Sp |
| 466 |
Finally, the multiple-angle-bracket form does \fInot\fR alter the interpretation |
| 467 |
of nested formatting codes, meaning that the following four example lines are |
| 468 |
identical in meaning: |
| 469 |
.Sp |
| 470 |
.Vb 1 |
| 471 |
\& B<example: C<$a E<lt>=E<gt> $b>> |
| 472 |
\& |
| 473 |
\& B<example: C<< $a <=> $b >>> |
| 474 |
\& |
| 475 |
\& B<example: C<< $a E<lt>=E<gt> $b >>> |
| 476 |
\& |
| 477 |
\& B<<< example: C<< $a E<lt>=E<gt> $b >> >>> |
| 478 |
.Ve |
| 479 |
.PP |
| 480 |
In parsing Pod, a notably tricky part is the correct parsing of |
| 481 |
(potentially nested!) formatting codes. Implementors should |
| 482 |
consult the code in the \f(CW\*(C`parse_text\*(C'\fR routine in Pod::Parser as an |
| 483 |
example of a correct implementation. |
| 484 |
.ie n .IP """I<text>"" \-\- italic text" 4 |
| 485 |
.el .IP "\f(CWI<text>\fR \-\- italic text" 4 |
| 486 |
.IX Item "I<text> -- italic text" |
| 487 |
See the brief discussion in "Formatting Codes" in perlpod. |
| 488 |
.ie n .IP """B<text>"" \-\- bold text" 4 |
| 489 |
.el .IP "\f(CWB<text>\fR \-\- bold text" 4 |
| 490 |
.IX Item "B<text> -- bold text" |
| 491 |
See the brief discussion in "Formatting Codes" in perlpod. |
| 492 |
.ie n .IP """C<code>"" \-\- code text" 4 |
| 493 |
.el .IP "\f(CWC<code>\fR \-\- code text" 4 |
| 494 |
.IX Item "C<code> -- code text" |
| 495 |
See the brief discussion in "Formatting Codes" in perlpod. |
| 496 |
.ie n .IP """F<filename>"" \-\- style for filenames" 4 |
| 497 |
.el .IP "\f(CWF<filename>\fR \-\- style for filenames" 4 |
| 498 |
.IX Item "F<filename> -- style for filenames" |
| 499 |
See the brief discussion in "Formatting Codes" in perlpod. |
| 500 |
.ie n .IP """X<topic name>"" \-\- an index entry" 4 |
| 501 |
.el .IP "\f(CWX<topic name>\fR \-\- an index entry" 4 |
| 502 |
.IX Item "X<topic name> -- an index entry" |
| 503 |
See the brief discussion in "Formatting Codes" in perlpod. |
| 504 |
.Sp |
| 505 |
This code is unusual in that most formatters completely discard |
| 506 |
this code and its content. Other formatters will render it with |
| 507 |
invisible codes that can be used in building an index of |
| 508 |
the current document. |
| 509 |
.ie n .IP """Z<>"" \-\- a null (zero-effect) formatting code" 4 |
| 510 |
.el .IP "\f(CWZ<>\fR \-\- a null (zero-effect) formatting code" 4 |
| 511 |
.IX Item "Z<> -- a null (zero-effect) formatting code" |
| 512 |
Discussed briefly in "Formatting Codes" in perlpod. |
| 513 |
.Sp |
| 514 |
This code is unusual in that it should have no content. That is, |
| 515 |
a processor may complain if it sees \f(CW\*(C`Z<potatoes>\*(C'\fR. Whether |
| 516 |
or not it complains, the \fIpotatoes\fR text should ignored. |
| 517 |
.ie n .IP """L<name>"" \-\- a hyperlink" 4 |
| 518 |
.el .IP "\f(CWL<name>\fR \-\- a hyperlink" 4 |
| 519 |
.IX Item "L<name> -- a hyperlink" |
| 520 |
The complicated syntaxes of this code are discussed at length in |
| 521 |
"Formatting Codes" in perlpod, and implementation details are |
| 522 |
discussed below, in "About L<...> Codes". Parsing the |
| 523 |
contents of L<content> is tricky. Notably, the content has to be |
| 524 |
checked for whether it looks like a URL, or whether it has to be split |
| 525 |
on literal "|" and/or "/" (in the right order!), and so on, |
| 526 |
\&\fIbefore\fR E<...> codes are resolved. |
| 527 |
.ie n .IP """E<escape>"" \-\- a character escape" 4 |
| 528 |
.el .IP "\f(CWE<escape>\fR \-\- a character escape" 4 |
| 529 |
.IX Item "E<escape> -- a character escape" |
| 530 |
See "Formatting Codes" in perlpod, and several points in |
| 531 |
"Notes on Implementing Pod Processors". |
| 532 |
.ie n .IP """S<text>"" \-\- text contains non-breaking spaces" 4 |
| 533 |
.el .IP "\f(CWS<text>\fR \-\- text contains non-breaking spaces" 4 |
| 534 |
.IX Item "S<text> -- text contains non-breaking spaces" |
| 535 |
This formatting code is syntactically simple, but semantically |
| 536 |
complex. What it means is that each space in the printable |
| 537 |
content of this code signifies a non-breaking space. |
| 538 |
.Sp |
| 539 |
Consider: |
| 540 |
.Sp |
| 541 |
.Vb 1 |
| 542 |
\& C<$x ? $y : $z> |
| 543 |
\& |
| 544 |
\& S<C<$x ? $y : $z>> |
| 545 |
.Ve |
| 546 |
.Sp |
| 547 |
Both signify the monospace (c[ode] style) text consisting of |
| 548 |
"$x", one space, "?", one space, ":", one space, "$z". The |
| 549 |
difference is that in the latter, with the S code, those spaces |
| 550 |
are not "normal" spaces, but instead are non-breaking spaces. |
| 551 |
.PP |
| 552 |
If a Pod processor sees any formatting code other than the ones |
| 553 |
listed above (as in "N<...>", or "Q<...>", etc.), that |
| 554 |
processor must by default treat this as an error. |
| 555 |
A Pod parser may allow a way for particular |
| 556 |
applications to add to the above list of known formatting codes; |
| 557 |
a Pod parser might even allow a way to stipulate, for each additional |
| 558 |
command, whether it requires some form of special processing, as |
| 559 |
L<...> does. |
| 560 |
.PP |
| 561 |
Future versions of this specification may add additional |
| 562 |
formatting codes. |
| 563 |
.PP |
| 564 |
Historical note: A few older Pod processors would not see a ">" as |
| 565 |
closing a "C<" code, if the ">" was immediately preceded by |
| 566 |
a "\-". This was so that this: |
| 567 |
.PP |
| 568 |
.Vb 1 |
| 569 |
\& C<$foo\->bar> |
| 570 |
.Ve |
| 571 |
.PP |
| 572 |
would parse as equivalent to this: |
| 573 |
.PP |
| 574 |
.Vb 1 |
| 575 |
\& C<$foo\-E<gt>bar> |
| 576 |
.Ve |
| 577 |
.PP |
| 578 |
instead of as equivalent to a "C" formatting code containing |
| 579 |
only "$foo\-", and then a "bar>" outside the "C" formatting code. This |
| 580 |
problem has since been solved by the addition of syntaxes like this: |
| 581 |
.PP |
| 582 |
.Vb 1 |
| 583 |
\& C<< $foo\->bar >> |
| 584 |
.Ve |
| 585 |
.PP |
| 586 |
Compliant parsers must not treat "\->" as special. |
| 587 |
.PP |
| 588 |
Formatting codes absolutely cannot span paragraphs. If a code is |
| 589 |
opened in one paragraph, and no closing code is found by the end of |
| 590 |
that paragraph, the Pod parser must close that formatting code, |
| 591 |
and should complain (as in "Unterminated I code in the paragraph |
| 592 |
starting at line 123: 'Time objects are not...'"). So these |
| 593 |
two paragraphs: |
| 594 |
.PP |
| 595 |
.Vb 1 |
| 596 |
\& I<I told you not to do this! |
| 597 |
\& |
| 598 |
\& Don\*(Aqt make me say it again!> |
| 599 |
.Ve |
| 600 |
.PP |
| 601 |
\&...must \fInot\fR be parsed as two paragraphs in italics (with the I |
| 602 |
code starting in one paragraph and starting in another.) Instead, |
| 603 |
the first paragraph should generate a warning, but that aside, the |
| 604 |
above code must parse as if it were: |
| 605 |
.PP |
| 606 |
.Vb 1 |
| 607 |
\& I<I told you not to do this!> |
| 608 |
\& |
| 609 |
\& Don\*(Aqt make me say it again!E<gt> |
| 610 |
.Ve |
| 611 |
.PP |
| 612 |
(In SGMLish jargon, all Pod commands are like block-level |
| 613 |
elements, whereas all Pod formatting codes are like inline-level |
| 614 |
elements.) |
| 615 |
.SH "Notes on Implementing Pod Processors" |
| 616 |
.IX Header "Notes on Implementing Pod Processors" |
| 617 |
The following is a long section of miscellaneous requirements |
| 618 |
and suggestions to do with Pod processing. |
| 619 |
.IP \(bu 4 |
| 620 |
Pod formatters should tolerate lines in verbatim blocks that are of |
| 621 |
any length, even if that means having to break them (possibly several |
| 622 |
times, for very long lines) to avoid text running off the side of the |
| 623 |
page. Pod formatters may warn of such line-breaking. Such warnings |
| 624 |
are particularly appropriate for lines are over 100 characters long, which |
| 625 |
are usually not intentional. |
| 626 |
.IP \(bu 4 |
| 627 |
Pod parsers must recognize \fIall\fR of the three well-known newline |
| 628 |
formats: CR, LF, and CRLF. See perlport. |
| 629 |
.IP \(bu 4 |
| 630 |
Pod parsers should accept input lines that are of any length. |
| 631 |
.IP \(bu 4 |
| 632 |
Since Perl recognizes a Unicode Byte Order Mark at the start of files |
| 633 |
as signaling that the file is Unicode encoded as in UTF\-16 (whether |
| 634 |
big-endian or little-endian) or UTF\-8, Pod parsers should do the |
| 635 |
same. Otherwise, the character encoding should be understood as |
| 636 |
being UTF\-8 if the first highbit byte sequence in the file seems |
| 637 |
valid as a UTF\-8 sequence, or otherwise as CP\-1252 (earlier versions of |
| 638 |
this specification used Latin\-1 instead of CP\-1252). |
| 639 |
.Sp |
| 640 |
Future versions of this specification may specify |
| 641 |
how Pod can accept other encodings. Presumably treatment of other |
| 642 |
encodings in Pod parsing would be as in XML parsing: whatever the |
| 643 |
encoding declared by a particular Pod file, content is to be |
| 644 |
stored in memory as Unicode characters. |
| 645 |
.IP \(bu 4 |
| 646 |
The well known Unicode Byte Order Marks are as follows: if the |
| 647 |
file begins with the two literal byte values 0xFE 0xFF, this is |
| 648 |
the BOM for big-endian UTF\-16. If the file begins with the two |
| 649 |
literal byte value 0xFF 0xFE, this is the BOM for little-endian |
| 650 |
UTF\-16. On an ASCII platform, if the file begins with the three literal |
| 651 |
byte values |
| 652 |
0xEF 0xBB 0xBF, this is the BOM for UTF\-8. |
| 653 |
A mechanism portable to EBCDIC platforms is to: |
| 654 |
.Sp |
| 655 |
.Vb 2 |
| 656 |
\& my $utf8_bom = "\ex{FEFF}"; |
| 657 |
\& utf8::encode($utf8_bom); |
| 658 |
.Ve |
| 659 |
.IP \(bu 4 |
| 660 |
A naive, but often sufficient heuristic on ASCII platforms, for testing |
| 661 |
the first highbit |
| 662 |
byte-sequence in a BOM-less file (whether in code or in Pod!), to see |
| 663 |
whether that sequence is valid as UTF\-8 (RFC 2279) is to check whether |
| 664 |
that the first byte in the sequence is in the range 0xC2 \- 0xFD |
| 665 |
\&\fIand\fR whether the next byte is in the range |
| 666 |
0x80 \- 0xBF. If so, the parser may conclude that this file is in |
| 667 |
UTF\-8, and all highbit sequences in the file should be assumed to |
| 668 |
be UTF\-8. Otherwise the parser should treat the file as being |
| 669 |
in CP\-1252. (A better check, and which works on EBCDIC platforms as |
| 670 |
well, is to pass a copy of the sequence to |
| 671 |
\&\fButf8::decode()\fR which performs a full validity check on the |
| 672 |
sequence and returns TRUE if it is valid UTF\-8, FALSE otherwise. This |
| 673 |
function is always pre-loaded, is fast because it is written in C, and |
| 674 |
will only get called at most once, so you don't need to avoid it out of |
| 675 |
performance concerns.) |
| 676 |
In the unlikely circumstance that the first highbit |
| 677 |
sequence in a truly non\-UTF\-8 file happens to appear to be UTF\-8, one |
| 678 |
can cater to our heuristic (as well as any more intelligent heuristic) |
| 679 |
by prefacing that line with a comment line containing a highbit |
| 680 |
sequence that is clearly \fInot\fR valid as UTF\-8. A line consisting |
| 681 |
of simply "#", an e\-acute, and any non-highbit byte, |
| 682 |
is sufficient to establish this file's encoding. |
| 683 |
.IP \(bu 4 |
| 684 |
Pod processors must treat a "=for [label] [content...]" paragraph as |
| 685 |
meaning the same thing as a "=begin [label]" paragraph, content, and |
| 686 |
an "=end [label]" paragraph. (The parser may conflate these two |
| 687 |
constructs, or may leave them distinct, in the expectation that the |
| 688 |
formatter will nevertheless treat them the same.) |
| 689 |
.IP \(bu 4 |
| 690 |
When rendering Pod to a format that allows comments (i.e., to nearly |
| 691 |
any format other than plaintext), a Pod formatter must insert comment |
| 692 |
text identifying its name and version number, and the name and |
| 693 |
version numbers of any modules it might be using to process the Pod. |
| 694 |
Minimal examples: |
| 695 |
.Sp |
| 696 |
.Vb 1 |
| 697 |
\& %% POD::Pod2PS v3.14159, using POD::Parser v1.92 |
| 698 |
\& |
| 699 |
\& <!\-\- Pod::HTML v3.14159, using POD::Parser v1.92 \-\-> |
| 700 |
\& |
| 701 |
\& {\edoccomm generated by Pod::Tree::RTF 3.14159 using Pod::Tree 1.08} |
| 702 |
\& |
| 703 |
\& .\e" Pod::Man version 3.14159, using POD::Parser version 1.92 |
| 704 |
.Ve |
| 705 |
.Sp |
| 706 |
Formatters may also insert additional comments, including: the |
| 707 |
release date of the Pod formatter program, the contact address for |
| 708 |
the author(s) of the formatter, the current time, the name of input |
| 709 |
file, the formatting options in effect, version of Perl used, etc. |
| 710 |
.Sp |
| 711 |
Formatters may also choose to note errors/warnings as comments, |
| 712 |
besides or instead of emitting them otherwise (as in messages to |
| 713 |
STDERR, or \f(CW\*(C`die\*(C'\fRing). |
| 714 |
.IP \(bu 4 |
| 715 |
Pod parsers \fImay\fR emit warnings or error messages ("Unknown E code |
| 716 |
E<zslig>!") to STDERR (whether through printing to STDERR, or |
| 717 |
\&\f(CW\*(C`warn\*(C'\fRing/\f(CW\*(C`carp\*(C'\fRing, or \f(CW\*(C`die\*(C'\fRing/\f(CW\*(C`croak\*(C'\fRing), but \fImust\fR allow |
| 718 |
suppressing all such STDERR output, and instead allow an option for |
| 719 |
reporting errors/warnings |
| 720 |
in some other way, whether by triggering a callback, or noting errors |
| 721 |
in some attribute of the document object, or some similarly unobtrusive |
| 722 |
mechanism \-\- or even by appending a "Pod Errors" section to the end of |
| 723 |
the parsed form of the document. |
| 724 |
.IP \(bu 4 |
| 725 |
In cases of exceptionally aberrant documents, Pod parsers may abort the |
| 726 |
parse. Even then, using \f(CW\*(C`die\*(C'\fRing/\f(CW\*(C`croak\*(C'\fRing is to be avoided; where |
| 727 |
possible, the parser library may simply close the input file |
| 728 |
and add text like "*** Formatting Aborted ***" to the end of the |
| 729 |
(partial) in-memory document. |
| 730 |
.IP \(bu 4 |
| 731 |
In paragraphs where formatting codes (like E<...>, B<...>) |
| 732 |
are understood (i.e., \fInot\fR verbatim paragraphs, but \fIincluding\fR |
| 733 |
ordinary paragraphs, and command paragraphs that produce renderable |
| 734 |
text, like "=head1"), literal whitespace should generally be considered |
| 735 |
"insignificant", in that one literal space has the same meaning as any |
| 736 |
(nonzero) number of literal spaces, literal newlines, and literal tabs |
| 737 |
(as long as this produces no blank lines, since those would terminate |
| 738 |
the paragraph). Pod parsers should compact literal whitespace in each |
| 739 |
processed paragraph, but may provide an option for overriding this |
| 740 |
(since some processing tasks do not require it), or may follow |
| 741 |
additional special rules (for example, specially treating |
| 742 |
period-space-space or period-newline sequences). |
| 743 |
.IP \(bu 4 |
| 744 |
Pod parsers should not, by default, try to coerce apostrophe (') and |
| 745 |
quote (") into smart quotes (little 9's, 66's, 99's, etc), nor try to |
| 746 |
turn backtick (`) into anything else but a single backtick character |
| 747 |
(distinct from an open quote character!), nor "\-\-" into anything but |
| 748 |
two minus signs. They \fImust never\fR do any of those things to text |
| 749 |
in C<...> formatting codes, and never \fIever\fR to text in verbatim |
| 750 |
paragraphs. |
| 751 |
.IP \(bu 4 |
| 752 |
When rendering Pod to a format that has two kinds of hyphens (\-), one |
| 753 |
that's a non-breaking hyphen, and another that's a breakable hyphen |
| 754 |
(as in "object-oriented", which can be split across lines as |
| 755 |
"object\-", newline, "oriented"), formatters are encouraged to |
| 756 |
generally translate "\-" to non-breaking hyphen, but may apply |
| 757 |
heuristics to convert some of these to breaking hyphens. |
| 758 |
.IP \(bu 4 |
| 759 |
Pod formatters should make reasonable efforts to keep words of Perl |
| 760 |
code from being broken across lines. For example, "Foo::Bar" in some |
| 761 |
formatting systems is seen as eligible for being broken across lines |
| 762 |
as "Foo::" newline "Bar" or even "Foo::\-" newline "Bar". This should |
| 763 |
be avoided where possible, either by disabling all line-breaking in |
| 764 |
mid-word, or by wrapping particular words with internal punctuation |
| 765 |
in "don't break this across lines" codes (which in some formats may |
| 766 |
not be a single code, but might be a matter of inserting non-breaking |
| 767 |
zero-width spaces between every pair of characters in a word.) |
| 768 |
.IP \(bu 4 |
| 769 |
Pod parsers should, by default, expand tabs in verbatim paragraphs as |
| 770 |
they are processed, before passing them to the formatter or other |
| 771 |
processor. Parsers may also allow an option for overriding this. |
| 772 |
.IP \(bu 4 |
| 773 |
Pod parsers should, by default, remove newlines from the end of |
| 774 |
ordinary and verbatim paragraphs before passing them to the |
| 775 |
formatter. For example, while the paragraph you're reading now |
| 776 |
could be considered, in Pod source, to end with (and contain) |
| 777 |
the newline(s) that end it, it should be processed as ending with |
| 778 |
(and containing) the period character that ends this sentence. |
| 779 |
.IP \(bu 4 |
| 780 |
Pod parsers, when reporting errors, should make some effort to report |
| 781 |
an approximate line number ("Nested E<>'s in Paragraph #52, near |
| 782 |
line 633 of Thing/Foo.pm!"), instead of merely noting the paragraph |
| 783 |
number ("Nested E<>'s in Paragraph #52 of Thing/Foo.pm!"). Where |
| 784 |
this is problematic, the paragraph number should at least be |
| 785 |
accompanied by an excerpt from the paragraph ("Nested E<>'s in |
| 786 |
Paragraph #52 of Thing/Foo.pm, which begins 'Read/write accessor for |
| 787 |
the C<interest rate> attribute...'"). |
| 788 |
.IP \(bu 4 |
| 789 |
Pod parsers, when processing a series of verbatim paragraphs one |
| 790 |
after another, should consider them to be one large verbatim |
| 791 |
paragraph that happens to contain blank lines. I.e., these two |
| 792 |
lines, which have a blank line between them: |
| 793 |
.Sp |
| 794 |
.Vb 1 |
| 795 |
\& use Foo; |
| 796 |
\& |
| 797 |
\& print Foo\->VERSION |
| 798 |
.Ve |
| 799 |
.Sp |
| 800 |
should be unified into one paragraph ("\etuse Foo;\en\en\etprint |
| 801 |
Foo\->VERSION") before being passed to the formatter or other |
| 802 |
processor. Parsers may also allow an option for overriding this. |
| 803 |
.Sp |
| 804 |
While this might be too cumbersome to implement in event-based Pod |
| 805 |
parsers, it is straightforward for parsers that return parse trees. |
| 806 |
.IP \(bu 4 |
| 807 |
Pod formatters, where feasible, are advised to avoid splitting short |
| 808 |
verbatim paragraphs (under twelve lines, say) across pages. |
| 809 |
.IP \(bu 4 |
| 810 |
Pod parsers must treat a line with only spaces and/or tabs on it as a |
| 811 |
"blank line" such as separates paragraphs. (Some older parsers |
| 812 |
recognized only two adjacent newlines as a "blank line" but would not |
| 813 |
recognize a newline, a space, and a newline, as a blank line. This |
| 814 |
is noncompliant behavior.) |
| 815 |
.IP \(bu 4 |
| 816 |
Authors of Pod formatters/processors should make every effort to |
| 817 |
avoid writing their own Pod parser. There are already several in |
| 818 |
CPAN, with a wide range of interface styles \-\- and one of them, |
| 819 |
Pod::Simple, comes with modern versions of Perl. |
| 820 |
.IP \(bu 4 |
| 821 |
Characters in Pod documents may be conveyed either as literals, or by |
| 822 |
number in E<n> codes, or by an equivalent mnemonic, as in |
| 823 |
E<eacute> which is exactly equivalent to E<233>. The numbers |
| 824 |
are the Latin1/Unicode values, even on EBCDIC platforms. |
| 825 |
.Sp |
| 826 |
When referring to characters by using a E<n> numeric code, numbers |
| 827 |
in the range 32\-126 refer to those well known US-ASCII characters (also |
| 828 |
defined there by Unicode, with the same meaning), which all Pod |
| 829 |
formatters must render faithfully. Characters whose E<> numbers |
| 830 |
are in the ranges 0\-31 and 127\-159 should not be used (neither as |
| 831 |
literals, |
| 832 |
nor as E<number> codes), except for the literal byte-sequences for |
| 833 |
newline (ASCII 13, ASCII 13 10, or ASCII 10), and tab (ASCII 9). |
| 834 |
.Sp |
| 835 |
Numbers in the range 160\-255 refer to Latin\-1 characters (also |
| 836 |
defined there by Unicode, with the same meaning). Numbers above |
| 837 |
255 should be understood to refer to Unicode characters. |
| 838 |
.IP \(bu 4 |
| 839 |
Be warned |
| 840 |
that some formatters cannot reliably render characters outside 32\-126; |
| 841 |
and many are able to handle 32\-126 and 160\-255, but nothing above |
| 842 |
255. |
| 843 |
.IP \(bu 4 |
| 844 |
Besides the well-known "E<lt>" and "E<gt>" codes for |
| 845 |
less-than and greater-than, Pod parsers must understand "E<sol>" |
| 846 |
for "/" (solidus, slash), and "E<verbar>" for "|" (vertical bar, |
| 847 |
pipe). Pod parsers should also understand "E<lchevron>" and |
| 848 |
"E<rchevron>" as legacy codes for characters 171 and 187, i.e., |
| 849 |
"left-pointing double angle quotation mark" = "left pointing |
| 850 |
guillemet" and "right-pointing double angle quotation mark" = "right |
| 851 |
pointing guillemet". (These look like little "<<" and ">>", and they |
| 852 |
are now preferably expressed with the HTML/XHTML codes "E<laquo>" |
| 853 |
and "E<raquo>".) |
| 854 |
.IP \(bu 4 |
| 855 |
Pod parsers should understand all "E<html>" codes as defined |
| 856 |
in the entity declarations in the most recent XHTML specification at |
| 857 |
\&\f(CW\*(C`www.W3.org\*(C'\fR. Pod parsers must understand at least the entities |
| 858 |
that define characters in the range 160\-255 (Latin\-1). Pod parsers, |
| 859 |
when faced with some unknown "E<\fIidentifier\fR>" code, |
| 860 |
shouldn't simply replace it with nullstring (by default, at least), |
| 861 |
but may pass it through as a string consisting of the literal characters |
| 862 |
E, less-than, \fIidentifier\fR, greater-than. Or Pod parsers may offer the |
| 863 |
alternative option of processing such unknown |
| 864 |
"E<\fIidentifier\fR>" codes by firing an event especially |
| 865 |
for such codes, or by adding a special node-type to the in-memory |
| 866 |
document tree. Such "E<\fIidentifier\fR>" may have special meaning |
| 867 |
to some processors, or some processors may choose to add them to |
| 868 |
a special error report. |
| 869 |
.IP \(bu 4 |
| 870 |
Pod parsers must also support the XHTML codes "E<quot>" for |
| 871 |
character 34 (doublequote, "), "E<amp>" for character 38 |
| 872 |
(ampersand, &), and "E<apos>" for character 39 (apostrophe, '). |
| 873 |
.IP \(bu 4 |
| 874 |
Note that in all cases of "E<whatever>", \fIwhatever\fR (whether |
| 875 |
an htmlname, or a number in any base) must consist only of |
| 876 |
alphanumeric characters \-\- that is, \fIwhatever\fR must match |
| 877 |
\&\f(CW\*(C`m/\eA\ew+\ez/\*(C'\fR. So "E<\ 0\ 1\ 2\ 3\ >" is invalid, because |
| 878 |
it contains spaces, which aren't alphanumeric characters. This |
| 879 |
presumably does not \fIneed\fR special treatment by a Pod processor; |
| 880 |
"\ 0\ 1\ 2\ 3\ " doesn't look like a number in any base, so it would |
| 881 |
presumably be looked up in the table of HTML-like names. Since |
| 882 |
there isn't (and cannot be) an HTML-like entity called "\ 0\ 1\ 2\ 3\ ", |
| 883 |
this will be treated as an error. However, Pod processors may |
| 884 |
treat "E<\ 0\ 1\ 2\ 3\ >" or "E<e\-acute>" as \fIsyntactically\fR |
| 885 |
invalid, potentially earning a different error message than the |
| 886 |
error message (or warning, or event) generated by a merely unknown |
| 887 |
(but theoretically valid) htmlname, as in "E<qacute>" |
| 888 |
[sic]. However, Pod parsers are not required to make this |
| 889 |
distinction. |
| 890 |
.IP \(bu 4 |
| 891 |
Note that E<number> \fImust not\fR be interpreted as simply |
| 892 |
"codepoint \fInumber\fR in the current/native character set". It always |
| 893 |
means only "the character represented by codepoint \fInumber\fR in |
| 894 |
Unicode." (This is identical to the semantics of &#\fInumber\fR; in XML.) |
| 895 |
.Sp |
| 896 |
This will likely require many formatters to have tables mapping from |
| 897 |
treatable Unicode codepoints (such as the "\exE9" for the e\-acute |
| 898 |
character) to the escape sequences or codes necessary for conveying |
| 899 |
such sequences in the target output format. A converter to *roff |
| 900 |
would, for example know that "\exE9" (whether conveyed literally, or via |
| 901 |
a E<...> sequence) is to be conveyed as "e\e\e*'". |
| 902 |
Similarly, a program rendering Pod in a Mac OS application window, would |
| 903 |
presumably need to know that "\exE9" maps to codepoint 142 in MacRoman |
| 904 |
encoding that (at time of writing) is native for Mac OS. Such |
| 905 |
Unicode2whatever mappings are presumably already widely available for |
| 906 |
common output formats. (Such mappings may be incomplete! Implementers |
| 907 |
are not expected to bend over backwards in an attempt to render |
| 908 |
Cherokee syllabics, Etruscan runes, Byzantine musical symbols, or any |
| 909 |
of the other weird things that Unicode can encode.) And |
| 910 |
if a Pod document uses a character not found in such a mapping, the |
| 911 |
formatter should consider it an unrenderable character. |
| 912 |
.IP \(bu 4 |
| 913 |
If, surprisingly, the implementor of a Pod formatter can't find a |
| 914 |
satisfactory pre-existing table mapping from Unicode characters to |
| 915 |
escapes in the target format (e.g., a decent table of Unicode |
| 916 |
characters to *roff escapes), it will be necessary to build such a |
| 917 |
table. If you are in this circumstance, you should begin with the |
| 918 |
characters in the range 0x00A0 \- 0x00FF, which is mostly the heavily |
| 919 |
used accented characters. Then proceed (as patience permits and |
| 920 |
fastidiousness compels) through the characters that the (X)HTML |
| 921 |
standards groups judged important enough to merit mnemonics |
| 922 |
for. These are declared in the (X)HTML specifications at the |
| 923 |
www.W3.org site. At time of writing (September 2001), the most recent |
| 924 |
entity declaration files are: |
| 925 |
.Sp |
| 926 |
.Vb 3 |
| 927 |
\& http://www.w3.org/TR/xhtml1/DTD/xhtml\-lat1.ent |
| 928 |
\& http://www.w3.org/TR/xhtml1/DTD/xhtml\-special.ent |
| 929 |
\& http://www.w3.org/TR/xhtml1/DTD/xhtml\-symbol.ent |
| 930 |
.Ve |
| 931 |
.Sp |
| 932 |
Then you can progress through any remaining notable Unicode characters |
| 933 |
in the range 0x2000\-0x204D (consult the character tables at |
| 934 |
www.unicode.org), and whatever else strikes your fancy. For example, |
| 935 |
in \fIxhtml\-symbol.ent\fR, there is the entry: |
| 936 |
.Sp |
| 937 |
.Vb 1 |
| 938 |
\& <!ENTITY infin "∞"> <!\-\- infinity, U+221E ISOtech \-\-> |
| 939 |
.Ve |
| 940 |
.Sp |
| 941 |
While the mapping "infin" to the character "\ex{221E}" will (hopefully) |
| 942 |
have been already handled by the Pod parser, the presence of the |
| 943 |
character in this file means that it's reasonably important enough to |
| 944 |
include in a formatter's table that maps from notable Unicode characters |
| 945 |
to the codes necessary for rendering them. So for a Unicode\-to\-*roff |
| 946 |
mapping, for example, this would merit the entry: |
| 947 |
.Sp |
| 948 |
.Vb 1 |
| 949 |
\& "\ex{221E}" => \*(Aq\e(in\*(Aq, |
| 950 |
.Ve |
| 951 |
.Sp |
| 952 |
It is eagerly hoped that in the future, increasing numbers of formats |
| 953 |
(and formatters) will support Unicode characters directly (as (X)HTML |
| 954 |
does with \f(CW\*(C`∞\*(C'\fR, \f(CW\*(C`∞\*(C'\fR, or \f(CW\*(C`∞\*(C'\fR), reducing the need |
| 955 |
for idiosyncratic mappings of Unicode\-to\-\fImy_escapes\fR. |
| 956 |
.IP \(bu 4 |
| 957 |
It is up to individual Pod formatter to display good judgement when |
| 958 |
confronted with an unrenderable character (which is distinct from an |
| 959 |
unknown E<thing> sequence that the parser couldn't resolve to |
| 960 |
anything, renderable or not). It is good practice to map Latin letters |
| 961 |
with diacritics (like "E<eacute>"/"E<233>") to the corresponding |
| 962 |
unaccented US-ASCII letters (like a simple character 101, "e"), but |
| 963 |
clearly this is often not feasible, and an unrenderable character may |
| 964 |
be represented as "?", or the like. In attempting a sane fallback |
| 965 |
(as from E<233> to "e"), Pod formatters may use the |
| 966 |
\&\f(CW%Latin1Code_to_fallback\fR table in Pod::Escapes, or |
| 967 |
Text::Unidecode, if available. |
| 968 |
.Sp |
| 969 |
For example, this Pod text: |
| 970 |
.Sp |
| 971 |
.Vb 1 |
| 972 |
\& magic is enabled if you set C<$Currency> to \*(AqE<euro>\*(Aq. |
| 973 |
.Ve |
| 974 |
.Sp |
| 975 |
may be rendered as: |
| 976 |
"magic is enabled if you set \f(CW$Currency\fR to '\fI?\fR'" or as |
| 977 |
"magic is enabled if you set \f(CW$Currency\fR to '\fB[euro]\fR'", or as |
| 978 |
"magic is enabled if you set \f(CW$Currency\fR to '[x20AC]', etc. |
| 979 |
.Sp |
| 980 |
A Pod formatter may also note, in a comment or warning, a list of what |
| 981 |
unrenderable characters were encountered. |
| 982 |
.IP \(bu 4 |
| 983 |
E<...> may freely appear in any formatting code (other than |
| 984 |
in another E<...> or in an Z<>). That is, "X<The |
| 985 |
E<euro>1,000,000 Solution>" is valid, as is "L<The |
| 986 |
E<euro>1,000,000 Solution|Million::Euros>". |
| 987 |
.IP \(bu 4 |
| 988 |
Some Pod formatters output to formats that implement non-breaking |
| 989 |
spaces as an individual character (which I'll call "NBSP"), and |
| 990 |
others output to formats that implement non-breaking spaces just as |
| 991 |
spaces wrapped in a "don't break this across lines" code. Note that |
| 992 |
at the level of Pod, both sorts of codes can occur: Pod can contain a |
| 993 |
NBSP character (whether as a literal, or as a "E<160>" or |
| 994 |
"E<nbsp>" code); and Pod can contain "S<foo |
| 995 |
I<bar> baz>" codes, where "mere spaces" (character 32) in |
| 996 |
such codes are taken to represent non-breaking spaces. Pod |
| 997 |
parsers should consider supporting the optional parsing of "S<foo |
| 998 |
I<bar> baz>" as if it were |
| 999 |
"foo\fINBSP\fRI<bar>\fINBSP\fRbaz", and, going the other way, the |
| 1000 |
optional parsing of groups of words joined by NBSP's as if each group |
| 1001 |
were in a S<...> code, so that formatters may use the |
| 1002 |
representation that maps best to what the output format demands. |
| 1003 |
.IP \(bu 4 |
| 1004 |
Some processors may find that the \f(CW\*(C`S<...>\*(C'\fR code is easiest to |
| 1005 |
implement by replacing each space in the parse tree under the content |
| 1006 |
of the S, with an NBSP. But note: the replacement should apply \fInot\fR to |
| 1007 |
spaces in \fIall\fR text, but \fIonly\fR to spaces in \fIprintable\fR text. (This |
| 1008 |
distinction may or may not be evident in the particular tree/event |
| 1009 |
model implemented by the Pod parser.) For example, consider this |
| 1010 |
unusual case: |
| 1011 |
.Sp |
| 1012 |
.Vb 1 |
| 1013 |
\& S<L</Autoloaded Functions>> |
| 1014 |
.Ve |
| 1015 |
.Sp |
| 1016 |
This means that the space in the middle of the visible link text must |
| 1017 |
not be broken across lines. In other words, it's the same as this: |
| 1018 |
.Sp |
| 1019 |
.Vb 1 |
| 1020 |
\& L<"AutoloadedE<160>Functions"/Autoloaded Functions> |
| 1021 |
.Ve |
| 1022 |
.Sp |
| 1023 |
However, a misapplied space-to-NBSP replacement could (wrongly) |
| 1024 |
produce something equivalent to this: |
| 1025 |
.Sp |
| 1026 |
.Vb 1 |
| 1027 |
\& L<"AutoloadedE<160>Functions"/AutoloadedE<160>Functions> |
| 1028 |
.Ve |
| 1029 |
.Sp |
| 1030 |
\&...which is almost definitely not going to work as a hyperlink (assuming |
| 1031 |
this formatter outputs a format supporting hypertext). |
| 1032 |
.Sp |
| 1033 |
Formatters may choose to just not support the S format code, |
| 1034 |
especially in cases where the output format simply has no NBSP |
| 1035 |
character/code and no code for "don't break this stuff across lines". |
| 1036 |
.IP \(bu 4 |
| 1037 |
Besides the NBSP character discussed above, implementors are reminded |
| 1038 |
of the existence of the other "special" character in Latin\-1, the |
| 1039 |
"soft hyphen" character, also known as "discretionary hyphen", |
| 1040 |
i.e. \f(CW\*(C`E<173>\*(C'\fR = \f(CW\*(C`E<0xAD>\*(C'\fR = |
| 1041 |
\&\f(CW\*(C`E<shy>\*(C'\fR). This character expresses an optional hyphenation |
| 1042 |
point. That is, it normally renders as nothing, but may render as a |
| 1043 |
"\-" if a formatter breaks the word at that point. Pod formatters |
| 1044 |
should, as appropriate, do one of the following: 1) render this with |
| 1045 |
a code with the same meaning (e.g., "\e\-" in RTF), 2) pass it through |
| 1046 |
in the expectation that the formatter understands this character as |
| 1047 |
such, or 3) delete it. |
| 1048 |
.Sp |
| 1049 |
For example: |
| 1050 |
.Sp |
| 1051 |
.Vb 3 |
| 1052 |
\& sigE<shy>action |
| 1053 |
\& manuE<shy>script |
| 1054 |
\& JarkE<shy>ko HieE<shy>taE<shy>nieE<shy>mi |
| 1055 |
.Ve |
| 1056 |
.Sp |
| 1057 |
These signal to a formatter that if it is to hyphenate "sigaction" |
| 1058 |
or "manuscript", then it should be done as |
| 1059 |
"sig\-\fI[linebreak]\fRaction" or "manu\-\fI[linebreak]\fRscript" |
| 1060 |
(and if it doesn't hyphenate it, then the \f(CW\*(C`E<shy>\*(C'\fR doesn't |
| 1061 |
show up at all). And if it is |
| 1062 |
to hyphenate "Jarkko" and/or "Hietaniemi", it can do |
| 1063 |
so only at the points where there is a \f(CW\*(C`E<shy>\*(C'\fR code. |
| 1064 |
.Sp |
| 1065 |
In practice, it is anticipated that this character will not be used |
| 1066 |
often, but formatters should either support it, or delete it. |
| 1067 |
.IP \(bu 4 |
| 1068 |
If you think that you want to add a new command to Pod (like, say, a |
| 1069 |
"=biblio" command), consider whether you could get the same |
| 1070 |
effect with a for or begin/end sequence: "=for biblio ..." or "=begin |
| 1071 |
biblio" ... "=end biblio". Pod processors that don't understand |
| 1072 |
"=for biblio", etc, will simply ignore it, whereas they may complain |
| 1073 |
loudly if they see "=biblio". |
| 1074 |
.IP \(bu 4 |
| 1075 |
Throughout this document, "Pod" has been the preferred spelling for |
| 1076 |
the name of the documentation format. One may also use "POD" or |
| 1077 |
"pod". For the documentation that is (typically) in the Pod |
| 1078 |
format, you may use "pod", or "Pod", or "POD". Understanding these |
| 1079 |
distinctions is useful; but obsessing over how to spell them, usually |
| 1080 |
is not. |
| 1081 |
.SH "About L<...> Codes" |
| 1082 |
.IX Header "About L<...> Codes" |
| 1083 |
As you can tell from a glance at perlpod, the L<...> |
| 1084 |
code is the most complex of the Pod formatting codes. The points below |
| 1085 |
will hopefully clarify what it means and how processors should deal |
| 1086 |
with it. |
| 1087 |
.IP \(bu 4 |
| 1088 |
In parsing an L<...> code, Pod parsers must distinguish at least |
| 1089 |
four attributes: |
| 1090 |
.RS 4 |
| 1091 |
.IP First: 4 |
| 1092 |
.IX Item "First:" |
| 1093 |
The link-text. If there is none, this must be \f(CW\*(C`undef\*(C'\fR. (E.g., in |
| 1094 |
"L<Perl Functions|perlfunc>", the link-text is "Perl Functions". |
| 1095 |
In "L<Time::HiRes>" and even "L<|Time::HiRes>", there is no |
| 1096 |
link text. Note that link text may contain formatting.) |
| 1097 |
.IP Second: 4 |
| 1098 |
.IX Item "Second:" |
| 1099 |
The possibly inferred link-text; i.e., if there was no real link |
| 1100 |
text, then this is the text that we'll infer in its place. (E.g., for |
| 1101 |
"L<Getopt::Std>", the inferred link text is "Getopt::Std".) |
| 1102 |
.IP Third: 4 |
| 1103 |
.IX Item "Third:" |
| 1104 |
The name or URL, or \f(CW\*(C`undef\*(C'\fR if none. (E.g., in "L<Perl |
| 1105 |
Functions|perlfunc>", the name (also sometimes called the page) |
| 1106 |
is "perlfunc". In "L</CAVEATS>", the name is \f(CW\*(C`undef\*(C'\fR.) |
| 1107 |
.IP Fourth: 4 |
| 1108 |
.IX Item "Fourth:" |
| 1109 |
The section (AKA "item" in older perlpods), or \f(CW\*(C`undef\*(C'\fR if none. E.g., |
| 1110 |
in "L<Getopt::Std/DESCRIPTION>", "DESCRIPTION" is the section. (Note |
| 1111 |
that this is not the same as a manpage section like the "5" in "man 5 |
| 1112 |
crontab". "Section Foo" in the Pod sense means the part of the text |
| 1113 |
that's introduced by the heading or item whose text is "Foo".) |
| 1114 |
.RE |
| 1115 |
.RS 4 |
| 1116 |
.Sp |
| 1117 |
Pod parsers may also note additional attributes including: |
| 1118 |
.IP Fifth: 4 |
| 1119 |
.IX Item "Fifth:" |
| 1120 |
A flag for whether item 3 (if present) is a URL (like |
| 1121 |
"http://lists.perl.org" is), in which case there should be no section |
| 1122 |
attribute; a Pod name (like "perldoc" and "Getopt::Std" are); or |
| 1123 |
possibly a man page name (like "\fBcrontab\fR\|(5)" is). |
| 1124 |
.IP Sixth: 4 |
| 1125 |
.IX Item "Sixth:" |
| 1126 |
The raw original L<...> content, before text is split on |
| 1127 |
"|", "/", etc, and before E<...> codes are expanded. |
| 1128 |
.RE |
| 1129 |
.RS 4 |
| 1130 |
.Sp |
| 1131 |
(The above were numbered only for concise reference below. It is not |
| 1132 |
a requirement that these be passed as an actual list or array.) |
| 1133 |
.Sp |
| 1134 |
For example: |
| 1135 |
.Sp |
| 1136 |
.Vb 7 |
| 1137 |
\& L<Foo::Bar> |
| 1138 |
\& => undef, # link text |
| 1139 |
\& "Foo::Bar", # possibly inferred link text |
| 1140 |
\& "Foo::Bar", # name |
| 1141 |
\& undef, # section |
| 1142 |
\& \*(Aqpod\*(Aq, # what sort of link |
| 1143 |
\& "Foo::Bar" # original content |
| 1144 |
\& |
| 1145 |
\& L<Perlport\*(Aqs section on NL\*(Aqs|perlport/Newlines> |
| 1146 |
\& => "Perlport\*(Aqs section on NL\*(Aqs", # link text |
| 1147 |
\& "Perlport\*(Aqs section on NL\*(Aqs", # possibly inferred link text |
| 1148 |
\& "perlport", # name |
| 1149 |
\& "Newlines", # section |
| 1150 |
\& \*(Aqpod\*(Aq, # what sort of link |
| 1151 |
\& "Perlport\*(Aqs section on NL\*(Aqs|perlport/Newlines" |
| 1152 |
\& # original content |
| 1153 |
\& |
| 1154 |
\& L<perlport/Newlines> |
| 1155 |
\& => undef, # link text |
| 1156 |
\& \*(Aq"Newlines" in perlport\*(Aq, # possibly inferred link text |
| 1157 |
\& "perlport", # name |
| 1158 |
\& "Newlines", # section |
| 1159 |
\& \*(Aqpod\*(Aq, # what sort of link |
| 1160 |
\& "perlport/Newlines" # original content |
| 1161 |
\& |
| 1162 |
\& L<crontab(5)/"DESCRIPTION"> |
| 1163 |
\& => undef, # link text |
| 1164 |
\& \*(Aq"DESCRIPTION" in crontab(5)\*(Aq, # possibly inferred link text |
| 1165 |
\& "crontab(5)", # name |
| 1166 |
\& "DESCRIPTION", # section |
| 1167 |
\& \*(Aqman\*(Aq, # what sort of link |
| 1168 |
\& \*(Aqcrontab(5)/"DESCRIPTION"\*(Aq # original content |
| 1169 |
\& |
| 1170 |
\& L</Object Attributes> |
| 1171 |
\& => undef, # link text |
| 1172 |
\& \*(Aq"Object Attributes"\*(Aq, # possibly inferred link text |
| 1173 |
\& undef, # name |
| 1174 |
\& "Object Attributes", # section |
| 1175 |
\& \*(Aqpod\*(Aq, # what sort of link |
| 1176 |
\& "/Object Attributes" # original content |
| 1177 |
\& |
| 1178 |
\& L<https://www.perl.org/> |
| 1179 |
\& => undef, # link text |
| 1180 |
\& "https://www.perl.org/", # possibly inferred link text |
| 1181 |
\& "https://www.perl.org/", # name |
| 1182 |
\& undef, # section |
| 1183 |
\& \*(Aqurl\*(Aq, # what sort of link |
| 1184 |
\& "https://www.perl.org/" # original content |
| 1185 |
\& |
| 1186 |
\& L<Perl.org|https://www.perl.org/> |
| 1187 |
\& => "Perl.org", # link text |
| 1188 |
\& "https://www.perl.org/", # possibly inferred link text |
| 1189 |
\& "https://www.perl.org/", # name |
| 1190 |
\& undef, # section |
| 1191 |
\& \*(Aqurl\*(Aq, # what sort of link |
| 1192 |
\& "Perl.org|https://www.perl.org/" # original content |
| 1193 |
.Ve |
| 1194 |
.Sp |
| 1195 |
Note that you can distinguish URL-links from anything else by the |
| 1196 |
fact that they match \f(CW\*(C`m/\eA\ew+:[^:\es]\eS*\ez/\*(C'\fR. So |
| 1197 |
\&\f(CW\*(C`L<http://www.perl.com>\*(C'\fR is a URL, but |
| 1198 |
\&\f(CW\*(C`L<HTTP::Response>\*(C'\fR isn't. |
| 1199 |
.RE |
| 1200 |
.IP \(bu 4 |
| 1201 |
In case of L<...> codes with no "text|" part in them, |
| 1202 |
older formatters have exhibited great variation in actually displaying |
| 1203 |
the link or cross reference. For example, L<\fBcrontab\fR\|(5)> would render |
| 1204 |
as "the \f(CWcrontab(5)\fR manpage", or "in the \f(CWcrontab(5)\fR manpage" |
| 1205 |
or just "\f(CWcrontab(5)\fR". |
| 1206 |
.Sp |
| 1207 |
Pod processors must now treat "text|"\-less links as follows: |
| 1208 |
.Sp |
| 1209 |
.Vb 3 |
| 1210 |
\& L<name> => L<name|name> |
| 1211 |
\& L</section> => L<"section"|/section> |
| 1212 |
\& L<name/section> => L<"section" in name|name/section> |
| 1213 |
.Ve |
| 1214 |
.IP \(bu 4 |
| 1215 |
Note that section names might contain markup. I.e., if a section |
| 1216 |
starts with: |
| 1217 |
.Sp |
| 1218 |
.Vb 1 |
| 1219 |
\& =head2 About the C<\-M> Operator |
| 1220 |
.Ve |
| 1221 |
.Sp |
| 1222 |
or with: |
| 1223 |
.Sp |
| 1224 |
.Vb 1 |
| 1225 |
\& =item About the C<\-M> Operator |
| 1226 |
.Ve |
| 1227 |
.Sp |
| 1228 |
then a link to it would look like this: |
| 1229 |
.Sp |
| 1230 |
.Vb 1 |
| 1231 |
\& L<somedoc/About the C<\-M> Operator> |
| 1232 |
.Ve |
| 1233 |
.Sp |
| 1234 |
Formatters may choose to ignore the markup for purposes of resolving |
| 1235 |
the link and use only the renderable characters in the section name, |
| 1236 |
as in: |
| 1237 |
.Sp |
| 1238 |
.Vb 2 |
| 1239 |
\& <h1><a name="About_the_\-M_Operator">About the <code>\-M</code> |
| 1240 |
\& Operator</h1> |
| 1241 |
\& |
| 1242 |
\& ... |
| 1243 |
\& |
| 1244 |
\& <a href="somedoc#About_the_\-M_Operator">About the <code>\-M</code> |
| 1245 |
\& Operator" in somedoc</a> |
| 1246 |
.Ve |
| 1247 |
.IP \(bu 4 |
| 1248 |
Previous versions of perlpod distinguished \f(CW\*(C`L<name/"section">\*(C'\fR |
| 1249 |
links from \f(CW\*(C`L<name/item>\*(C'\fR links (and their targets). These |
| 1250 |
have been merged syntactically and semantically in the current |
| 1251 |
specification, and \fIsection\fR can refer either to a "=head\fIn\fR Heading |
| 1252 |
Content" command or to a "=item Item Content" command. This |
| 1253 |
specification does not specify what behavior should be in the case |
| 1254 |
of a given document having several things all seeming to produce the |
| 1255 |
same \fIsection\fR identifier (e.g., in HTML, several things all producing |
| 1256 |
the same \fIanchorname\fR in <a name="\fIanchorname\fR">...</a> |
| 1257 |
elements). Where Pod processors can control this behavior, they should |
| 1258 |
use the first such anchor. That is, \f(CW\*(C`L<Foo/Bar>\*(C'\fR refers to the |
| 1259 |
\&\fIfirst\fR "Bar" section in Foo. |
| 1260 |
.Sp |
| 1261 |
But for some processors/formats this cannot be easily controlled; as |
| 1262 |
with the HTML example, the behavior of multiple ambiguous |
| 1263 |
<a name="\fIanchorname\fR">...</a> is most easily just left up to |
| 1264 |
browsers to decide. |
| 1265 |
.IP \(bu 4 |
| 1266 |
In a \f(CW\*(C`L<text|...>\*(C'\fR code, text may contain formatting codes |
| 1267 |
for formatting or for E<...> escapes, as in: |
| 1268 |
.Sp |
| 1269 |
.Vb 1 |
| 1270 |
\& L<B<ummE<234>stuff>|...> |
| 1271 |
.Ve |
| 1272 |
.Sp |
| 1273 |
For \f(CW\*(C`L<...>\*(C'\fR codes without a "name|" part, only |
| 1274 |
\&\f(CW\*(C`E<...>\*(C'\fR and \f(CW\*(C`Z<>\*(C'\fR codes may occur. That is, |
| 1275 |
authors should not use "\f(CW\*(C`L<B<Foo::Bar>>\*(C'\fR". |
| 1276 |
.Sp |
| 1277 |
Note, however, that formatting codes and Z<>'s can occur in any |
| 1278 |
and all parts of an L<...> (i.e., in \fIname\fR, \fIsection\fR, \fItext\fR, |
| 1279 |
and \fIurl\fR). |
| 1280 |
.Sp |
| 1281 |
Authors must not nest L<...> codes. For example, "L<The |
| 1282 |
L<Foo::Bar> man page>" should be treated as an error. |
| 1283 |
.IP \(bu 4 |
| 1284 |
Note that Pod authors may use formatting codes inside the "text" |
| 1285 |
part of "L<text|name>" (and so on for L<text|/"sec">). |
| 1286 |
.Sp |
| 1287 |
In other words, this is valid: |
| 1288 |
.Sp |
| 1289 |
.Vb 1 |
| 1290 |
\& Go read L<the docs on C<$.>|perlvar/"$."> |
| 1291 |
.Ve |
| 1292 |
.Sp |
| 1293 |
Some output formats that do allow rendering "L<...>" codes as |
| 1294 |
hypertext, might not allow the link-text to be formatted; in |
| 1295 |
that case, formatters will have to just ignore that formatting. |
| 1296 |
.IP \(bu 4 |
| 1297 |
At time of writing, \f(CW\*(C`L<name>\*(C'\fR values are of two types: |
| 1298 |
either the name of a Pod page like \f(CW\*(C`L<Foo::Bar>\*(C'\fR (which |
| 1299 |
might be a real Perl module or program in an \f(CW@INC\fR / PATH |
| 1300 |
directory, or a .pod file in those places); or the name of a Unix |
| 1301 |
man page, like \f(CW\*(C`L<crontab(5)>\*(C'\fR. In theory, \f(CW\*(C`L<chmod>\*(C'\fR |
| 1302 |
is ambiguous between a Pod page called "chmod", or the Unix man page |
| 1303 |
"chmod" (in whatever man-section). However, the presence of a string |
| 1304 |
in parens, as in "\fBcrontab\fR\|(5)", is sufficient to signal that what |
| 1305 |
is being discussed is not a Pod page, and so is presumably a |
| 1306 |
Unix man page. The distinction is of no importance to many |
| 1307 |
Pod processors, but some processors that render to hypertext formats |
| 1308 |
may need to distinguish them in order to know how to render a |
| 1309 |
given \f(CW\*(C`L<foo>\*(C'\fR code. |
| 1310 |
.IP \(bu 4 |
| 1311 |
Previous versions of perlpod allowed for a \f(CW\*(C`L<section>\*(C'\fR syntax (as in |
| 1312 |
\&\f(CW\*(C`L<Object Attributes>\*(C'\fR), which was not easily distinguishable from |
| 1313 |
\&\f(CW\*(C`L<name>\*(C'\fR syntax and for \f(CW\*(C`L<"section">\*(C'\fR which was only |
| 1314 |
slightly less ambiguous. This syntax is no longer in the specification, and |
| 1315 |
has been replaced by the \f(CW\*(C`L</section>\*(C'\fR syntax (where the slash was |
| 1316 |
formerly optional). Pod parsers should tolerate the \f(CW\*(C`L<"section">\*(C'\fR |
| 1317 |
syntax, for a while at least. The suggested heuristic for distinguishing |
| 1318 |
\&\f(CW\*(C`L<section>\*(C'\fR from \f(CW\*(C`L<name>\*(C'\fR is that if it contains any |
| 1319 |
whitespace, it's a \fIsection\fR. Pod processors should warn about this being |
| 1320 |
deprecated syntax. |
| 1321 |
.SH "About =over...=back Regions" |
| 1322 |
.IX Header "About =over...=back Regions" |
| 1323 |
"=over"..."=back" regions are used for various kinds of list-like |
| 1324 |
structures. (I use the term "region" here simply as a collective |
| 1325 |
term for everything from the "=over" to the matching "=back".) |
| 1326 |
.IP \(bu 4 |
| 1327 |
The non-zero numeric \fIindentlevel\fR in "=over \fIindentlevel\fR" ... |
| 1328 |
"=back" is used for giving the formatter a clue as to how many |
| 1329 |
"spaces" (ems, or roughly equivalent units) it should tab over, |
| 1330 |
although many formatters will have to convert this to an absolute |
| 1331 |
measurement that may not exactly match with the size of spaces (or M's) |
| 1332 |
in the document's base font. Other formatters may have to completely |
| 1333 |
ignore the number. The lack of any explicit \fIindentlevel\fR parameter is |
| 1334 |
equivalent to an \fIindentlevel\fR value of 4. Pod processors may |
| 1335 |
complain if \fIindentlevel\fR is present but is not a positive number |
| 1336 |
matching \f(CW\*(C`m/\eA(\ed*\e.)?\ed+\ez/\*(C'\fR. |
| 1337 |
.IP \(bu 4 |
| 1338 |
Authors of Pod formatters are reminded that "=over" ... "=back" may |
| 1339 |
map to several different constructs in your output format. For |
| 1340 |
example, in converting Pod to (X)HTML, it can map to any of |
| 1341 |
<ul>...</ul>, <ol>...</ol>, <dl>...</dl>, or |
| 1342 |
<blockquote>...</blockquote>. Similarly, "=item" can map to <li> or |
| 1343 |
<dt>. |
| 1344 |
.IP \(bu 4 |
| 1345 |
Each "=over" ... "=back" region should be one of the following: |
| 1346 |
.RS 4 |
| 1347 |
.IP \(bu 4 |
| 1348 |
An "=over" ... "=back" region containing only "=item *" commands, |
| 1349 |
each followed by some number of ordinary/verbatim paragraphs, other |
| 1350 |
nested "=over" ... "=back" regions, "=for..." paragraphs, and |
| 1351 |
"=begin"..."=end" regions. |
| 1352 |
.Sp |
| 1353 |
(Pod processors must tolerate a bare "=item" as if it were "=item |
| 1354 |
*".) Whether "*" is rendered as a literal asterisk, an "o", or as |
| 1355 |
some kind of real bullet character, is left up to the Pod formatter, |
| 1356 |
and may depend on the level of nesting. |
| 1357 |
.IP \(bu 4 |
| 1358 |
An "=over" ... "=back" region containing only |
| 1359 |
\&\f(CW\*(C`m/\eA=item\es+\ed+\e.?\es*\ez/\*(C'\fR paragraphs, each one (or each group of them) |
| 1360 |
followed by some number of ordinary/verbatim paragraphs, other nested |
| 1361 |
"=over" ... "=back" regions, "=for..." paragraphs, and/or |
| 1362 |
"=begin"..."=end" codes. Note that the numbers must start at 1 |
| 1363 |
in each section, and must proceed in order and without skipping |
| 1364 |
numbers. |
| 1365 |
.Sp |
| 1366 |
(Pod processors must tolerate lines like "=item 1" as if they were |
| 1367 |
"=item 1.", with the period.) |
| 1368 |
.IP \(bu 4 |
| 1369 |
An "=over" ... "=back" region containing only "=item [text]" |
| 1370 |
commands, each one (or each group of them) followed by some number of |
| 1371 |
ordinary/verbatim paragraphs, other nested "=over" ... "=back" |
| 1372 |
regions, or "=for..." paragraphs, and "=begin"..."=end" regions. |
| 1373 |
.Sp |
| 1374 |
The "=item [text]" paragraph should not match |
| 1375 |
\&\f(CW\*(C`m/\eA=item\es+\ed+\e.?\es*\ez/\*(C'\fR or \f(CW\*(C`m/\eA=item\es+\e*\es*\ez/\*(C'\fR, nor should it |
| 1376 |
match just \f(CW\*(C`m/\eA=item\es*\ez/\*(C'\fR. |
| 1377 |
.IP \(bu 4 |
| 1378 |
An "=over" ... "=back" region containing no "=item" paragraphs at |
| 1379 |
all, and containing only some number of |
| 1380 |
ordinary/verbatim paragraphs, and possibly also some nested "=over" |
| 1381 |
\&... "=back" regions, "=for..." paragraphs, and "=begin"..."=end" |
| 1382 |
regions. Such an itemless "=over" ... "=back" region in Pod is |
| 1383 |
equivalent in meaning to a "<blockquote>...</blockquote>" element in |
| 1384 |
HTML. |
| 1385 |
.RE |
| 1386 |
.RS 4 |
| 1387 |
.Sp |
| 1388 |
Note that with all the above cases, you can determine which type of |
| 1389 |
"=over" ... "=back" you have, by examining the first (non\-"=cut", |
| 1390 |
non\-"=pod") Pod paragraph after the "=over" command. |
| 1391 |
.RE |
| 1392 |
.IP \(bu 4 |
| 1393 |
Pod formatters \fImust\fR tolerate arbitrarily large amounts of text |
| 1394 |
in the "=item \fItext...\fR" paragraph. In practice, most such |
| 1395 |
paragraphs are short, as in: |
| 1396 |
.Sp |
| 1397 |
.Vb 1 |
| 1398 |
\& =item For cutting off our trade with all parts of the world |
| 1399 |
.Ve |
| 1400 |
.Sp |
| 1401 |
But they may be arbitrarily long: |
| 1402 |
.Sp |
| 1403 |
.Vb 2 |
| 1404 |
\& =item For transporting us beyond seas to be tried for pretended |
| 1405 |
\& offenses |
| 1406 |
\& |
| 1407 |
\& =item He is at this time transporting large armies of foreign |
| 1408 |
\& mercenaries to complete the works of death, desolation and |
| 1409 |
\& tyranny, already begun with circumstances of cruelty and perfidy |
| 1410 |
\& scarcely paralleled in the most barbarous ages, and totally |
| 1411 |
\& unworthy the head of a civilized nation. |
| 1412 |
.Ve |
| 1413 |
.IP \(bu 4 |
| 1414 |
Pod processors should tolerate "=item *" / "=item \fInumber\fR" commands |
| 1415 |
with no accompanying paragraph. The middle item is an example: |
| 1416 |
.Sp |
| 1417 |
.Vb 1 |
| 1418 |
\& =over |
| 1419 |
\& |
| 1420 |
\& =item 1 |
| 1421 |
\& |
| 1422 |
\& Pick up dry cleaning. |
| 1423 |
\& |
| 1424 |
\& =item 2 |
| 1425 |
\& |
| 1426 |
\& =item 3 |
| 1427 |
\& |
| 1428 |
\& Stop by the store. Get Abba Zabas, Stoli, and cheap lawn chairs. |
| 1429 |
\& |
| 1430 |
\& =back |
| 1431 |
.Ve |
| 1432 |
.IP \(bu 4 |
| 1433 |
No "=over" ... "=back" region can contain headings. Processors may |
| 1434 |
treat such a heading as an error. |
| 1435 |
.IP \(bu 4 |
| 1436 |
Note that an "=over" ... "=back" region should have some |
| 1437 |
content. That is, authors should not have an empty region like this: |
| 1438 |
.Sp |
| 1439 |
.Vb 1 |
| 1440 |
\& =over |
| 1441 |
\& |
| 1442 |
\& =back |
| 1443 |
.Ve |
| 1444 |
.Sp |
| 1445 |
Pod processors seeing such a contentless "=over" ... "=back" region, |
| 1446 |
may ignore it, or may report it as an error. |
| 1447 |
.IP \(bu 4 |
| 1448 |
Processors must tolerate an "=over" list that goes off the end of the |
| 1449 |
document (i.e., which has no matching "=back"), but they may warn |
| 1450 |
about such a list. |
| 1451 |
.IP \(bu 4 |
| 1452 |
Authors of Pod formatters should note that this construct: |
| 1453 |
.Sp |
| 1454 |
.Vb 1 |
| 1455 |
\& =item Neque |
| 1456 |
\& |
| 1457 |
\& =item Porro |
| 1458 |
\& |
| 1459 |
\& =item Quisquam Est |
| 1460 |
\& |
| 1461 |
\& Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci |
| 1462 |
\& velit, sed quia non numquam eius modi tempora incidunt ut |
| 1463 |
\& labore et dolore magnam aliquam quaerat voluptatem. |
| 1464 |
\& |
| 1465 |
\& =item Ut Enim |
| 1466 |
.Ve |
| 1467 |
.Sp |
| 1468 |
is semantically ambiguous, in a way that makes formatting decisions |
| 1469 |
a bit difficult. On the one hand, it could be mention of an item |
| 1470 |
"Neque", mention of another item "Porro", and mention of another |
| 1471 |
item "Quisquam Est", with just the last one requiring the explanatory |
| 1472 |
paragraph "Qui dolorem ipsum quia dolor..."; and then an item |
| 1473 |
"Ut Enim". In that case, you'd want to format it like so: |
| 1474 |
.Sp |
| 1475 |
.Vb 1 |
| 1476 |
\& Neque |
| 1477 |
\& |
| 1478 |
\& Porro |
| 1479 |
\& |
| 1480 |
\& Quisquam Est |
| 1481 |
\& Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci |
| 1482 |
\& velit, sed quia non numquam eius modi tempora incidunt ut |
| 1483 |
\& labore et dolore magnam aliquam quaerat voluptatem. |
| 1484 |
\& |
| 1485 |
\& Ut Enim |
| 1486 |
.Ve |
| 1487 |
.Sp |
| 1488 |
But it could equally well be a discussion of three (related or equivalent) |
| 1489 |
items, "Neque", "Porro", and "Quisquam Est", followed by a paragraph |
| 1490 |
explaining them all, and then a new item "Ut Enim". In that case, you'd |
| 1491 |
probably want to format it like so: |
| 1492 |
.Sp |
| 1493 |
.Vb 6 |
| 1494 |
\& Neque |
| 1495 |
\& Porro |
| 1496 |
\& Quisquam Est |
| 1497 |
\& Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci |
| 1498 |
\& velit, sed quia non numquam eius modi tempora incidunt ut |
| 1499 |
\& labore et dolore magnam aliquam quaerat voluptatem. |
| 1500 |
\& |
| 1501 |
\& Ut Enim |
| 1502 |
.Ve |
| 1503 |
.Sp |
| 1504 |
But (for the foreseeable future), Pod does not provide any way for Pod |
| 1505 |
authors to distinguish which grouping is meant by the above |
| 1506 |
"=item"\-cluster structure. So formatters should format it like so: |
| 1507 |
.Sp |
| 1508 |
.Vb 1 |
| 1509 |
\& Neque |
| 1510 |
\& |
| 1511 |
\& Porro |
| 1512 |
\& |
| 1513 |
\& Quisquam Est |
| 1514 |
\& |
| 1515 |
\& Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci |
| 1516 |
\& velit, sed quia non numquam eius modi tempora incidunt ut |
| 1517 |
\& labore et dolore magnam aliquam quaerat voluptatem. |
| 1518 |
\& |
| 1519 |
\& Ut Enim |
| 1520 |
.Ve |
| 1521 |
.Sp |
| 1522 |
That is, there should be (at least roughly) equal spacing between |
| 1523 |
items as between paragraphs (although that spacing may well be less |
| 1524 |
than the full height of a line of text). This leaves it to the reader |
| 1525 |
to use (con)textual cues to figure out whether the "Qui dolorem |
| 1526 |
ipsum..." paragraph applies to the "Quisquam Est" item or to all three |
| 1527 |
items "Neque", "Porro", and "Quisquam Est". While not an ideal |
| 1528 |
situation, this is preferable to providing formatting cues that may |
| 1529 |
be actually contrary to the author's intent. |
| 1530 |
.SH "About Data Paragraphs and ""=begin/=end"" Regions" |
| 1531 |
.IX Header "About Data Paragraphs and ""=begin/=end"" Regions" |
| 1532 |
Data paragraphs are typically used for inlining non-Pod data that is |
| 1533 |
to be used (typically passed through) when rendering the document to |
| 1534 |
a specific format: |
| 1535 |
.PP |
| 1536 |
.Vb 1 |
| 1537 |
\& =begin rtf |
| 1538 |
\& |
| 1539 |
\& \epar{\epard\eqr\esa4500{\ei Printed\e~\echdate\e~\echtime}\epar} |
| 1540 |
\& |
| 1541 |
\& =end rtf |
| 1542 |
.Ve |
| 1543 |
.PP |
| 1544 |
The exact same effect could, incidentally, be achieved with a single |
| 1545 |
"=for" paragraph: |
| 1546 |
.PP |
| 1547 |
.Vb 1 |
| 1548 |
\& =for rtf \epar{\epard\eqr\esa4500{\ei Printed\e~\echdate\e~\echtime}\epar} |
| 1549 |
.Ve |
| 1550 |
.PP |
| 1551 |
(Although that is not formally a data paragraph, it has the same |
| 1552 |
meaning as one, and Pod parsers may parse it as one.) |
| 1553 |
.PP |
| 1554 |
Another example of a data paragraph: |
| 1555 |
.PP |
| 1556 |
.Vb 1 |
| 1557 |
\& =begin html |
| 1558 |
\& |
| 1559 |
\& I like <em>PIE</em>! |
| 1560 |
\& |
| 1561 |
\& <hr>Especially pecan pie! |
| 1562 |
\& |
| 1563 |
\& =end html |
| 1564 |
.Ve |
| 1565 |
.PP |
| 1566 |
If these were ordinary paragraphs, the Pod parser would try to |
| 1567 |
expand the "E</em>" (in the first paragraph) as a formatting |
| 1568 |
code, just like "E<lt>" or "E<eacute>". But since this |
| 1569 |
is in a "=begin \fIidentifier\fR"..."=end \fIidentifier\fR" region \fIand\fR |
| 1570 |
the identifier "html" doesn't begin have a ":" prefix, the contents |
| 1571 |
of this region are stored as data paragraphs, instead of being |
| 1572 |
processed as ordinary paragraphs (or if they began with a spaces |
| 1573 |
and/or tabs, as verbatim paragraphs). |
| 1574 |
.PP |
| 1575 |
As a further example: At time of writing, no "biblio" identifier is |
| 1576 |
supported, but suppose some processor were written to recognize it as |
| 1577 |
a way of (say) denoting a bibliographic reference (necessarily |
| 1578 |
containing formatting codes in ordinary paragraphs). The fact that |
| 1579 |
"biblio" paragraphs were meant for ordinary processing would be |
| 1580 |
indicated by prefacing each "biblio" identifier with a colon: |
| 1581 |
.PP |
| 1582 |
.Vb 1 |
| 1583 |
\& =begin :biblio |
| 1584 |
\& |
| 1585 |
\& Wirth, Niklaus. 1976. I<Algorithms + Data Structures = |
| 1586 |
\& Programs.> Prentice\-Hall, Englewood Cliffs, NJ. |
| 1587 |
\& |
| 1588 |
\& =end :biblio |
| 1589 |
.Ve |
| 1590 |
.PP |
| 1591 |
This would signal to the parser that paragraphs in this begin...end |
| 1592 |
region are subject to normal handling as ordinary/verbatim paragraphs |
| 1593 |
(while still tagged as meant only for processors that understand the |
| 1594 |
"biblio" identifier). The same effect could be had with: |
| 1595 |
.PP |
| 1596 |
.Vb 3 |
| 1597 |
\& =for :biblio |
| 1598 |
\& Wirth, Niklaus. 1976. I<Algorithms + Data Structures = |
| 1599 |
\& Programs.> Prentice\-Hall, Englewood Cliffs, NJ. |
| 1600 |
.Ve |
| 1601 |
.PP |
| 1602 |
The ":" on these identifiers means simply "process this stuff |
| 1603 |
normally, even though the result will be for some special target". |
| 1604 |
I suggest that parser APIs report "biblio" as the target identifier, |
| 1605 |
but also report that it had a ":" prefix. (And similarly, with the |
| 1606 |
above "html", report "html" as the target identifier, and note the |
| 1607 |
\&\fIlack\fR of a ":" prefix.) |
| 1608 |
.PP |
| 1609 |
Note that a "=begin \fIidentifier\fR"..."=end \fIidentifier\fR" region where |
| 1610 |
\&\fIidentifier\fR begins with a colon, \fIcan\fR contain commands. For example: |
| 1611 |
.PP |
| 1612 |
.Vb 1 |
| 1613 |
\& =begin :biblio |
| 1614 |
\& |
| 1615 |
\& Wirth\*(Aqs classic is available in several editions, including: |
| 1616 |
\& |
| 1617 |
\& =for comment |
| 1618 |
\& hm, check abebooks.com for how much used copies cost. |
| 1619 |
\& |
| 1620 |
\& =over |
| 1621 |
\& |
| 1622 |
\& =item |
| 1623 |
\& |
| 1624 |
\& Wirth, Niklaus. 1975. I<Algorithmen und Datenstrukturen.> |
| 1625 |
\& Teubner, Stuttgart. [Yes, it\*(Aqs in German.] |
| 1626 |
\& |
| 1627 |
\& =item |
| 1628 |
\& |
| 1629 |
\& Wirth, Niklaus. 1976. I<Algorithms + Data Structures = |
| 1630 |
\& Programs.> Prentice\-Hall, Englewood Cliffs, NJ. |
| 1631 |
\& |
| 1632 |
\& =back |
| 1633 |
\& |
| 1634 |
\& =end :biblio |
| 1635 |
.Ve |
| 1636 |
.PP |
| 1637 |
Note, however, a "=begin \fIidentifier\fR"..."=end \fIidentifier\fR" |
| 1638 |
region where \fIidentifier\fR does \fInot\fR begin with a colon, should not |
| 1639 |
directly contain "=head1" ... "=head4" commands, nor "=over", nor "=back", |
| 1640 |
nor "=item". For example, this may be considered invalid: |
| 1641 |
.PP |
| 1642 |
.Vb 1 |
| 1643 |
\& =begin somedata |
| 1644 |
\& |
| 1645 |
\& This is a data paragraph. |
| 1646 |
\& |
| 1647 |
\& =head1 Don\*(Aqt do this! |
| 1648 |
\& |
| 1649 |
\& This is a data paragraph too. |
| 1650 |
\& |
| 1651 |
\& =end somedata |
| 1652 |
.Ve |
| 1653 |
.PP |
| 1654 |
A Pod processor may signal that the above (specifically the "=head1" |
| 1655 |
paragraph) is an error. Note, however, that the following should |
| 1656 |
\&\fInot\fR be treated as an error: |
| 1657 |
.PP |
| 1658 |
.Vb 1 |
| 1659 |
\& =begin somedata |
| 1660 |
\& |
| 1661 |
\& This is a data paragraph. |
| 1662 |
\& |
| 1663 |
\& =cut |
| 1664 |
\& |
| 1665 |
\& # Yup, this isn\*(Aqt Pod anymore. |
| 1666 |
\& sub excl { (rand() > .5) ? "hoo!" : "hah!" } |
| 1667 |
\& |
| 1668 |
\& =pod |
| 1669 |
\& |
| 1670 |
\& This is a data paragraph too. |
| 1671 |
\& |
| 1672 |
\& =end somedata |
| 1673 |
.Ve |
| 1674 |
.PP |
| 1675 |
And this too is valid: |
| 1676 |
.PP |
| 1677 |
.Vb 1 |
| 1678 |
\& =begin someformat |
| 1679 |
\& |
| 1680 |
\& This is a data paragraph. |
| 1681 |
\& |
| 1682 |
\& And this is a data paragraph. |
| 1683 |
\& |
| 1684 |
\& =begin someotherformat |
| 1685 |
\& |
| 1686 |
\& This is a data paragraph too. |
| 1687 |
\& |
| 1688 |
\& And this is a data paragraph too. |
| 1689 |
\& |
| 1690 |
\& =begin :yetanotherformat |
| 1691 |
\& |
| 1692 |
\& =head2 This is a command paragraph! |
| 1693 |
\& |
| 1694 |
\& This is an ordinary paragraph! |
| 1695 |
\& |
| 1696 |
\& And this is a verbatim paragraph! |
| 1697 |
\& |
| 1698 |
\& =end :yetanotherformat |
| 1699 |
\& |
| 1700 |
\& =end someotherformat |
| 1701 |
\& |
| 1702 |
\& Another data paragraph! |
| 1703 |
\& |
| 1704 |
\& =end someformat |
| 1705 |
.Ve |
| 1706 |
.PP |
| 1707 |
The contents of the above "=begin :yetanotherformat" ... |
| 1708 |
"=end :yetanotherformat" region \fIaren't\fR data paragraphs, because |
| 1709 |
the immediately containing region's identifier (":yetanotherformat") |
| 1710 |
begins with a colon. In practice, most regions that contain |
| 1711 |
data paragraphs will contain \fIonly\fR data paragraphs; however, |
| 1712 |
the above nesting is syntactically valid as Pod, even if it is |
| 1713 |
rare. However, the handlers for some formats, like "html", |
| 1714 |
will accept only data paragraphs, not nested regions; and they may |
| 1715 |
complain if they see (targeted for them) nested regions, or commands, |
| 1716 |
other than "=end", "=pod", and "=cut". |
| 1717 |
.PP |
| 1718 |
Also consider this valid structure: |
| 1719 |
.PP |
| 1720 |
.Vb 1 |
| 1721 |
\& =begin :biblio |
| 1722 |
\& |
| 1723 |
\& Wirth\*(Aqs classic is available in several editions, including: |
| 1724 |
\& |
| 1725 |
\& =over |
| 1726 |
\& |
| 1727 |
\& =item |
| 1728 |
\& |
| 1729 |
\& Wirth, Niklaus. 1975. I<Algorithmen und Datenstrukturen.> |
| 1730 |
\& Teubner, Stuttgart. [Yes, it\*(Aqs in German.] |
| 1731 |
\& |
| 1732 |
\& =item |
| 1733 |
\& |
| 1734 |
\& Wirth, Niklaus. 1976. I<Algorithms + Data Structures = |
| 1735 |
\& Programs.> Prentice\-Hall, Englewood Cliffs, NJ. |
| 1736 |
\& |
| 1737 |
\& =back |
| 1738 |
\& |
| 1739 |
\& Buy buy buy! |
| 1740 |
\& |
| 1741 |
\& =begin html |
| 1742 |
\& |
| 1743 |
\& <img src=\*(Aqwirth_spokesmodeling_book.png\*(Aq> |
| 1744 |
\& |
| 1745 |
\& <hr> |
| 1746 |
\& |
| 1747 |
\& =end html |
| 1748 |
\& |
| 1749 |
\& Now now now! |
| 1750 |
\& |
| 1751 |
\& =end :biblio |
| 1752 |
.Ve |
| 1753 |
.PP |
| 1754 |
There, the "=begin html"..."=end html" region is nested inside |
| 1755 |
the larger "=begin :biblio"..."=end :biblio" region. Note that the |
| 1756 |
content of the "=begin html"..."=end html" region is data |
| 1757 |
paragraph(s), because the immediately containing region's identifier |
| 1758 |
("html") \fIdoesn't\fR begin with a colon. |
| 1759 |
.PP |
| 1760 |
Pod parsers, when processing a series of data paragraphs one |
| 1761 |
after another (within a single region), should consider them to |
| 1762 |
be one large data paragraph that happens to contain blank lines. So |
| 1763 |
the content of the above "=begin html"..."=end html" \fImay\fR be stored |
| 1764 |
as two data paragraphs (one consisting of |
| 1765 |
"<img src='wirth_spokesmodeling_book.png'>\en" |
| 1766 |
and another consisting of "<hr>\en"), but \fIshould\fR be stored as |
| 1767 |
a single data paragraph (consisting of |
| 1768 |
"<img src='wirth_spokesmodeling_book.png'>\en\en<hr>\en"). |
| 1769 |
.PP |
| 1770 |
Pod processors should tolerate empty |
| 1771 |
"=begin \fIsomething\fR"..."=end \fIsomething\fR" regions, |
| 1772 |
empty "=begin :\fIsomething\fR"..."=end :\fIsomething\fR" regions, and |
| 1773 |
contentless "=for \fIsomething\fR" and "=for :\fIsomething\fR" |
| 1774 |
paragraphs. I.e., these should be tolerated: |
| 1775 |
.PP |
| 1776 |
.Vb 1 |
| 1777 |
\& =for html |
| 1778 |
\& |
| 1779 |
\& =begin html |
| 1780 |
\& |
| 1781 |
\& =end html |
| 1782 |
\& |
| 1783 |
\& =begin :biblio |
| 1784 |
\& |
| 1785 |
\& =end :biblio |
| 1786 |
.Ve |
| 1787 |
.PP |
| 1788 |
Incidentally, note that there's no easy way to express a data |
| 1789 |
paragraph starting with something that looks like a command. Consider: |
| 1790 |
.PP |
| 1791 |
.Vb 1 |
| 1792 |
\& =begin stuff |
| 1793 |
\& |
| 1794 |
\& =shazbot |
| 1795 |
\& |
| 1796 |
\& =end stuff |
| 1797 |
.Ve |
| 1798 |
.PP |
| 1799 |
There, "=shazbot" will be parsed as a Pod command "shazbot", not as a data |
| 1800 |
paragraph "=shazbot\en". However, you can express a data paragraph consisting |
| 1801 |
of "=shazbot\en" using this code: |
| 1802 |
.PP |
| 1803 |
.Vb 1 |
| 1804 |
\& =for stuff =shazbot |
| 1805 |
.Ve |
| 1806 |
.PP |
| 1807 |
The situation where this is necessary, is presumably quite rare. |
| 1808 |
.PP |
| 1809 |
Note that =end commands must match the currently open =begin command. That |
| 1810 |
is, they must properly nest. For example, this is valid: |
| 1811 |
.PP |
| 1812 |
.Vb 1 |
| 1813 |
\& =begin outer |
| 1814 |
\& |
| 1815 |
\& X |
| 1816 |
\& |
| 1817 |
\& =begin inner |
| 1818 |
\& |
| 1819 |
\& Y |
| 1820 |
\& |
| 1821 |
\& =end inner |
| 1822 |
\& |
| 1823 |
\& Z |
| 1824 |
\& |
| 1825 |
\& =end outer |
| 1826 |
.Ve |
| 1827 |
.PP |
| 1828 |
while this is invalid: |
| 1829 |
.PP |
| 1830 |
.Vb 1 |
| 1831 |
\& =begin outer |
| 1832 |
\& |
| 1833 |
\& X |
| 1834 |
\& |
| 1835 |
\& =begin inner |
| 1836 |
\& |
| 1837 |
\& Y |
| 1838 |
\& |
| 1839 |
\& =end outer |
| 1840 |
\& |
| 1841 |
\& Z |
| 1842 |
\& |
| 1843 |
\& =end inner |
| 1844 |
.Ve |
| 1845 |
.PP |
| 1846 |
This latter is improper because when the "=end outer" command is seen, the |
| 1847 |
currently open region has the formatname "inner", not "outer". (It just |
| 1848 |
happens that "outer" is the format name of a higher-up region.) This is |
| 1849 |
an error. Processors must by default report this as an error, and may halt |
| 1850 |
processing the document containing that error. A corollary of this is that |
| 1851 |
regions cannot "overlap". That is, the latter block above does not represent |
| 1852 |
a region called "outer" which contains X and Y, overlapping a region called |
| 1853 |
"inner" which contains Y and Z. But because it is invalid (as all |
| 1854 |
apparently overlapping regions would be), it doesn't represent that, or |
| 1855 |
anything at all. |
| 1856 |
.PP |
| 1857 |
Similarly, this is invalid: |
| 1858 |
.PP |
| 1859 |
.Vb 1 |
| 1860 |
\& =begin thing |
| 1861 |
\& |
| 1862 |
\& =end hting |
| 1863 |
.Ve |
| 1864 |
.PP |
| 1865 |
This is an error because the region is opened by "thing", and the "=end" |
| 1866 |
tries to close "hting" [sic]. |
| 1867 |
.PP |
| 1868 |
This is also invalid: |
| 1869 |
.PP |
| 1870 |
.Vb 1 |
| 1871 |
\& =begin thing |
| 1872 |
\& |
| 1873 |
\& =end |
| 1874 |
.Ve |
| 1875 |
.PP |
| 1876 |
This is invalid because every "=end" command must have a formatname |
| 1877 |
parameter. |
| 1878 |
.SH "SEE ALSO" |
| 1879 |
.IX Header "SEE ALSO" |
| 1880 |
perlpod, "PODs: Embedded Documentation" in perlsyn, |
| 1881 |
podchecker |
| 1882 |
.SH AUTHOR |
| 1883 |
.IX Header "AUTHOR" |
| 1884 |
Sean M. Burke |