pod-plain-old-documentation-of-perl.tt

=title POD - Plain Old Documentation
=timestamp 2013-03-02T18:40:59
=indexes POD, perldoc, =head1, =cut, =pod, =head2, documentation, pod2html, pod2pdf
=status show
=books beginner_book
=author szabgab
=index 1
=archive 1
=feed 1
=comments 1
=social 1

=abstract start

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

That requires learning the word processor and investing a lot of energy in
trying to make the document "look good" instead of "having good content".

That's not the case with Perl. Normally you would write the
documentation of your modules right in the source code and rely
on external tool to format it to look good.

=abstract end

In this episode of the <a href="/perl-tutorial">Perl tutorials</a>
we are going to see the <b>POD - Plain Old Documentation</b> which is
the mark-up language used by perl developers.

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

<code lang="perl">
#!/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";
</code>

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

On the other hand, if you type in <hl>perldoc script.pl</hl>, the <b>perldoc</b> command
will disregard all the code. It will fetch the lines between <hl>=pod</hl> and <hl>=cut</hl>,
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
<a href="/core-perl-documentation-cpan-module-documentation">standard documentation of Perl</a>.

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

<h2>Too simple?</h2>

The assumption is that if you remove most of the obstacles from writing
documentation then more people will write documentation. 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. (Check out the documents on <a href="http://metacpan.org/">Meta CPAN</a>
to see nicely formatted version of PODs.)

<h2>The markup language</h2>

Detailed description of the <a href="http://perldoc.perl.org/perlpod.html">POD markup language</a>
can be found by typing in <a href="http://perldoc.perl.org/perlpod.html">perldoc perlpod</a> but
it is very simple.

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

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

Any string that starts with an equal sign <hl>=</hl> as the first character in a row will
be interpreted as a POD markup, and will start a POD section closed by <hl>=cut</hl>

POD even allows the embedding of hyper-links using the L<some-link> notation.

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 lines will remain short. This is used for code examples.

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

<code lang="perl">
=head1 Title
=head2 Subtitle
Some Text
=cut
</code>

won't do what you are expecting.

<h2>The look</h2>

As POD is a mark-up language it does not by itself define how things will be displayed.
Using an <hl>=head1</hl> indicates something important, <hl>=head2</hl> means something less important.

The tool that is used to display the POD will usually use bigger characters to display the
text of a head1 than that of a head2 which in turn will be displayed using bigger fonts than the regular
text. The control is in the hands of the display tool.

The <hl>perldoc</hl> command that comes with perl displays the POD as a man-page. It is quite useful on Linux.
Not so good on Windows.

The <a href="https://metacpan.org/module/Pod::Html">Pod::Html</a> module provides another command line tool called
<hl>pod2html</hl>. This can convert a POD to an HTML document you can view in a browser.

There are additional tools to generated pdf or mobi files from POD.

<h2>Who is the audience?</h2>

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 users are other Perl programmers who need
to build applications or 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
<hl>perldoc</hl> command.


<h2>Conclusion</h2>

Writing documentation and making it look nice is not that hard in Perl.