mingw/html/pod/perlpodspec.html

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