POD - Plain Old Doculmentation

Programmers usually dislike writing documentation. Part of the reason is that programs are plain text files and in many cases they are required to write documentation in some word processor.

That's not the case with Perl. Normally you would write the documentation of your modules right in the source code.

In this episode of the Perl tutorials we are going to see the POD - Plain Old Documentation which is the mark-up language used by perl developers.

As simple piece of perl code with POD looks like this:

  #!/usr/bin/perl
  use strict;
  use warnings;

  =pod

  =head1 DESCRIPTION

  This script can have 2 parameters. The name or address of a machine
  and a command. It will execute the command on the given machine and 
  print the output to the screen.

  =cut

  print "Here comes the code ... \n";

If you save this as script.pl and run it using perl script.pl, perl will disregard anything between the =pod and the =cut lines. It will only execute the actual code.

OTOH if you type in perldoc script.pl, perldoc will disregard all the code, fetch the lines between =pod and =cut, format them according to certain rules and display them on the screen.

These rules depend on your operating system but they are exactly the same as you saw when we learned about the standard documentation of Perl.

The added value of using the embedded POD is that your code will never be supplied without documentation by accident as it is inside modules and scripts. You can also reuse the tools and infrastructure the Open Source Perl community built to itself. Even for your in-house purposes.

Too simple?

The assumption is that if you remove most of the obstacles from writing documentation then more people will do it. Instead of learning how to use a word processor to create nice looking documents you just type in some text with a few extra symbols and you can get a reasonably looking document.

The markup language

Detailed description of the POD markup language can be found by typing in perldoc perlpod but it is very simple.

There are a few tags such as =head1 and =head2 to mark "very important" and "somewhat less important" headers. There is =over to provide indentation and =item to allow the creation of bullet points and there are a few more.

There is =cut to mark the end of a POD section and =pod to start one. Though this starting one isn't strictly required.

Any string that starts with an = as the first character in a row will be taken as a POD markup and will start a POD section closing by =cut

An important thing to remember is that POD requires empty rows around the tags. So

  =head1 Title
  =head2 Subtitle
  Some Text
  =cut

won't do what you are expecting.

The text you put on the line of =head1 will be shown with the biggest letters - where possible =head2 will generate slightly smaller letter but still bigger than the regular text.

Text between the markup parts will be shown as paragraphs of plain text.

If the text does not start on the first character of the row, it will be taken verbatim, meaning they will look exactly as you typed them: long lines will stay long lines and short line will remain short. This is used for code examples.

Who is the audience?

After seeing the technique, let's see who is the audience?

Comments (the thing that start with a # ) are explanations for the maintenance programmer. The person who needs to add features of fix bugs.

Documentation written in POD is for the users. People who should not look at the source code. In case of an application those will be so called "end users". That's anyone.

In case of Perl modules the user are other Perl programmers who need to build applications (or just other modules). They still should not need to look at your source code. They should be able to use your module just by reading the documentation via the perldoc command.

Next

Debugging Perl scripts

Perl tutorial and video course