📄 ch26_01.htm
字号:
<html><head><title>Plain Old Documentation (Programming Perl)</title><!-- STYLESHEET --><link rel="stylesheet" type="text/css" href="../style/style1.css"><!-- METADATA --><!--Dublin Core Metadata--><meta name="DC.Creator" content=""><meta name="DC.Date" content=""><meta name="DC.Format" content="text/xml" scheme="MIME"><meta name="DC.Generator" content="XSLT stylesheet, xt by James Clark"><meta name="DC.Identifier" content=""><meta name="DC.Language" content="en-US"><meta name="DC.Publisher" content="O'Reilly & Associates, Inc."><meta name="DC.Source" content="" scheme="ISBN"><meta name="DC.Subject.Keyword" content=""><meta name="DC.Title" content="Plain Old Documentation"><meta name="DC.Type" content="Text.Monograph"></head><body><!-- START OF BODY --><!-- TOP BANNER --><img src="gifs/smbanner.gif" usemap="#banner-map" border="0" alt="Book Home"><map name="banner-map"><AREA SHAPE="RECT" COORDS="0,0,466,71" HREF="index.htm" ALT="Programming Perl"><AREA SHAPE="RECT" COORDS="467,0,514,18" HREF="jobjects/fsearch.htm" ALT="Search this book"></map><!-- TOP NAV BAR --><div class="navbar"><table width="515" border="0"><tr><td align="left" valign="top" width="172"><a href="ch25_10.htm"><img src="../gifs/txtpreva.gif" alt="Previous" border="0"></a></td><td align="center" valign="top" width="171"><a href="part4.htm">Part 4: Perl as Culture</a></td><td align="right" valign="top" width="172"><a href="ch26_02.htm"><img src="../gifs/txtnexta.gif" alt="Next" border="0"></a></td></tr></table></div><hr width="515" align="left"><!-- SECTION BODY --><h1 class="chapter">Chapter 26. Plain Old Documentation</h1><div class="htmltoc"><h4 class="tochead">Contents:</h4><p><a href="ch26_01.htm">Pod in a Nutshell</a><br><a href="ch26_02.htm">Pod Translators and Modules</a><br><a href="ch26_03.htm">Writing Your Own Pod Tools</a><br><a href="ch26_04.htm">Pod Pitfalls</a><br><a href="ch26_05.htm">Documenting Your Perl Programs</a><br></p></div><a name="INDEX-4372"></a><a name="INDEX-4373"></a><p>One of the principles underlying Perl's design is that simple thingsshould be simple, and hard things should be possible. Documentationshould be simple.</p><p>Perl supports a simple text markup format called <em class="emphasis">pod</em> that canstand on its own or be freely intermixed with your source code to createembedded documentation. Pod can be converted to many other formats forprinting or viewing, or you can just read it directly, because it'splain.</p><p>Pod is not as expressive as languages like XML, [LaTeX], <em class="emphasis">troff</em>(1), oreven HTML. This is intentional: we sacrificed that expressiveness forsimplicity and convenience. Some text markup languages make authorswrite more markup than text, which makes writing harder than it has tobe, and reading next to impossible. A good format, like a good moviescore, stays in the background without causing distraction.</p><p>Getting programmers to write documentation is almost as hard as gettingthem to wear ties. Pod was designed to be so easy to write that even aprogrammer could do it--and would. We don't claim that pod issufficient for writing a book, although it was sufficient for writingthis one.</p><h2 class="sect1">26.1. Pod in a Nutshell</h2><a name="INDEX-4374"></a><p>Most document formats require the entire document to be in thatformat. Pod is more forgiving: you can embed pod in any sort offile, relying on <em class="emphasis">pod translators</em> to extract the pod. Some files consist entirely of 100% pure pod. But other files, notablyPerl programs and modules, may contain dollops of pod sprinkledabout wherever the author feels like it. Perl simply skips overthe pod text when parsing the file for execution.</p><p>The Perl lexer knows to begin skipping when, at a spot where it wouldordinarily find a statement, it instead encounters a linebeginning with an equal sign and an identifier, like this:<blockquote><pre class="programlisting">=head1 Here There Be Pods!</pre></blockquote>That text, along with all remaining text up through and including a linebeginning with <tt class="literal">=cut</tt>, will be ignored. This allows you to intermixyour source code and your documentation freely, as in:<blockquote><pre class="programlisting">=item snazzleThe snazzle() function will behave in the most spectacularform that you can possibly imagine, not even exceptingcybernetic pyrotechnics.=cutsub snazzle { my $arg = shift; ....}=item razzleThe razzle() function enables autodidactic epistemology generation.=cutsub razzle { print "Epistemology generation unimplemented on this platform.\n";}</pre></blockquote>For more examples, look at any standard or CPAN Perl module.They're all supposed to come with pod, and nearly all do, except forthe ones that don't.</p><p><a name="INDEX-4375"></a>Since pod is recognized by the Perl lexer and thrown out, you may alsouse an appropriate pod directive to quickly comment out an arbitrarilylarge section of code. Use a <tt class="literal">=for</tt> pod block tocomment out one paragraph, or a<tt class="literal">=begin</tt>/<tt class="literal">=end</tt> pair for a largersection. We'll cover the syntax of those pod directives later.Remember, though, that in both cases, you're still in pod modeafterwards, so you need to <tt class="literal">=cut</tt> back to thecompiler.<blockquote><pre class="programlisting">print "got 1\n";=for commentaryThis paragraph alone is ignored by anyone except themythical "commentary" translator. When it's over, you'restill in pod mode, not program mode.print "got 2\n";=cut# ok, real program againprint "got 3\n";=begin comment print "got 4\n";all of this stuffhere will be ignoredby everyoneprint "got 5\n";=end comment =cutprint "got 6\n";</pre></blockquote>This will print out that it got <tt class="literal">1</tt>, <tt class="literal">3</tt>, and <tt class="literal">6</tt>. Remember thatthese pod directives can't go just anywhere. You have to put themonly where the parser is expecting to see a new statement, not just inthe middle of an expression or at other arbitrary locations.</p><p>From the viewpoint of Perl, all pod markup is thrown out, but fromthe viewpoint of pod translators, it's the code that is thrown out.Pod translators view the remaining text as a sequence of paragraphsseparated by blank lines. All modern pod translators parse pod thesame way, using the standard <tt class="literal">Pod::Parser</tt> module. They differ onlyin their output, since each translator specializes in one outputformat.</p><p>There are three kinds of paragraphs: verbatim paragraphs, commandparagraphs, and prose paragraphs.</p><h3 class="sect2">26.1.1. Verbatim Paragraphs</h3><p>Verbatim paragraphs are used for literal text that you want toappear as is, such as snippets of code. A verbatim paragraph mustbe indented; that is, it must begin with a space or tab character. Thetranslator should reproduce it exactly, typically in a constantwidth font, with tabs assumed to be on eight-column boundaries. Thereare no special formatting escapes, so you can't play font games toitalicize or embolden. A <tt class="literal"><</tt> character means a literal <tt class="literal"><</tt>, and nothing else.</p><h3 class="sect2">26.1.2. Pod Directives</h3><a name="INDEX-4376"></a><a name="INDEX-4377"></a><a name="INDEX-4378"></a><p>All pod directives start with <tt class="literal">=</tt> followed by an identifier. This maybe followed by any amount of arbitrary text that the directive can usehowever it pleases. The only syntactic requirement is that the text must all beone paragraph. Currently recognized directives (sometimes called <em class="emphasis">podcommands</em>) are:</p><dl><dt><b><tt class="literal">=head1</tt></b></dt><dt><b><tt class="literal">=head2</tt></b></dt><dt><b>...</b></dt><dd><p>The <tt class="literal">=head1</tt>, <tt class="literal">=head2</tt>,... directives produce headings at the levelspecified. The rest of the text in the paragraph is treated as theheading description. These are similar to the <tt class="literal">.SH</tt> and <tt class="literal">.SS</tt>section and subsection headers in <em class="emphasis">man</em>(7), or to <tt class="literal"><H1></tt>...<tt class="literal"></H1></tt> and <tt class="literal"><H2></tt>...<tt class="literal"></H2></tt> tags in HTML. In fact, that'sexactly what those translators convert these directives into.</p></dd><dt><b><tt class="literal">=cut</tt></b></dt><dd><p>The <tt class="literal">=cut</tt> directive indicates the end of a stretch of pod. (Theremight be more pod later in the document, but if so it will beintroduced with another pod directive.)</p></dd><dt><b><tt class="literal">=pod</tt></b></dt><dd><p>The <tt class="literal">=pod</tt> directive does nothing beyond telling the compiler to layoff parsing code through the next <tt class="literal">=cut</tt>. It's useful for addinganother paragraph to the document if you're mixing up code and pod alot.</p></dd><dt><b><tt class="literal">=over</tt> <em class="replaceable">NUMBER</em></b></dt><dt><b><tt class="literal">=item</tt> <em class="replaceable">SYMBOL</em></b></dt><dt><b><tt class="literal">=back</tt></b></dt><dd><p>The <tt class="literal">=over</tt> directive starts a section specifically for the generationof a list using the <tt class="literal">=item</tt> directive. At the end of your list, use<tt class="literal">=back</tt> to end it. The <em class="replaceable">NUMBER</em>, if provided, hints to theformatter how many spaces to indent. Some formatters aren't richenough to respect the hint, while others are <em class="emphasis">too</em> rich to respectit, insofar as it's difficult when working with proportional fonts tomake anything line up merely by counting spaces. (However, four spaces is generally construed as enough room for bulletsor numbers.)</p><p>The actual type of the list is indicated by the <em class="replaceable">SYMBOL</em> on theindividual items. Here is a bulleted list:<blockquote><pre class="programlisting">=over 4=item *Mithril armor=item *Elven cloak=back</pre></blockquote>And a numbered list:<blockquote><pre class="programlisting">=over 4=item 1.First, speak "friend".=item 2.Second, enter Moria.=back</pre></blockquote>And a named list:<blockquote><pre class="programlisting">=over 4=item armor()Description of the armor() function=item chant()Description of the chant() function=back</pre></blockquote>You may nest lists of the same or different types, but somebasic rules apply: don't use <tt class="literal">=item</tt> outside an <tt class="literal">=over</tt>/<tt class="literal">=back</tt> block; useat least one <tt class="literal">=item</tt> inside an <tt class="literal">=over</tt>/<tt class="literal">=back</tt> block; and perhapsmost importantly, keep the type of the items consistent within a givenlist. Either use <tt class="literal">=item *</tt> for each item to produce a bulleted list,or <tt class="literal">=item 1.</tt>, <tt class="literal">=item 2.</tt>, and so on to produce numbered list, or use<tt class="literal">=item foo</tt>, <tt class="literal">=item bar</tt>, and so on to produce a named list. If youstart with bullets or numbers, stick with them, since formatters areallowed to use the first <tt class="literal">=item</tt> type to decide how to format thelist.</p><p>As with everything in pod, the result is only as good as thetranslator. Some translators pay attention to the particularnumbers (or letters, or Roman numerals) following the <tt class="literal">=item</tt>, andothers don't. The current <em class="emphasis">pod2html</em> translator, for instance,is quite cavalier: it strips out the sequence indicators entirelywithout looking at them to infer what sequence you're using, thenwraps the entire list inside <tt class="literal"><OL></tt> and <tt class="literal"></OL></tt> tags sothat the browser can display it as an ordered list in HTML. Thisis not to be construed a feature; it may eventually be fixed.</p></dd><dt><b><tt class="literal">=for</tt> <em class="replaceable">TRANSLATOR</em></b></dt><dt><b><tt class="literal">=begin</tt> <em class="replaceable">TRANSLATOR</em></b></dt><dt><b><tt class="literal">=end</tt> <em class="replaceable">TRANSLATOR</em></b></dt><dd><p><tt class="literal">=for</tt>, <tt class="literal">=begin</tt>, and⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -