{
    "content": [
        {
            "type": "text",
            "text": "# perlpodspec (man)\n\n## NAME\n\nperlpodspec - Plain Old Documentation: format specification and notes\n\n## DESCRIPTION\n\nThis document is detailed notes on the Pod markup language.  Most people will only have to\nread perlpod to know how to write in Pod, but this document may answer some incidental\nquestions to do with parsing and rendering Pod.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **Pod Definitions**\n- **Pod Commands**\n- **Pod Formatting Codes**\n- **Notes on Implementing Pod Processors**\n- **SEE ALSO**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "perlpodspec",
        "section": "",
        "mode": "man",
        "summary": "perlpodspec - Plain Old Documentation: format specification and notes",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 17,
                "subsections": []
            },
            {
                "name": "Pod Definitions",
                "lines": 111,
                "subsections": []
            },
            {
                "name": "Pod Commands",
                "lines": 142,
                "subsections": []
            },
            {
                "name": "Pod Formatting Codes",
                "lines": 152,
                "subsections": []
            },
            {
                "name": "Notes on Implementing Pod Processors",
                "lines": 1028,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 3,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "perlpodspec - Plain Old Documentation: format specification and notes\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This document is detailed notes on the Pod markup language.  Most people will only have to\nread perlpod to know how to write in Pod, but this document may answer some incidental\nquestions to do with parsing and rendering Pod.\n\nIn this document, \"must\" / \"must not\", \"should\" / \"should not\", and \"may\" have their\nconventional (cf. RFC 2119) meanings: \"X must do Y\" means that if X doesn't do Y, it's\nagainst this specification, and should really be fixed.  \"X should do Y\" means that it's\nrecommended, but X may fail to do Y, if there's a good reason.  \"X may do Y\" is merely a note\nthat X can do Y at will (although it is up to the reader to detect any connotation of \"and I\nthink it would be nice if X did Y\" versus \"it wouldn't really bother me if X did Y\").\n\nNotably, when I say \"the parser should do Y\", the parser may fail to do Y, if the calling\napplication explicitly requests that the parser not do Y.  I often phrase this as \"the parser\nshould, by default, do Y.\"  This doesn't require the parser to provide an option for turning\noff whatever feature Y is (like expanding tabs in verbatim paragraphs), although it\nimplicates that such an option may be provided.\n",
                "subsections": []
            },
            "Pod Definitions": {
                "content": "Pod is embedded in files, typically Perl source files, although you can write a file that's\nnothing but Pod.\n\nA line in a file consists of zero or more non-newline characters, terminated by either a\nnewline or the end of the file.\n\nA newline sequence is usually a platform-dependent concept, but Pod parsers should understand\nit to mean any of CR (ASCII 13), LF (ASCII 10), or a CRLF (ASCII 13 followed immediately by\nASCII 10), in addition to any other system-specific meaning.  The first CR/CRLF/LF sequence\nin the file may be used as the basis for identifying the newline sequence for parsing the\nrest of the file.\n\nA blank line is a line consisting entirely of zero or more spaces (ASCII 32) or tabs (ASCII\n9), and terminated by a newline or end-of-file.  A non-blank line is a line containing one or\nmore characters other than space or tab (and terminated by a newline or end-of-file).\n\n(Note: Many older Pod parsers did not accept a line consisting of spaces/tabs and then a\nnewline as a blank line. The only lines they considered blank were lines consisting of no\ncharacters at all, terminated by a newline.)\n\nWhitespace is used in this document as a blanket term for spaces, tabs, and newline\nsequences.  (By itself, this term usually refers to literal whitespace.  That is, sequences\nof whitespace characters in Pod source, as opposed to \"E<32>\", which is a formatting code\nthat denotes a whitespace character.)\n\nA Pod parser is a module meant for parsing Pod (regardless of whether this involves calling\ncallbacks or building a parse tree or directly formatting it).  A Pod formatter (or Pod\ntranslator) is a module or program that converts Pod to some other format (HTML, plaintext,\nTeX, PostScript, RTF).  A Pod processor might be a formatter or translator, or might be a\nprogram that does something else with the Pod (like counting words, scanning for index\npoints, etc.).\n\nPod content is contained in Pod blocks.  A Pod block starts with a line that matches\n\"m/\\A=[a-zA-Z]/\", and continues up to the next line that matches \"m/\\A=cut/\" or up to the end\nof the file if there is no \"m/\\A=cut/\" line.\n\nNote that a parser is not expected to distinguish between something that looks like pod, but\nis in a quoted string, such as a here document.\n\nWithin a Pod block, there are Pod paragraphs.  A Pod paragraph consists of non-blank lines of\ntext, separated by one or more blank lines.\n\nFor purposes of Pod processing, there are four types of paragraphs in a Pod block:\n\n•   A  command  paragraph (also called a \"directive\").  The first line of this paragraph must\nmatch \"m/\\A=[a-zA-Z]/\".  Command paragraphs are typically one line, as in:\n\n=head1 NOTES\n\n=item *\n\nBut they may span several (non-blank) lines:\n\n=for comment\nHm, I wonder what it would look like if\nyou tried to write a BNF for Pod from this.\n\n=head3 Dr. Strangelove, or: How I Learned to\nStop Worrying and Love the Bomb\n\nSome command paragraphs allow formatting codes in their content  (i.e.,  after  the  part\nthat matches \"m/\\A=[a-zA-Z]\\S*\\s*/\"), as in:\n\n=head1 Did You Remember to C<use strict;>?\n\nIn  other words, the Pod processing handler for \"head1\" will apply the same processing to\n\"Did You Remember to C<use strict;>?\" that it  would  to  an  ordinary  paragraph  (i.e.,\nformatting  codes  like  \"C<...>\") are parsed and presumably formatted appropriately, and\nwhitespace in the form of literal spaces and/or tabs is not significant.\n\n•   A verbatim paragraph.  The first line of this paragraph must be a literal space  or  tab,\nand  this  paragraph  must  not  be  inside  a \"=begin identifier\", ... \"=end identifier\"\nsequence unless \"identifier\" begins with a colon (\":\").  That is, if a  paragraph  starts\nwith  a  literal space or tab, but is inside a \"=begin identifier\", ... \"=end identifier\"\nregion, then it's a data paragraph, unless \"identifier\" begins with a colon.\n\nWhitespace is significant in verbatim  paragraphs  (although,  in  processing,  tabs  are\nprobably expanded).\n\n•   An  ordinary  paragraph.   A paragraph is an ordinary paragraph if its first line matches\nneither \"m/\\A=[a-zA-Z]/\" nor \"m/\\A[ \\t]/\", and if it's not inside a \"=begin  identifier\",\n... \"=end identifier\" sequence unless \"identifier\" begins with a colon (\":\").\n\n•   A  data  paragraph.   This  is a paragraph that is inside a \"=begin identifier\" ... \"=end\nidentifier\" sequence where \"identifier\" does not begin with a literal  colon  (\":\").   In\nsome  sense,  a data paragraph is not part of Pod at all (i.e., effectively it's \"out-of-\nband\"), since it's not subject to most kinds of Pod parsing; but it  is  specified  here,\nsince  Pod parsers need to be able to call an event for it, or store it in some form in a\nparse tree, or at least just parse around it.\n\nFor example: consider the following paragraphs:\n\n# <- that's the 0th column\n\n=head1 Foo\n\nStuff\n\n$foo->bar\n\n=cut\n\nHere, \"=head1 Foo\" and \"=cut\" are command paragraphs because the first line of  each  matches\n\"m/\\A=[a-zA-Z]/\".   \"[space][space]$foo->bar\" is a verbatim paragraph, because its first line\nstarts with a literal whitespace character (and there's no \"=begin\"...\"=end\" region around).\n\nThe \"=begin identifier\" ... \"=end identifier\" commands stop  paragraphs  that  they  surround\nfrom  being  parsed  as  ordinary  or verbatim paragraphs, if identifier doesn't begin with a\ncolon.  This is discussed in detail in the section \"About Data Paragraphs  and  \"=begin/=end\"\nRegions\".\n",
                "subsections": []
            },
            "Pod Commands": {
                "content": "This  section  is intended to supplement and clarify the discussion in \"Command Paragraph\" in\nperlpod.  These are the currently recognized Pod commands:\n\n\"=head1\", \"=head2\", \"=head3\", \"=head4\", \"=head5\", \"=head6\"\nThis command indicates that the text in the remainder of  the  paragraph  is  a  heading.\nThat text may contain formatting codes.  Examples:\n\n=head1 Object Attributes\n\n=head3 What B<Not> to Do!\n\nBoth  \"=head5\"  and  \"=head6\"  were  added  in 2020 and might not be supported on all Pod\nparsers. Pod::Simple 3.41 was released  on  October  2020  and  supports  both  of  these\nproviding support for all Pod::Simple-based Pod parsers.\n\n\"=pod\"\nThis command indicates that this paragraph begins a Pod block.  (If we are already in the\nmiddle  of a Pod block, this command has no effect at all.)  If there is any text in this\ncommand paragraph after \"=pod\", it must be ignored.  Examples:\n\n=pod\n\nThis is a plain Pod paragraph.\n\n=pod This text is ignored.\n\n\"=cut\"\nThis command indicates that this line is the end of this previously  started  Pod  block.\nIf there is any text after \"=cut\" on the line, it must be ignored.  Examples:\n\n=cut\n\n=cut The documentation ends here.\n\n=cut\n# This is the first line of program text.\nsub foo { # This is the second.\n\nIt  is an error to try to start a Pod block with a \"=cut\" command.  In that case, the Pod\nprocessor must halt parsing of the input file, and must by default emit a warning.\n\n\"=over\"\nThis command indicates that this is the start of a list/indent region.  If there  is  any\ntext  following  the  \"=over\",  it  must consist of only a nonzero positive numeral.  The\nsemantics of this numeral is explained in  the  \"About  =over...=back  Regions\"  section,\nfurther below.  Formatting codes are not expanded.  Examples:\n\n=over 3\n\n=over 3.5\n\n=over\n\n\"=item\"\nThis  command  indicates  that  an  item  in  a  list  begins here.  Formatting codes are\nprocessed.  The semantics of the (optional) text in the remainder of this  paragraph  are\nexplained in the \"About =over...=back Regions\" section, further below.  Examples:\n\n=item\n\n=item *\n\n=item      *\n\n=item 14\n\n=item   3.\n\n=item C<< $thing->stuff(I<dodad>) >>\n\n=item For transporting us beyond seas to be tried for pretended\noffenses\n\n=item He is at this time transporting large armies of foreign\nmercenaries to complete the works of death, desolation and\ntyranny, already begun with circumstances of cruelty and perfidy\nscarcely paralleled in the most barbarous ages, and totally\nunworthy the head of a civilized nation.\n\n\"=back\"\nThis  command  indicates  that  this  is  the  end of the region begun by the most recent\n\"=over\" command.  It permits no text after the \"=back\" command.\n\n\"=begin formatname\"\n\"=begin formatname parameter\"\nThis marks the following paragraphs (until the matching \"=end formatname\") as  being  for\nsome  special kind of processing.  Unless \"formatname\" begins with a colon, the contained\nnon-command paragraphs are data paragraphs.  But if \"formatname\" does begin with a colon,\nthen non-command  paragraphs  are  ordinary  paragraphs  or  data  paragraphs.   This  is\ndiscussed in detail in the section \"About Data Paragraphs and \"=begin/=end\" Regions\".\n\nIt  is  advised  that formatnames match the regexp \"m/\\A:?[-a-zA-Z0-9]+\\z/\".  Everything\nfollowing whitespace after the formatname  is  a  parameter  that  may  be  used  by  the\nformatter  when  dealing  with  this  region.  This parameter must not be repeated in the\n\"=end\" paragraph.  Implementors should anticipate future expansion in the  semantics  and\nsyntax of the first parameter to \"=begin\"/\"=end\"/\"=for\".\n\n\"=end formatname\"\nThis  marks  the end of the region opened by the matching \"=begin formatname\" region.  If\n\"formatname\" is not the formatname of the most recent open  \"=begin  formatname\"  region,\nthen  this  is an error, and must generate an error message.  This is discussed in detail\nin the section \"About Data Paragraphs and \"=begin/=end\" Regions\".\n\n\"=for formatname text...\"\nThis is synonymous with:\n\n=begin formatname\n\ntext...\n\n=end formatname\n\nThat is, it creates a region consisting of a single paragraph; that paragraph  is  to  be\ntreated  as a normal paragraph if \"formatname\" begins with a \":\"; if \"formatname\" doesn't\nbegin with a colon, then \"text...\" will constitute a data paragraph.  There is no way  to\nuse \"=for formatname text...\" to express \"text...\" as a verbatim paragraph.\n\n\"=encoding encodingname\"\nThis  command, which should occur early in the document (at least before any non-US-ASCII\ndata!), declares that this document is encoded in the encoding encodingname,  which  must\nbe  an  encoding  name that Encode recognizes.  (Encode's list of supported encodings, in\nEncode::Supported, is useful here.)   If  the  Pod  parser  cannot  decode  the  declared\nencoding, it should emit a warning and may abort parsing the document altogether.\n\nA  document  having  more  than  one \"=encoding\" line should be considered an error.  Pod\nprocessors may silently tolerate  this  if  the  not-first  \"=encoding\"  lines  are  just\nduplicates  of  the  first  one  (e.g.,  if there's a \"=encoding utf8\" line, and later on\nanother \"=encoding utf8\"  line).   But  Pod  processors  should  complain  if  there  are\ncontradictory  \"=encoding\"  lines  in  the  same document (e.g., if there is a \"=encoding\nutf8\" early in the document and \"=encoding big5\" later).  Pod processors  that  recognize\nBOMs may also complain if they see an \"=encoding\" line that contradicts the BOM (e.g., if\na document with a UTF-16LE BOM has an \"=encoding shiftjis\" line).\n\nIf  a  Pod  processor  sees  any  command  other than the ones listed above (like \"=head\", or\n\"=haed1\", or \"=stuff\", or \"=cuttlefish\", or \"=w123\"), that processor must  by  default  treat\nthis  as  an  error.   It must not process the paragraph beginning with that command, must by\ndefault warn of this as an error, and may abort the parse.  A Pod parser may allow a way  for\nparticular  applications  to  add  to the above list of known commands, and to stipulate, for\neach additional command, whether formatting codes should be processed.\n\nFuture versions of this specification may add additional commands.\n",
                "subsections": []
            },
            "Pod Formatting Codes": {
                "content": "(Note that in previous drafts of this document and of perlpod, formatting codes were referred\nto as \"interior sequences\", and this term may still be found in  the  documentation  for  Pod\nparsers, and in error messages from Pod processors.)\n\nThere are two syntaxes for formatting codes:\n\n•   A  formatting  code starts with a capital letter (just US-ASCII [A-Z]) followed by a \"<\",\nany number of characters, and ending with the first matching \">\".  Examples:\n\nThat's what I<you> think!\n\nWhat's C<CORE::dump()> for?\n\nX<C<chmod> and C<unlink()> Under Different Operating Systems>\n\n•   A formatting code starts with a capital letter (just US-ASCII [A-Z]) followed by  two  or\nmore  \"<\"'s,  one  or  more  whitespace characters, any number of characters, one or more\nwhitespace characters, and ending with the first matching sequence of two or more  \">\"'s,\nwhere  the  number  of \">\"'s equals the number of \"<\"'s in the opening of this formatting\ncode.  Examples:\n\nThat's what I<< you >> think!\n\nC<<< open(X, \">>thing.dat\") || die $! >>>\n\nB<< $foo->bar(); >>\n\nWith this syntax, the whitespace character(s) after the \"C<<<\" and before the  \">>>\"  (or\nwhatever  letter)  are not renderable. They do not signify whitespace, are merely part of\nthe formatting codes themselves.  That is, these are all synonymous:\n\nC<thing>\nC<< thing >>\nC<<           thing     >>\nC<<<   thing >>>\nC<<<<\nthing\n>>>>\n\nand so on.\n\nFinally, the multiple-angle-bracket form does not  alter  the  interpretation  of  nested\nformatting codes, meaning that the following four example lines are identical in meaning:\n\nB<example: C<$a E<lt>=E<gt> $b>>\n\nB<example: C<< $a <=> $b >>>\n\nB<example: C<< $a E<lt>=E<gt> $b >>>\n\nB<<< example: C<< $a E<lt>=E<gt> $b >> >>>\n\nIn  parsing  Pod,  a  notably  tricky  part  is  the correct parsing of (potentially nested!)\nformatting codes.  Implementors should consult  the  code  in  the  \"parsetext\"  routine  in\nPod::Parser as an example of a correct implementation.\n\n\"I<text>\" -- italic text\nSee the brief discussion in \"Formatting Codes\" in perlpod.\n\n\"B<text>\" -- bold text\nSee the brief discussion in \"Formatting Codes\" in perlpod.\n\n\"C<code>\" -- code text\nSee the brief discussion in \"Formatting Codes\" in perlpod.\n\n\"F<filename>\" -- style for filenames\nSee the brief discussion in \"Formatting Codes\" in perlpod.\n\n\"X<topic name>\" -- an index entry\nSee the brief discussion in \"Formatting Codes\" in perlpod.\n\nThis  code  is  unusual  in  that  most  formatters  completely discard this code and its\ncontent.  Other formatters will render it with  invisible  codes  that  can  be  used  in\nbuilding an index of the current document.\n\n\"Z<>\" -- a null (zero-effect) formatting code\nDiscussed briefly in \"Formatting Codes\" in perlpod.\n\nThis  code  is  unusual  in  that  it  should  have no content.  That is, a processor may\ncomplain if it sees \"Z<potatoes>\".  Whether or not it complains, the potatoes text should\nignored.\n\n\"L<name>\" -- a hyperlink\nThe complicated syntaxes of this code are discussed at length in  \"Formatting  Codes\"  in\nperlpod,  and  implementation  details  are  discussed  below,  in  \"About L<...> Codes\".\nParsing the contents of L<content> is tricky.  Notably, the content has to be checked for\nwhether it looks like a URL, or whether it has to be split on literal \"|\" and/or \"/\"  (in\nthe right order!), and so on, before E<...> codes are resolved.\n\n\"E<escape>\" -- a character escape\nSee  \"Formatting  Codes\"  in  perlpod,  and  several points in \"Notes on Implementing Pod\nProcessors\".\n\n\"S<text>\" -- text contains non-breaking spaces\nThis formatting code is syntactically simple, but semantically complex.  What it means is\nthat each space in the printable content of this code signifies a non-breaking space.\n\nConsider:\n\nC<$x ? $y    :  $z>\n\nS<C<$x ? $y     :  $z>>\n\nBoth signify the monospace (c[ode] style) text consisting of \"$x\", one  space,  \"?\",  one\nspace,  \":\",  one  space,  \"$z\".   The difference is that in the latter, with the S code,\nthose spaces are not \"normal\" spaces, but instead are non-breaking spaces.\n\nIf a Pod processor sees any formatting code other than the ones listed above (as in \"N<...>\",\nor \"Q<...>\", etc.), that processor must by default treat this as an error.  A Pod parser  may\nallow a way for particular applications to add to the above list of known formatting codes; a\nPod  parser  might  even  allow  a  way to stipulate, for each additional command, whether it\nrequires some form of special processing, as L<...> does.\n\nFuture versions of this specification may add additional formatting codes.\n\nHistorical note:  A few older Pod processors would not see a \">\" as closing a \"C<\"  code,  if\nthe \">\" was immediately preceded by a \"-\".  This was so that this:\n\nC<$foo->bar>\n\nwould parse as equivalent to this:\n\nC<$foo-E<gt>bar>\n\ninstead  of as equivalent to a \"C\" formatting code containing only \"$foo-\", and then a \"bar>\"\noutside the \"C\" formatting code.  This problem has since  been  solved  by  the  addition  of\nsyntaxes like this:\n\nC<< $foo->bar >>\n\nCompliant parsers must not treat \"->\" as special.\n\nFormatting  codes  absolutely  cannot span paragraphs.  If a code is opened in one paragraph,\nand no closing code is found by the end of that paragraph, the Pod  parser  must  close  that\nformatting code, and should complain (as in \"Unterminated I code in the paragraph starting at\nline 123: 'Time objects are not...'\").  So these two paragraphs:\n\nI<I told you not to do this!\n\nDon't make me say it again!>\n\n...must not be parsed as two paragraphs in italics (with the I code starting in one paragraph\nand  starting  in another.)  Instead, the first paragraph should generate a warning, but that\naside, the above code must parse as if it were:\n\nI<I told you not to do this!>\n\nDon't make me say it again!E<gt>\n\n(In SGMLish jargon,  all  Pod  commands  are  like  block-level  elements,  whereas  all  Pod\nformatting codes are like inline-level elements.)\n",
                "subsections": []
            },
            "Notes on Implementing Pod Processors": {
                "content": "The  following is a long section of miscellaneous requirements and suggestions to do with Pod\nprocessing.\n\n•   Pod formatters should tolerate lines in verbatim blocks that are of any length,  even  if\nthat  means  having  to break them (possibly several times, for very long lines) to avoid\ntext running off the side of the page.  Pod formatters may warn  of  such  line-breaking.\nSuch  warnings are particularly appropriate for lines are over 100 characters long, which\nare usually not intentional.\n\n•   Pod parsers must recognize all of the three well-known newline formats: CR, LF, and CRLF.\nSee perlport.\n\n•   Pod parsers should accept input lines that are of any length.\n\n•   Since Perl recognizes a Unicode Byte Order Mark at the start of files as  signaling  that\nthe  file is Unicode encoded as in UTF-16 (whether big-endian or little-endian) or UTF-8,\nPod parsers should do the same.  Otherwise, the character encoding should  be  understood\nas  being  UTF-8  if  the  first highbit byte sequence in the file seems valid as a UTF-8\nsequence, or otherwise as CP-1252 (earlier versions of this  specification  used  Latin-1\ninstead of CP-1252).\n\nFuture  versions  of  this  specification may specify how Pod can accept other encodings.\nPresumably treatment of other encodings in Pod  parsing  would  be  as  in  XML  parsing:\nwhatever  the  encoding  declared  by  a  particular Pod file, content is to be stored in\nmemory as Unicode characters.\n\n•   The well known Unicode Byte Order Marks are as follows:  if the file begins with the  two\nliteral byte values 0xFE 0xFF, this is the BOM for big-endian UTF-16.  If the file begins\nwith  the two literal byte value 0xFF 0xFE, this is the BOM for little-endian UTF-16.  On\nan ASCII platform, if the file begins with the three literal byte values 0xEF 0xBB  0xBF,\nthis is the BOM for UTF-8.  A mechanism portable to EBCDIC platforms is to:\n\nmy $utf8bom = \"\\x{FEFF}\";\nutf8::encode($utf8bom);\n\n•   A naive, but often sufficient heuristic on ASCII platforms, for testing the first highbit\nbyte-sequence  in  a  BOM-less  file  (whether  in  code or in Pod!), to see whether that\nsequence is valid as UTF-8 (RFC 2279) is to check whether that  the  first  byte  in  the\nsequence  is  in  the  range 0xC2 - 0xFD and whether the next byte is in the range 0x80 -\n0xBF.  If so, the parser may conclude that  this  file  is  in  UTF-8,  and  all  highbit\nsequences  in  the file should be assumed to be UTF-8.  Otherwise the parser should treat\nthe file as being in CP-1252.  (A better check, and which works on  EBCDIC  platforms  as\nwell,  is to pass a copy of the sequence to utf8::decode() which performs a full validity\ncheck on the sequence and returns TRUE if it  is  valid  UTF-8,  FALSE  otherwise.   This\nfunction  is  always  pre-loaded,  is  fast because it is written in C, and will only get\ncalled at most once, so you don't need to avoid it out of performance concerns.)  In  the\nunlikely  circumstance  that the first highbit sequence in a truly non-UTF-8 file happens\nto appear to be UTF-8, one can cater to our heuristic (as well as  any  more  intelligent\nheuristic)  by prefacing that line with a comment line containing a highbit sequence that\nis clearly not valid as UTF-8.  A line consisting of simply \"#\", an e-acute, and any non-\nhighbit byte, is sufficient to establish this file's encoding.\n\n•   Pod processors must treat a \"=for [label] [content...]\" paragraph  as  meaning  the  same\nthing  as  a  \"=begin [label]\" paragraph, content, and an \"=end [label]\" paragraph.  (The\nparser may conflate these two constructs, or may leave them distinct, in the  expectation\nthat the formatter will nevertheless treat them the same.)\n\n•   When  rendering  Pod  to  a format that allows comments (i.e., to nearly any format other\nthan plaintext), a Pod formatter must  insert  comment  text  identifying  its  name  and\nversion  number,  and  the  name  and version numbers of any modules it might be using to\nprocess the Pod.  Minimal examples:\n\n%% POD::Pod2PS v3.14159, using POD::Parser v1.92\n\n<!-- Pod::HTML v3.14159, using POD::Parser v1.92 -->\n\n{\\doccomm generated by Pod::Tree::RTF 3.14159 using Pod::Tree 1.08}\n\n.\\\" Pod::Man version 3.14159, using POD::Parser version 1.92\n\nFormatters may also insert additional comments, including: the release date  of  the  Pod\nformatter  program,  the  contact address for the author(s) of the formatter, the current\ntime, the name of input file, the formatting options in effect,  version  of  Perl  used,\netc.\n\nFormatters  may  also  choose  to note errors/warnings as comments, besides or instead of\nemitting them otherwise (as in messages to STDERR, or \"die\"ing).\n\n•   Pod parsers may emit warnings or error messages (\"Unknown E code  E<zslig>!\")  to  STDERR\n(whether through printing to STDERR, or \"warn\"ing/\"carp\"ing, or \"die\"ing/\"croak\"ing), but\nmust  allow suppressing all such STDERR output, and instead allow an option for reporting\nerrors/warnings in some other way, whether by triggering a callback, or noting errors  in\nsome attribute of the document object, or some similarly unobtrusive mechanism -- or even\nby appending a \"Pod Errors\" section to the end of the parsed form of the document.\n\n•   In  cases  of  exceptionally  aberrant  documents, Pod parsers may abort the parse.  Even\nthen, using \"die\"ing/\"croak\"ing is to be avoided; where possible, the parser library  may\nsimply  close the input file and add text like \"* Formatting Aborted *\" to the end of\nthe (partial) in-memory document.\n\n•   In paragraphs where formatting codes (like E<...>,  B<...>)  are  understood  (i.e.,  not\nverbatim  paragraphs,  but  including  ordinary  paragraphs,  and command paragraphs that\nproduce  renderable  text,  like  \"=head1\"),  literal  whitespace  should  generally   be\nconsidered  \"insignificant\",  in  that  one  literal  space  has  the same meaning as any\n(nonzero) number of literal spaces, literal newlines, and literal tabs (as long  as  this\nproduces  no blank lines, since those would terminate the paragraph).  Pod parsers should\ncompact literal whitespace in each processed paragraph, but may  provide  an  option  for\noverriding this (since some processing tasks do not require it), or may follow additional\nspecial  rules  (for  example,  specially  treating  period-space-space or period-newline\nsequences).\n\n•   Pod parsers should not, by default, try to coerce apostrophe (') and quote (\") into smart\nquotes (little 9's, 66's, 99's, etc), nor try to turn backtick (`) into anything else but\na single backtick character (distinct from an  open  quote  character!),  nor  \"--\"  into\nanything  but  two minus signs.  They must never do any of those things to text in C<...>\nformatting codes, and never ever to text in verbatim paragraphs.\n\n•   When rendering Pod to a format that has two kinds of  hyphens  (-),  one  that's  a  non-\nbreaking  hyphen,  and  another that's a breakable hyphen (as in \"object-oriented\", which\ncan be split across lines as \"object-\", newline, \"oriented\"), formatters  are  encouraged\nto  generally  translate  \"-\" to non-breaking hyphen, but may apply heuristics to convert\nsome of these to breaking hyphens.\n\n•   Pod formatters should make reasonable efforts to keep  words  of  Perl  code  from  being\nbroken  across  lines.   For  example,  \"Foo::Bar\"  in some formatting systems is seen as\neligible for being broken across lines as \"Foo::\" newline \"Bar\" or even \"Foo::-\"  newline\n\"Bar\".   This  should be avoided where possible, either by disabling all line-breaking in\nmid-word, or by wrapping particular words with internal punctuation in \"don't break  this\nacross  lines\"  codes  (which  in  some  formats may not be a single code, but might be a\nmatter of inserting non-breaking zero-width spaces between every pair of characters in  a\nword.)\n\n•   Pod parsers should, by default, expand tabs in verbatim paragraphs as they are processed,\nbefore  passing  them  to  the  formatter  or other processor.  Parsers may also allow an\noption for overriding this.\n\n•   Pod parsers should, by default, remove newlines from the end  of  ordinary  and  verbatim\nparagraphs before passing them to the formatter.  For example, while the paragraph you're\nreading  now could be considered, in Pod source, to end with (and contain) the newline(s)\nthat end it, it should be processed as ending with (and containing) the period  character\nthat ends this sentence.\n\n•   Pod parsers, when reporting errors, should make some effort to report an approximate line\nnumber  (\"Nested  E<>'s  in  Paragraph  #52, near line 633 of Thing/Foo.pm!\"), instead of\nmerely noting the paragraph number (\"Nested E<>'s in Paragraph  #52  of  Thing/Foo.pm!\").\nWhere  this  is  problematic,  the  paragraph number should at least be accompanied by an\nexcerpt from the paragraph (\"Nested E<>'s in Paragraph #52 of Thing/Foo.pm, which  begins\n'Read/write accessor for the C<interest rate> attribute...'\").\n\n•   Pod  parsers,  when  processing a series of verbatim paragraphs one after another, should\nconsider them to be one large verbatim paragraph that happens  to  contain  blank  lines.\nI.e., these two lines, which have a blank line between them:\n\nuse Foo;\n\nprint Foo->VERSION\n\nshould  be unified into one paragraph (\"\\tuse Foo;\\n\\n\\tprint Foo->VERSION\") before being\npassed to the formatter or other  processor.   Parsers  may  also  allow  an  option  for\noverriding this.\n\nWhile  this  might  be  too  cumbersome  to  implement  in event-based Pod parsers, it is\nstraightforward for parsers that return parse trees.\n\n•   Pod formatters, where feasible, are advised to avoid splitting short verbatim  paragraphs\n(under twelve lines, say) across pages.\n\n•   Pod  parsers  must treat a line with only spaces and/or tabs on it as a \"blank line\" such\nas separates paragraphs.  (Some older parsers recognized only two adjacent newlines as  a\n\"blank  line\" but would not recognize a newline, a space, and a newline, as a blank line.\nThis is noncompliant behavior.)\n\n•   Authors of Pod formatters/processors should make every effort to avoid writing their  own\nPod  parser.  There are already several in CPAN, with a wide range of interface styles --\nand one of them, Pod::Simple, comes with modern versions of Perl.\n\n•   Characters in Pod documents may be conveyed either as literals,  or  by  number  in  E<n>\ncodes,  or  by  an  equivalent  mnemonic,  as in E<eacute> which is exactly equivalent to\nE<233>.  The numbers are the Latin1/Unicode values, even on EBCDIC platforms.\n\nWhen referring to characters by using a E<n> numeric code, numbers in  the  range  32-126\nrefer  to  those  well known US-ASCII characters (also defined there by Unicode, with the\nsame meaning), which all Pod formatters must render  faithfully.   Characters  whose  E<>\nnumbers  are  in the ranges 0-31 and 127-159 should not be used (neither as literals, nor\nas E<number> codes), except for the literal byte-sequences for newline (ASCII  13,  ASCII\n13 10, or ASCII 10), and tab (ASCII 9).\n\nNumbers  in the range 160-255 refer to Latin-1 characters (also defined there by Unicode,\nwith the same meaning).  Numbers above 255 should  be  understood  to  refer  to  Unicode\ncharacters.\n\n•   Be warned that some formatters cannot reliably render characters outside 32-126; and many\nare able to handle 32-126 and 160-255, but nothing above 255.\n\n•   Besides  the  well-known  \"E<lt>\"  and  \"E<gt>\" codes for less-than and greater-than, Pod\nparsers must understand \"E<sol>\" for  \"/\"  (solidus,  slash),  and  \"E<verbar>\"  for  \"|\"\n(vertical bar, pipe).  Pod parsers should also understand \"E<lchevron>\" and \"E<rchevron>\"\nas  legacy  codes for characters 171 and 187, i.e., \"left-pointing double angle quotation\nmark\" = \"left pointing guillemet\" and \"right-pointing  double  angle  quotation  mark\"  =\n\"right  pointing  guillemet\".   (These  look  like little \"<<\" and \">>\", and they are now\npreferably expressed with the HTML/XHTML codes \"E<laquo>\" and \"E<raquo>\".)\n\n•   Pod parsers should understand all \"E<html>\" codes as defined in the  entity  declarations\nin  the  most recent XHTML specification at \"www.W3.org\".  Pod parsers must understand at\nleast the entities that define characters in the range 160-255 (Latin-1).   Pod  parsers,\nwhen  faced  with  some  unknown  \"E<identifier>\"  code, shouldn't simply replace it with\nnullstring (by default, at least), but may pass it through as a string consisting of  the\nliteral  characters E, less-than, identifier, greater-than.  Or Pod parsers may offer the\nalternative option of processing such unknown \"E<identifier>\" codes by  firing  an  event\nespecially  for  such  codes,  or by adding a special node-type to the in-memory document\ntree.  Such \"E<identifier>\"  may  have  special  meaning  to  some  processors,  or  some\nprocessors may choose to add them to a special error report.\n\n•   Pod  parsers  must  also support the XHTML codes \"E<quot>\" for character 34 (doublequote,\n\"), \"E<amp>\" for character 38 (ampersand, &), and \"E<apos>\" for character 39 (apostrophe,\n').\n\n•   Note that in all cases of \"E<whatever>\", whatever (whether an htmlname, or  a  number  in\nany  base)  must  consist only of alphanumeric characters -- that is, whatever must match\n\"m/\\A\\w+\\z/\".  So \"E< 0 1 2 3 >\" is invalid, because it  contains  spaces,  which  aren't\nalphanumeric  characters.   This  presumably  does  not  need  special treatment by a Pod\nprocessor; \" 0 1 2 3 \" doesn't look like a number in any base, so it would presumably  be\nlooked  up  in  the table of HTML-like names.  Since there isn't (and cannot be) an HTML-\nlike entity called  \" 0 1 2 3 \",  this  will  be  treated  as  an  error.   However,  Pod\nprocessors may treat \"E< 0 1 2 3 >\" or \"E<e-acute>\" as syntactically invalid, potentially\nearning a different error message than the error message (or warning, or event) generated\nby  a  merely  unknown  (but  theoretically  valid)  htmlname,  as  in \"E<qacute>\" [sic].\nHowever, Pod parsers are not required to make this distinction.\n\n•   Note that  E<number>  must  not  be  interpreted  as  simply  \"codepoint  number  in  the\ncurrent/native  character  set\".   It  always  means  only  \"the character represented by\ncodepoint number in Unicode.\"  (This is identical to the semantics of &#number; in XML.)\n\nThis will likely require many formatters to have tables mapping  from  treatable  Unicode\ncodepoints  (such  as  the  \"\\xE9\"  for the e-acute character) to the escape sequences or\ncodes necessary for conveying such sequences in the target output format.  A converter to\n*roff would, for example know that \"\\xE9\" (whether conveyed literally, or  via  a  E<...>\nsequence)  is  to be conveyed as \"e\\\\*'\".  Similarly, a program rendering Pod in a Mac OS\napplication window, would presumably need to know that \"\\xE9\" maps to  codepoint  142  in\nMacRoman  encoding that (at time of writing) is native for Mac OS.  Such Unicode2whatever\nmappings are presumably already  widely  available  for  common  output  formats.   (Such\nmappings  may  be incomplete!  Implementers are not expected to bend over backwards in an\nattempt to render Cherokee syllabics, Etruscan runes, Byzantine musical symbols,  or  any\nof  the  other  weird  things  that  Unicode  can  encode.)  And if a Pod document uses a\ncharacter not found in such a mapping, the formatter should consider it  an  unrenderable\ncharacter.\n\n•   If,  surprisingly,  the  implementor  of  a  Pod formatter can't find a satisfactory pre-\nexisting table mapping from Unicode characters to escapes in the target format  (e.g.,  a\ndecent  table of Unicode characters to *roff escapes), it will be necessary to build such\na table.  If you are in this circumstance, you should begin with the  characters  in  the\nrange  0x00A0  -  0x00FF,  which  is  mostly  the heavily used accented characters.  Then\nproceed (as patience permits and fastidiousness compels) through the characters that  the\n(X)HTML  standards  groups  judged  important  enough  to merit mnemonics for.  These are\ndeclared in the (X)HTML specifications at  the  www.W3.org  site.   At  time  of  writing\n(September 2001), the most recent entity declaration files are:\n\nhttp://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent\nhttp://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent\nhttp://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent\n\nThen  you  can  progress  through  any  remaining notable Unicode characters in the range\n0x2000-0x204D (consult the  character  tables  at  www.unicode.org),  and  whatever  else\nstrikes your fancy.  For example, in xhtml-symbol.ent, there is the entry:\n\n<!ENTITY infin    \"&#8734;\"> <!-- infinity, U+221E ISOtech -->\n\nWhile  the mapping \"infin\" to the character \"\\x{221E}\" will (hopefully) have been already\nhandled by the Pod parser, the presence of the character in this  file  means  that  it's\nreasonably  important  enough  to  include  in a formatter's table that maps from notable\nUnicode characters to the codes necessary for rendering them.  So for a  Unicode-to-*roff\nmapping, for example, this would merit the entry:\n\n\"\\x{221E}\" => '\\(in',\n\nIt  is  eagerly  hoped that in the future, increasing numbers of formats (and formatters)\nwill support Unicode characters directly (as (X)HTML does with \"&infin;\",  \"&#8734;\",  or\n\"&#x221E;\"), reducing the need for idiosyncratic mappings of Unicode-to-myescapes.\n\n•   It  is  up  to individual Pod formatter to display good judgement when confronted with an\nunrenderable character (which is distinct from an  unknown  E<thing>  sequence  that  the\nparser  couldn't  resolve  to  anything,  renderable or not).  It is good practice to map\nLatin letters with diacritics (like \"E<eacute>\"/\"E<233>\") to the corresponding unaccented\nUS-ASCII letters (like a simple character 101,  \"e\"),  but  clearly  this  is  often  not\nfeasible,  and  an  unrenderable  character  may  be represented as \"?\", or the like.  In\nattempting a sane  fallback  (as  from  E<233>  to  \"e\"),  Pod  formatters  may  use  the\n%Latin1Codetofallback table in Pod::Escapes, or Text::Unidecode, if available.\n\nFor example, this Pod text:\n\nmagic is enabled if you set C<$Currency> to 'E<euro>'.\n\nmay  be  rendered  as:  \"magic  is  enabled  if you set $Currency to '?'\" or as \"magic is\nenabled if you set $Currency to '[euro]'\", or as \"magic is enabled if you  set  $Currency\nto '[x20AC]', etc.\n\nA  Pod  formatter  may  also  note,  in a comment or warning, a list of what unrenderable\ncharacters were encountered.\n\n•   E<...> may freely appear in any formatting code (other than in another E<...>  or  in  an\nZ<>).    That   is,   \"X<The   E<euro>1,000,000   Solution>\"   is  valid,  as  is  \"L<The\nE<euro>1,000,000 Solution|Million::Euros>\".\n\n•   Some Pod formatters output to formats that implement non-breaking spaces as an individual\ncharacter (which I'll call \"NBSP\"), and others output  to  formats  that  implement  non-\nbreaking  spaces  just as spaces wrapped in a \"don't break this across lines\" code.  Note\nthat at the level of Pod, both sorts of codes can occur: Pod can contain a NBSP character\n(whether as a literal, or as a \"E<160>\" or \"E<nbsp>\" code); and Pod  can  contain  \"S<foo\nI<bar>  baz>\"  codes,  where  \"mere  spaces\"  (character  32)  in such codes are taken to\nrepresent non-breaking spaces.  Pod  parsers  should  consider  supporting  the  optional\nparsing of \"S<foo I<bar> baz>\" as if it were \"fooNBSPI<bar>NBSPbaz\", and, going the other\nway,  the optional parsing of groups of words joined by NBSP's as if each group were in a\nS<...> code, so that formatters may use the representation that maps  best  to  what  the\noutput format demands.\n\n•   Some processors may find that the \"S<...>\" code is easiest to implement by replacing each\nspace  in  the  parse  tree  under  the  content  of  the S, with an NBSP.  But note: the\nreplacement should apply not to spaces in all text, but only to spaces in printable text.\n(This distinction  may  or  may  not  be  evident  in  the  particular  tree/event  model\nimplemented by the Pod parser.)  For example, consider this unusual case:\n\nS<L</Autoloaded Functions>>\n\nThis  means  that  the  space  in  the middle of the visible link text must not be broken\nacross lines.  In other words, it's the same as this:\n\nL<\"AutoloadedE<160>Functions\"/Autoloaded Functions>\n\nHowever,  a  misapplied  space-to-NBSP  replacement  could  (wrongly)  produce  something\nequivalent to this:\n\nL<\"AutoloadedE<160>Functions\"/AutoloadedE<160>Functions>\n\n...which  is  almost definitely not going to work as a hyperlink (assuming this formatter\noutputs a format supporting hypertext).\n\nFormatters may choose to just not support the S format code, especially  in  cases  where\nthe  output  format  simply  has no NBSP character/code and no code for \"don't break this\nstuff across lines\".\n\n•   Besides the NBSP character discussed above, implementors are reminded of the existence of\nthe other \"special\" character in Latin-1, the \"soft  hyphen\"  character,  also  known  as\n\"discretionary  hyphen\", i.e. \"E<173>\" = \"E<0xAD>\" = \"E<shy>\").  This character expresses\nan optional hyphenation point.  That is, it normally renders as nothing, but  may  render\nas  a  \"-\"  if  a  formatter  breaks  the  word at that point.  Pod formatters should, as\nappropriate, do one of the following:  1) render this with a code with the  same  meaning\n(e.g., \"\\-\" in RTF), 2) pass it through in the expectation that the formatter understands\nthis character as such, or 3) delete it.\n\nFor example:\n\nsigE<shy>action\nmanuE<shy>script\nJarkE<shy>ko HieE<shy>taE<shy>nieE<shy>mi\n\nThese  signal to a formatter that if it is to hyphenate \"sigaction\" or \"manuscript\", then\nit should be done as  \"sig-[linebreak]action\"  or  \"manu-[linebreak]script\"  (and  if  it\ndoesn't  hyphenate  it,  then  the  \"E<shy>\"  doesn't  show  up at all).  And if it is to\nhyphenate \"Jarkko\" and/or \"Hietaniemi\", it can do so only at the points where there is  a\n\"E<shy>\" code.\n\nIn practice, it is anticipated that this character will not be used often, but formatters\nshould either support it, or delete it.\n\n•   If  you think that you want to add a new command to Pod (like, say, a \"=biblio\" command),\nconsider whether you could get the same effect with a for or  begin/end  sequence:  \"=for\nbiblio  ...\"  or \"=begin biblio\" ... \"=end biblio\".  Pod processors that don't understand\n\"=for biblio\", etc, will simply ignore it, whereas they may complain loudly if  they  see\n\"=biblio\".\n\n•   Throughout  this  document,  \"Pod\"  has  been  the preferred spelling for the name of the\ndocumentation format.  One may also use \"POD\" or \"pod\".  For the  documentation  that  is\n(typically)  in  the  Pod  format,  you may use \"pod\", or \"Pod\", or \"POD\".  Understanding\nthese distinctions is useful; but obsessing over how to spell them, usually is not.\n\nAbout L<...> Codes\nAs you can tell from a glance at perlpod, the L<...> code is the  most  complex  of  the  Pod\nformatting  codes.   The points below will hopefully clarify what it means and how processors\nshould deal with it.\n\n•   In parsing an L<...> code, Pod parsers must distinguish at least four attributes:\n\nFirst:\nThe link-text.   If  there  is  none,  this  must  be  \"undef\".   (E.g.,  in  \"L<Perl\nFunctions|perlfunc>\",  the  link-text  is  \"Perl Functions\".  In \"L<Time::HiRes>\" and\neven \"L<|Time::HiRes>\", there is no link text.   Note  that  link  text  may  contain\nformatting.)\n\nSecond:\nThe  possibly  inferred link-text; i.e., if there was no real link text, then this is\nthe text that we'll infer in its place.  (E.g., for  \"L<Getopt::Std>\",  the  inferred\nlink text is \"Getopt::Std\".)\n\nThird:\nThe  name  or  URL,  or \"undef\" if none.  (E.g., in \"L<Perl Functions|perlfunc>\", the\nname (also sometimes called the page) is \"perlfunc\".  In \"L</CAVEATS>\", the  name  is\n\"undef\".)\n\nFourth:\nThe  section  (AKA  \"item\"  in  older  perlpods),  or  \"undef\"  if  none.   E.g.,  in\n\"L<Getopt::Std/DESCRIPTION>\", \"DESCRIPTION\" is the section.  (Note that this  is  not\nthe  same as a manpage section like the \"5\" in \"man 5 crontab\".  \"Section Foo\" in the\nPod sense means the part of the text that's introduced by the heading or  item  whose\ntext is \"Foo\".)\n\nPod parsers may also note additional attributes including:\n\nFifth:\nA flag for whether item 3 (if present) is a URL (like \"http://lists.perl.org\" is), in\nwhich  case  there  should  be  no  section attribute; a Pod name (like \"perldoc\" and\n\"Getopt::Std\" are); or possibly a man page name (like \"crontab(5)\" is).\n\nSixth:\nThe raw original L<...> content, before text is split on \"|\", \"/\",  etc,  and  before\nE<...> codes are expanded.\n\n(The  above were numbered only for concise reference below.  It is not a requirement that\nthese be passed as an actual list or array.)\n\nFor example:\n\nL<Foo::Bar>\n=>  undef,                         # link text\n\"Foo::Bar\",                    # possibly inferred link text\n\"Foo::Bar\",                    # name\nundef,                         # section\n'pod',                         # what sort of link\n\"Foo::Bar\"                     # original content\n\nL<Perlport's section on NL's|perlport/Newlines>\n=>  \"Perlport's section on NL's\",  # link text\n\"Perlport's section on NL's\",  # possibly inferred link text\n\"perlport\",                    # name\n\"Newlines\",                    # section\n'pod',                         # what sort of link\n\"Perlport's section on NL's|perlport/Newlines\"\n# original content\n\nL<perlport/Newlines>\n=>  undef,                         # link text\n'\"Newlines\" in perlport',      # possibly inferred link text\n\"perlport\",                    # name\n\"Newlines\",                    # section\n'pod',                         # what sort of link\n\"perlport/Newlines\"            # original content\n\nL<crontab(5)/\"DESCRIPTION\">\n=>  undef,                         # link text\n'\"DESCRIPTION\" in crontab(5)', # possibly inferred link text\n\"crontab(5)\",                  # name\n\"DESCRIPTION\",                 # section\n'man',                         # what sort of link\n'crontab(5)/\"DESCRIPTION\"'     # original content\n\nL</Object Attributes>\n=>  undef,                         # link text\n'\"Object Attributes\"',         # possibly inferred link text\nundef,                         # name\n\"Object Attributes\",           # section\n'pod',                         # what sort of link\n\"/Object Attributes\"           # original content\n\nL<https://www.perl.org/>\n=>  undef,                         # link text\n\"https://www.perl.org/\",       # possibly inferred link text\n\"https://www.perl.org/\",       # name\nundef,                         # section\n'url',                         # what sort of link\n\"https://www.perl.org/\"         # original content\n\nL<Perl.org|https://www.perl.org/>\n=>  \"Perl.org\",                    # link text\n\"https://www.perl.org/\",       # possibly inferred link text\n\"https://www.perl.org/\",       # name\nundef,                         # section\n'url',                         # what sort of link\n\"Perl.org|https://www.perl.org/\" # original content\n\nNote that you can distinguish URL-links from anything else by the fact  that  they  match\n\"m/\\A\\w+:[^:\\s]\\S*\\z/\".   So  \"L<http://www.perl.com>\"  is a URL, but \"L<HTTP::Response>\"\nisn't.\n\n•   In case of L<...> codes with no \"text|\" part in them,  older  formatters  have  exhibited\ngreat  variation  in  actually  displaying  the  link  or  cross reference.  For example,\nL<crontab(5)> would render as \"the crontab(5) manpage\", or \"in the crontab(5) manpage\" or\njust \"crontab(5)\".\n\nPod processors must now treat \"text|\"-less links as follows:\n\nL<name>         =>  L<name|name>\nL</section>     =>  L<\"section\"|/section>\nL<name/section> =>  L<\"section\" in name|name/section>\n\n•   Note that section names might contain markup.  I.e., if a section starts with:\n\n=head2 About the C<-M> Operator\n\nor with:\n\n=item About the C<-M> Operator\n\nthen a link to it would look like this:\n\nL<somedoc/About the C<-M> Operator>\n\nFormatters may choose to ignore the markup for purposes of resolving  the  link  and  use\nonly the renderable characters in the section name, as in:\n\n<h1><a name=\"Aboutthe-MOperator\">About the <code>-M</code>\nOperator</h1>\n\n...\n\n<a href=\"somedoc#Aboutthe-MOperator\">About the <code>-M</code>\nOperator\" in somedoc</a>\n\n•   Previous  versions of perlpod distinguished \"L<name/\"section\">\" links from \"L<name/item>\"\nlinks (and their targets).  These have been merged syntactically and semantically in  the\ncurrent specification, and section can refer either to a \"=headn Heading Content\" command\nor  to a \"=item Item Content\" command.  This specification does not specify what behavior\nshould be in the case of a given document having several things all  seeming  to  produce\nthe  same  section  identifier  (e.g.,  in  HTML,  several  things all producing the same\nanchorname in <a name=\"anchorname\">...</a> elements).  Where Pod processors  can  control\nthis  behavior,  they  should use the first such anchor.  That is, \"L<Foo/Bar>\" refers to\nthe first \"Bar\" section in Foo.\n\nBut for some processors/formats this cannot  be  easily  controlled;  as  with  the  HTML\nexample,  the  behavior of multiple ambiguous <a name=\"anchorname\">...</a> is most easily\njust left up to browsers to decide.\n\n•   In a \"L<text|...>\" code, text may contain formatting codes for formatting or  for  E<...>\nescapes, as in:\n\nL<B<ummE<234>stuff>|...>\n\nFor \"L<...>\" codes without a \"name|\" part, only \"E<...>\" and \"Z<>\" codes may occur.  That\nis, authors should not use \"\"L<B<Foo::Bar>>\"\".\n\nNote,  however,  that  formatting  codes  and  Z<>'s can occur in any and all parts of an\nL<...> (i.e., in name, section, text, and url).\n\nAuthors must not nest L<...> codes.  For example, \"L<The L<Foo::Bar> man page>\" should be\ntreated as an error.\n\n•   Note that Pod authors may use formatting codes inside the \"text\" part  of  \"L<text|name>\"\n(and so on for L<text|/\"sec\">).\n\nIn other words, this is valid:\n\nGo read L<the docs on C<$.>|perlvar/\"$.\">\n\nSome  output formats that do allow rendering \"L<...>\" codes as hypertext, might not allow\nthe link-text to be formatted; in that case, formatters will have  to  just  ignore  that\nformatting.\n\n•   At time of writing, \"L<name>\" values are of two types: either the name of a Pod page like\n\"L<Foo::Bar>\"  (which might be a real Perl module or program in an @INC / PATH directory,\nor a .pod file in those places); or the name of a Unix man  page,  like  \"L<crontab(5)>\".\nIn  theory,  \"L<chmod>\"  is  ambiguous between a Pod page called \"chmod\", or the Unix man\npage \"chmod\" (in whatever man-section).  However, the presence of a string in parens,  as\nin  \"crontab(5)\", is sufficient to signal that what is being discussed is not a Pod page,\nand so is presumably a Unix man page.  The distinction is of no importance  to  many  Pod\nprocessors,  but some processors that render to hypertext formats may need to distinguish\nthem in order to know how to render a given \"L<foo>\" code.\n\n•   Previous versions  of  perlpod  allowed  for  a  \"L<section>\"  syntax  (as  in  \"L<Object\nAttributes>\"),  which  was  not  easily  distinguishable  from  \"L<name>\"  syntax and for\n\"L<\"section\">\" which was only slightly less ambiguous.  This syntax is no longer  in  the\nspecification,  and  has  been  replaced by the \"L</section>\" syntax (where the slash was\nformerly optional).  Pod parsers should tolerate the \"L<\"section\">\" syntax, for  a  while\nat least.  The suggested heuristic for distinguishing \"L<section>\" from \"L<name>\" is that\nif  it  contains  any  whitespace, it's a section.  Pod processors should warn about this\nbeing deprecated syntax.\n\nAbout =over...=back Regions\n\"=over\"...\"=back\" regions are used for various kinds of list-like  structures.   (I  use  the\nterm  \"region\"  here  simply  as  a  collective  term  for everything from the \"=over\" to the\nmatching \"=back\".)\n\n•   The non-zero numeric indentlevel in \"=over indentlevel\" ...  \"=back\" is used  for  giving\nthe formatter a clue as to how many \"spaces\" (ems, or roughly equivalent units) it should\ntab  over,  although many formatters will have to convert this to an absolute measurement\nthat may not exactly match with the size of spaces (or M's) in the document's base  font.\nOther  formatters  may  have  to  completely ignore the number.  The lack of any explicit\nindentlevel parameter is equivalent to an indentlevel value of  4.   Pod  processors  may\ncomplain   if   indentlevel   is   present   but   is  not  a  positive  number  matching\n\"m/\\A(\\d*\\.)?\\d+\\z/\".\n\n•   Authors of Pod formatters are reminded that  \"=over\"  ...  \"=back\"  may  map  to  several\ndifferent  constructs  in your output format.  For example, in converting Pod to (X)HTML,\nit   can   map   to    any    of    <ul>...</ul>,    <ol>...</ol>,    <dl>...</dl>,    or\n<blockquote>...</blockquote>.  Similarly, \"=item\" can map to <li> or <dt>.\n\n•   Each \"=over\" ... \"=back\" region should be one of the following:\n\n•   An  \"=over\"  ...  \"=back\" region containing only \"=item *\" commands, each followed by\nsome number  of  ordinary/verbatim  paragraphs,  other  nested  \"=over\"  ...  \"=back\"\nregions, \"=for...\" paragraphs, and \"=begin\"...\"=end\" regions.\n\n(Pod  processors  must tolerate a bare \"=item\" as if it were \"=item *\".)  Whether \"*\"\nis rendered as a literal asterisk, an \"o\", or as some kind of real bullet  character,\nis left up to the Pod formatter, and may depend on the level of nesting.\n\n•   An  \"=over\" ... \"=back\" region containing only \"m/\\A=item\\s+\\d+\\.?\\s*\\z/\" paragraphs,\neach one (or each group  of  them)  followed  by  some  number  of  ordinary/verbatim\nparagraphs,  other  nested  \"=over\" ... \"=back\" regions, \"=for...\" paragraphs, and/or\n\"=begin\"...\"=end\" codes.  Note that the numbers must start at 1 in each section,  and\nmust proceed in order and without skipping numbers.\n\n(Pod  processors  must tolerate lines like \"=item 1\" as if they were \"=item 1.\", with\nthe period.)\n\n•   An \"=over\" ... \"=back\" region containing only \"=item [text]\" commands, each  one  (or\neach  group  of  them) followed by some number of ordinary/verbatim paragraphs, other\nnested \"=over\" ... \"=back\" regions, or \"=for...\"  paragraphs,  and  \"=begin\"...\"=end\"\nregions.\n\nThe   \"=item   [text]\"  paragraph  should  not  match  \"m/\\A=item\\s+\\d+\\.?\\s*\\z/\"  or\n\"m/\\A=item\\s+\\*\\s*\\z/\", nor should it match just \"m/\\A=item\\s*\\z/\".\n\n•   An \"=over\" ... \"=back\" region containing no \"=item\" paragraphs at all, and containing\nonly some number of ordinary/verbatim  paragraphs,  and  possibly  also  some  nested\n\"=over\"  ...  \"=back\"  regions,  \"=for...\" paragraphs, and \"=begin\"...\"=end\" regions.\nSuch an itemless \"=over\" ... \"=back\" region in Pod is  equivalent  in  meaning  to  a\n\"<blockquote>...</blockquote>\" element in HTML.\n\nNote  that  with all the above cases, you can determine which type of \"=over\" ... \"=back\"\nyou have, by examining the first (non-\"=cut\", non-\"=pod\") Pod paragraph after the \"=over\"\ncommand.\n\n•   Pod formatters must tolerate arbitrarily large amounts of text  in  the  \"=item  text...\"\nparagraph.  In practice, most such paragraphs are short, as in:\n\n=item For cutting off our trade with all parts of the world\n\nBut they may be arbitrarily long:\n\n=item For transporting us beyond seas to be tried for pretended\noffenses\n\n=item He is at this time transporting large armies of foreign\nmercenaries to complete the works of death, desolation and\ntyranny, already begun with circumstances of cruelty and perfidy\nscarcely paralleled in the most barbarous ages, and totally\nunworthy the head of a civilized nation.\n\n•   Pod  processors  should tolerate \"=item *\" / \"=item number\" commands with no accompanying\nparagraph.  The middle item is an example:\n\n=over\n\n=item 1\n\nPick up dry cleaning.\n\n=item 2\n\n=item 3\n\nStop by the store.  Get Abba Zabas, Stoli, and cheap lawn chairs.\n\n=back\n\n•   No \"=over\" ... \"=back\" region can contain headings.  Processors may treat such a  heading\nas an error.\n\n•   Note  that  an  \"=over\"  ...  \"=back\"  region should have some content.  That is, authors\nshould not have an empty region like this:\n\n=over\n\n=back\n\nPod processors seeing such a contentless \"=over\" ... \"=back\" region, may  ignore  it,  or\nmay report it as an error.\n\n•   Processors  must  tolerate  an  \"=over\" list that goes off the end of the document (i.e.,\nwhich has no matching \"=back\"), but they may warn about such a list.\n\n•   Authors of Pod formatters should note that this construct:\n\n=item Neque\n\n=item Porro\n\n=item Quisquam Est\n\nQui dolorem ipsum quia dolor sit amet, consectetur, adipisci\nvelit, sed quia non numquam eius modi tempora incidunt ut\nlabore et dolore magnam aliquam quaerat voluptatem.\n\n=item Ut Enim\n\nis semantically ambiguous, in a way that makes formatting decisions a bit difficult.   On\nthe  one  hand,  it could be mention of an item \"Neque\", mention of another item \"Porro\",\nand mention of another item  \"Quisquam  Est\",  with  just  the  last  one  requiring  the\nexplanatory  paragraph \"Qui dolorem ipsum quia dolor...\"; and then an item \"Ut Enim\".  In\nthat case, you'd want to format it like so:\n\nNeque\n\nPorro\n\nQuisquam Est\nQui dolorem ipsum quia dolor sit amet, consectetur, adipisci\nvelit, sed quia non numquam eius modi tempora incidunt ut\nlabore et dolore magnam aliquam quaerat voluptatem.\n\nUt Enim\n\nBut it could equally well be  a  discussion  of  three  (related  or  equivalent)  items,\n\"Neque\",  \"Porro\",  and  \"Quisquam Est\", followed by a paragraph explaining them all, and\nthen a new item \"Ut Enim\".  In that case, you'd probably want to format it like so:\n\nNeque\nPorro\nQuisquam Est\nQui dolorem ipsum quia dolor sit amet, consectetur, adipisci\nvelit, sed quia non numquam eius modi tempora incidunt ut\nlabore et dolore magnam aliquam quaerat voluptatem.\n\nUt Enim\n\nBut (for the foreseeable future), Pod does  not  provide  any  way  for  Pod  authors  to\ndistinguish  which  grouping  is  meant  by  the  above  \"=item\"-cluster  structure.   So\nformatters should format it like so:\n\nNeque\n\nPorro\n\nQuisquam Est\n\nQui dolorem ipsum quia dolor sit amet, consectetur, adipisci\nvelit, sed quia non numquam eius modi tempora incidunt ut\nlabore et dolore magnam aliquam quaerat voluptatem.\n\nUt Enim\n\nThat is, there should be (at least  roughly)  equal  spacing  between  items  as  between\nparagraphs  (although  that  spacing  may  well be less than the full height of a line of\ntext).  This leaves it to the reader to use (con)textual cues to figure out  whether  the\n\"Qui dolorem ipsum...\" paragraph applies to the \"Quisquam Est\" item or to all three items\n\"Neque\",  \"Porro\",  and \"Quisquam Est\".  While not an ideal situation, this is preferable\nto providing formatting cues that may be actually contrary to the author's intent.\n\nAbout Data Paragraphs and \"=begin/=end\" Regions\nData paragraphs are typically used for inlining non-Pod data that is to  be  used  (typically\npassed through) when rendering the document to a specific format:\n\n=begin rtf\n\n\\par{\\pard\\qr\\sa4500{\\i Printed\\~\\chdate\\~\\chtime}\\par}\n\n=end rtf\n\nThe exact same effect could, incidentally, be achieved with a single \"=for\" paragraph:\n\n=for rtf \\par{\\pard\\qr\\sa4500{\\i Printed\\~\\chdate\\~\\chtime}\\par}\n\n(Although  that  is  not  formally  a data paragraph, it has the same meaning as one, and Pod\nparsers may parse it as one.)\n\nAnother example of a data paragraph:\n\n=begin html\n\nI like <em>PIE</em>!\n\n<hr>Especially pecan pie!\n\n=end html\n\nIf these were ordinary paragraphs, the Pod parser would try to expand the  \"E</em>\"  (in  the\nfirst  paragraph)  as a formatting code, just like \"E<lt>\" or \"E<eacute>\".  But since this is\nin a \"=begin identifier\"...\"=end identifier\" region and the identifier \"html\"  doesn't  begin\nhave  a  \":\"  prefix,  the  contents of this region are stored as data paragraphs, instead of\nbeing processed as ordinary paragraphs (or if they  began  with  a  spaces  and/or  tabs,  as\nverbatim paragraphs).\n\nAs  a  further  example: At time of writing, no \"biblio\" identifier is supported, but suppose\nsome processor were written to recognize it as  a  way  of  (say)  denoting  a  bibliographic\nreference  (necessarily  containing  formatting codes in ordinary paragraphs).  The fact that\n\"biblio\" paragraphs were meant for ordinary processing would be indicated by  prefacing  each\n\"biblio\" identifier with a colon:\n\n=begin :biblio\n\nWirth, Niklaus.  1976.  I<Algorithms + Data Structures =\nPrograms.>  Prentice-Hall, Englewood Cliffs, NJ.\n\n=end :biblio\n\nThis  would  signal  to  the parser that paragraphs in this begin...end region are subject to\nnormal handling as ordinary/verbatim  paragraphs  (while  still  tagged  as  meant  only  for\nprocessors that understand the \"biblio\" identifier).  The same effect could be had with:\n\n=for :biblio\nWirth, Niklaus.  1976.  I<Algorithms + Data Structures =\nPrograms.>  Prentice-Hall, Englewood Cliffs, NJ.\n\nThe  \":\"  on  these  identifiers  means  simply \"process this stuff normally, even though the\nresult will be for some special target\".  I suggest that parser APIs report \"biblio\"  as  the\ntarget  identifier, but also report that it had a \":\" prefix.  (And similarly, with the above\n\"html\", report \"html\" as the target identifier, and note the lack of a \":\" prefix.)\n\nNote that a \"=begin identifier\"...\"=end identifier\" region where  identifier  begins  with  a\ncolon, can contain commands.  For example:\n\n=begin :biblio\n\nWirth's classic is available in several editions, including:\n\n=for comment\nhm, check abebooks.com for how much used copies cost.\n\n=over\n\n=item\n\nWirth, Niklaus.  1975.  I<Algorithmen und Datenstrukturen.>\nTeubner, Stuttgart.  [Yes, it's in German.]\n\n=item\n\nWirth, Niklaus.  1976.  I<Algorithms + Data Structures =\nPrograms.>  Prentice-Hall, Englewood Cliffs, NJ.\n\n=back\n\n=end :biblio\n\nNote,  however,  a  \"=begin  identifier\"...\"=end identifier\" region where identifier does not\nbegin with a colon, should not directly contain \"=head1\" ... \"=head4\" commands, nor  \"=over\",\nnor \"=back\", nor \"=item\".  For example, this may be considered invalid:\n\n=begin somedata\n\nThis is a data paragraph.\n\n=head1 Don't do this!\n\nThis is a data paragraph too.\n\n=end somedata\n\nA  Pod processor may signal that the above (specifically the \"=head1\" paragraph) is an error.\nNote, however, that the following should not be treated as an error:\n\n=begin somedata\n\nThis is a data paragraph.\n\n=cut\n\n# Yup, this isn't Pod anymore.\nsub excl { (rand() > .5) ? \"hoo!\" : \"hah!\" }\n\n=pod\n\nThis is a data paragraph too.\n\n=end somedata\n\nAnd this too is valid:\n\n=begin someformat\n\nThis is a data paragraph.\n\nAnd this is a data paragraph.\n\n=begin someotherformat\n\nThis is a data paragraph too.\n\nAnd this is a data paragraph too.\n\n=begin :yetanotherformat\n\n=head2 This is a command paragraph!\n\nThis is an ordinary paragraph!\n\nAnd this is a verbatim paragraph!\n\n=end :yetanotherformat\n\n=end someotherformat\n\nAnother data paragraph!\n\n=end someformat\n\nThe contents of the above \"=begin :yetanotherformat\"  ...   \"=end  :yetanotherformat\"  region\naren't   data   paragraphs,   because   the   immediately   containing   region's  identifier\n(\":yetanotherformat\") begins with a colon.  In  practice,  most  regions  that  contain  data\nparagraphs  will  contain  only  data paragraphs; however, the above nesting is syntactically\nvalid as Pod, even if it is rare.  However, the handlers for some formats, like \"html\",  will\naccept  only data paragraphs, not nested regions; and they may complain if they see (targeted\nfor them) nested regions, or commands, other than \"=end\", \"=pod\", and \"=cut\".\n\nAlso consider this valid structure:\n\n=begin :biblio\n\nWirth's classic is available in several editions, including:\n\n=over\n\n=item\n\nWirth, Niklaus.  1975.  I<Algorithmen und Datenstrukturen.>\nTeubner, Stuttgart.  [Yes, it's in German.]\n\n=item\n\nWirth, Niklaus.  1976.  I<Algorithms + Data Structures =\nPrograms.>  Prentice-Hall, Englewood Cliffs, NJ.\n\n=back\n\nBuy buy buy!\n\n=begin html\n\n<img src='wirthspokesmodelingbook.png'>\n\n<hr>\n\n=end html\n\nNow now now!\n\n=end :biblio\n\nThere,  the  \"=begin  html\"...\"=end  html\"  region  is  nested  inside  the  larger   \"=begin\n:biblio\"...\"=end  :biblio\"  region.  Note that the content of the \"=begin html\"...\"=end html\"\nregion is data paragraph(s), because the immediately containing region's identifier  (\"html\")\ndoesn't begin with a colon.\n\nPod  parsers,  when processing a series of data paragraphs one after another (within a single\nregion), should consider them to be one large data paragraph that happens  to  contain  blank\nlines.   So  the  content  of the above \"=begin html\"...\"=end html\" may be stored as two data\nparagraphs (one  consisting  of  \"<img  src='wirthspokesmodelingbook.png'>\\n\"  and  another\nconsisting of \"<hr>\\n\"), but should be stored as a single data paragraph (consisting of \"<img\nsrc='wirthspokesmodelingbook.png'>\\n\\n<hr>\\n\").\n\nPod  processors  should  tolerate  empty \"=begin something\"...\"=end something\" regions, empty\n\"=begin :something\"...\"=end :something\" regions, and contentless \"=for something\"  and  \"=for\n:something\" paragraphs.  I.e., these should be tolerated:\n\n=for html\n\n=begin html\n\n=end html\n\n=begin :biblio\n\n=end :biblio\n\nIncidentally,  note  that  there's  no  easy  way  to  express a data paragraph starting with\nsomething that looks like a command.  Consider:\n\n=begin stuff\n\n=shazbot\n\n=end stuff\n\nThere, \"=shazbot\" will be parsed as  a  Pod  command  \"shazbot\",  not  as  a  data  paragraph\n\"=shazbot\\n\".   However,  you  can  express a data paragraph consisting of \"=shazbot\\n\" using\nthis code:\n\n=for stuff =shazbot\n\nThe situation where this is necessary, is presumably quite rare.\n\nNote that =end commands must match the currently open =begin command.   That  is,  they  must\nproperly nest.  For example, this is valid:\n\n=begin outer\n\nX\n\n=begin inner\n\nY\n\n=end inner\n\nZ\n\n=end outer\n\nwhile this is invalid:\n\n=begin outer\n\nX\n\n=begin inner\n\nY\n\n=end outer\n\nZ\n\n=end inner\n\nThis  latter  is  improper  because when the \"=end outer\" command is seen, the currently open\nregion has the formatname \"inner\", not \"outer\".  (It just happens that \"outer\" is the  format\nname of a higher-up region.)  This is an error.  Processors must by default report this as an\nerror,  and  may  halt processing the document containing that error.  A corollary of this is\nthat regions cannot \"overlap\". That is, the latter block above does not  represent  a  region\ncalled  \"outer\"  which contains X and Y, overlapping a region called \"inner\" which contains Y\nand Z.  But because it is invalid (as  all  apparently  overlapping  regions  would  be),  it\ndoesn't represent that, or anything at all.\n\nSimilarly, this is invalid:\n\n=begin thing\n\n=end hting\n\nThis  is  an  error  because  the  region is opened by \"thing\", and the \"=end\" tries to close\n\"hting\" [sic].\n\nThis is also invalid:\n\n=begin thing\n\n=end\n\nThis is invalid because every \"=end\" command must have a formatname parameter.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "perlpod, \"PODs: Embedded Documentation\" in perlsyn, podchecker\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Sean M. Burke\n\nperl v5.38.2                                 2026-06-12                               PERLPODSPEC(1)",
                "subsections": []
            }
        }
    }
}