[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