|
|
|
Chapter 8Documenting Perl Scripts Perl/Tk
CONTENTSThis chapter introduces you to the types of documentation available for Perl scripts. I cover two documentation methods: embedding nroff 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 man pages from the source files. Embedding man PagesGenerally, 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. Since Perl 4, you can keep your documentation and code in the same source file. The way to do this is to use the nroff tags in the man package and embed these codes in a Perl source file. This trick works only if you are using the -man package with nroff; therefore, if your system is not UNIX-like or if you abhor nroff, you should skip ahead to the next section, which is on POD formats. The way to do this embedding was documented initially in the book Programming Perl by Larry Wall and Randall Schwartz, published by O'Reilly & Associates. Wall has also written for this book a shell script, called wrapman, that performs embedding as a template. However, it will be instructive to see how the method works. The trick in embedding man pages is to use the .di and .ig commands in nroff. The .di command in nroff "diverts" text into an nroff macro. It works this way: There are two .di tags; one is defined at the top of the text to be diverted as .di X, and the other .di tag (with no arguments) at the bottom of the text. The first .di X asks nroff to divert all the text into macro X until it sees .di at the start of a line. The .ig macro in nroff works the same way as .di, but it forces nroff to ignore all text between .ig X and any other .X tag. Now comes the important part: The double quotes ("") in both .ig and .di commands can be replaced with a single quote to get 'ig and 'di commands that do the same thing as the .ig and .di 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. Another point to remember is that Perl stops interpreting your script when it sees an _ _END_ _ token. This stopping feature can be used to your advantage because you can put all of your text after the _ _END_ _ token. So if you were to add the following two statements to the start of a Perl script, your script would still run: 'di'; As far as Perl is concerned, these two lines are simply strings. For nroff, the two lines are interpreted as calls to macros. The first line uses the 'di'; macro to divert text until it sees 'di on a line by itself. The next line 'ig00 '; diverts text until it sees .00 on a line by itself. Now, at the end of the source file, place the following lines, which are valid in Perl and in nroff: .00 # Terminates the .ig processing 'di and '; really do define a Perl string between single quotes. _ _END_ _ stops Perl from processing further, and .00 is conveniently ignored by Perl. Now you can place the man page contents after the line containing the _ _END_ _ statement. Look at the sample listing shown in Listing 8.1. The output from this listing is shown in Figure 8.1. Listing 8.1. Embedding man pages in Perl. 1 #!/usr/bin/perl
You have been warned. The limitation of this method should be obvious by now: It's useful for generating one man page for one source file. In addition, it's too heavily tied to the nroff package. The man page will not be generated on NT machines that do not have the nroff packages installed by default. Obviously, something more generic is needed. This is where the POD format comes in. The POD FormatThe 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 man 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.
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 (=).
An example here will help. In Listing 8.2, a file called tf.pod is constructed to document the man page in POD format. Listing 8.2. A sample POD file. 0 #!/usr/bin/perl 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 "=cut" 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. Now, look at line 18 in Listing 8.2. The B<text> tag is used here to place text in bold typeface. Several tags exist for formatting text. Table 8.2 lists these tags.
In most cases you only wind up using the B<> and I<> 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. 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 =pod, =cut, and =over/back pairs matched, you shouldn't run into any problems. Translating POD into Other FormatsThree filters exist that convert POD formatted documents into three different formats. Here's a list of these filters:
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: pod2html gnat.pod You'll find that running the pod2html program on gnat.pod created a file called gnat.html in your directory. The output for Listing 18.2 is shown in Figure 18.2. Figure 8.2 : HTML output from pod2html SummaryThis chapter covered two ways of documenting Perl files: one using man pages and the other using POD documentation. man pages can be embedded in the source file, but they require the use of nroff with the man package. POD files are more generic in that you can use translators to convert from POD to one of three known formats: HTML, man, 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 pod2html program and placing the output in a word processor, such as Microsoft Word, to edit the HTML file directly. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
With any suggestions or questions please feel free to contact us | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
