POD (Plain Old Documentation with Perl)

	How to use POD (Perl's Documentation Tool)
This article was found on: http://perl.about.com How to use POD One of the really nice features of Perl is that its so easy to document. There is a simple documentation tool will help you learn about modules you may be using, view documentation on Perl functions from the command line, and allow you to document your code as you write it. Its called Plain Old Documentation, or Pod, and knowing how to use it will help you find and share information on Perl programming. Introduction Although programmers enjoy working with clean, well documented code, most of us fall short when it comes to documenting our own projects. All too often information is written after the fact, if at all. It doesn't seem like its a big deal after you finally get the code running, but if your code is passed on to another programmer they'll end up having to figure it all out from scratch. And even if you're the only one who will ever see the code, you'll probably have trouble remembering the details of a particular project if you don't look at it until six months to a year later. Fortunately Perl provides a simple solution with Plain Old Documentation, known as Pod. 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. Its as simple as that. Even if you're not a programmer (yet!) you can still benefit from knowing about pod. For instance, you can use the pod utility perldoc to view pod information in code files written by someone else. You can also use perldoc to view the documentation on Perl functions. Can't remember exactly how to use open()? ... No problem ... Just type: perldoc -f open and its all there for you. Other pod utilities can convert pod documentation into files, so you can look at them when you need to. One of my favorites is pod2html, which will create documentation I can view from my browser. I just bookmark the page and save it for those times when I need quick answers. So you see, knowing about pod can really help you. Read on to learn more. We'll start by learning how to view existing pod information that you'll find in the Perl documentation, or modules that you are using, and then we'll learn how to write it ourselves. Using perldoc Perldoc is a pod utility that 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. If you would like to see the information on CGI.pm, for instance, you'd type perldoc CGI.pm You'd have to modify the path, of course, but the documentation in all its glory would be made available to you. As I mentioned earlier, you can use perldoc for a quick reference to Perl functions. Type perldoc -f function_name and you'll have all the information available on the function usage and parameters. Its really handy for learning the functions, as well as for those times when your brain pops into neutral at a critical moment. There are other options for using perldoc, and you can learn more about them by typing perldoc perldoc Using pod2html Another good pod utility to know about is pod2html. It converts pod information into HTML format so you can see it from your browser. For example, if you'd like the documentation for CGI.pm saved to an HTML file, you'd have all that wonderful information available when you need it, all nicely formatted with links, you'd type: pod2html CGI.pm -outfile CGIpm.html Other pod utilities There are other pod utilities which are equally useful, and the documentation can be viewed with perldoc. Some of these utilities are: pod2fm - Translates pod to FrameMaker format pod2latex - Translates pod to LaTeX format pod2man - Translates pod to Unix manpage format pod2text - Translates pod to text As you can see, you have lots of options, and you might want to look on CPAN to see if there are other utilities that might meet your needs. Writing pod OK, by now I hope I have sold you on just how useful pod can be. Now let's look at how you can use it in your own code files. 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. 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). =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. Using pod in your code files 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!"; Summary As you can see, knowing about pod can be very useful. You can read pertinent information about modules you can use, access online documentation for Perl functions, and document your code as you write it. Although the art of documenting code is not well documented, its a very important part of programming. Now that you know how easy it is, try and document the code you write as you go along. That way it doesn't take up much of your time and energy, but it can sure save a lot of it for you or the programmers that modify your code.

How to use POD (Perl's Documentation Tool)

This article was found on: http://perl.about.com

How to use POD

One of the really nice features of Perl is that its so easy to document. There is a simple documentation tool will help you learn about modules you may be using, view documentation on Perl functions from the command line, and allow you to document your code as you write it. Its called Plain Old Documentation, or Pod, and knowing how to use it will help you find and share information on Perl programming.

Introduction

Although programmers enjoy working with clean, well documented code, most of us fall short when it comes to documenting our own projects. All too often information is written after the fact, if at all. It doesn't seem like its a big deal after you finally get the code running, but if your code is passed on to another programmer they'll end up having to figure it all out from scratch. And even if you're the only one who will ever see the code, you'll probably have trouble remembering the details of a particular project if you don't look at it until six months to a year later. Fortunately Perl provides a simple solution with Plain Old Documentation, known as Pod.

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. Its as simple as that.

Even if you're not a programmer (yet!) you can still benefit from knowing about pod. For instance, you can use the pod utility perldoc to view pod information in code files written by someone else. You can also use perldoc to view the documentation on Perl functions.

Can't remember exactly how to use open()? ... No problem ... Just type:

perldoc -f open

and its all there for you.

Other pod utilities can convert pod documentation into files, so you can look at them when you need to. One of my favorites is pod2html, which will create documentation I can view from my browser. I just bookmark the page and save it for those times when I need quick answers.

So you see, knowing about pod can really help you. Read on to learn more. We'll start by learning how to view existing pod information that you'll find in the Perl documentation, or modules that you are using, and then we'll learn how to write it ourselves.

Using perldoc

Perldoc is a pod utility that 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. If you would like to see the information on CGI.pm, for instance, you'd type

perldoc CGI.pm

You'd have to modify the path, of course, but the documentation in all its glory would be made available to you.

As I mentioned earlier, you can use perldoc for a quick reference to Perl functions. Type

perldoc -f function_name

and you'll have all the information available on the function usage and parameters. Its really handy for learning the functions, as well as for those times when your brain pops into neutral at a critical moment. There are other options for using perldoc, and you can learn more about them by typing

perldoc perldoc

Using pod2html

Another good pod utility to know about is pod2html. It converts pod information into HTML format so you can see it from your browser. For example, if you'd like the documentation for CGI.pm saved to an HTML file, you'd have all that wonderful information available when you need it, all nicely formatted with links, you'd type:

pod2html CGI.pm -outfile CGIpm.html

Other pod utilities

There are other pod utilities which are equally useful, and the documentation can be viewed with perldoc. Some of these utilities are:

pod2fm - Translates pod to FrameMaker format
pod2latex - Translates pod to LaTeX format
pod2man - Translates pod to Unix manpage format
pod2text - Translates pod to text

As you can see, you have lots of options, and you might want to look on CPAN to see if there are other utilities that might meet your needs.

Writing pod

OK, by now I hope I have sold you on just how useful pod can be. Now let's look at how you can use it in your own code files. 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. 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).

=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.

Using pod in your code files

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!";

Summary

As you can see, knowing about pod can be very useful. You can read pertinent information about modules you can use, access online documentation for Perl functions, and document your code as you write it. Although the art of documenting code is not well documented, its a very important part of programming. Now that you know how easy it is, try and document the code you write as you go along. That way it doesn't take up much of your time and energy, but it can sure save a lot of it for you or the programmers that modify your code.