[Purdue-pm] Variables in POD docs

Mark Senn mark at ecn.purdue.edu
Wed Dec 3 08:30:00 PST 2014


Rick Westerman <westerman at purdue.edu> wrote on 2014-12-03 at 08:19-0500

|  Found an interesting way to embed variables into pod.  You might want
|  this so you could report the VERSION both inside pod plus as $VERSION.
|  But you could also do this for exported modules.  You could make a list
|  of routines plus their descriptions to be shown in pod plus have them in
|  the actual @EXPORT thus avoiding the need have the routine listed twice
|  ---and potentially missing the documentation when a new routine is added
|  to the module.  Another use is to show a hash or array inside pod.
|
|  I'll probably give a short talk on this at the next Mongers meeting.
|  Dave, in the meantime, could look at my recent PI.pm module for concrete
|  examples.
|
|  The idea is to do a here-is capture of the POD comments and then parse
|  out the Perl-runtime information from the captured doc.  There is a
|  small run-time hit in doing the parsing but I do not think that the hit
|  is significant and the ability to not have to have information in two
|  places is powerful.  A short example:
|
|  =====
|
|  my $version_pod = <<'=cut';
|
|  =head1 VERSION 1.0
|
|      Complete re-write to use database and to be more stable.
|
|  =cut
|
|  our ($VERSION) = $version_pod =~ m/VERSION\s+(.*)/;
|
|  =====

I like to define things top down instead of from the inside out.
I don't like POD, I like to use my pro file preprossor along
with LaTeX typesetting system software for tasks like this---it
gives me more power and control.  Below is a short example of
one way it can be done.

=====

:: Start Perl program.
#!/usr/local/bin/perl

:: Give some gratuitous Emacs advice.
::
:: I set up my .emacs file so typing Control-C Control-D inserts, for example,
::     z.pl  2014-12-03  Mark Senn'
:: if a string like that doesn't exist.  If a string like that does exist
:: it updates the date in the first matching string.
.$revised = 'z.pl.pro  2014-12-03  Mark Senn'
.$created = 'z.pl.pro  2014-12-03  Mark Senn'

:: Define version in outermost scope.
.$version = '1.0'

:: Compute LaTeX file name.
.($latexfile) = $revised =~ m#^(^[^.]+)#
.$latexfile .= '.tex'

:: Produce rest of LaTeX input.
.divert $latexfile
\head1{VERSION .<$version>}

    Complete re-write to use database to be more stable.
.revert

:: Produce rest of Perl program.
print "version is $version\n";

=====

If you don't need the full power of pro and LaTeX but would still
like to defie things in a "top-down" way do a google search for
    perl preprocessor

-mark


More information about the Purdue-pm mailing list