Perl documentation in Pod format ~ Another Look Up [ Tutorial ]

[2teez]

One of the finest initiative was the full documentation bundled with every version of Perl Programming language. Using the plain old documentation (pod) utility called perldoc one can literally read or learn the programming language without another book.

E.g

perldoc perl

gives you the Name of the perl language Interpreter, the SYNOPSIS, shows you how to get help using perldoc, Overview, Tutorials files names, Reference Manual e.t.c.

However, using perldoc could be a pain in the neck most times for so many reasons. Among those reason(s), is the the fact that many perl programmers majorly beginners ( or otherwise ), really don't enjoy the scrolling of the 'white' lines over the 'black' background ( or whatever your Command Line Interface background colour is, especially on window OS ).
For those, who hate the dos looking environments, or would not even want to have anything to do with except to issue a command to run their perl programs, am glad to say there are more than one way out of this! ( The purpose of this tutorial ).

Solution #1:
visit http://perldoc.perl.org/ to either read online or download the whole documentation in either html ot pdf format. Then you can read them at your own time offline.
Please note, this is so cool and good because it has all the documentation for all the perl version 5.8.8, the latest been 5.16.0 ( as at the time of this write up ).

Solution #2:
Using Pod::Webserver. This is so beautiful because it gives you documentation on all the modules installed on your local system. And you can then read them from your browser.
Install Pod::Webserver using cpan from your command Line Interface (CLI):

perl -MCPAN -eshell
cpan> install Pod::Webserver

See how that plays out. After that all you have to do is use:

podwebserver

from your CLI, then wait after podwebserver is done, you are instructed to use

http://localhost:8020/

on your browser to access documentations of all the modules available on your system ( ofcourse, for all the modules with documentation )

Solution #3:
Using our old, strong lovely friend perldoc in a new light! ( really this solutiion is my favourite ). Let see:
if you do

perldoc perldoc

Under SYNOPSIS, you are showned how to use perldoc with all manner of flags to generate different formats of outputs. The ones that got my attention for so long and changed the way I see and use perldoc are ( -oformatname) and (-ddestination_file), which can allow me generate any file format especially html files formats on the fly, so that I stop reading from CLI.
Here is an example:

# generate a File::Find Module documentation in html format
perldoc -o html -d file_find.html File::Find

OR

perldoc -o html -d input_seperator.html -v $/

After a while I got tired and more lazy typing all these on the CLI so I hacked together a simple script I called pperldoc.pl ( ofcourse, any Perl valid name could be used ).
And ever since I have never remain the same again getting documentation from perl.

#!/usr/bin/perl
use warnings;
use strict;
use Carp qw(croak);
use Readonly;

Readonly my $space => q{ };    #a single space
croak " Usage pperldoc <option> docname " unless @ARGV == 1 or @ARGV == 2;

# initialized the value of $ARGV[0] and [1], in-case no value was given
$ARGV[0] //= $space;
$ARGV[1] //= $space;

my $first_arugment  = $ARGV[0];
my $second_arugment = $ARGV[1];

if ( $first_arugment =~ m/^-/ ) {    # check flag for first arugment
    if ( $second_arugment ne $space ) {

        # check second arugment were other character
        if ( $second_arugment !~ m/[a-z]+?/i ) {
            my $special_name = transform_doc_name($second_arugment);
            system(
qq{ perldoc -o html -d ${special_name}.html $first_arugment $second_arugment}
            );

        }
        else {
            system(
qq{ perldoc -o html -d ${second_arugment}.html $first_arugment $second_arugment}
            );
        }
    }
    else { croak "Please specify docname" }
}
elsif ( $first_arugment !~ m/^-/ ) {    # check flag for first arugment
    # check first arugment if module has double full colon
    if ( $first_arugment =~ m/.+?::.+?/ ) {
        ( my $doc_new_name = $first_arugment ) =~ y/::/_/s;
        system(qq{ perldoc -o html -d ${doc_new_name}.html $first_arugment});
    }
    else {
        system(qq{ perldoc -o html -d ${first_arugment}.html $first_arugment});
    }
}

sub transform_doc_name {
    my ($doc) = @_;
    $doc = 'perl_lingo';
    return $doc;
}

So, I use, read documentation made easy like so:

 pperldoc.pl -f substr

And I have substr.html to read from!
I think the languag the gods speak is perl!. I believe their lingua franca is perl!