📄 ch04_13.htm
字号:
<html><head><title>Pod (Perl in a Nutshell, 2nd Edition)</title><link rel="stylesheet" type="text/css" href="../style/style1.css" /><meta name="DC.Creator" content="Stephen Spainhour" /><meta name="DC.Format" content="text/xml" scheme="MIME" /><meta name="DC.Language" content="en-US" /><meta name="DC.Publisher" content="O'Reilly & Associates, Inc." /><meta name="DC.Source" scheme="ISBN" content="0596002416L" /><meta name="DC.Subject.Keyword" content="stuff" /><meta name="DC.Title" content="Perl in a Nutshell, 2nd Edition" /><meta name="DC.Type" content="Text.Monograph" /></head><body bgcolor="#ffffff"><img src="gifs/smbanner.gif" usemap="#banner-map" border="0" alt="Book Home" /><map name="banner-map"><area shape="rect" coords="1,-2,616,66" href="index.htm" alt="Java and XSLT" /><area shape="rect" coords="629,-11,726,25" href="jobjects/fsearch.htm" alt="Search this book" /></map><div class="navbar"><table width="684" border="0"><tr><td align="left" valign="top" width="228"><a href="ch04_12.htm"><img src="../gifs/txtpreva.gif" alt="Previous" border="0" /></a></td><td align="center" valign="top" width="228" /><td align="right" valign="top" width="228"><a href="ch05_01.htm"><img src="../gifs/txtnexta.gif" alt="Next" border="0" /></a></td></tr></table></div><h2 class="sect1">4.13. Pod</h2><p><a name="INDEX-818" /><a name="INDEX-819" /><a name="INDEX-820" />Pod is a simple, but surprisinglycapable, text formatter that uses tags to tell a translator how toformat the text. The tags serve several purposes:</p><ul><li><p>They tell the formatter how to lay out text on the page.</p></li><li><p>They provide font and cross-reference information.</p></li><li><p>They start and stop parsing of code.</p></li></ul><p>The last item is indicative of one of pod's mostuseful features—that it can be intermixed with Perl code. Whileit can be difficult to force yourself to go back and writedocumentation for your code after the fact, with Perl you can simplyintermingle the documentation with the code, and do it all at once.It also lets you use the same text as both code documentation anduser documentation.</p><p>A pod translator reads a file paragraph by paragraph, ignoring textthat isn't pod, and converting it to the properformat. Paragraphs are separated by blank lines (not just bynewlines). The various translators recognize three kinds ofparagraphs:</p><dl><dt><i><em class="emphasis">Command</em></i></dt><dd><a name="INDEX-821" /><a name="INDEX-822" />Commands begin with<tt class="literal">=</tt>, followed immediately by the command identifier:</p><blockquote><pre class="code">=cut</pre></blockquote><p>They can also be followed by text: </p><blockquote><pre class="code">=head2 <em class="replaceable"><tt>Second-level head</tt></em></pre></blockquote><p>A blank line signals the end of the command.</p></dd><dt><i><em class="emphasis">Text</em></i></dt><dd>A paragraph consisting of a block of text, generally filled andpossibly justified, depending on the translator. For example, acommand such as <tt class="literal">=head2</tt> will probably be followedwith a text paragraph:</p><blockquote><pre class="code">=head2 PodPod is a simple, but surprisingly capable, text formatter that usestags to tell a translator how to format the text.</pre></blockquote></dd><dt><i><em class="emphasis">Verbatim</em></i></dt><dd><a name="INDEX-823" />Aparagraph that is to be reproduced as is, with no filling orjustification. To create a verbatim paragraph, indent each line oftext with at least one space:</p><blockquote><pre class="code">Don't fill this paragraph. It's supposed to look exactly like this on the page.There are blanks at the beginning of each line.</pre></blockquote></dd></dl><a name="perlnut2-CHP-4-SECT-13.1" /><div class="sect2"><h3 class="sect2">4.13.1. Paragraph Tags</h3><p><a name="INDEX-824" />Thefollowing paragraph tags are recognized as valid pod commands.</p><a name="INDEX-825" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>=back</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>=back</pre><p><a name="INDEX-825" />Moves left margin back to where it wasbefore the last <tt class="literal">=over</tt>. Ends the innermost<tt class="literal">=over/=back</tt> block of indented text. If there aremultiple levels of indent, one <tt class="literal">=back</tt> is needed foreach level.</p></div><a name="INDEX-826" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>=begin</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>=begin <em class="replaceable">format</em></pre><p><a name="INDEX-826" />Starts a block of text that willbe passed directly to a particular formatter rather than beingtreated as pod. For example:</p><blockquote><pre class="code">=begin html</pre></blockquote><p>A <tt class="literal">=begin/=end</tt> block is like<tt class="literal">=for</tt> except that it doesn'tnecessarily apply to a single paragraph.</p></div><a name="INDEX-827" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>=cut</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>=cut</pre><p><a name="INDEX-827" />Indicates the end of pod text. Tells thecompiler that there isn't anymore pod (for now) andto start compiling again.</p></div><a name="INDEX-828" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>=end</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>=end</pre><p><a name="INDEX-828" />Ends a <tt class="literal">=begin</tt> block.Tells the translator to treat what follows as pod again.</p></div><a name="INDEX-829" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>=for</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>=for <em class="replaceable">format</em></pre><p><a name="INDEX-829" />Indicates a format change, for the nextparagraph only.</p></div><a name="INDEX-830" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>=head1</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>=head1 <em class="replaceable">text</em></pre><p><a name="INDEX-830" /><em class="replaceable">text</em> followingthe tag is formatted as a top-level heading. Generally all uppercase.</p></div><a name="INDEX-831" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>=head2</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>=head2 <em class="replaceable">text</em></pre><p><em class="replaceable">text</em><a name="INDEX-831" /> followingthe tag is formatted as a second-level heading.</p></div><a name="INDEX-832" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>=item</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>=item <em class="replaceable">text</em></pre><p><a name="INDEX-832" />Starts a list. Lists should always beinside an <tt class="literal">over/back</tt> block. Many translators usethe value of <em class="replaceable"><tt>text</tt></em> on the first<tt class="literal">=item</tt> to determine the type of list:</p><dl><dt><b><tt class="literal">=item *</tt></b></dt><dd>Bulleted list. An asterisk (<tt class="literal">*</tt>) is commonly usedfor the bullet, but can be replaced with any other single character.Followed by a blank line and then the text of the bulleted item:</p><blockquote><pre class="code">=item *This is the text of the bullet.</pre></blockquote></dd><dt><b><tt class="literal">=item</tt> <em class="replaceable">n</em></b></dt><dd>Numbered list. Replace <em class="replaceable"><tt>n</tt></em> with<tt class="literal">1</tt> on the first item, <tt class="literal">2</tt> on thesecond, and so on. Pod does not automatically generate the numbers.</p></dd><dt><b><tt class="literal">=item</tt> <em class="replaceable">text</em></b></dt><dd>Definition list. Formats <em class="replaceable"><tt>text</tt></em> as the termand the following paragraph as the body of the list item. Forexample:</p><blockquote><pre class="code">=item <HTML>Indicates the beginning of an HTML file</pre></blockquote><p>The exact appearance of the output depends on the translator you use,but it will look pretty much like this:</p><blockquote><pre class="code"><HTML> Indicates the beginning of an HTML file</pre></blockquote></dd></dl></div><a name="INDEX-833" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>=over</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>=over <em class="replaceable">n</em></pre><p><a name="INDEX-833" />Specifies the beginning of a list, inwhich <em class="replaceable"><tt>n</tt></em> indicates the depth of the indent.For example, <tt class="literal">=over 4</tt> will indent four spaces.Another <tt class="literal">=over</tt> before a <tt class="literal">=back</tt>creates nested lists. The <tt class="literal">=over</tt> tag should befollowed by at least one <tt class="literal">=item</tt>.</p></div><a name="INDEX-834" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>=pod</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>=pod</pre><p><a name="INDEX-834" />Indicates the beginning of pod text. Atranslator starts to pay attention when it sees this tag, and thecompiler ignores everything from there to the next<tt class="literal">=cut</tt>.</p></div></div><a name="perlnut2-CHP-4-SECT-13.2" /><div class="sect2"><h3 class="sect2">4.13.2. Interior Sequences</h3><p><a name="INDEX-835" /><a name="INDEX-836" /><a name="INDEX-837" /><a name="INDEX-838" /><a name="INDEX-839" /><a name="INDEX-840" /><a name="INDEX-841" />In addition to the paragraph tags, pod hasa set of tags that apply within text, either in a paragraph or acommand. These interior sequences are:</p><a name="ch04-29-fm2xml" /><table border="1" cellpadding="3"><tr><th><p>Sequence</p></th><th></th><th><p>Function</p></th><th></th></tr><tr><td><p><tt class="literal">B<</tt><em class="replaceable"><tt>text</tt></em><tt class="literal">></tt></p></td><td> </td><td><p>Makes text bold, usually for switches and programs</p></td></tr><tr><td><p><tt class="literal">C<</tt><em class="replaceable"><tt>code</tt></em><tt class="literal">></tt></p></td><td> </td><td><p>Literal code</p></td></tr><tr><td><p><tt class="literal">E<</tt><em class="replaceable"><tt>escape</tt></em><tt class="literal">></tt></p></td><td> </td><td><p>Named character:</p></td></tr><tr><td> </td><td><p><tt class="literal">E<gt></tt></p></td><td><p>Literal <tt class="literal">></tt></p></td></tr><tr><td> </td><td><p><tt class="literal">E<lt></tt></p></td><td><p>Literal <tt class="literal"><</tt></p></td></tr><tr><td> </td><td><p><tt class="literal">E<</tt><em class="replaceable"><tt>html</tt></em><tt class="literal">></tt></p></td><td><p>Non-numeric HTML entity</p></td></tr><tr><td> </td><td><p><tt class="literal">E<</tt><em class="replaceable"><tt>n</tt></em><tt class="literal">></tt></p></td><td><p>Character number <em class="replaceable"><tt>n</tt></em>, usually an ASCIIcharacter</p></td></tr><tr><td><p><tt class="literal">F<</tt><em class="replaceable"><tt>file</tt></em><tt class="literal">></tt></p></td><td> </td><td><p>Filename</p></td></tr><tr><td><p><tt class="literal">I<</tt><em class="replaceable"><tt>text</tt></em><tt class="literal">></tt></p></td><td> </td><td><p>Italicize <em class="replaceable"><tt>text</tt></em>, usually for emphasis orvariables</p></td></tr><tr><td><p><tt class="literal">L<</tt><em class="replaceable"><tt>name</tt></em><tt class="literal">></tt></p></td><td> </td><td><p>Link (cross-reference) to <em class="replaceable"><tt>name</tt></em>:</p></td></tr><tr><td> </td><td><p><tt class="literal">L<</tt><em class="replaceable"><tt>name</tt></em><tt class="literal">></tt></p></td><td><p>Manpage</p></td></tr><tr><td> </td><td><p><tt class="literal">L<</tt><em class="replaceable"><tt>name</em><tt class="literal">/</tt><em class="replaceable">ident</tt></em><tt class="literal">></tt></p></td><td><p>Item in a manpage</p></td></tr><tr><td> </td><td><p><tt class="literal">L<</tt><em class="replaceable"><tt>name</em><tt class="literal">/"</tt><em class="replaceable">sec</tt></em><tt class="literal">"></tt></p></td><td><p>Section in another manpage</p></td></tr><tr><td> </td><td><p><tt class="literal">L<"</tt><em class="replaceable"><tt>sec</tt></em><tt class="literal">"></tt></p></td><td><p>Section in this manpage; quotes are optional</p></td></tr><tr><td> </td><td><p><tt class="literal">L</"</tt><em class="replaceable"><tt>sec</tt></em><tt class="literal">"></tt></p></td><td><p>Same as<tt class="literal">L<"</tt><em class="replaceable"><tt>sec</tt></em><tt class="literal">"></tt></p></td></tr><tr><td><p><tt class="literal">S<</tt><em class="replaceable"><tt>text</tt></em><tt class="literal">></tt></p></td><td> </td><td><p><em class="replaceable"><tt>text</tt></em> has non-breaking spaces</p></td></tr><tr><td><p><tt class="literal">X<</tt><em class="replaceable"><tt>index</tt></em><tt class="literal">></tt></p></td><td> </td><td><p>Index entry</p></td></tr><tr><td><p><tt class="literal">Z<></tt></p></td><td> </td><td><p>Zero-width character</p></td></tr></table><p></div><a name="perlnut2-CHP-4-SECT-13.3" /><div class="sect2"><h3 class="sect2">4.13.3. Pod Utilities</h3><p><a name="INDEX-842" /><a name="INDEX-843" /><a name="INDEX-844" />As mentioned earlier, a number of utilityprograms have been written to convert files from pod to a variety ofoutput formats. Some of the utilities are described here,particularly those that are part of the Perl distribution. Otherprograms are available on CPAN.</p><a name="INDEX-845" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>perldoc</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>perldoc [<em class="replaceable">options</em>] <em class="replaceable">docname</em></pre><p><a name="INDEX-845" />Formats anddisplays Perl pod documentation. Extracts the documentation from podformat and displays it. For all options except<em class="emphasis">-f</em>, <em class="replaceable"><tt>docname</tt></em> is thename of the manpage, module, or program containing pod to bedisplayed. For <em class="emphasis">-f</em>, it's thename of a built-in Perl function to be displayed.</p><h4 class="refsect1">Options</h4><dl><dt><i><em class="emphasis">-f function</em></i></dt><dd>Formats and displays documentation for the specified Perl function.</p></dd>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -