NAME

Lip::Pod - Literate Perl to POD conversion

SYNOPSIS

  #!/usr/bin/perl -w
  use strict;
  use Lip::Pod;
  package main;
  my $parser = new Lip::Pod;
  $parser->parseopts( -want_nonPODs => 1, -process_cut_cmd => 1 );
  push @ARGV, '-' unless @ARGV;
  for (@ARGV) { $parser->parse_from_file($_); }
  exit 0;

DESCRIPTION

Donald Knuth introduced Literate Programming, which is the idea that computer programs should be written in an expository style, as works of literature. He created a system called web, which implemented his ideas for Pascal and TeX. Later, a derivative system, cweb was created for the C programming language (with text still in TeX).

Full Literate Programming in the style of Knuth involves disconnecting the order of presentation to humans from the order of presentation to a machine. The input files written by the author/programmer are in an order convenient for instructing the reader, not necessarily in the order required to build an executable program. Programs then process the combined text/code input to create human-readable output (the program is called weave in Knuth's system), or compiler-appropriate output (tangle in web).

This module implements a very simple Literate Programming capability for Perl. Just as Perl's Plain Old Documentation (POD) is intended to be just powerful enough to be useful, and easy for the programmer, Literate Perl (LIP) is intended to bring the basic benefits of Literate Programming to Perl without radically altering the way programmers/authors work.

When you use LIP, you put the contents of your source file in the best order you can for exposition that does not interfere with its function. This may involve, for example, alphabetizing subroutines and/or grouping them by some criteria. Here is a simple example:

  #!/usr/bin/perl -w
  use strict;

  =begin lip

  =head1 NAME

  hello - LIP example

  =head1 IMPLEMENTATION

  Print a friendly message to standard output.

  =cut

  print "Hello, world!\n";

  exit 0;

  =end lip

  =cut

Running this program will have the expected result. Running it through lip2pod will select the internal documenation and include the code itself as verbatim paragraphs. This results in POD output that can be formatted nicely by one of the pod2* "podlators".

External documenation (like this) can be tacked on to the end of a file as usual. So, adding these lines to the end of the example above:

  __END__

  =head1 NAME

  hello - LIP example

  =head1 SYNOPSIS

    hello

  =head1 DESCRIPTION

  A simple example used to demonstrate the use of B<Lip::Pod> and B<lip2pod>.

  =cut

results in a single file that

• is executable; and

• contains internal documentation that can be formatted nicely (after conversion via lip2pod; and

• contains external documentation using the same mechanism as non-LIP files.

This module leverages the Pod::Parser and Text::Tabs modules. Pod::Parser is a standard module as of Perl version 5.6. For use with prior versions of Perl, download the latest copy from the CPAN.

REFERENCES

• Knuth, Donald Ervin. Literate Programming, Center for the Study of Language and Information, 1992. ISBN 0-987073-80-6 (paper).

AUTHOR

Gregor N. Purdy <gregor@focusresearch.com>

COPYRIGHT

This program is free software. You may copy or redistribute it under the same terms as Perl itself.