Perl POD as literate programming tool

Perl comes with its own documentation. The most straightforward and widely preferred way to read it is by means of the perldoc command line utility. It will give access to specific perl manpages (e.g.: perlsyn for Perl syntax or perlop for Perl operators) as well as to the documentation for individual functions and faq entries: it supports a large number of command line switches that are described in its own documentation. To access the latter just issue the following command at your shell's prompt:

perldoc perldoc

For some tips about where to look for some particular information, see brian_d_foy's Perl documentation documentation tutorial.

To put it briefly, however, most times you will want to use perldoc as in one of the following examples:

• perldoc perldata - to read about Perl data types;
• perldoc -f open - to read about the open() function;
• perldoc -q "how do I do X" - to search the FAQ.

HTML

The language used by perldoc, POD makes it easy to render the documentation in a variety of target formats, including HTML. Some Perl distributions, most notably ActiveState's ActivePerl, a very popular one under Windows, come with ready made HTML documentation, which some find easier to read and walk through.

An HTML version of the documentation is also available on the web at http://perldoc.perl.org/ and some other locations. As such, it can be searched through with Google and the above mentioned tutorial contains some specific examples about how to do so.

Grep

Some people prefer to use a grep or grep-like utility to search specific stuff in the POD documentation installed on their computers, and one can indeed use such an approach when everything else fails.

Other options include:

• the pure Perl tcgrep implementation from the Perl Power Tools project;
• the specialized podgrep utility from the pmtools distribution;
• zentara's Gtk2 Visual Grep;
• diotalevi's grep, which in turn borrows the pretty formatting of
• petdance's ack.

Other options

One additional possibility is to use the perlindex utility, which is "a program to index and search the perl documentation."

The tkpod standalone Tk POD viewer from Tk::Pod (which is a GUI for viewing and browsing Perl's POD documentation) also provides an interface to perlindex if it is installed, and its features additionally include:

• support for single or multiple POD windows;
• tree view of available PODs.

Yet another alternative to perldoc is Pod::Webserver, a minimal web server which serves local Perl documentation: with it one can browse all the docs available on the machine it runs on with a web browser.

POD is skipped by Perl interpeter

Here is a very simple example of POD:

#!/usr/bin/perl
 
=head1 DESCRIPTION
Pretty printer Neatbash can be called a "fuzzy" pretty-printer.

If does not perform full lexical analysis (which for bash is impossible  as BASH does not have lexical level defined). 

Instead it relies on analysis of a limited context of each line (prefix and suffix) to "guess" correct nesting level.  

It does not perform any reorganization of the text other then re-indentation. 
 
=cut
 
use strict;
use warnings;

#
# Main loop initialization variables
#

$new_nest=$cur_nest=0;
$top=0; $stack[$top]='';
$lineno=0;
$fline=0; # line number in formatted code
$here_delim="\n"; # impossible combination
$noformat=0;
$InfoTags='';

 

If you save this as script.pl and run it using perl script.pl, perl will disregard anything between the first line starting with = (=head1 in our example) and the =cut lines. It will only execute the actual code.

If you type in perldoc script.pl, the effect will opposite: the perldoc command will disregard all the code. It will fetch the lines between ==head1 and =cut, format them , and display them on the screen.

There might be multiple =head<digit>  =cut sections in the script. They all will be merged in a single document as intergral section and the TOC for the document will be generated too.

The POD markup language

Detailed description of the POD markup language can be found by typing in perldoc perlpod

The key idea is very simple. There is a set of simple tags such as =head1 and =head2 to mark several levels of headers..

There are also additional directives like  =over to provide indentation and =item to allow the creation of bullet points.

Each section of POD ends with the "=cut" delimiter to mark the end. 

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

POD 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 useful for code examples.

the test which starts at first position will be reflowing into paragraphs.

POD requires empty rows around the tags.

The perldoc command that comes with perl displays the POD as a man-page. It is quite useful on Linux but man format is outdated. Standard de facto is HTML format.

pod2html convertor

Another command line tool that can read POD documentation imbedded in scripts is called pod2html. As the name suggests, it  converts a POD to an HTML document which you can view in a browser.

Usage:  /usr/bin/pod2html --help --htmldir= --htmlroot=
           --infile= --outfile=
           --podpath=:...: --podroot=
           --cachedir= --flush --recurse --norecurse
           --quiet --noquiet --verbose --noverbose
           --index --noindex --backlink --nobacklink
           --header --noheader --poderrors --nopoderrors
           --css= --title=

  --[no]backlink  - turn =head1 directives into links pointing to the top of
                      the page (off by default).
  --cachedir      - directory for the directory cache files.
  --css           - stylesheet URL
  --flush         - flushes the directory cache.
  --[no]header    - produce block header/footer (default is no headers).
  --help          - prints this message.
  --htmldir       - directory for resulting HTML files.
  --htmlroot      - http-server base directory from which all relative paths
                      in podpath stem (default is /).
  --[no]index     - generate an index at the top of the resulting html
                      (default behaviour).
  --infile        - filename for the pod to convert (input taken from stdin
                      by default).
  --outfile       - filename for the resulting html file (output sent to
                      stdout by default).
  --[no]poderrors - include a POD ERRORS section in the output if there were
                      any POD errors in the input (default behavior).
  --podpath       - colon-separated list of directories containing library
                      pods (empty by default).
  --podroot       - filesystem base directory from which all relative paths
                      in podpath stem (default is .).
  --[no]quiet     - suppress some benign warning messages (default is off).
  --[no]recurse   - recurse on those subdirectories listed in podpath
                      (default behaviour).
  --title         - title that will appear in resulting html file.
  --[no]verbose   - self-explanatory (off by default).

There are additional tools which allow to generate pdf or mobi files from POD.

POD sections vs comments

Comments  are explanations for the the author of the script and the person who will maintain it in the future. The person who needs to add features or fix bugs.

Documentation written in POD is kind of build in manual for the program and represent approach called literary programming.

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 perldoc command.

NEWS CONTENTS

• 20171113 : Strip Pod as Pod from Perl file - Stack Overflow ( Nov 13, 2017 , stackoverflow.com )

Old News

Plain Old Documentation in 5 minutes - Juerd's site

[Nov 13, 2017] Strip Pod as Pod from Perl file - Stack Overflow

Nov 13, 2017 | stackoverflow.com

Håkon Hægland ,Nov 2, 2014 at 12:10

I am trying to extract the Pod documentation from a Perl file. I do not want to convert the documentation to text as is done by Pod::Simple::Text . I just want the Pod text as Pod text, such that I can feed it into Pod::Template later. For example:

use warnings;
use strict;
use Pod::Simple::Text;
my $ps=Pod::Simple::Text->new();
my $str;
$ps->output_string( \$str );
$ps->parse_file($0);
print $str;

__END__

=head1 SYNOPSIS

prog [OPTIONS]

This will print the Pod as text. Is there a CPAN module that can give me the Pod text, that is:

=head1 SYNOPSIS

prog [OPTIONS]

instead?

Update

The solution should be able to handle Pod docs in strings, like

my $str = '__END__

=head1 SYNOPSIS';

Miller ,Nov 2, 2014 at 18:42

This can be done using PPI :

use strict;
use warnings;

use PPI;

# Slurp source code
my $src = do { local ( @ARGV, $/ ) = $0; <> };

# Load a document
my $doc = PPI::Document->new( \$src );

# Find all the pod within the doc
my $pod = $doc->find('PPI::Token::Pod');
for (@$pod) {
    print $_->content, "\n";
}

=comment
Hi Pod
=cut

1;

__END__

=head1 SYNOPSIS

prog [OPTIONS]

Outputs:

=comment
Hi Pod
=cut

=head1 SYNOPSIS

prog [OPTIONS]

Håkon Hægland ,Nov 3, 2014 at 12:51

Thanks for this great solution. It even works with Pod docs embedded in strings, like my $str='__END__ =head1 SYNOPSIS'; – Håkon Hægland Nov 3 '14 at 12:51

Tim ,Nov 2, 2014 at 13:58

Use the -u option for perldoc . This strips out the POD and displays it raw.

If you want to extract the POD from within a Perl program, you could do something like this:

my $rawpod;
if (open my $fh, '-|', 'perldoc', '-u', $filename) {
  local $/;
  my $output = <$fh>;
  if (close $fh) {
    $rawpod = $output;
  }
}

If you really don't want to run perldoc as an executable, you might be interested that the perldoc executable is a very simple wrapper around Pod::Perldoc which you might want to consider using yourself.

Håkon Hægland ,Nov 3, 2014 at 12:55

Thanks, but it does not work with Pod docs embedded in strings. See my updated question for an example.. – Håkon Hægland Nov 3 '14 at 12:55

Tim ,Nov 3, 2014 at 18:54

Well, if you change the question, it's not that surprising that a given answer no longer works. I'm pleased you've found a solution to your new question. – Tim Nov 3 '14 at 18:54

Håkon Hægland ,Nov 5, 2014 at 6:40

The problem with perldoc is that there is a bug, so it thinks Pod embedded in a string belongs to the document. – Håkon Hægland Nov 5 '14 at 6:40

Calle Dybedahl ,Nov 2, 2014 at 12:54

Pod::Simple::SimpleTree will give it to you as a parse tree. You can convert that back to POD source easily enough.

toolic ,Nov 2, 2014 at 13:51

+1 if you provide a runnable code example. – toolic Nov 2 '14 at 13:51

Recommended Links

Plain Old Documentation - Wikipedia, the free encyclopedia

perldoc - Look up Perl documentation in pod format.

POD - Plain Old Documentation

POD Quick Reference provides a categorized list of the most frequently used docs right in front of the reader for easy and intuitive access to them.

perlpod - perldoc.perl.org

Pod2WinHlp - search.cpan.org