Gtk2-Perl Study Guide: Gaining an understanding of Gtk2-Perl
PrevNext

Appendix B. POD Appendix

This gives more background and tips on POD

B.1. Introduction

Plain Old Documentation, or POD as it is known to Perl programmers, is one of the really nice features of Perl. It keeps the documentation and the code in one place. Although programmers enjoy working with clean, well documented code, most of us fall short when it comes to documenting our own projects.

POD is a very simple text formatter that relies on tags that tell a translator how to format the text. The tags can be embedded in your code files, and Perl will ignore them when it runs your script. Likewise, when you run your script file through a pod translator, it will ignore lines in the file that are not pod specific. That means that you can write your documentation as you write the code. The interpreter deals with the code and the pod translator deals with the pod tags. It's as simple as that.

B.1.1. POD readers

POD can be displayed in various formats. The most common utility to display POD, is perldoc. It formats and displays POD information. You use it from the command line, and the syntax is like this: 

# perldoc [options] docname
docname is the name of the file you want to view.

There are also utilities to show POD in different formats, these include:

  • pod2html - This will create web pages from POD.

  • pod2man - This creates man pages. Gtk2-Perl creates those during installation.

  • pod2text - Creates text files from POD.

Note

Now you know why POD is sometimes referred to as man pages, or why on the Gtk2-Perl homepage the online POD are in html format. It is all POD, just different ways of presenting it.

B.1.2. Writing POD

A POD tag consists of an equal sign '=' followed by a string that occurs at the beginning of a line. POD works with paragraphs, which is any string that is separated by at least two newlines. In other words, the string must have a blank line before and after it.

The important tags you'll need to know are =headx, =item, =over and =back. Let's look at them one by one. (If you want to learn about the others, use perldoc perlpod). 

=headx
This tag formats the paragraph that follows as a heading. The level is determined by a number that directly follows =head. In other words, you'll have to replace the x in =headx for the level you want. For example, a top level heading would be: 
=head1 This is a top level heading
If you want a second-level heading, you'd use =head2, a third-level heading would be =head3, and so forth. 
=item, =over, =back
These three tags are discussed together, since that's how they work. They are used to create a list, and =over specifies the depth of the indent. =item defines an item in the list, and =back moves the left margin back to where it was before the list began. Here's how it looks. 
=over 4
=item *
This is the first item
=item *
This is the second item
=back
There are other options for creating the type of list, and you'll need to see the documentation to learn more.

One more important tag you'll need to know about is =cut. This is essential if you're embedding your pod documentation in with your code. When your script is run, Perl will ignore everything between an ={pod tag} and =cut. If you forget to use =cut, then Perl will ignore everything that follows the first tag. Here's how a script would look with both pod and code.

#!/usr/bin/perl -w
use strict;
print "Content-type: text/plain\n\n";
print "Hello World!\n";

=head1 Testing POD
This is a test of the POD system of documentation.

=head2 Header 2
This is a second level heading

=over 4

=item *
This is the first item

=item *
This is the second item

=back

=head2 Now we're back where we were

=cut

print "Hello again, World!";

B.1.3. Eazy POD

When you program, you don't want a struggle to get information on the modules you are using. There are currently very nice utilities available which eases pod retrieval.

  • Gavin Brown's podviewer and podbrowser. The podviewer is available here, and you can find the podbrowser here.

  • Muppet's two object browser programs, which can be found here here and here. It is also included in this documentation, but may be dated.

    The nice thing about Muppet's programs is that it gives out a hierarchical treeviev with Glib as the root. This can be walked when searching for info. There is a "Find" option, and the abitily to add more Perl namespaces.

    Oject Browser

  • Konqueror has a nice shortcut "#" which will then search through all the man page directories. Tabbed browsing allows multiple open man pages.

PrevHomeNext
Pango Appendix Resource File Appendix