[Purdue-pm] Variables in POD docs
Rick Westerman
westerman at purdue.edu
Wed Dec 3 07:53:17 PST 2014
There is no doubt that POD is not very powerful. I am not overly fond of it myself. But it is universal and widely accepted. Given that I force myself to use it. If I could define Perl variables and insert them into POD instead of vice-versa then I would do that. But it just isn’t possible.
--
Rick Westerman
westerman at purdue.edu
> On Dec 3, 2014, at 10:49 AM, Mark Senn <mark at ecn.purdue.edu> wrote:
>
> 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";
>
> =====
>
> -mark
More information about the Purdue-pm
mailing list