📄 ch8.htm
字号:
<HTML>
<HEAD>
<TITLE>Chapter 8 -- Documenting Perl Scripts</FONT><TT><FONT FACE="Courier">Perl/Tk</FONT></TT></TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.0b5aGold (WinNT; I) [Netscape]">
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#CE2910">
<H1><FONT COLOR=#FF0000>Chapter 8
</FONT></H1>
<H1><B><FONT SIZE=5 COLOR=#FF0000>Documenting Perl Scripts </FONT><TT><FONT FACE="Courier" COLOR=#FF0000>Perl/Tk</FONT></TT></FONT></B>
</H1>
<P>
<HR WIDTH="100%"></P>
<P>
<H3 ALIGN=CENTER><FONT COLOR="#000000"><FONT SIZE=+2>CONTENTS<A NAME="CONTENTS"></A>
</FONT></FONT></H3>
<UL>
<LI><A HREF="#EmbeddingmanPages" >Embedding man Pages</A>
<LI><A HREF="#ThePODFormat" >The POD Format</A>
<LI><A HREF="#TranslatingPODintoOtherFormats" >Translating POD into Other Formats</A>
<LI><A HREF="#Summary" >Summary</A>
</UL>
<HR>
<P>
This chapter introduces you to the types of documentation available
for Perl scripts. I cover two documentation methods: embedding
<TT><FONT FACE="Courier">nroff</FONT></TT> pages and using the
plain old documentation (POD) format. Documenting your Perl scripts
is easy and standardized enough in Perl 5 to allow for generating
LaTex, HTML, and <TT><FONT FACE="Courier">man</FONT></TT> pages
from the source files.
<H2><A NAME="EmbeddingmanPages"><FONT SIZE=5 COLOR=#FF0000>Embedding
</FONT><TT><FONT SIZE=5 COLOR=#FF0000 FACE="Courier">man</FONT></TT><FONT SIZE=5 COLOR=#FF0000>
Pages</FONT></A></H2>
<P>
Generally, you have to keep the software documentation for your
program in a file separate from the source code. This separate
storage forces you to remember two different files for every change
you make: one for the source file and the other for the documentation.
The consequence is that the source file is almost never in sync
with the documentation.
<P>
Since Perl 4, you can keep your documentation and code in the
same source file. The way to do this is to use the <TT><FONT FACE="Courier">nroff</FONT></TT>
tags in the <TT><FONT FACE="Courier">man</FONT></TT> package and
embed these codes in a Perl source file. This trick works only
if you are using the<B> </B><TT><FONT FACE="Courier">-man</FONT></TT>
package with <TT><FONT FACE="Courier">nroff</FONT></TT>; therefore,
if your system is not UNIX-like or if you abhor <TT><FONT FACE="Courier">nroff</FONT></TT>,
you should skip ahead to the next section, which is on POD formats.
<P>
The way to do this embedding was documented initially in the book
<I>Programming Perl</I> by Larry Wall and Randall Schwartz, published
by O'Reilly & Associates. Wall has also written for this book
a shell script, called <TT><FONT FACE="Courier">wrapman</FONT></TT>,
that performs embedding as a template. However, it will be instructive
to see how the method works.
<P>
The trick in embedding <TT><FONT FACE="Courier">man</FONT></TT>
pages is to use the <TT><FONT FACE="Courier">.di</FONT></TT> and
<TT><FONT FACE="Courier">.ig</FONT></TT> commands in <TT><FONT FACE="Courier">nroff</FONT></TT>.
The <TT><FONT FACE="Courier">.di</FONT></TT> command in <TT><FONT FACE="Courier">nroff</FONT></TT>
"diverts" text into an <TT><FONT FACE="Courier">nroff</FONT></TT>
macro. It works this way: There are two <TT><FONT FACE="Courier">.di</FONT></TT>
tags; one is defined at the top of the text to be diverted as
<TT><FONT FACE="Courier">.di X</FONT></TT>, and the other <TT><FONT FACE="Courier">.di</FONT></TT>
tag (with no arguments) at the bottom of the text. The first <TT><FONT FACE="Courier">.di
X</FONT></TT> asks <TT><FONT FACE="Courier">nroff</FONT></TT>
to divert all the text into macro <TT><FONT FACE="Courier">X</FONT></TT>
until it sees <TT><FONT FACE="Courier">.di</FONT></TT> at the
start of a line. The <TT><FONT FACE="Courier">.ig</FONT></TT>
macro in <TT><FONT FACE="Courier">nroff</FONT></TT> works the
same way as <TT><FONT FACE="Courier">.di</FONT></TT>, but it forces
<TT><FONT FACE="Courier">nroff</FONT></TT> to ignore all text
between <TT><FONT FACE="Courier">.ig X</FONT></TT> and any other
<TT><FONT FACE="Courier">.X</FONT></TT> tag. Now comes the important
part: The double quotes (<TT><FONT FACE="Courier">""</FONT></TT>)
in both <TT><FONT FACE="Courier">.ig</FONT></TT> and <TT><FONT FACE="Courier">.di</FONT></TT>
commands can be replaced with a single quote to get <TT><FONT FACE="Courier">'ig</FONT></TT>
and <TT><FONT FACE="Courier">'di</FONT></TT> commands that do
the same thing as the <TT><FONT FACE="Courier">.ig</FONT></TT>
and <TT><FONT FACE="Courier">.di</FONT></TT> commands, except
that text output is suppressed until the macro call is over. Note
also that the single quote is, interestingly enough, also the
defining character for a string in Perl.
<P>
Another point to remember is that Perl stops interpreting your
script when it sees an <TT><FONT FACE="Courier">_ _END_ _</FONT></TT>
token. This stopping feature can be used to your advantage because
you can put all of your text after the <TT><FONT FACE="Courier">_ _END_ _</FONT></TT>
token.
<P>
So if you were to add the following two statements to the start
of a Perl script, your script would still run:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">'di';<BR>
'ig00 ';</FONT></TT>
</BLOCKQUOTE>
<P>
As far as Perl is concerned, these two lines are simply strings.
For <TT><FONT FACE="Courier">nroff</FONT></TT>, the two lines
are interpreted as calls to macros. The first line uses the <TT><FONT FACE="Courier">'di';</FONT></TT>
macro to divert text until it sees <TT><FONT FACE="Courier">'di</FONT></TT>
on a line by itself. The next line <TT><FONT FACE="Courier">'ig00
';</FONT></TT> diverts text until it sees <TT><FONT FACE="Courier">.00</FONT></TT>
on a line by itself.
<P>
Now, at the end of the source file, place the following lines,
which are valid in Perl and in <TT><FONT FACE="Courier">nroff</FONT></TT>:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">.00 #
Terminates the .ig processing<BR>
'di #
Terminates the 'di X processing.<BR>
.nr nl 0-1 # Sets the page to the start of the
document<BR>
.nr % 0 # Sets the page count
back to zero<BR>
'; _ _END_ _ # Terminates the 'di macro
and all Perl interpreting</FONT></TT>
</BLOCKQUOTE>
<P>
<TT><FONT FACE="Courier">'di</FONT></TT> and <TT><FONT FACE="Courier">';</FONT></TT>
really do define a Perl string between single quotes. <TT><FONT FACE="Courier">_ _END_ _</FONT></TT>
stops Perl from processing further, and <TT><FONT FACE="Courier">.00</FONT></TT>
is conveniently ignored by Perl.
<P>
Now you can place the <TT><FONT FACE="Courier">man</FONT></TT>
page contents after the line containing the <TT><FONT FACE="Courier">_ _END_ _</FONT></TT>
statement. Look at the sample listing shown in Listing 8.1. The
output from this listing is shown in Figure 8.1.
<P>
<A HREF="f8-1.gif" tppabs="http://www.mcp.com/815097600/0-672/0-672-30891-6/f8-1.gif" ><B>Figure 8.1 : </B><I>man page output</I></A><I>
<A HREF="f8-1.gif" tppabs="http://www.mcp.com/815097600/0-672/0-672-30891-6/f8-1.gif" ></A></I>
<HR>
<BLOCKQUOTE>
<B>Listing 8.1. Embedding </B><TT><B><FONT FACE="Courier">man</FONT></B></TT><B>
pages in Perl.<BR>
</B>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier"> 1 #!/usr/bin/perl<BR>
2 'di ';<BR>
3 'ig 00 ';<BR>
4<BR>
5 print "$#ARGV \n"
;<BR>
6 if ( $#ARGV ) {<BR>
7 print
"\n Usage: $0 file \n";<BR>
8 exit 0;<BR>
9 }
<BR>
10 $name = $ARGV[0];<BR>
11<BR>
12 print "\nTesting flags for $name \n";<BR>
13 print "\n========== Effective User ID tests ";<BR>
14 print "\n is readable" if ( -r $name);<BR>
15 print "\n is writeable" if ( -w $name);<BR>
16 print "\n is executeable" if ( -x $name);<BR>
17 print "\n is owned " if ( -o $name);<BR>
18 print "\n========== Real User ID tests ";<BR>
19 print "\n is readable" if ( -r $name);<BR>
20 print "\n is writeable" if ( -w $name);<BR>
21 print "\n is executeable" if ( -x $name);<BR>
22 print "\n is owned by you" if ( -o $name);<BR>
23<BR>
24 print "\n========== Reality Checks ";<BR>
25 print "\n exists " if ( -r $name);<BR>
26 print "\n has zero size " if ( -z $name);<BR>
27 print "\n has some bytes in it " if ( -s $name);
<BR>
28<BR>
29 print "\n is a file " if (-f $name);<BR>
30 print "\n is a directory " if (-d $name);<BR>
31 print "\n is a link " if (-l $name);<BR>
32 print "\n is a socket " if (-S $name);<BR>
33 print "\n is a pipe " if (-p $name);<BR>
34<BR>
35 print "\n is a block device " if (-b $name);<BR>
36 print "\n is a character device " if (-c $name);
<BR>
37<BR>
38<BR>
39 print "\n has setuid bit set " if (-u $name);<BR>
40 print "\n has sticky bit set " if (-k $name);<BR>
41 print "\n has gid bit set " if (-g $name);<BR>
42<BR>
43 print "\n is open to terminal " if (-t $name);<BR>
44 print "\n is a Binary file " if (-B $name);<BR>
45 print "\n is a Binary file " if (-T $name);<BR>
46<BR>
47 print "\n is Binary to terminal " if (-t $name);
<BR>
48 print "\n is open to terminal " if (-t $name);<BR>
49<BR>
50<BR>
51 .00 ;<BR>
52<BR>
53 'di \"
finish diversion<BR>
54 .nr nl 0-1 \" Start
new page with -1<BR>
55 .nr % 0 \" start at page 1<BR>
56 '; _ _END_ _ #### Start Man Page ####<BR>
57<BR>
58 .TH Test 1 "Apr 15, 1996"<BR>
59 .AT 3<BR>
60 .SH NAME<BR>
61 tf - Test file attributes<BR>
62 .SH SYNOPSIS<BR>
63 .B tf file<BR>
64 .P<BR>
65 .B tf directory<BR>
66 .SH DESCRIPTION<BR>
67 .I tf<BR>
68 Prints out the file attributes for a file.<BR>
69 .SH FILES<BR>
70 Just add perl.<BR>
71 .SH AUTHOR<BR>
72 Kamran Husain.<BR>
73 .SH BUGS<BR>
74 We don't believe in bugs, we introduce features.</FONT></TT>
</BLOCKQUOTE>
<HR>
<P>
<CENTER>
<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD ><B>Warning</B></TD></TR>
<TR VALIGN=TOP><TD >
<BLOCKQUOTE>
You might have to work with lines 2, 3, and 51 to get the spaces right if you are using different versions of <TT><FONT FACE="Courier">nroff</FONT></TT>. The <TT><FONT FACE="Courier">groff</FONT></TT> version of GNU did not work on two machines but worked
fine on a Sun with these lines:
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">'di';<BR>
'ig00';</FONT></TT>
</BLOCKQUOTE>
<BLOCKQUOTE>
To get the two lines to work properly, I had to introduce a space in the calls to the macros:</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">'di ';<BR>
'ig 00 ';</FONT></TT>
</BLOCKQUOTE>
</TD></TR>
</TABLE></CENTER>
<P>
<P>
You have been warned. The limitation of this method should be
obvious by now: It's useful for generating one <TT><FONT FACE="Courier">man</FONT></TT>
page for one source file. In addition, it's too heavily tied to
the <TT><FONT FACE="Courier">nroff</FONT></TT> package. The <TT><FONT FACE="Courier">man</FONT></TT>
page will not be generated on NT machines that do not have the
<TT><FONT FACE="Courier">nroff</FONT></TT> packages installed
by default. Obviously, something more generic is needed. This
is where the POD format comes in.
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -