📄 ch12_17.htm
字号:
<HTML><HEAD><TITLE>Recipe 12.16. Documenting Your Module with Pod (Perl Cookbook)</TITLE><METANAME="DC.title"CONTENT="Perl Cookbook"><METANAME="DC.creator"CONTENT="Tom Christiansen & Nathan Torkington"><METANAME="DC.publisher"CONTENT="O'Reilly & Associates, Inc."><METANAME="DC.date"CONTENT="1999-07-02T01:42:01Z"><METANAME="DC.type"CONTENT="Text.Monograph"><METANAME="DC.format"CONTENT="text/html"SCHEME="MIME"><METANAME="DC.source"CONTENT="1-56592-243-3"SCHEME="ISBN"><METANAME="DC.language"CONTENT="en-US"><METANAME="generator"CONTENT="Jade 1.1/O'Reilly DocBook 3.0 to HTML 4.0"><LINKREV="made"HREF="mailto:online-books@oreilly.com"TITLE="Online Books Comments"><LINKREL="up"HREF="ch12_01.htm"TITLE="12. Packages, Libraries, and Modules"><LINKREL="prev"HREF="ch12_16.htm"TITLE="12.15. Using h2xs to Make a Module with C Code"><LINKREL="next"HREF="ch12_18.htm"TITLE="12.17. Building and Installing a CPAN Module"></HEAD><BODYBGCOLOR="#FFFFFF"><img alt="Book Home" border="0" src="gifs/smbanner.gif" usemap="#banner-map" /><map name="banner-map"><area shape="rect" coords="1,-2,616,66" href="index.htm" alt="Perl Cookbook"><area shape="rect" coords="629,-11,726,25" href="jobjects/fsearch.htm" alt="Search this book" /></map><div class="navbar"><p><TABLEWIDTH="684"BORDER="0"CELLSPACING="0"CELLPADDING="0"><TR><TDALIGN="LEFT"VALIGN="TOP"WIDTH="228"><ACLASS="sect1"HREF="ch12_16.htm"TITLE="12.15. Using h2xs to Make a Module with C Code"><IMGSRC="../gifs/txtpreva.gif"ALT="Previous: 12.15. Using h2xs to Make a Module with C Code"BORDER="0"></A></TD><TDALIGN="CENTER"VALIGN="TOP"WIDTH="228"><B><FONTFACE="ARIEL,HELVETICA,HELV,SANSERIF"SIZE="-1"><ACLASS="chapter"REL="up"HREF="ch12_01.htm"TITLE="12. Packages, Libraries, and Modules"></A></FONT></B></TD><TDALIGN="RIGHT"VALIGN="TOP"WIDTH="228"><ACLASS="sect1"HREF="ch12_18.htm"TITLE="12.17. Building and Installing a CPAN Module"><IMGSRC="../gifs/txtnexta.gif"ALT="Next: 12.17. Building and Installing a CPAN Module"BORDER="0"></A></TD></TR></TABLE></DIV><DIVCLASS="sect1"><H2CLASS="sect1"><ACLASS="title"NAME="ch12-chap12_documenting_0">12.16. Documenting Your Module with Pod</A></H2><DIVCLASS="sect2"><H3CLASS="sect2"><ACLASS="title"NAME="ch12-pgfId-1724">Problem<ACLASS="indexterm"NAME="ch12-idx-1000005295-0"></A><ACLASS="indexterm"NAME="ch12-idx-1000005295-1"></A><ACLASS="indexterm"NAME="ch12-idx-1000005295-2"></A><ACLASS="indexterm"NAME="ch12-idx-1000005295-3"></A></A></H3><PCLASS="para">You need to document your module, but don't know what format to use.</P></DIV><DIVCLASS="sect2"><H3CLASS="sect2"><ACLASS="title"NAME="ch12-pgfId-1730">Solution</A></H3><PCLASS="para">Embed your documentation in the your module file using pod format.</P></DIV><DIVCLASS="sect2"><H3CLASS="sect2"><ACLASS="title"NAME="ch12-pgfId-1736">Discussion</A></H3><PCLASS="para">Pod stands for <ICLASS="firstterm">plain old documentation</I>. It's documentation embedded in your program using a very simple markup format. Programmers are notorious for writing the code first and the documentation never, so pod was designed to make writing documentation so easy that anyone can and will do so. Sometimes this even works.</P><PCLASS="para">When Perl is parsing your source code, a line starting with an equal sign (where a new statement is expected) says to ignore all text until it finds a line beginning with <CODECLASS="literal">=cut</CODE>, after which it will start parsing code again. This lets you mix code and documentation throughout your Perl program or module file. Since it's mostly plain text, type in your documentation as literal text, or nearly so. The translators try to be clever and make output-specific decisions so the programmer doesn't have to specifically format variable names, function calls, etc.</P><PCLASS="para">Along with Perl are shipped several translators that filter generic pod format into specific output styles. These include <EMCLASS="emphasis">pod2man</EM> to change your pods into <EMCLASS="emphasis">troff</EM> for use with the <EMCLASS="emphasis">man</EM> program or for phototypesetting and printing; <EMCLASS="emphasis">pod2html</EM><ACLASS="indexterm"NAME="ch12-idx-1000005308-0"></A><ACLASS="indexterm"NAME="ch12-idx-1000005308-1"></A> for creating web pages (which works even on non-Unix systems); and <EMCLASS="emphasis">pod2text</EM> for plain ASCII. Other translators, like <EMCLASS="emphasis">pod2ipf</EM>, <EMCLASS="emphasis">pod2fm</EM>, <EMCLASS="emphasis">pod2texi</EM>, <EMCLASS="emphasis">pod2latex</EM>, and <EMCLASS="emphasis">pod2ps</EM>, may also be available or can be found on CPAN.</P><PCLASS="para">Many books are written using proprietary word processors with limited scripting capabilities. Not this one! It was written in pod format using common text editors (<EMCLASS="emphasis">vi</EM> for Tom, <EMCLASS="emphasis">emacs</EM> for Nat) before being translated into <EMCLASS="emphasis">troff</EM> for printing during technical review using a special translator written by Larry called <EMCLASS="emphasis">pod2ora</EM>. The final book was produced by converting the pod source files to FrameMaker.</P><PCLASS="para"><ACLASS="indexterm"NAME="ch12-idx-1000005301-0"></A>Although formally documented in <ICLASS="filename">perlpod </I>(1), pod is probably easiest to learn by reading existing module files. If you started making your module using <EMCLASS="emphasis">h2xs</EM>, then you already have the sample pods right there. The <EMCLASS="emphasis">Makefile</EM> knows to convert these into <EMCLASS="emphasis">man</EM> format and install those manpages so others can read them. Alternatively, the <EMCLASS="emphasis">perldoc</EM><ACLASS="indexterm"NAME="ch12-idx-1000005305-0"></A> program can translate pods on the fly using <EMCLASS="emphasis">pod2text</EM>.</P><PCLASS="para">Indented <ACLASS="indexterm"NAME="ch12-idx-1000005302-0"></A>paragraphs will be left verbatim. Other paragraphs will be reformatted to fit the page. Only two kinds of markups are used in pod: paragraphs beginning with an equal sign and one or more words, and interior sequences starting with a single letter followed by text enclosed in angle brackets. Paragraph tags are for headers, list enumeration, and per-translator escapes. Angle bracket sequences are mainly used for font changes, such as selecting bold, italic, or constant-width fonts. Here's an example of an <CODECLASS="literal">=head2</CODE><ACLASS="indexterm"NAME="ch12-idx-1000005303-0"></A> pod directive and various bracket escapes for font changes:</P><PRECLASS="programlisting">=head2 DiscussionIf we had a I<.h> file with function prototype declarations, wecould include that, but since we're writing this one from scratch,we'll use the B<-c> flag to omit building code to translate anyC<#define> symbols. The B<-n> flag says to create a module directorynamed I<FineTime/>, which will have the following files.</PRE><PCLASS="para">The <CODECLASS="literal">=for</CODE><ACLASS="indexterm"NAME="ch12-idx-1000005309-0"></A> escape introduces specific code that is only <EMCLASS="emphasis">for</EM> a particular output filter. This book, for example, written mostly in pod, includes calls to the standard <EMCLASS="emphasis">troff</EM> tools <EMCLASS="emphasis">eqn</EM>, <EMCLASS="emphasis">tbl</EM>, and <EMCLASS="emphasis">pic</EM>. Here's an example of embedded <EMCLASS="emphasis">eqn</EM>. Only translators that produce <EMCLASS="emphasis">troff</EM> will heed this paragraph.</P><PRECLASS="programlisting">=for troff.EQlog sub n (x) = { {log sub e (x)} over {log sub e (n)} }.EN</PRE><PCLASS="para">Pod can also create multiline comments. In C, the sequence <CODECLASS="literal">/*</CODE> <CODECLASS="literal">....</CODE> <CODECLASS="literal">*/</CODE> can comment out many lines of text all at once - there's no need to put a marker on each line. Since Perl ignores pod directives, use these for block commenting. The trick is to find a directive that the pod filters ignore. You could specify that a block is "for later" or "for nobody":</P><PRECLASS="programlisting">=for laternext if 1 .. ?^$?;s/^(.)/>$1/;s/(.{73})........*/$1<SNIP>/;=cut back to perl</PRE><PCLASS="para">or you could use a <CODECLASS="literal">=begin</CODE><ACLASS="indexterm"NAME="ch12-idx-1000005310-0"></A><ACLASS="indexterm"NAME="ch12-idx-1000005310-1"></A> and <CODECLASS="literal">=end</CODE> pair:</P><PRECLASS="programlisting">=begin commentif (!open(FILE, $file)) { unless ($opt_q) { warn "$me: $file: $!\n"; $Errors++; } next FILE;}$total = 0;$matches = 0;=end comment<ACLASS="indexterm"NAME="ch12-idx-1000005297-0"></A><ACLASS="indexterm"NAME="ch12-idx-1000005297-1"></A><ACLASS="indexterm"NAME="ch12-idx-1000005297-2"></A><ACLASS="indexterm"NAME="ch12-idx-1000005297-3"></A></PRE></DIV><DIVCLASS="sect2"><H3CLASS="sect2"><ACLASS="title"NAME="ch12-pgfId-1820">See Also</A></H3><PCLASS="para">The section on "PODs: Embedded Documentation" in <ICLASS="filename">perlsyn </I>(1), as well as <ICLASS="filename">perlpod</I> (1), <ICLASS="filename">pod2man </I>(1), <ICLASS="filename">pod2html </I>(1), and <ICLASS="filename">pod2text </I>(1)</P></DIV></DIV><DIVCLASS="htmlnav"><P></P><HRALIGN="LEFT"WIDTH="684"TITLE="footer"><TABLEWIDTH="684"BORDER="0"CELLSPACING="0"CELLPADDING="0"><TR><TDALIGN="LEFT"VALIGN="TOP"WIDTH="228"><ACLASS="sect1"HREF="ch12_16.htm"TITLE="12.15. Using h2xs to Make a Module with C Code"><IMGSRC="../gifs/txtpreva.gif"ALT="Previous: 12.15. Using h2xs to Make a Module with C Code"BORDER="0"></A></TD><TDALIGN="CENTER"VALIGN="TOP"WIDTH="228"><ACLASS="book"HREF="index.htm"TITLE="Perl Cookbook"><IMGSRC="../gifs/txthome.gif"ALT="Perl Cookbook"BORDER="0"></A></TD><TDALIGN="RIGHT"VALIGN="TOP"WIDTH="228"><ACLASS="sect1"HREF="ch12_18.htm"TITLE="12.17. Building and Installing a CPAN Module"><IMGSRC="../gifs/txtnexta.gif"ALT="Next: 12.17. Building and Installing a CPAN Module"BORDER="0"></A></TD></TR><TR><TDALIGN="LEFT"VALIGN="TOP"WIDTH="228">12.15. Using h2xs to Make a Module with C Code</TD><TDALIGN="CENTER"VALIGN="TOP"WIDTH="228"><ACLASS="index"HREF="index/index.htm"TITLE="Book Index"><IMGSRC="../gifs/index.gif"ALT="Book Index"BORDER="0"></A></TD><TDALIGN="RIGHT"VALIGN="TOP"WIDTH="228">12.17. Building and Installing a CPAN Module</TD></TR></TABLE><HRALIGN="LEFT"WIDTH="684"TITLE="footer"><FONTSIZE="-1"></DIV<!-- LIBRARY NAV BAR --> <img src="../gifs/smnavbar.gif" usemap="#library-map" border="0" alt="Library Navigation Links"><p> <a href="copyrght.htm">Copyright © 2002</a> O'Reilly & Associates. All rights reserved.</font> </p> <map name="library-map"> <area shape="rect" coords="1,0,85,94" href="../index.htm"><area shape="rect" coords="86,1,178,103" href="../lwp/index.htm"><area shape="rect" coords="180,0,265,103" href="../lperl/index.htm"><area shape="rect" coords="267,0,353,105" href="../perlnut/index.htm"><area shape="rect" coords="354,1,446,115" href="../prog/index.htm"><area shape="rect" coords="448,0,526,132" href="../tk/index.htm"><area shape="rect" coords="528,1,615,119" href="../cookbook/index.htm"><area shape="rect" coords="617,0,690,135" href="../pxml/index.htm"></map> </BODY></HTML>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -