POD with example in Perl

POD - Plain Old Documentation

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.


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.

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