ЭЛЕКТРОННАЯ БИБЛИОТЕКА КОАПП |
Сборники Художественной, Технической, Справочной, Английской, Нормативной, Исторической, и др. литературы. |
12.16. Documenting Your Module with PodProblemYou need to document your module, but don't know what format to use. SolutionEmbed your documentation in the your module file using pod format. DiscussionPod stands for plain old documentation. 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. 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 Along with Perl are shipped several translators that filter generic pod format into specific output styles. These include pod2man to change your pods into troff for use with the man program or for phototypesetting and printing; pod2html for creating web pages (which works even on non-Unix systems); and pod2text for plain ASCII. Other translators, like pod2ipf, pod2fm, pod2texi, pod2latex, and pod2ps, may also be available or can be found on CPAN. 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 (vi for Tom, emacs for Nat) before being translated into troff for printing during technical review using a special translator written by Larry called pod2ora. The final book was produced by converting the pod source files to FrameMaker. Although formally documented in perlpod (1), pod is probably easiest to learn by reading existing module files. If you started making your module using h2xs, then you already have the sample pods right there. The Makefile knows to convert these into man format and install those manpages so others can read them. Alternatively, the perldoc program can translate pods on the fly using pod2text. Indented 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 =head2 Discussion If we had a I<.h> file with function prototype declarations, we could include that, but since we're writing this one from scratch, we'll use the B<-c> flag to omit building code to translate any C<#define> symbols. The B<-n> flag says to create a module directory named I<FineTime/>, which will have the following files. The =for troff .EQ log sub n (x) = { {log sub e (x)} over {log sub e (n)} } .EN Pod can also create multiline comments. In C, the sequence =for later next if 1 .. ?^$?; s/^(.)/>$1/; s/(.{73})........*/$1<SNIP>/; =cut back to perl or you could use a =begin comment if (!open(FILE, $file)) { unless ($opt_q) { warn "$me: $file: $!\n"; $Errors++; } next FILE; } $total = 0; $matches = 0; =end comment See AlsoThe section on "PODs: Embedded Documentation" in perlsyn (1), as well as perlpod (1), pod2man (1), pod2html (1), and pod2text (1) |