{
    "content": [
        {
            "type": "text",
            "text": "# perlpod (man)\n\n## NAME\n\nperlpod - the Plain Old Documentation format\n\n## DESCRIPTION\n\nPod is a simple-to-use markup language used for writing documentation for Perl, Perl\nprograms, and Perl modules.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION** (7 subsections)\n- **SEE ALSO**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "perlpod",
        "section": "",
        "mode": "man",
        "summary": "perlpod - the Plain Old Documentation format",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 8,
                "subsections": [
                    {
                        "name": "Ordinary Paragraph",
                        "lines": 8
                    },
                    {
                        "name": "Verbatim Paragraph",
                        "lines": 8
                    },
                    {
                        "name": "Command Paragraph",
                        "lines": 230
                    },
                    {
                        "name": "Formatting Codes",
                        "lines": 199
                    },
                    {
                        "name": "The Intent",
                        "lines": 12
                    },
                    {
                        "name": "Embedding Pods in Perl Modules",
                        "lines": 18
                    },
                    {
                        "name": "Hints for Writing Pod",
                        "lines": 55
                    }
                ]
            },
            {
                "name": "SEE ALSO",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 3,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "perlpod - the Plain Old Documentation format\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "Pod is a simple-to-use markup language used for writing documentation for Perl, Perl\nprograms, and Perl modules.\n\nTranslators are available for converting Pod to various formats like plain text, HTML, man\npages, and more.\n\nPod markup consists of three basic kinds of paragraphs: ordinary, verbatim, and command.\n",
                "subsections": [
                    {
                        "name": "Ordinary Paragraph",
                        "content": "Most paragraphs in your documentation will be ordinary blocks of text, like this one.  You\ncan simply type in your text without any markup whatsoever, and with just a blank line before\nand after.  When it gets formatted, it will undergo minimal formatting, like being rewrapped,\nprobably put into a proportionally spaced font, and maybe even justified.\n\nYou can use formatting codes in ordinary paragraphs, for bold, italic, \"code-style\",\nhyperlinks, and more.  Such codes are explained in the \"Formatting Codes\" section, below.\n"
                    },
                    {
                        "name": "Verbatim Paragraph",
                        "content": "Verbatim paragraphs are usually used for presenting a codeblock or other text which does not\nrequire any special parsing or formatting, and which shouldn't be wrapped.\n\nA verbatim paragraph is distinguished by having its first character be a space or a tab.\n(And commonly, all its lines begin with spaces and/or tabs.)  It should be reproduced\nexactly, with tabs assumed to be on 8-column boundaries.  There are no special formatting\ncodes, so you can't italicize or anything like that.  A \\ means \\, and nothing else.\n"
                    },
                    {
                        "name": "Command Paragraph",
                        "content": "A command paragraph is used for special treatment of whole chunks of text, usually as\nheadings or parts of lists.\n\nAll command paragraphs (which are typically only one line long) start with \"=\", followed by\nan identifier, followed by arbitrary text that the command can use however it pleases.\nCurrently recognized commands are\n\n=pod\n=head1 Heading Text\n=head2 Heading Text\n=head3 Heading Text\n=head4 Heading Text\n=head5 Heading Text\n=head6 Heading Text\n=over indentlevel\n=item stuff\n=back\n=begin format\n=end format\n=for format text...\n=encoding type\n=cut\n\nTo explain them each in detail:\n\n\"=head1 Heading Text\"\n\"=head2 Heading Text\"\n\"=head3 Heading Text\"\n\"=head4 Heading Text\"\n\"=head5 Heading Text\"\n\"=head6 Heading Text\"\nHead1  through  head6  produce  headings, head1 being the highest level.  The text in the\nrest of this paragraph is the content of the heading.  For example:\n\n=head2 Object Attributes\n\nThe text \"Object Attributes\" comprises the heading there.   The  text  in  these  heading\ncommands can use formatting codes, as seen here:\n\n=head2 Possible Values for C<$/>\n\nSuch commands are explained in the \"Formatting Codes\" section, below.\n\nNote  that  \"head5\" and \"head6\" were introduced in 2020 and in Pod::Simple 3.41, released\nin October 2020, so they might not be supported on the Pod parser you use.\n\n\"=over indentlevel\"\n\"=item stuff...\"\n\"=back\"\nItem, over, and back  require  a  little  more  explanation:   \"=over\"  starts  a  region\nspecifically  for  the  generation  of  a  list  using \"=item\" commands, or for indenting\n(groups of) normal paragraphs.  At the end of your list, use  \"=back\"  to  end  it.   The\nindentlevel  option  to \"=over\" indicates how far over to indent, generally in ems (where\none em is the width of an \"M\" in the document's base font) or roughly  comparable  units;\nif  there  is  no indentlevel option, it defaults to four.  (And some formatters may just\nignore whatever indentlevel you provide.)  In the stuff in \"=item stuff...\", you may  use\nformatting codes, as seen here:\n\n=item Using C<$|> to Control Buffering\n\nSuch commands are explained in the \"Formatting Codes\" section, below.\n\nNote also that there are some basic rules to using \"=over\" ...  \"=back\" regions:\n\n•   Don't use \"=item\"s outside of an \"=over\" ... \"=back\" region.\n\n•   The  first  thing after the \"=over\" command should be an \"=item\", unless there aren't\ngoing to be any items at all in this \"=over\" ... \"=back\" region.\n\n•   Don't put \"=headn\" commands inside an \"=over\" ... \"=back\" region.\n\n•   And perhaps most importantly, keep the items consistent: either use \"=item *\" for all\nof them, to produce bullets; or use \"=item 1.\", \"=item 2.\", etc., to produce numbered\nlists; or use \"=item foo\", \"=item bar\", etc.--namely, things that look  nothing  like\nbullets  or  numbers.   (If  you have a list that contains both: 1) things that don't\nlook like bullets nor numbers,  plus 2)  things  that  do,  you  should  preface  the\nbullet- or number-like items with \"Z<>\".  See Z<> below for an example.)\n\nIf  you  start  with bullets or numbers, stick with them, as formatters use the first\n\"=item\" type to decide how to format the list.\n\n\"=cut\"\nTo end a Pod block, use a blank line, then a line beginning with \"=cut\", and a blank line\nafter it.  This lets Perl (and the Pod formatter) know that this is where  Perl  code  is\nresuming.  (The blank line before the \"=cut\" is not technically necessary, but many older\nPod processors require it.)\n\n\"=pod\"\nThe \"=pod\" command by itself doesn't do much of anything, but it signals to Perl (and Pod\nformatters) that a Pod block starts here.  A Pod block starts with any command paragraph,\nso  a  \"=pod\"  command  is  usually  used just when you want to start a Pod block with an\nordinary paragraph or a verbatim paragraph.  For example:\n\n=item stuff()\n\nThis function does stuff.\n\n=cut\n\nsub stuff {\n...\n}\n\n=pod\n\nRemember to check its return value, as in:\n\nstuff() || die \"Couldn't do stuff!\";\n\n=cut\n\n\"=begin formatname\"\n\"=end formatname\"\n\"=for formatname text...\"\nFor, begin, and end will let you have regions of text/code/data that  are  not  generally\ninterpreted  as normal Pod text, but are passed directly to particular formatters, or are\notherwise special.  A formatter that can use that format will use the  region,  otherwise\nit will be completely ignored.\n\nA  command  \"=begin  formatname\",  some paragraphs, and a command \"=end formatname\", mean\nthat the text/data in between is meant for formatters that understand the special  format\ncalled formatname.  For example,\n\n=begin html\n\n<hr> <img src=\"thang.png\">\n<p> This is a raw HTML paragraph </p>\n\n=end html\n\nThe  command  \"=for  formatname  text...\"   specifies  that  the  remainder  of just this\nparagraph (starting right after formatname) is in that special format.\n\n=for html <hr> <img src=\"thang.png\">\n<p> This is a raw HTML paragraph </p>\n\nThis means the same thing as the above \"=begin html\" ... \"=end html\" region.\n\nThat is, with \"=for\", you can have only one paragraph's worth of text (i.e., the text  in\n\"=foo  targetname  text...\"), but with \"=begin targetname\" ... \"=end targetname\", you can\nhave any amount of stuff in between.  (Note that there still must be a blank  line  after\nthe \"=begin\" command and a blank line before the \"=end\" command.)\n\nHere are some examples of how to use these:\n\n=begin html\n\n<br>Figure 1.<br><IMG SRC=\"figure1.png\"><br>\n\n=end html\n\n=begin text\n\n---------------\n|  foo        |\n|        bar  |\n---------------\n\n^^^^ Figure 1. ^^^^\n\n=end text\n\nSome  format  names  that formatters currently are known to accept include \"roff\", \"man\",\n\"latex\", \"tex\", \"text\", and \"html\".   (Some  formatters  will  treat  some  of  these  as\nsynonyms.)\n\nA  format name of \"comment\" is common for just making notes (presumably to yourself) that\nwon't appear in any formatted version of the Pod document:\n\n=for comment\nMake sure that all the available options are documented!\n\nSome formatnames will require a leading colon  (as  in  \"=for  :formatname\",  or  \"=begin\n:formatname\"  ...  \"=end  :formatname\"),  to  signal  that  the text is not raw data, but\ninstead is Pod text (i.e., possibly containing formatting  codes)  that's  just  not  for\nnormal  formatting  (e.g., may not be a normal-use paragraph, but might be for formatting\nas a footnote).\n\n\"=encoding encodingname\"\nThis command is used for declaring the encoding of a document.   Most  users  won't  need\nthis;  but  if  your encoding isn't US-ASCII, then put a \"=encoding encodingname\" command\nvery early in the document so that pod formatters will know how to decode  the  document.\nFor  encodingname,  use  a  name  recognized  by  the Encode::Supported module.  Some pod\nformatters may try to guess between a Latin-1 or CP-1252 versus UTF-8 encoding, but  they\nmay  guess  wrong.   It's  best  to be explicit if you use anything besides strict ASCII.\nExamples:\n\n=encoding latin1\n\n=encoding utf8\n\n=encoding koi8-r\n\n=encoding ShiftJIS\n\n=encoding big5\n\n\"=encoding\" affects the whole document, and must occur only once.\n\nAnd don't forget, all commands but \"=encoding\" last up until the end of  its  paragraph,  not\nits  line.   So  in  the  examples below, you can see that every command needs the blank line\nafter it, to end its paragraph.  (And some older Pod translators may require the  \"=encoding\"\nline to have a following blank line as well, even though it should be legal to omit.)\n\nSome examples of lists include:\n\n=over\n\n=item *\n\nFirst item\n\n=item *\n\nSecond item\n\n=back\n\n=over\n\n=item Foo()\n\nDescription of Foo function\n\n=item Bar()\n\nDescription of Bar function\n\n=back\n"
                    },
                    {
                        "name": "Formatting Codes",
                        "content": "In  ordinary  paragraphs  and  in  some  command paragraphs, various formatting codes (a.k.a.\n\"interior sequences\") can be used:\n\n\"I<text>\" -- italic text\nUsed for emphasis (\"\"be I<careful!>\"\") and parameters (\"\"redo I<LABEL>\"\")\n\n\"B<text>\" -- bold text\nUsed for switches (\"\"perl's B<-n> switch\"\"), programs (\"\"some systems provide  a  B<chfn>\nfor  that\"\"),  emphasis  (\"\"be  B<careful!>\"\"), and so on (\"\"and that feature is known as\nB<autovivification>\"\").\n\n\"C<code>\" -- code text\nRenders code in a typewriter font, or gives some other indication  that  this  represents\nprogram text (\"\"C<gmtime($^T)>\"\") or some other form of computerese (\"\"C<drwxr-xr-x>\"\").\n\n\"L<name>\" -- a hyperlink\nThere  are  various  syntaxes,  listed below.  In the syntaxes given, \"text\", \"name\", and\n\"section\" cannot contain the characters '/' and  '|';  and  any  '<'  or  '>'  should  be\nmatched.\n\n•   \"L<name>\"\n\nLink  to  a  Perl  manual  page  (e.g., \"L<Net::Ping>\").  Note that \"name\" should not\ncontain spaces.  This syntax is also occasionally used for  references  to  Unix  man\npages, as in \"L<crontab(5)>\".\n\n•   \"L<name/\"sec\">\" or \"L<name/sec>\"\n\nLink to a section in other manual page.  E.g., \"L<perlsyn/\"For Loops\">\"\n\n•   \"L</\"sec\">\" or \"L</sec>\"\n\nLink to a section in this manual page.  E.g., \"L</\"Object Methods\">\"\n\nA  section  is  started  by  the  named heading or item.  For example, \"L<perlvar/$.>\" or\n\"L<perlvar/\"$.\">\" both link to the section started  by  \"\"=item  $.\"\"  in  perlvar.   And\n\"L<perlsyn/For  Loops>\"  or  \"L<perlsyn/\"For Loops\">\" both link to the section started by\n\"\"=head2 For Loops\"\" in perlsyn.\n\nTo control what text is used for display, you use \"\"L<text|...>\"\", as in:\n\n•   \"L<text|name>\"\n\nLink this text to that manual page.  E.g., \"L<Perl Error Messages|perldiag>\"\n\n•   \"L<text|name/\"sec\">\" or \"L<text|name/sec>\"\n\nLink  this  text  to  that  section  in   that   manual   page.    E.g.,   \"L<postfix\n\"if\"|perlsyn/\"Statement Modifiers\">\"\n\n•   \"L<text|/\"sec\">\" or \"L<text|/sec>\" or \"L<text|\"sec\">\"\n\nLink  this  text  to  that  section  in  this  manual  page.   E.g.,  \"L<the  various\nattributes|/\"Member Data\">\"\n\nOr you can link to a web page:\n\n•   \"L<scheme:...>\"\n\n\"L<text|scheme:...>\"\n\nLinks to an absolute URL.  For example, \"L<http://www.perl.org/>\" or \"L<The Perl Home\nPage|http://www.perl.org/>\".\n\n\"E<escape>\" -- a character escape\nVery similar to HTML/XML \"&foo;\" \"entity references\":\n\n•   \"E<lt>\" -- a literal < (less than)\n\n•   \"E<gt>\" -- a literal > (greater than)\n\n•   \"E<verbar>\" -- a literal | (vertical bar)\n\n•   \"E<sol>\" -- a literal / (solidus)\n\nThe above four are optional except in other formatting codes, notably  \"L<...>\",  and\nwhen preceded by a capital letter.\n\n•   \"E<htmlname>\"\n\nSome  non-numeric  HTML  entity  name, such as \"E<eacute>\", meaning the same thing as\n\"&eacute;\" in HTML -- i.e., a lowercase e with an acute (/-shaped) accent.\n\n•   \"E<number>\"\n\nThe ASCII/Latin-1/Unicode character with that number.   A  leading  \"0x\"  means  that\nnumber  is  hex,  as in \"E<0x201E>\".  A leading \"0\" means that number is octal, as in\n\"E<075>\".  Otherwise number is interpreted as being in decimal, as in \"E<181>\".\n\nNote that older Pod formatters might not recognize octal or hex numeric escapes,  and\nthat  many  formatters cannot reliably render characters above 255.  (Some formatters\nmay even have to use  compromised  renderings  of  Latin-1/CP-1252  characters,  like\nrendering \"E<eacute>\" as just a plain \"e\".)\n\n\"F<filename>\" -- used for filenames\nTypically displayed in italics.  Example: \"\"F<.cshrc>\"\"\n\n\"S<text>\" -- text contains non-breaking spaces\nThis  means  that  the  words  in  text  should  not  be  broken  across lines.  Example:\n\"S<$x ? $y : $z>\".\n\n\"X<topic name>\" -- an index entry\nThis is ignored by most formatters, but some may use it for building indexes.  It  always\nrenders as empty-string.  Example: \"X<absolutizing relative URLs>\"\n\n\"Z<>\" -- a null (zero-effect) formatting code\nThis  is  rarely  used.   It's one way to get around using an E<...> code sometimes.  For\nexample, instead of \"\"NE<lt>3\"\" (for \"N<3\") you could write \"\"NZ<><3\"\" (the \"Z<>\"  breaks\nup  the  \"N\"  and the \"<\" so they can't be considered the part of a (fictitious) \"N<...>\"\ncode).\n\nAnother use is to indicate that stuff in \"=item Z<>stuff...\"  is not to be considered  to\nbe a bullet or number.  For example, without the \"Z<>\", the line\n\n=item Z<>500 Server error\n\ncould possibly be parsed as an item in a numbered list when it isn't meant to be.\n\nStill another use is to maintain visual space between \"=item\" lines.  If you specify\n\n=item foo\n\n=item bar\n\nit will typically get rendered as\n\nfoo\nbar\n\nThat may be what you want, but if what you really want is\n\nfoo\n\nbar\n\nyou can use \"Z<>\" to accomplish that\n\n=item foo\n\nZ<>\n\n=item bar\n\nMost  of the time, you will need only a single set of angle brackets to delimit the beginning\nand end of formatting codes.  However, sometimes you will want to  put  a  real  right  angle\nbracket  (a greater-than sign, '>') inside of a formatting code.  This is particularly common\nwhen using a formatting code to provide a different font-type for a snippet of code.  As with\nall things in Perl, there is more than one way to do it.  One way is  to  simply  escape  the\nclosing bracket using an \"E\" code:\n\nC<$a E<lt>=E<gt> $b>\n\nThis will produce: \"\"$a <=> $b\"\"\n\nA  more  readable, and perhaps more \"plain\" way is to use an alternate set of delimiters that\ndoesn't require a single \">\" to be escaped.  Doubled angle brackets (\"<<\" and  \">>\")  may  be\nused  if  and  only  if  there is whitespace right after the opening delimiter and whitespace\nright before the closing delimiter!  For example, the following will do the trick:\n\nC<< $a <=> $b >>\n\nIn fact, you can use as many repeated angle-brackets as you like so long as you have the same\nnumber of them in  the  opening  and  closing  delimiters,  and  make  sure  that  whitespace\nimmediately follows the last '<' of the opening delimiter, and immediately precedes the first\n'>' of the closing delimiter.  (The whitespace is ignored.)  So the following will also work:\n\nC<<< $a <=> $b >>>\nC<<<<  $a <=> $b     >>>>\n\nAnd they all mean exactly the same as this:\n\nC<$a E<lt>=E<gt> $b>\n\nThe  multiple-bracket  form  does  not  affect  the  interpretation  of  the  contents of the\nformatting code, only how it must end.  That means that the examples above are  also  exactly\nthe same as this:\n\nC<< $a E<lt>=E<gt> $b >>\n\nAs  a  further example, this means that if you wanted to put these bits of code in \"C\" (code)\nstyle:\n\nopen(X, \">>thing.dat\") || die $!\n$foo->bar();\n\nyou could do it like so:\n\nC<<< open(X, \">>thing.dat\") || die $! >>>\nC<< $foo->bar(); >>\n\nwhich is presumably easier to read than the old way:\n\nC<open(X, \"E<gt>E<gt>thing.dat\") || die $!>\nC<$foo-E<gt>bar();>\n\nThis is currently supported by  pod2text  (Pod::Text),  pod2man  (Pod::Man),  and  any  other\npod2xxx  or  Pod::Xxxx  translators that use Pod::Parser 1.093 or later, or Pod::Tree 1.02 or\nlater.\n"
                    },
                    {
                        "name": "The Intent",
                        "content": "The intent is simplicity of use, not power of expression.  Paragraphs  look  like  paragraphs\n(block  format),  so that they stand out visually, and so that I could run them through \"fmt\"\neasily to reformat them (that's F7 in my version of vi, or Esc Q in my version of emacs).   I\nwanted the translator to always leave the \"'\" and \"`\" and \"\"\" quotes alone, in verbatim mode,\nso  I could slurp in a working program, shift it over four spaces, and have it print out, er,\nverbatim.  And presumably in a monospace font.\n\nThe Pod format is not necessarily sufficient for writing a book.  Pod is just meant to be  an\nidiot-proof  common  source  for  nroff,  HTML,  TeX, and other markup languages, as used for\nonline documentation.  Translators exist for pod2text, pod2html, pod2man (that's for nroff(1)\nand troff(1)), pod2latex, and pod2fm.  Various others are available in CPAN.\n"
                    },
                    {
                        "name": "Embedding Pods in Perl Modules",
                        "content": "You can embed Pod documentation in your Perl modules and scripts.  Start  your  documentation\nwith an empty line, a \"=head1\" command at the beginning, and end it with a \"=cut\" command and\nan  empty line.  The perl executable will ignore the Pod text.  You can place a Pod statement\nwhere perl expects the beginning of a new statement, but not  within  a  statement,  as  that\nwould result in an error.  See any of the supplied library modules for examples.\n\nIf  you're  going  to  put  your Pod at the end of the file, and you're using an \"END\" or\n\"DATA\" cut mark, make sure to put an empty line there before the first Pod command.\n\nEND\n\n=head1 NAME\n\nTime::Local - efficiently compute time from local and GMT time\n\nWithout that empty line before the \"=head1\", many translators wouldn't  have  recognized  the\n\"=head1\" as starting a Pod block.\n"
                    },
                    {
                        "name": "Hints for Writing Pod",
                        "content": "•\n\n\nThe  podchecker command is provided for checking Pod syntax for errors and warnings.  For\nexample, it checks for completely blank lines in Pod blocks and for unknown commands  and\nformatting  codes.   You  should  still  also  pass  your  document  through  one or more\ntranslators and proofread the result, or print out the result and proofread  that.   Some\nof  the  problems  found may be bugs in the translators, which you may or may not wish to\nwork around.\n\n•   If you're more familiar with writing in HTML than with writing in Pod, you can  try  your\nhand  at  writing  documentation  in  simple  HTML,  and  converting  it  to Pod with the\nexperimental Pod::HTML2Pod module, (available in CPAN),  and  looking  at  the  resulting\ncode.  The experimental Pod::PXML module in CPAN might also be useful.\n\n•   Many older Pod translators require the lines before every Pod command and after every Pod\ncommand (including \"=cut\"!) to be a blank line.  Having something like this:\n\n# - - - - - - - - - - - -\n=item $firecracker->boom()\n\nThis noisily detonates the firecracker object.\n=cut\nsub boom {\n...\n\n...will make such Pod translators completely fail to see the Pod block at all.\n\nInstead, have it like this:\n\n# - - - - - - - - - - - -\n\n=item $firecracker->boom()\n\nThis noisily detonates the firecracker object.\n\n=cut\n\nsub boom {\n...\n\n•   Some  older Pod translators require paragraphs (including command paragraphs like \"=head2\nFunctions\") to be separated by completely empty lines.  If you have an  apparently  empty\nline  with  some spaces on it, this might not count as a separator for those translators,\nand that could cause odd formatting.\n\n•   Older translators might add wording around an L<> link, so that \"L<Foo::Bar>\" may  become\n\"the  Foo::Bar  manpage\",  for  example.   So you shouldn't write things like \"the L<foo>\ndocumentation\", if you want the translated document to  read  sensibly.   Instead,  write\n\"the  L<Foo::Bar|Foo::Bar> documentation\" or \"L<the Foo::Bar documentation|Foo::Bar>\", to\ncontrol how the link comes out.\n\n•   Going past the 70th column in a verbatim block might  be  ungracefully  wrapped  by  some\nformatters.\n"
                    }
                ]
            },
            "SEE ALSO": {
                "content": "perlpodspec,  \"PODs:  Embedded  Documentation\"  in  perlsyn,  perlnewmod,  perldoc, pod2html,\npod2man, podchecker.\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Larry Wall, Sean M. Burke\n\nperl v5.38.2                                 2026-06-12                                   PERLPOD(1)",
                "subsections": []
            }
        }
    }
}