Plain Old Documentation or POD is a way to document Perl programs. POD documentation allows multi-line comments to be inserted in Perl programs. In addition, POD documentation allows comments to be inserted that can be extracted to produce standalone documentation for Perl programs and modules. In fact, all documentation at the CPAN site, www.cpan.org is produced from POD documentation. Documentation on installed modules on a system can be obtained using the perldoc command. Such documentation is also produced using POD. The discussion in this section is with respect to the programs given in SectionÊ6.12. Documentation can be obtained in HTML from a POD-documented script file by running the command pod2html with the script file name as argument. There are several Perl modules to process POD documentation as well. POD documents can be easily converted to text, PDF, LaTeX, and Unix man page formats.
Multiple line comments can be introduced in a Perl program by including them within =pod and =cut markers or tags. Each marker must start in the first column and must be followed by a blank line. To produce documentation in HTML form, we can use POD tags such as =head1, and =over. =head1 produces a first level HTML header, i.e., a header included within HTML tags <H1> and </H1> when pod2html is run on the program file. =over starts a list. =over takes an argument that indicates indentation of list items. =item is used to produce list items in HTML. =back is used to signal the end of a list started by =over. =cut is used to indicate the end of POD documentation. Every POD marker or tag must be followed by a blank line. POD documentation can occur anywhere in a program file. There are several other POD tags that we have not discussed here.
The first script given in SectionÊ6.12 is called archive.pl. It is a regular Perl script with POD directives inside the code. To obtain HTML documentation for archive.pl, we run the following command.
%pod2html archive.pl > archive.html
Here, we redirect the HTML output of the pod2html command to the file archive.html. When viewed using a Web browser, the documentation looks like that in Figure 1.1.
Figure 1.1: POD Documentation Generated by pod2html