diff options
Diffstat (limited to 'upstream/archlinux/man1/perlpod.1perl')
| -rw-r--r-- | upstream/archlinux/man1/perlpod.1perl | 831 |
1 files changed, 831 insertions, 0 deletions
diff --git a/upstream/archlinux/man1/perlpod.1perl b/upstream/archlinux/man1/perlpod.1perl new file mode 100644 index 00000000..a340ab8c --- /dev/null +++ b/upstream/archlinux/man1/perlpod.1perl @@ -0,0 +1,831 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (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 +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. 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 1perl" +.TH PERLPOD 1perl 2024-02-11 "perl v5.38.2" "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, HTML, 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 "=", 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\fR""" 4 +.el .IP "\f(CW=head1 \fR\f(CIHeading Text\fR\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\fR""" 4 +.el .IP "\f(CW=head2 \fR\f(CIHeading Text\fR\f(CW\fR" 4 +.IX Item "=head2 Heading Text" +.ie n .IP """=head3 \fIHeading Text\fR""" 4 +.el .IP "\f(CW=head3 \fR\f(CIHeading Text\fR\f(CW\fR" 4 +.IX Item "=head3 Heading Text" +.ie n .IP """=head4 \fIHeading Text\fR""" 4 +.el .IP "\f(CW=head4 \fR\f(CIHeading Text\fR\f(CW\fR" 4 +.IX Item "=head4 Heading Text" +.ie n .IP """=head5 \fIHeading Text\fR""" 4 +.el .IP "\f(CW=head5 \fR\f(CIHeading Text\fR\f(CW\fR" 4 +.IX Item "=head5 Heading Text" +.ie n .IP """=head6 \fIHeading Text\fR""" 4 +.el .IP "\f(CW=head6 \fR\f(CIHeading Text\fR\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 "Object Attributes" 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\fR""" 4 +.el .IP "\f(CW=over \fR\f(CIindentlevel\fR\f(CW\fR" 4 +.IX Xref "=over =item =back over item back" +.IX Item "=over indentlevel" +.PD 0 +.ie n .IP """=item \fIstuff...\fR""" 4 +.el .IP "\f(CW=item \fR\f(CIstuff...\fR\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: "=over" starts +a region specifically for the generation of a list using "=item" +commands, or for indenting (groups of) normal paragraphs. At the end +of your list, use "=back" to end it. The \fIindentlevel\fR option to +"=over" indicates how far over to indent, generally in ems (where +one em is the width of an "M" 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 \fR\f(CIstuff...\fR\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 "=over" ... +"=back" regions: +.RS 4 +.IP \(bu 4 +Don't use "=item"s outside of an "=over" ... "=back" region. +.IP \(bu 4 +The first thing after the "=over" command should be an "=item", unless +there aren't going to be any items at all in this "=over" ... "=back" +region. +.IP \(bu 4 +Don't put "=head\fIn\fR" commands inside an "=over" ... "=back" region. +.IP \(bu 4 +And perhaps most importantly, keep the items consistent: either use +"=item *" for all of them, to produce bullets; or use "=item 1.", +"=item 2.", etc., to produce numbered lists; or use "=item foo", +"=item bar", 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 "=item" 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 "=cut", 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 "=cut" +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 "=pod" 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 "=pod" 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\fR""" 4 +.el .IP "\f(CW=begin \fR\f(CIformatname\fR\f(CW\fR" 4 +.IX Xref "=begin =end =for begin end for" +.IX Item "=begin formatname" +.PD 0 +.ie n .IP """=end \fIformatname\fR""" 4 +.el .IP "\f(CW=end \fR\f(CIformatname\fR\f(CW\fR" 4 +.IX Item "=end formatname" +.ie n .IP """=for \fIformatname\fR \fItext...\fR""" 4 +.el .IP "\f(CW=for \fR\f(CIformatname\fR\f(CW \fR\f(CItext...\fR\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", some paragraphs, and a +command "=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 "=begin html" ... "=end html" +region. +.Sp +That is, with "=for", you can have only one paragraph's worth +of text (i.e., the text in "=foo targetname text..."), but with +"=begin targetname" ... "=end targetname", you can have any amount +of stuff in between. (Note that there still must be a blank line +after the "=begin" command and a blank line before the "=end" +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 "roff", "man", "latex", "tex", "text", and "html". (Some +formatters will treat some of these as synonyms.) +.Sp +A format name of "comment" 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\fR""" 4 +.el .IP "\f(CW=encoding \fR\f(CIencodingname\fR\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 \fR\f(CIencodingname\fR\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 +CP\-1252 versus +UTF\-8 encoding, but they may guess wrong. It's best to be explicit if +you use anything besides strict ASCII. 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. "interior sequences") 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") and parameters +("\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"), programs +("\f(CW\*(C`some systems provide a B<chfn> for that\*(C'\fR"), +emphasis ("\f(CW\*(C`be B<careful!>\*(C'\fR"), and so on +("\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") or some other +form of computerese ("\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 URL. 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 HTML/XML \f(CW\*(C`&\fR\f(CIfoo\fR\f(CW;\*(C'\fR "entity references": +.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 HTML entity name, such as \f(CW\*(C`E<eacute>\*(C'\fR, +meaning the same thing as \f(CW\*(C`é\*(C'\fR in HTML \-\- 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 "0x" means that \fInumber\fR is hex, as in +\&\f(CW\*(C`E<0x201E>\*(C'\fR. A leading "0" 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 "e".) +.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" (for "N<3") you could write +"\f(CW\*(C`NZ<><3\*(C'\fR" (the "Z<>" breaks up the "N" and +the "<" so they can't be considered +the part of a (fictitious) "N<...>" code). +.Sp +Another use is to indicate that \fIstuff\fR in \f(CW\*(C`=item Z<>\fR\f(CIstuff...\fR\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 "plain" way is to use an alternate +set of delimiters that doesn't require a single ">" to be escaped. +Doubled angle brackets ("<<" and ">>") 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, HTML, +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 CPAN. +.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 "=head1" command at the +beginning, and end it with a "=cut" 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 "=head1", many translators wouldn't +have recognized the "=head1" 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 HTML than with writing in Pod, you +can try your hand at writing documentation in simple HTML, and converting +it to Pod with the experimental Pod::HTML2Pod module, +(available in CPAN), and looking at the resulting code. The experimental +Pod::PXML module in CPAN might also be useful. +.IP \(bu 4 +Many older Pod translators require the lines before every Pod +command and after every Pod command (including "=cut"!) 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 "=head2 Functions") 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 "the Foo::Bar manpage", 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, "PODs: Embedded Documentation" in perlsyn, +perlnewmod, perldoc, pod2html, pod2man, podchecker. +.SH AUTHOR +.IX Header "AUTHOR" +Larry Wall, Sean M. Burke |