📄 ch26_04.htm
字号:
<html><head><title>Pod Pitfalls (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="Pod Pitfalls"><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="ch26_03.htm"><img src="../gifs/txtpreva.gif" alt="Previous" border="0"></a></td><td align="center" valign="top" width="171"><a href="ch26_01.htm">Chapter 26: Plain Old Documentation</a></td><td align="right" valign="top" width="172"><a href="ch26_05.htm"><img src="../gifs/txtnexta.gif" alt="Next" border="0"></a></td></tr></table></div><hr width="515" align="left"><!-- SECTION BODY --><h2 class="sect1">26.4. Pod Pitfalls</h2><p>Pod is fairly straightforward, but it's still possible to flub a few things:</p><ul><li><p>It's really easy to leave out the trailing angle bracket.</p></li><li><p>It's really easy to leave out the trailing <tt class="literal">=back</tt> directive.</p></li><li><p>It's easy to accidentally put a blank line into the middle of a long<tt class="literal">=for</tt><em class="replaceable">comment</em> directive. Consider using <tt class="literal">=begin</tt>/<tt class="literal">=end</tt> instead.</p></li><li><p>If you mistype one of the tags on a <tt class="literal">=begin</tt>/<tt class="literal">=end</tt> pair, it'll eatthe rest of your file (podwise). Consider using <tt class="literal">=for</tt> instead.</p></li><li><p>Pod translators require paragraphs to be separated by completely emptylines; that is, by two or more consecutive newline (<tt class="literal">\n</tt>) characters.If you have a line with spaces or tabs on it, it will not be treated as ablank line. This can cause two or more paragraphs to be treated as one.</p></li><li><p>The meaning of a "link" is not defined by pod, and it's up to eachtranslator to decide what to do with it. (If you're starting toget the idea that most decisions have been deferred to the translators,not pod, you're right.) Translators will often add wording arounda <tt class="literal">L<></tt> link, so that "<tt class="literal">L<foo(1)></tt>" becomes "the<em class="emphasis">foo</em>(1) manpage", for example. So you shouldn't write thingslike "<tt class="literal">the L<foo> manpage</tt>" if you want the translateddocument to read sensibly: that would end up saying "the the<em class="emphasis">foo</em>(1) manpage manpage".</p><p>If you need total control of the text used for a link,use the form <tt class="literal">L<show this text|foo></tt> instead.</p></li></ul><p>The standard <em class="emphasis">podchecker</em> program checks pod syntax for errors andwarnings. For example, it checks for unknown pod sequences and forseemingly blank lines containing whitespace. It is still advisable topass your document through two or more different pod translators andproofread the results. Someof the problems you find may be idiosyncrasies of the particulartranslators, which you may or may not wish to work around.</p><p>And, as always, Everything is Subject To Change at the Whim of theRandom Hacker.</p><!-- BOTTOM NAV BAR --><hr width="515" align="left"><div class="navbar"><table width="515" border="0"><tr><td align="left" valign="top" width="172"><a href="ch26_03.htm"><img src="../gifs/txtpreva.gif" alt="Previous" border="0"></a></td><td align="center" valign="top" width="171"><a href="index.htm"><img src="../gifs/txthome.gif" alt="Home" border="0"></a></td><td align="right" valign="top" width="172"><a href="ch26_05.htm"><img src="../gifs/txtnexta.gif" alt="Next" border="0"></a></td></tr><tr><td align="left" valign="top" width="172">26.3. Writing Your Own Pod Tools</td><td align="center" valign="top" width="171"><a href="index/index.htm"><img src="../gifs/index.gif" alt="Book Index" border="0"></a></td><td align="right" valign="top" width="172">26.5. Documenting Your Perl Programs</td></tr></table></div><hr width="515" align="left"><!-- LIBRARY NAV BAR --><img src="../gifs/smnavbar.gif" usemap="#library-map" border="0" alt="Library Navigation Links"><p><font size="-1"><a href="copyrght.htm">Copyright © 2001</a> O'Reilly & Associates. All rights reserved.</font></p><map name="library-map"> <area shape="rect" coords="2,-1,79,99" href="../index.htm"><area shape="rect" coords="84,1,157,108" href="../perlnut/index.htm"><area shape="rect" coords="162,2,248,125" href="../prog/index.htm"><area shape="rect" coords="253,2,326,130" href="../advprog/index.htm"><area shape="rect" coords="332,1,407,112" href="../cookbook/index.htm"><area shape="rect" coords="414,2,523,103" href="../sysadmin/index.htm"></map><!-- END OF BODY --></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -