[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