ch8.htm

《Perl 5 Unreleased》

<H2><A NAME="ThePODFormat"><FONT SIZE=5 COLOR=#FF0000>The POD
Format</FONT></A></H2>
<P>
The Perl plain old documentation (POD) format is designed to be
an easier way to get your Perl files documented. Once you have
documented your files in the POD format, you can use a translator
program to convert your documents into HTML, LaTeX, or <TT><FONT FACE="Courier">man</FONT></TT>
pages. Nothing really prevents you from writing your own translator
program; however, once you convert your documents into HTML, you
can use off-the-shelf products to convert them into other word
processing formats. For example, the Internet Assistant for Microsoft
Word lets you read and convert HTML into a variety of formats.
<P>
The POD format lets you introduce some formatting directives into
your source files. Note that the formatting terms in Table 8.1
all begin with an equal sign (<TT><FONT FACE="Courier">=</FONT></TT>).
<BR>
<P>
<CENTER><B>Table 8.1. Formatting terms for POD files.</B></CENTER>
<CENTER>
<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD WIDTH=181><I>Term</I></TD><TD WIDTH=409><I>Description</I>
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=181><TT><FONT FACE="Courier">=pod</FONT></TT></TD>
<TD WIDTH=409>Begins formatting. The Perl interpreter ignores all text until it sees the <TT><FONT FACE="Courier">=end</FONT></TT> directive. Only POD-related text is found between the <TT><FONT FACE="Courier">=pod</FONT></TT> and <TT><FONT 
FACE="Courier">=end</FONT></TT> directives.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=181><TT><FONT FACE="Courier">=end</FONT></TT></TD>
<TD WIDTH=409>Stops formatting. Only POD-related text is found between the <TT><FONT FACE="Courier">=pod</FONT></TT> and <TT><FONT FACE="Courier">=end</FONT></TT> directives.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=181><TT><FONT FACE="Courier">=head1</FONT></TT>
</TD><TD WIDTH=409>Header level 1.</TD></TR>
<TR VALIGN=TOP><TD WIDTH=181><TT><FONT FACE="Courier">=head2</FONT></TT>
</TD><TD WIDTH=409>Header level 2.</TD></TR>
<TR VALIGN=TOP><TD WIDTH=181><TT><FONT FACE="Courier">=over N</FONT></TT>
</TD><TD WIDTH=409>Starts indentation by moving the text to the right by <TT><FONT FACE="Courier">N</FONT></TT> columns. By convention, the value of <TT><FONT FACE="Courier">N</FONT></TT> is <TT><FONT FACE="Courier">4</FONT></TT> to accommodate the 
translation programs; however, it does not have to be <TT><FONT FACE="Courier">4</FONT></TT>.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=181><TT><FONT FACE="Courier">=back</FONT></TT></TD>
<TD WIDTH=409>Nullifies a previous <TT><FONT FACE="Courier">=over</FONT></TT> directive. An <TT><FONT FACE="Courier">=over/=back</FONT></TT> pair is used to print lists of items.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=181><TT><FONT FACE="Courier">=item C</FONT></TT>
</TD><TD WIDTH=409>Specifies an item to be used between <TT><FONT FACE="Courier">=over/=back</FONT></TT> pairs. <TT><FONT FACE="Courier">C</FONT></TT> is a character or number to use as the bulleted item. There must be at least one <TT><FONT 
FACE="Courier">=item</FONT></TT> in an <TT><FONT FACE="Courier">=over/=back</FONT></TT> list.
</TD></TR>
</TABLE></CENTER>
<P>
<P>
An example here will help. In Listing 8.2, a file called <TT><FONT FACE="Courier">tf.pod</FONT></TT>
is constructed to document the <TT><FONT FACE="Courier">man</FONT></TT>
page in POD format.
<HR>
<BLOCKQUOTE>
<B>Listing 8.2. A sample POD file.<BR>
</B>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">&nbsp;0 #!/usr/bin/perl<BR>
&nbsp;1 =pod<BR>
&nbsp;2 =head1 NAME<BR>
&nbsp;3 tf - Test file attributes<BR>
&nbsp;4<BR>
&nbsp;5 =head1 SYNOPSIS<BR>
&nbsp;6<BR>
&nbsp;7 Usage:<BR>
&nbsp;8<BR>
&nbsp;9&nbsp;&nbsp;tf F&lt;file&gt;<BR>
10<BR>
11&nbsp;&nbsp;tf F&lt;directory&gt;<BR>
12<BR>
13 =head1 DESCRIPTION<BR>
14<BR>
15 The first thing to rememeber is that text is not formatted
in a pod<BR>
16 file but rather in the formatter. Paragraphs are left as they
are.<BR>
17<BR>
18 The B&lt;tf&gt; program (notice how tf bold) works on these
items:<BR>
19<BR>
20 =over 4<BR>
21<BR>
22 =item * Files<BR>
23<BR>
24 Just file names in your directory tree. The file name could
be a<BR>
25 regular file, socket, device or a link.<BR>
26<BR>
27 =item * Directories<BR>
28<BR>
29 Yes, it'll work on directories too.<BR>
30<BR>
31 =back<BR>
32<BR>
33 Ship it!<BR>
34<BR>
35 =head1 BUGS<BR>
36<BR>
37 Remember the note about features?<BR>
38<BR>
39 =head1 Header 1<BR>
40<BR>
41 This is a header 1<BR>
42<BR>
43 =head2 Header 2<BR>
44<BR>
45 This is header 2 in I&lt;Italics&gt;.<BR>
46<BR>
47 =head2&nbsp;&nbsp;Another Header 2<BR>
48<BR>
49 This is header 2 in B&lt;BOLD&gt;.<BR>
50<BR>
51 Another list with non-bulleted items.<BR>
52<BR>
53 =over 5<BR>
54<BR>
55 =item First<BR>
56<BR>
57 This is the First item.<BR>
58<BR>
59 =item Second<BR>
60<BR>
61 This is the Second item.<BR>
62<BR>
63 =item Third<BR>
64<BR>
65 This is the Third item.<BR>
66<BR>
67 =back<BR>
68<BR>
69 =cut<BR>
70&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...
<I>the rest of the script will be here</I> ...</FONT></TT>
</BLOCKQUOTE>
<HR>
<P>
Line 1 begins the POD portion, and line 69 is where POD processing
is cut. Line 70 is where the executable code would start; that
is, right after the line that contains the <TT><FONT FACE="Courier">&quot;=cut&quot;</FONT></TT>
tag. Line 0 is present if this is an executable script and absent
if this is only a Perl file. All the tags are separated by a blank
line, but this is really unnecessary. In my opinion, the POD documentation
is more readable if the tags are separated by blank lines.
<P>
Now, look at line 18 in Listing 8.2. The <TT><FONT FACE="Courier">B&lt;<I>text</I>&gt;</FONT></TT>
tag is used here to place <I>text</I> in bold typeface. Several
tags exist for formatting text. Table 8.2 lists these tags.<P>
<CENTER><B>Table 8.2. Tags for formatting text.</B></CENTER>
<CENTER>
<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD WIDTH=148><I>Tag</I></TD><TD WIDTH=404><I>Description</I>
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=148><TT><FONT FACE="Courier">B&lt;text&gt;</FONT></TT>
</TD><TD WIDTH=404>The <TT><FONT FACE="Courier">text</FONT></TT> is placed in bold.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=148><TT><FONT FACE="Courier">I&lt;text&gt;</FONT></TT>
</TD><TD WIDTH=404>The <TT><FONT FACE="Courier">text</FONT></TT> is placed in italics.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=148><TT><FONT FACE="Courier">S&lt;text&gt;</FONT></TT>
</TD><TD WIDTH=404>The <TT><FONT FACE="Courier">text</FONT></TT> contains non-breaking spaces.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=148><TT><FONT FACE="Courier">C&lt;code&gt;</FONT></TT>
</TD><TD WIDTH=404>A literal code for the formatter.</TD></TR>
<TR VALIGN=TOP><TD WIDTH=148><TT><FONT FACE="Courier">L&lt;name&gt;</FONT></TT>
</TD><TD WIDTH=404>A link to a <TT><FONT FACE="Courier">man</FONT></TT> page referred to by <TT><FONT FACE="Courier">name</FONT></TT>.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=148><TT><FONT FACE="Courier">L&lt;name/sec&gt;</FONT></TT>
</TD><TD WIDTH=404>A link to a section <TT><FONT FACE="Courier">sec</FONT></TT> in a <TT><FONT FACE="Courier">man</FONT></TT> page referred to by <TT><FONT FACE="Courier">name</FONT></TT>.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=148><TT><FONT FACE="Courier">L&lt;name/&quot;sec&quot;&gt;</FONT></TT>
</TD><TD WIDTH=404>A link to a section in this <TT><FONT FACE="Courier">man</FONT></TT> page.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=148><TT><FONT FACE="Courier">L&lt;&quot;sec&quot;&gt;</FONT></TT>
</TD><TD WIDTH=404>A link to a section in this <TT><FONT FACE="Courier">man</FONT></TT> page.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=148><TT><FONT FACE="Courier">F&lt;file&gt;</FONT></TT>
</TD><TD WIDTH=404>A file name.</TD></TR>
<TR VALIGN=TOP><TD WIDTH=148><TT><FONT FACE="Courier">X&lt;index&gt;</FONT></TT>
</TD><TD WIDTH=404>An indexed entry.</TD></TR>
<TR VALIGN=TOP><TD WIDTH=148><TT><FONT FACE="Courier">Z&lt;&gt;</FONT></TT>
</TD><TD WIDTH=404>A zero width character.</TD></TR>
</TABLE></CENTER>
<P>
<P>
In most cases you only wind up using the <TT><FONT FACE="Courier">B&lt;&gt;</FONT></TT>
and <TT><FONT FACE="Courier">I&lt;&gt;</FONT></TT> tags, as you'll
see in the documentation that comes with Perl. Refer to Listing
18.2 to see how some of the formatting codes are used in POD files.
<P>
The POD information in a file can be included just about anywhere
in a source file, although it's best to place this information
either at the top or bottom of the source file. As long as you
keep your <TT><FONT FACE="Courier">=pod</FONT></TT>, <TT><FONT FACE="Courier">=cut</FONT></TT>,
and <TT><FONT FACE="Courier">=over/back</FONT></TT> pairs matched,
you shouldn't run into any problems.
<H2><A NAME="TranslatingPODintoOtherFormats"><FONT SIZE=5 COLOR=#FF0000>Translating
POD into Other Formats</FONT></A></H2>
<P>
Three filters exist that convert POD formatted documents into
three different formats. Here's a list of these filters:<P>
<CENTER>
<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD WIDTH=109><I>Filter</I></TD><TD WIDTH=287><I>Description</I>
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=109><TT><FONT FACE="Courier">pod2html</FONT></TT>
</TD><TD WIDTH=287>Used to convert POD files to HTML files</TD>
</TR>
<TR VALIGN=TOP><TD WIDTH=109><TT><FONT FACE="Courier">pod2man</FONT></TT>
</TD><TD WIDTH=287>Used to convert POD files to <TT><FONT FACE="Courier">man</FONT></TT> pages
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=109><TT><FONT FACE="Courier">pod2latex</FONT></TT>
</TD><TD WIDTH=287>Used to convert POD files to LaTeX files</TD>
</TR>
</TABLE></CENTER>
<P>
<P>
To run these programs, simply type the command and the filename.
For example, to generate HTML files from the POD file shown in
Listing 18.2, run this command:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">pod2html gnat.pod</FONT></TT>
</BLOCKQUOTE>
<P>
You'll find that running the <TT><FONT FACE="Courier">pod2html</FONT></TT>
program on <TT><FONT FACE="Courier">gnat.pod</FONT></TT> created
a file called <TT><FONT FACE="Courier">gnat.html</FONT></TT> in
your directory. The output for Listing 18.2 is shown in Figure
18.2.
<P>
<A HREF="f8-2.gif" tppabs="http://www.mcp.com/815097600/0-672/0-672-30891-6/f8-2.gif" ><B>Figure 8.2 : </B><I>HTML output from pod2html </I></A>
<H2><A NAME="Summary"><FONT SIZE=5 COLOR=#FF0000>Summary</FONT></A>
</H2>
<P>
This chapter covered two ways of documenting Perl files: one using
<TT><FONT FACE="Courier">man</FONT></TT> pages and the other using
POD documentation. <TT><FONT FACE="Courier">man</FONT></TT> pages
can be embedded in the source file, but they require the use of
<TT><FONT FACE="Courier">nroff</FONT></TT> with the <TT><FONT FACE="Courier">man</FONT></TT>
package. POD files are more generic in that you can use translators
to convert from POD to one of three known formats: HTML, <TT><FONT FACE="Courier">man</FONT></TT>,
or LaTeX. In extreme cases, you can even write your own Perl script
to decode the POD format and write files in your own format. If
you really need to do something elaborate, you might want to consider
taking the formatted HTML output from a <TT><FONT FACE="Courier">pod2html</FONT></TT>
program and placing the output in a word processor, such as Microsoft
Word, to edit the HTML file directly.
<P>
<HR WIDTH="100%"></P>

<CENTER><P><A HREF="ch7.htm" tppabs="http://www.mcp.com/815097600/0-672/0-672-30891-6/ch7.htm"><IMG SRC="pc.gif" tppabs="http://www.mcp.com/815097600/0-672/0-672-30891-6/pc.gif" BORDER=0 HEIGHT=88 WIDTH=140></A><A HREF="#CONTENTS"><IMG SRC="cc.gif" tppabs="http://www.mcp.com/815097600/0-672/0-672-30891-6/cc.gif" BORDER=0 HEIGHT=88 WIDTH=140></A><A HREF="index.htm" tppabs="http://www.mcp.com/815097600/0-672/0-672-30891-6/index.htm"><IMG SRC="hb.gif" tppabs="http://www.mcp.com/815097600/0-672/0-672-30891-6/hb.gif" BORDER=0 HEIGHT=88 WIDTH=140></A><A HREF="ch9.htm" tppabs="http://www.mcp.com/815097600/0-672/0-672-30891-6/ch9.htm"><IMG 
SRC="nc.gif" tppabs="http://www.mcp.com/815097600/0-672/0-672-30891-6/nc.gif" BORDER=0 HEIGHT=88 WIDTH=140></A></P></CENTER>

<P>
<HR WIDTH="100%"></P>

</BODY>
</HTML>