Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 847 insertions, 0 deletions

diff --git a/upstream/debian-bookworm/man1/perlpod.1 b/upstream/debian-bookworm/man1/perlpod.1
new file mode 100644
index 00000000..a6bc925e
--- /dev/null
+++ b/upstream/debian-bookworm/man1/perlpod.1
@@ -0,0 +1,847 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLPOD 1"
+.TH PERLPOD 1 "2023-11-25" "perl v5.36.0" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+perlpod \- the Plain Old Documentation format
+.IX Xref "POD plain old documentation"
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+Pod is a simple-to-use markup language used for writing documentation
+for Perl, Perl programs, and Perl modules.
+.PP
+Translators are available for converting Pod to various formats
+like plain text, \s-1HTML,\s0 man pages, and more.
+.PP
+Pod markup consists of three basic kinds of paragraphs:
+ordinary,
+verbatim, and 
+command.
+.SS "Ordinary Paragraph"
+.IX Xref "POD, ordinary paragraph"
+.IX Subsection "Ordinary Paragraph"
+Most paragraphs in your documentation will be ordinary blocks
+of text, like this one.  You can simply type in your text without
+any markup whatsoever, and with just a blank line before and
+after.  When it gets formatted, it will undergo minimal formatting, 
+like being rewrapped, probably put into a proportionally spaced
+font, and maybe even justified.
+.PP
+You can use formatting codes in ordinary paragraphs, for \fBbold\fR,
+\&\fIitalic\fR, \f(CW\*(C`code\-style\*(C'\fR, hyperlinks, and more.  Such
+codes are explained in the "Formatting Codes"
+section, below.
+.SS "Verbatim Paragraph"
+.IX Xref "POD, verbatim paragraph verbatim"
+.IX Subsection "Verbatim Paragraph"
+Verbatim paragraphs are usually used for presenting a codeblock or
+other text which does not require any special parsing or formatting,
+and which shouldn't be wrapped.
+.PP
+A verbatim paragraph is distinguished by having its first character
+be a space or a tab.  (And commonly, all its lines begin with spaces
+and/or tabs.)  It should be reproduced exactly, with tabs assumed to
+be on 8\-column boundaries.  There are no special formatting codes,
+so you can't italicize or anything like that.  A \e means \e, and
+nothing else.
+.SS "Command Paragraph"
+.IX Xref "POD, command"
+.IX Subsection "Command Paragraph"
+A command paragraph is used for special treatment of whole chunks
+of text, usually as headings or parts of lists.
+.PP
+All command paragraphs (which are typically only one line long) start
+with \*(L"=\*(R", followed by an identifier, followed by arbitrary text that
+the command can use however it pleases.  Currently recognized commands
+are
+.PP
+.Vb 10
+\&    =pod
+\&    =head1 Heading Text
+\&    =head2 Heading Text
+\&    =head3 Heading Text
+\&    =head4 Heading Text
+\&    =head5 Heading Text
+\&    =head6 Heading Text
+\&    =over indentlevel
+\&    =item stuff
+\&    =back
+\&    =begin format
+\&    =end format
+\&    =for format text...
+\&    =encoding type
+\&    =cut
+.Ve
+.PP
+To explain them each in detail:
+.ie n .IP """=head1 \fIHeading Text\fP""" 4
+.el .IP "\f(CW=head1 \f(CIHeading Text\f(CW\fR" 4
+.IX Xref "=head1 =head2 =head3 =head4 =head5 =head6 head1 head2 head3 head4 head5 head6"
+.IX Item "=head1 Heading Text"
+.PD 0
+.ie n .IP """=head2 \fIHeading Text\fP""" 4
+.el .IP "\f(CW=head2 \f(CIHeading Text\f(CW\fR" 4
+.IX Item "=head2 Heading Text"
+.ie n .IP """=head3 \fIHeading Text\fP""" 4
+.el .IP "\f(CW=head3 \f(CIHeading Text\f(CW\fR" 4
+.IX Item "=head3 Heading Text"
+.ie n .IP """=head4 \fIHeading Text\fP""" 4
+.el .IP "\f(CW=head4 \f(CIHeading Text\f(CW\fR" 4
+.IX Item "=head4 Heading Text"
+.ie n .IP """=head5 \fIHeading Text\fP""" 4
+.el .IP "\f(CW=head5 \f(CIHeading Text\f(CW\fR" 4
+.IX Item "=head5 Heading Text"
+.ie n .IP """=head6 \fIHeading Text\fP""" 4
+.el .IP "\f(CW=head6 \f(CIHeading Text\f(CW\fR" 4
+.IX Item "=head6 Heading Text"
+.PD
+Head1 through head6 produce headings, head1 being the highest
+level.  The text in the rest of this paragraph is the content of the
+heading.  For example:
+.Sp
+.Vb 1
+\&  =head2 Object Attributes
+.Ve
+.Sp
+The text \*(L"Object Attributes\*(R" comprises the heading there.
+The text in these heading commands can use formatting codes, as seen here:
+.Sp
+.Vb 1
+\&  =head2 Possible Values for C<$/>
+.Ve
+.Sp
+Such commands are explained in the
+"Formatting Codes" section, below.
+.Sp
+Note that \f(CW\*(C`head5\*(C'\fR and \f(CW\*(C`head6\*(C'\fR were introduced in 2020 and in
+Pod::Simple 3.41, released in October 2020, so they might not be
+supported on the Pod parser you use.
+.ie n .IP """=over \fIindentlevel\fP""" 4
+.el .IP "\f(CW=over \f(CIindentlevel\f(CW\fR" 4
+.IX Xref "=over =item =back over item back"
+.IX Item "=over indentlevel"
+.PD 0
+.ie n .IP """=item \fIstuff...\fP""" 4
+.el .IP "\f(CW=item \f(CIstuff...\f(CW\fR" 4
+.IX Item "=item stuff..."
+.ie n .IP """=back""" 4
+.el .IP "\f(CW=back\fR" 4
+.IX Item "=back"
+.PD
+Item, over, and back require a little more explanation:  \*(L"=over\*(R" starts
+a region specifically for the generation of a list using \*(L"=item\*(R"
+commands, or for indenting (groups of) normal paragraphs.  At the end
+of your list, use \*(L"=back\*(R" to end it.  The \fIindentlevel\fR option to
+\&\*(L"=over\*(R" indicates how far over to indent, generally in ems (where
+one em is the width of an \*(L"M\*(R" in the document's base font) or roughly
+comparable units; if there is no \fIindentlevel\fR option, it defaults
+to four.  (And some formatters may just ignore whatever \fIindentlevel\fR
+you provide.)  In the \fIstuff\fR in \f(CW\*(C`=item \f(CIstuff...\f(CW\*(C'\fR, you may
+use formatting codes, as seen here:
+.Sp
+.Vb 1
+\&  =item Using C<$|> to Control Buffering
+.Ve
+.Sp
+Such commands are explained in the
+"Formatting Codes" section, below.
+.Sp
+Note also that there are some basic rules to using \*(L"=over\*(R" ...
+\&\*(L"=back\*(R" regions:
+.RS 4
+.IP "\(bu" 4
+Don't use \*(L"=item\*(R"s outside of an \*(L"=over\*(R" ... \*(L"=back\*(R" region.
+.IP "\(bu" 4
+The first thing after the \*(L"=over\*(R" command should be an \*(L"=item\*(R", unless
+there aren't going to be any items at all in this \*(L"=over\*(R" ... \*(L"=back\*(R"
+region.
+.IP "\(bu" 4
+Don't put "=head\fIn\fR\*(L" commands inside an \*(R"=over\*(L" ... \*(R"=back" region.
+.IP "\(bu" 4
+And perhaps most importantly, keep the items consistent: either use
+\&\*(L"=item *\*(R" for all of them, to produce bullets; or use \*(L"=item 1.\*(R",
+\&\*(L"=item 2.\*(R", etc., to produce numbered lists; or use \*(L"=item foo\*(R",
+\&\*(L"=item bar\*(R", etc.\-\-namely, things that look nothing like bullets or
+numbers.  (If you have a list that contains both: 1) things that don't
+look like bullets nor numbers,  plus 2) things that do, you should
+preface the bullet\- or number-like items with \f(CW\*(C`Z<>\*(C'\fR.  See
+Z<>
+below for an example.)
+.Sp
+If you start with bullets or numbers, stick with them, as
+formatters use the first \*(L"=item\*(R" type to decide how to format the
+list.
+.RE
+.RS 4
+.RE
+.ie n .IP """=cut""" 4
+.el .IP "\f(CW=cut\fR" 4
+.IX Xref "=cut cut"
+.IX Item "=cut"
+To end a Pod block, use a blank line,
+then a line beginning with \*(L"=cut\*(R", and a blank
+line after it.  This lets Perl (and the Pod formatter) know that
+this is where Perl code is resuming.  (The blank line before the \*(L"=cut\*(R"
+is not technically necessary, but many older Pod processors require it.)
+.ie n .IP """=pod""" 4
+.el .IP "\f(CW=pod\fR" 4
+.IX Xref "=pod pod"
+.IX Item "=pod"
+The \*(L"=pod\*(R" command by itself doesn't do much of anything, but it
+signals to Perl (and Pod formatters) that a Pod block starts here.  A
+Pod block starts with \fIany\fR command paragraph, so a \*(L"=pod\*(R" command is
+usually used just when you want to start a Pod block with an ordinary
+paragraph or a verbatim paragraph.  For example:
+.Sp
+.Vb 1
+\&  =item stuff()
+\&
+\&  This function does stuff.
+\&
+\&  =cut
+\&
+\&  sub stuff {
+\&    ...
+\&  }
+\&
+\&  =pod
+\&
+\&  Remember to check its return value, as in:
+\&
+\&    stuff() || die "Couldn\*(Aqt do stuff!";
+\&
+\&  =cut
+.Ve
+.ie n .IP """=begin \fIformatname\fP""" 4
+.el .IP "\f(CW=begin \f(CIformatname\f(CW\fR" 4
+.IX Xref "=begin =end =for begin end for"
+.IX Item "=begin formatname"
+.PD 0
+.ie n .IP """=end \fIformatname\fP""" 4
+.el .IP "\f(CW=end \f(CIformatname\f(CW\fR" 4
+.IX Item "=end formatname"
+.ie n .IP """=for \fIformatname\fP \fItext...\fP""" 4
+.el .IP "\f(CW=for \f(CIformatname\f(CW \f(CItext...\f(CW\fR" 4
+.IX Item "=for formatname text..."
+.PD
+For, begin, and end will let you have regions of text/code/data that
+are not generally interpreted as normal Pod text, but are passed
+directly to particular formatters, or are otherwise special.  A
+formatter that can use that format will use the region, otherwise it
+will be completely ignored.
+.Sp
+A command "=begin \fIformatname\fR\*(L", some paragraphs, and a
+command \*(R"=end \fIformatname\fR", mean that the text/data in between
+is meant for formatters that understand the special format
+called \fIformatname\fR.  For example,
+.Sp
+.Vb 1
+\&  =begin html
+\&
+\&  <hr> <img src="thang.png">
+\&  <p> This is a raw HTML paragraph </p>
+\&
+\&  =end html
+.Ve
+.Sp
+The command "=for \fIformatname\fR \fItext...\fR"
+specifies that the remainder of just this paragraph (starting
+right after \fIformatname\fR) is in that special format.
+.Sp
+.Vb 2
+\&  =for html <hr> <img src="thang.png">
+\&  <p> This is a raw HTML paragraph </p>
+.Ve
+.Sp
+This means the same thing as the above \*(L"=begin html\*(R" ... \*(L"=end html\*(R"
+region.
+.Sp
+That is, with \*(L"=for\*(R", you can have only one paragraph's worth
+of text (i.e., the text in \*(L"=foo targetname text...\*(R"), but with
+\&\*(L"=begin targetname\*(R" ... \*(L"=end targetname\*(R", you can have any amount
+of stuff in between.  (Note that there still must be a blank line
+after the \*(L"=begin\*(R" command and a blank line before the \*(L"=end\*(R"
+command.)
+.Sp
+Here are some examples of how to use these:
+.Sp
+.Vb 1
+\&  =begin html
+\&
+\&  <br>Figure 1.<br><IMG SRC="figure1.png"><br>
+\&
+\&  =end html
+\&
+\&  =begin text
+\&
+\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&    |  foo        |
+\&    |        bar  |
+\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&
+\&  ^^^^ Figure 1. ^^^^
+\&
+\&  =end text
+.Ve
+.Sp
+Some format names that formatters currently are known to accept
+include \*(L"roff\*(R", \*(L"man\*(R", \*(L"latex\*(R", \*(L"tex\*(R", \*(L"text\*(R", and \*(L"html\*(R".  (Some
+formatters will treat some of these as synonyms.)
+.Sp
+A format name of \*(L"comment\*(R" is common for just making notes (presumably
+to yourself) that won't appear in any formatted version of the Pod
+document:
+.Sp
+.Vb 2
+\&  =for comment
+\&  Make sure that all the available options are documented!
+.Ve
+.Sp
+Some \fIformatnames\fR will require a leading colon (as in
+\&\f(CW"=for :formatname"\fR, or
+\&\f(CW"=begin :formatname" ... "=end :formatname"\fR),
+to signal that the text is not raw data, but instead \fIis\fR Pod text
+(i.e., possibly containing formatting codes) that's just not for
+normal formatting (e.g., may not be a normal-use paragraph, but might
+be for formatting as a footnote).
+.ie n .IP """=encoding \fIencodingname\fP""" 4
+.el .IP "\f(CW=encoding \f(CIencodingname\f(CW\fR" 4
+.IX Xref "=encoding encoding"
+.IX Item "=encoding encodingname"
+This command is used for declaring the encoding of a document.  Most
+users won't need this; but if your encoding isn't US-ASCII,
+then put a \f(CW\*(C`=encoding \f(CIencodingname\f(CW\*(C'\fR command very early in the document so
+that pod formatters will know how to decode the document.  For
+\&\fIencodingname\fR, use a name recognized by the Encode::Supported
+module.  Some pod formatters may try to guess between a Latin\-1 or
+\&\s-1CP\-1252\s0 versus
+\&\s-1UTF\-8\s0 encoding, but they may guess wrong.  It's best to be explicit if
+you use anything besides strict \s-1ASCII.\s0  Examples:
+.Sp
+.Vb 1
+\&  =encoding latin1
+\&
+\&  =encoding utf8
+\&
+\&  =encoding koi8\-r
+\&
+\&  =encoding ShiftJIS
+\&
+\&  =encoding big5
+.Ve
+.Sp
+\&\f(CW\*(C`=encoding\*(C'\fR affects the whole document, and must occur only once.
+.PP
+And don't forget, all commands but \f(CW\*(C`=encoding\*(C'\fR last up
+until the end of its \fIparagraph\fR, not its line.  So in the
+examples below, you can see that every command needs the blank
+line after it, to end its paragraph.  (And some older Pod translators
+may require the \f(CW\*(C`=encoding\*(C'\fR line to have a following blank line as
+well, even though it should be legal to omit.)
+.PP
+Some examples of lists include:
+.PP
+.Vb 1
+\&  =over
+\&
+\&  =item *
+\&
+\&  First item
+\&
+\&  =item *
+\&
+\&  Second item
+\&
+\&  =back
+\&
+\&  =over
+\&
+\&  =item Foo()
+\&
+\&  Description of Foo function
+\&
+\&  =item Bar()
+\&
+\&  Description of Bar function
+\&
+\&  =back
+.Ve
+.SS "Formatting Codes"
+.IX Xref "POD, formatting code formatting code POD, interior sequence interior sequence"
+.IX Subsection "Formatting Codes"
+In ordinary paragraphs and in some command paragraphs, various
+formatting codes (a.k.a. \*(L"interior sequences\*(R") can be used:
+.ie n .IP """I<text>"" \*(-- italic text" 4
+.el .IP "\f(CWI<text>\fR \*(-- italic text" 4
+.IX Xref "I I<> POD, formatting code, italic italic"
+.IX Item "I<text> italic text"
+Used for emphasis ("\f(CW\*(C`be I<careful!>\*(C'\fR\*(L") and parameters
+(\*(R"\f(CW\*(C`redo I<LABEL>\*(C'\fR")
+.ie n .IP """B<text>"" \*(-- bold text" 4
+.el .IP "\f(CWB<text>\fR \*(-- bold text" 4
+.IX Xref "B B<> POD, formatting code, bold bold"
+.IX Item "B<text> bold text"
+Used for switches ("\f(CW\*(C`perl\*(Aqs B<\-n> switch\*(C'\fR\*(L"), programs
+(\*(R"\f(CW\*(C`some systems provide a B<chfn> for that\*(C'\fR\*(L"),
+emphasis (\*(R"\f(CW\*(C`be B<careful!>\*(C'\fR\*(L"), and so on
+(\*(R"\f(CW\*(C`and that feature is known as B<autovivification>\*(C'\fR").
+.ie n .IP """C<code>"" \*(-- code text" 4
+.el .IP "\f(CWC<code>\fR \*(-- code text" 4
+.IX Xref "C C<> POD, formatting code, code code"
+.IX Item "C<code> code text"
+Renders code in a typewriter font, or gives some other indication that
+this represents program text ("\f(CW\*(C`C<gmtime($^T)>\*(C'\fR\*(L") or some other
+form of computerese (\*(R"\f(CW\*(C`C<drwxr\-xr\-x>\*(C'\fR").
+.ie n .IP """L<name>"" \*(-- a hyperlink" 4
+.el .IP "\f(CWL<name>\fR \*(-- a hyperlink" 4
+.IX Xref "L L<> POD, formatting code, hyperlink hyperlink"
+.IX Item "L<name> a hyperlink"
+There are various syntaxes, listed below.  In the syntaxes given,
+\&\f(CW\*(C`text\*(C'\fR, \f(CW\*(C`name\*(C'\fR, and \f(CW\*(C`section\*(C'\fR cannot contain the characters
+\&'/' and '|'; and any '<' or '>' should be matched.
+.RS 4
+.IP "\(bu" 4
+\&\f(CW\*(C`L<name>\*(C'\fR
+.Sp
+Link to a Perl manual page (e.g., \f(CW\*(C`L<Net::Ping>\*(C'\fR).  Note
+that \f(CW\*(C`name\*(C'\fR should not contain spaces.  This syntax
+is also occasionally used for references to Unix man pages, as in
+\&\f(CW\*(C`L<crontab(5)>\*(C'\fR.
+.IP "\(bu" 4
+\&\f(CW\*(C`L<name/"sec">\*(C'\fR or \f(CW\*(C`L<name/sec>\*(C'\fR
+.Sp
+Link to a section in other manual page.  E.g.,
+\&\f(CW\*(C`L<perlsyn/"For Loops">\*(C'\fR
+.IP "\(bu" 4
+\&\f(CW\*(C`L</"sec">\*(C'\fR or \f(CW\*(C`L</sec>\*(C'\fR
+.Sp
+Link to a section in this manual page.  E.g.,
+\&\f(CW\*(C`L</"Object Methods">\*(C'\fR
+.RE
+.RS 4
+.Sp
+A section is started by the named heading or item.  For
+example, \f(CW\*(C`L<perlvar/$.>\*(C'\fR or \f(CW\*(C`L<perlvar/"$.">\*(C'\fR both
+link to the section started by "\f(CW\*(C`=item $.\*(C'\fR" in perlvar.  And
+\&\f(CW\*(C`L<perlsyn/For Loops>\*(C'\fR or \f(CW\*(C`L<perlsyn/"For Loops">\*(C'\fR
+both link to the section started by "\f(CW\*(C`=head2 For Loops\*(C'\fR"
+in perlsyn.
+.Sp
+To control what text is used for display, you
+use "\f(CW\*(C`L<text|...>\*(C'\fR", as in:
+.IP "\(bu" 4
+\&\f(CW\*(C`L<text|name>\*(C'\fR
+.Sp
+Link this text to that manual page.  E.g.,
+\&\f(CW\*(C`L<Perl Error Messages|perldiag>\*(C'\fR
+.IP "\(bu" 4
+\&\f(CW\*(C`L<text|name/"sec">\*(C'\fR or \f(CW\*(C`L<text|name/sec>\*(C'\fR
+.Sp
+Link this text to that section in that manual page.  E.g.,
+\&\f(CW\*(C`L<postfix "if"|perlsyn/"Statement Modifiers">\*(C'\fR
+.IP "\(bu" 4
+\&\f(CW\*(C`L<text|/"sec">\*(C'\fR or \f(CW\*(C`L<text|/sec>\*(C'\fR
+or \f(CW\*(C`L<text|"sec">\*(C'\fR
+.Sp
+Link this text to that section in this manual page.  E.g.,
+\&\f(CW\*(C`L<the various attributes|/"Member Data">\*(C'\fR
+.RE
+.RS 4
+.Sp
+Or you can link to a web page:
+.IP "\(bu" 4
+\&\f(CW\*(C`L<scheme:...>\*(C'\fR
+.Sp
+\&\f(CW\*(C`L<text|scheme:...>\*(C'\fR
+.Sp
+Links to an absolute \s-1URL.\s0  For example, \f(CW\*(C`L<http://www.perl.org/>\*(C'\fR or
+\&\f(CW\*(C`L<The Perl Home Page|http://www.perl.org/>\*(C'\fR.
+.RE
+.RS 4
+.RE
+.ie n .IP """E<escape>"" \*(-- a character escape" 4
+.el .IP "\f(CWE<escape>\fR \*(-- a character escape" 4
+.IX Xref "E E<> POD, formatting code, escape escape"
+.IX Item "E<escape> a character escape"
+Very similar to \s-1HTML/XML\s0 \f(CW\*(C`&\f(CIfoo\f(CW;\*(C'\fR \*(L"entity references\*(R":
+.RS 4
+.IP "\(bu" 4
+\&\f(CW\*(C`E<lt>\*(C'\fR \*(-- a literal < (less than)
+.IP "\(bu" 4
+\&\f(CW\*(C`E<gt>\*(C'\fR \*(-- a literal > (greater than)
+.IP "\(bu" 4
+\&\f(CW\*(C`E<verbar>\*(C'\fR \*(-- a literal | (\fIver\fRtical \fIbar\fR)
+.IP "\(bu" 4
+\&\f(CW\*(C`E<sol>\*(C'\fR \*(-- a literal / (\fIsol\fRidus)
+.Sp
+The above four are optional except in other formatting codes,
+notably \f(CW\*(C`L<...>\*(C'\fR, and when preceded by a
+capital letter.
+.IP "\(bu" 4
+\&\f(CW\*(C`E<htmlname>\*(C'\fR
+.Sp
+Some non-numeric \s-1HTML\s0 entity name, such as \f(CW\*(C`E<eacute>\*(C'\fR,
+meaning the same thing as \f(CW\*(C`&eacute;\*(C'\fR in \s-1HTML\s0 \*(-- i.e., a lowercase
+e with an acute (/\-shaped) accent.
+.IP "\(bu" 4
+\&\f(CW\*(C`E<number>\*(C'\fR
+.Sp
+The ASCII/Latin\-1/Unicode character with that number.  A
+leading \*(L"0x\*(R" means that \fInumber\fR is hex, as in
+\&\f(CW\*(C`E<0x201E>\*(C'\fR.  A leading \*(L"0\*(R" means that \fInumber\fR is octal,
+as in \f(CW\*(C`E<075>\*(C'\fR.  Otherwise \fInumber\fR is interpreted as being
+in decimal, as in \f(CW\*(C`E<181>\*(C'\fR.
+.Sp
+Note that older Pod formatters might not recognize octal or
+hex numeric escapes, and that many formatters cannot reliably
+render characters above 255.  (Some formatters may even have
+to use compromised renderings of Latin\-1/CP\-1252 characters, like
+rendering \f(CW\*(C`E<eacute>\*(C'\fR as just a plain \*(L"e\*(R".)
+.RE
+.RS 4
+.RE
+.ie n .IP """F<filename>"" \*(-- used for filenames" 4
+.el .IP "\f(CWF<filename>\fR \*(-- used for filenames" 4
+.IX Xref "F F<> POD, formatting code, filename filename"
+.IX Item "F<filename> used for filenames"
+Typically displayed in italics.  Example: "\f(CW\*(C`F<.cshrc>\*(C'\fR"
+.ie n .IP """S<text>"" \*(-- text contains non-breaking spaces" 4
+.el .IP "\f(CWS<text>\fR \*(-- text contains non-breaking spaces" 4
+.IX Xref "S S<> POD, formatting code, non-breaking space non-breaking space"
+.IX Item "S<text> text contains non-breaking spaces"
+This means that the words in \fItext\fR should not be broken
+across lines.  Example: \f(CW\*(C`S<$x ? $y : $z>\*(C'\fR.
+.ie n .IP """X<topic name>"" \*(-- an index entry" 4
+.el .IP "\f(CWX<topic name>\fR \*(-- an index entry" 4
+.IX Xref "X X<> POD, formatting code, index entry index entry"
+.IX Item "X<topic name> an index entry"
+This is ignored by most formatters, but some may use it for building
+indexes.  It always renders as empty-string.
+Example: \f(CW\*(C`X<absolutizing relative URLs>\*(C'\fR
+.ie n .IP """Z<>"" \*(-- a null (zero-effect) formatting code" 4
+.el .IP "\f(CWZ<>\fR \*(-- a null (zero-effect) formatting code" 4
+.IX Xref "Z Z<> POD, formatting code, null null"
+.IX Item "Z<> a null (zero-effect) formatting code"
+This is rarely used.  It's one way to get around using an
+E<...> code sometimes.  For example, instead of
+"\f(CW\*(C`NE<lt>3\*(C'\fR\*(L" (for \*(R"N<3\*(L") you could write
+\&\*(R"\f(CW\*(C`NZ<><3\*(C'\fR\*(L" (the \*(R"Z<>\*(L" breaks up the \*(R"N\*(L" and
+the \*(R"<\*(L" so they can't be considered
+the part of a (fictitious) \*(R"N<...>" code).
+.Sp
+Another use is to indicate that \fIstuff\fR in \f(CW\*(C`=item Z<>\f(CIstuff...\f(CW\*(C'\fR
+is not to be considered to be a bullet or number.  For example,
+without the \f(CW\*(C`Z<>\*(C'\fR, the line
+.Sp
+.Vb 1
+\& =item Z<>500 Server error
+.Ve
+.Sp
+could possibly be parsed as an item in a numbered list when it isn't
+meant to be.
+.Sp
+Still another use is to maintain visual space between \f(CW\*(C`=item\*(C'\fR lines.
+If you specify
+.Sp
+.Vb 1
+\& =item foo
+\&
+\& =item bar
+.Ve
+.Sp
+it will typically get rendered as
+.Sp
+.Vb 2
+\& foo
+\& bar
+.Ve
+.Sp
+That may be what you want, but if what you really want is
+.Sp
+.Vb 1
+\& foo
+\&
+\& bar
+.Ve
+.Sp
+you can use \f(CW\*(C`Z<>\*(C'\fR to accomplish that
+.Sp
+.Vb 1
+\& =item foo
+\&
+\& Z<>
+\&
+\& =item bar
+.Ve
+.PP
+Most of the time, you will need only a single set of angle brackets to
+delimit the beginning and end of formatting codes.  However,
+sometimes you will want to put a real right angle bracket (a
+greater-than sign, '>') inside of a formatting code.  This is particularly
+common when using a formatting code to provide a different font-type for a
+snippet of code.  As with all things in Perl, there is more than
+one way to do it.  One way is to simply escape the closing bracket
+using an \f(CW\*(C`E\*(C'\fR code:
+.PP
+.Vb 1
+\&    C<$a E<lt>=E<gt> $b>
+.Ve
+.PP
+This will produce: "\f(CW\*(C`$a <=> $b\*(C'\fR"
+.PP
+A more readable, and perhaps more \*(L"plain\*(R" way is to use an alternate
+set of delimiters that doesn't require a single \*(L">\*(R" to be escaped.
+Doubled angle brackets (\*(L"<<\*(R" and \*(L">>\*(R") may be used \fIif and only if there is
+whitespace right after the opening delimiter and whitespace right
+before the closing delimiter!\fR  For example, the following will
+do the trick:
+.IX Xref "POD, formatting code, escaping with multiple brackets"
+.PP
+.Vb 1
+\&    C<< $a <=> $b >>
+.Ve
+.PP
+In fact, you can use as many repeated angle-brackets as you like so
+long as you have the same number of them in the opening and closing
+delimiters, and make sure that whitespace immediately follows the last
+\&'<' of the opening delimiter, and immediately precedes the first '>'
+of the closing delimiter.  (The whitespace is ignored.)  So the
+following will also work:
+.IX Xref "POD, formatting code, escaping with multiple brackets"
+.PP
+.Vb 2
+\&    C<<< $a <=> $b >>>
+\&    C<<<<  $a <=> $b     >>>>
+.Ve
+.PP
+And they all mean exactly the same as this:
+.PP
+.Vb 1
+\&    C<$a E<lt>=E<gt> $b>
+.Ve
+.PP
+The multiple-bracket form does not affect the interpretation of the contents of
+the formatting code, only how it must end.  That means that the examples above
+are also exactly the same as this:
+.PP
+.Vb 1
+\&    C<< $a E<lt>=E<gt> $b >>
+.Ve
+.PP
+As a further example, this means that if you wanted to put these bits of
+code in \f(CW\*(C`C\*(C'\fR (code) style:
+.PP
+.Vb 2
+\&    open(X, ">>thing.dat") || die $!
+\&    $foo\->bar();
+.Ve
+.PP
+you could do it like so:
+.PP
+.Vb 2
+\&    C<<< open(X, ">>thing.dat") || die $! >>>
+\&    C<< $foo\->bar(); >>
+.Ve
+.PP
+which is presumably easier to read than the old way:
+.PP
+.Vb 2
+\&    C<open(X, "E<gt>E<gt>thing.dat") || die $!>
+\&    C<$foo\-E<gt>bar();>
+.Ve
+.PP
+This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man),
+and any other pod2xxx or Pod::Xxxx translators that use
+Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.
+.SS "The Intent"
+.IX Xref "POD, intent of"
+.IX Subsection "The Intent"
+The intent is simplicity of use, not power of expression.  Paragraphs
+look like paragraphs (block format), so that they stand out
+visually, and so that I could run them through \f(CW\*(C`fmt\*(C'\fR easily to reformat
+them (that's F7 in my version of \fBvi\fR, or Esc Q in my version of
+\&\fBemacs\fR).  I wanted the translator to always leave the \f(CW\*(C`\*(Aq\*(C'\fR and \f(CW\*(C`\`\*(C'\fR and
+\&\f(CW\*(C`"\*(C'\fR quotes alone, in verbatim mode, so I could slurp in a
+working program, shift it over four spaces, and have it print out, er,
+verbatim.  And presumably in a monospace font.
+.PP
+The Pod format is not necessarily sufficient for writing a book.  Pod
+is just meant to be an idiot-proof common source for nroff, \s-1HTML,\s0
+TeX, and other markup languages, as used for online
+documentation.  Translators exist for \fBpod2text\fR, \fBpod2html\fR,
+\&\fBpod2man\fR (that's for \fBnroff\fR\|(1) and \fBtroff\fR\|(1)), \fBpod2latex\fR, and
+\&\fBpod2fm\fR.  Various others are available in \s-1CPAN.\s0
+.SS "Embedding Pods in Perl Modules"
+.IX Xref "POD, embedding"
+.IX Subsection "Embedding Pods in Perl Modules"
+You can embed Pod documentation in your Perl modules and scripts.  Start
+your documentation with an empty line, a \*(L"=head1\*(R" command at the
+beginning, and end it with a \*(L"=cut\*(R" command and an empty line.  The
+\&\fBperl\fR executable will ignore the Pod text.  You can place a Pod
+statement where \fBperl\fR expects the beginning of a new statement, but
+not within a statement, as that would result in an error.  See any of
+the supplied library modules for examples.
+.PP
+If you're going to put your Pod at the end of the file, and you're using
+an \f(CW\*(C`_\|_END_\|_\*(C'\fR or \f(CW\*(C`_\|_DATA_\|_\*(C'\fR cut mark, make sure to put an empty line there
+before the first Pod command.
+.PP
+.Vb 1
+\&  _\|_END_\|_
+\&
+\&  =head1 NAME
+\&
+\&  Time::Local \- efficiently compute time from local and GMT time
+.Ve
+.PP
+Without that empty line before the \*(L"=head1\*(R", many translators wouldn't
+have recognized the \*(L"=head1\*(R" as starting a Pod block.
+.SS "Hints for Writing Pod"
+.IX Subsection "Hints for Writing Pod"
+.IP "\(bu" 4
+
+.IX Xref "podchecker POD, validating"
+.Sp
+The \fBpodchecker\fR command is provided for checking Pod syntax for errors
+and warnings.  For example, it checks for completely blank lines in
+Pod blocks and for unknown commands and formatting codes.  You should
+still also pass your document through one or more translators and proofread
+the result, or print out the result and proofread that.  Some of the
+problems found may be bugs in the translators, which you may or may not
+wish to work around.
+.IP "\(bu" 4
+If you're more familiar with writing in \s-1HTML\s0 than with writing in Pod, you
+can try your hand at writing documentation in simple \s-1HTML,\s0 and converting
+it to Pod with the experimental Pod::HTML2Pod module,
+(available in \s-1CPAN\s0), and looking at the resulting code.  The experimental
+Pod::PXML module in \s-1CPAN\s0 might also be useful.
+.IP "\(bu" 4
+Many older Pod translators require the lines before every Pod
+command and after every Pod command (including \*(L"=cut\*(R"!) to be a blank
+line.  Having something like this:
+.Sp
+.Vb 2
+\& # \- \- \- \- \- \- \- \- \- \- \- \-
+\& =item $firecracker\->boom()
+\&
+\& This noisily detonates the firecracker object.
+\& =cut
+\& sub boom {
+\& ...
+.Ve
+.Sp
+\&...will make such Pod translators completely fail to see the Pod block
+at all.
+.Sp
+Instead, have it like this:
+.Sp
+.Vb 1
+\& # \- \- \- \- \- \- \- \- \- \- \- \-
+\&
+\& =item $firecracker\->boom()
+\&
+\& This noisily detonates the firecracker object.
+\&
+\& =cut
+\&
+\& sub boom {
+\& ...
+.Ve
+.IP "\(bu" 4
+Some older Pod translators require paragraphs (including command
+paragraphs like \*(L"=head2 Functions\*(R") to be separated by \fIcompletely\fR
+empty lines.  If you have an apparently empty line with some spaces
+on it, this might not count as a separator for those translators, and
+that could cause odd formatting.
+.IP "\(bu" 4
+Older translators might add wording around an L<> link, so that
+\&\f(CW\*(C`L<Foo::Bar>\*(C'\fR may become \*(L"the Foo::Bar manpage\*(R", for example.
+So you shouldn't write things like \f(CW\*(C`the L<foo>
+documentation\*(C'\fR, if you want the translated document to read sensibly.
+Instead, write \f(CW\*(C`the L<Foo::Bar|Foo::Bar> documentation\*(C'\fR or
+\&\f(CW\*(C`L<the Foo::Bar documentation|Foo::Bar>\*(C'\fR, to control how the
+link comes out.
+.IP "\(bu" 4
+Going past the 70th column in a verbatim block might be ungracefully
+wrapped by some formatters.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlpodspec, \*(L"PODs: Embedded Documentation\*(R" in perlsyn,
+perlnewmod, perldoc, pod2html, pod2man, podchecker.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Larry Wall, Sean M. Burke