📄 ch26_02.htm
字号:
<html><head><title>Pod Translators and Modules (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 Translators and Modules"><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_01.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_03.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.2. Pod Translators and Modules</h2><a name="INDEX-4379"></a><a name="INDEX-4380"></a><p>Perl is bundled with several pod translators that convert pod documents (or the embedded pod in other types of documents) intovarious formats. All should be 8-bit clean.</p><dl><dt><b><em class="emphasis">pod2text</em></b></dt><dd><p>Converts pod into text. Normally, this text will be 7-bit ASCII, but it will be 8-bit if it had 8-bit input, or specifically ISO-8859-1 (or Unicode) if you usesequences like <tt class="literal">LE<uacute>thien</tt> for <em class="emphasis">L&#250;thien</em> or<tt class="literal">EE<auml>rendil</tt> for <em class="emphasis">E&#228;rendil</em>.</p><p>If you have a file with pod in it, the easiest (although perhapsnot the prettiest) way to view just the formatted pod would be:<blockquote><pre class="programlisting">% <tt class="userinput"><b>pod2text File.pm | more</b></tt></pre></blockquote>Then again, pod is supposed to be human readable without formatting.</p></dd><dt><b><em class="emphasis">pod2man</em></b></dt><dd><p>Converts pod into Unix manpage format suitable for viewing through<em class="emphasis">nroff</em>(1) or creating typeset copies via <em class="emphasis">troff</em>(1). Forexample:<blockquote><pre class="programlisting">% <tt class="userinput"><b>pod2man File.pm | nroff -man | more</b></tt></pre></blockquote>or<blockquote><pre class="programlisting">% <tt class="userinput"><b>pod2man File.pm | troff -man -Tps -t > tmppage.ps</b></tt>% <tt class="userinput"><b>ghostview tmppage.ps</b></tt></pre></blockquote>and to print:<blockquote><pre class="programlisting">% <tt class="userinput"><b>lpr -Ppostscript tmppage.ps</b></tt></pre></blockquote></p></dd><dt><b><em class="emphasis">pod2html</em></b></dt><dd><p>Converts pod into HTML for use with your favorite viewer:<blockquote><pre class="programlisting">% <tt class="userinput"><b>pod2html File.pm > tmppage.html</b></tt>% <tt class="userinput"><b>lynx tmppage.html</b></tt>% <tt class="userinput"><b>netscape -remote "openURL(file:`pwd`/tmppage.html)"</b></tt></pre></blockquote>That last one is a <em class="emphasis">netscape</em> hack that works if you already have<em class="emphasis">netscape</em> running somewhere to tell that incarnation to load thepage. Otherwise, just call it as you did <em class="emphasis">lynx</em>.</p></dd><dt><b><em class="emphasis">pod2latex</em></b></dt><dd><p>Converts pod into [LaTeX].</p></dd></dl><p>Additional translators are available on CPAN for other formats.</p><p>Translators exhibit different default behaviors depending on theoutput format. For instance, if your pod has a prose paragraphsaying:<blockquote><pre class="programlisting">This is a $variable right here</pre></blockquote>then <em class="emphasis">pod2html</em> will turn that into:<blockquote><pre class="programlisting">This is a <STRONG>$variable</STRONG> right here</pre></blockquote>but <em class="emphasis">pod2text</em> will leave it unadorned, since the dollarshould be enough to let it be read.</p><p>You should write your pod as close to plain text as you possiblycan, with as few explicit markups as you can get away with. It isup to the individual translator to decide how things in your textshould be represented. That means letting the translator figureout how to create paired quotes, how to fill and adjust text, howto find a smaller font for words in all capitals, etc. Since thesewere written to process Perl documentation, most translators<a href="#FOOTNOTE-1">[1]</a> should also recognizeunadorned items like these and render them appropriately:</p><blockquote class="footnote"><a name="FOOTNOTE-1"></a><p>[1]Ifyou're designing a general-purpose pod translator, not one for Perlcode, your criteria may vary.</p></blockquote><ul><li><p><tt class="literal">FILEHANDLE</tt></p></li><li><p><tt class="literal">$scalar</tt></p></li><li><p><tt class="literal">@array</tt></p></li><li><p><tt class="literal">function()</tt></p></li><li><p><tt class="literal">manpage(3r)</tt></p></li><li><p><tt class="literal">somebody@someplace.com</tt></p></li><li><p><tt class="literal">http://foo.com/</tt></p></li></ul><p>Perl also comes with several standard modules for parsing and converting pod, including <tt class="literal">Pod::Checker</tt> (and the associated <em class="emphasis">podchecker</em> utility) for checking the syntaxof pod documents, <tt class="literal">Pod::Find</tt> for finding pod documents in directory trees, and <tt class="literal">Pod::Parser</tt> for creating your own pod utilities.</p><p>Note that pod translators should only look at paragraphs beginningwith a pod directive (this makes parsing easier), whereas the compileractually knows to look for pod escapes even in the middle of aparagraph. This means that the following secret stuff will be ignoredby both the compiler and the translators.<blockquote><pre class="programlisting">$a=3;=secret stuffwarn "Neither POD nor CODE!?"=cut backprint "got $a\n";</pre></blockquote>You probably shouldn't rely upon the <tt class="literal">warn</tt> being podded out forever.Not all pod translators are well-behaved in this regard, and the compiler may someday become pickier.</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_01.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_03.htm"><img src="../gifs/txtnexta.gif" alt="Next" border="0"></a></td></tr><tr><td align="left" valign="top" width="172">26.1. Pod in a Nutshell</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.3. Writing Your Own Pod Tools</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 + -