Interpolate Perl variables in POD

repellent has asked for the wisdom of the Perl Monks concerning the following question:

Replies are listed 'Best First'.
Re: Interpolate Perl variables in POD by toolic (Bishop) on Oct 01, 2008 at 01:46 UTC
I like the way you think, repellent; I have been wondering the same thing. Running a Super Search where title contains all of "pod", "variable" returned a couple of seemingly relevant nodes: Can a module's POD access the module's variables? variables in POD Perhaps they will give you some ideas.	[reply]
Re: Interpolate Perl variables in POD by JavaFan (Canon) on Oct 01, 2008 at 00:14 UTC
No, you cannot. POD code is skipped over by the `perl` compiler, and the Pod::* modules typically don't run the code at all.	[reply]
Re: Interpolate Perl variables in POD by GrandFather (Saint) on Oct 01, 2008 at 00:17 UTC
POD is not processed by the Perl interpreter in a fashion where interpolation makes sense (the interpreter parses POD just enough to ignore it). Programs that process POD do not parse Perl (except enough to ignore it) so don't have values for Perl variables. Perl reduces RSI - it saves typing	[reply]
Re^2: Interpolate Perl variables in POD by repellent (Priest) on Oct 01, 2008 at 01:04 UTC
OK. But could there be a way to instruct the POD modules with a directive to substitute when it sees `X<subst:keyword123>` in POD? Maybe up front: `use Pod::Subst qw(keyword123 replacement456)` [download] so that `pod2usage()` knows what to do. No Perl parsing need be involved. Thanks for the replies!	[reply] [d/l] [select]
Re^3: Interpolate Perl variables in POD by GrandFather (Saint) on Oct 01, 2008 at 01:11 UTC
You could post process the output from pod2usage() to do the substitutions. It would be smart to use a form of markup that is unlikely to be changed by the pod2usage() processing. Alternatively, you could preprocess the input to pod2usage() with the same caveat. Perl reduces RSI - it saves typing	[reply]
Re^4: Interpolate Perl variables in POD by repellent (Priest) on Oct 01, 2008 at 01:15 UTC
Re^5: Interpolate Perl variables in POD by GrandFather (Saint) on Oct 01, 2008 at 01:27 UTC
Re: Interpolate Perl variables in POD by jhourcle (Prior) on Oct 01, 2008 at 01:00 UTC
As JavaFan and GrandFather have already mentioned, no, you can't directly. However, there's nothing to stop you from generating a POD document from a perl script: `open (my $pod, '>', 'filename.pod') or die "Can't write pod file: $!"; my $my_perl_variable = 'something'; print $pod <<EOF; =head1 Imaginary Interpolation This was defined previously: C<$my_perl_variable> =cut EOF` [download] Of course, this would mean that you'd have to trigger the re-writing process somehow ... if you were to give an interface for updating whatever your variables were, you could regenerate the pod afterwards. I personally couldn't see the advantage of doing this, but I don't know what your full intentions are.	[reply] [d/l]
Re^2: Interpolate Perl variables in POD by repellent (Priest) on Oct 01, 2008 at 01:12 UTC
Upon writing a USAGE for a script, I would like for `pod2usage` to be updated dynamically as I maintain & update my code in the long term. A static USAGE means I would have to do manually update the POD when my code changes.	[reply] [d/l]
Re^3: Interpolate Perl variables in POD by GrandFather (Saint) on Oct 01, 2008 at 01:29 UTC
I run a script from within my editor to generate 'man pages' from the POD in the current buffer. Perl reduces RSI - it saves typing	[reply]
Re^2: Interpolate Perl variables in POD by snoopy (Curate) on Oct 01, 2008 at 06:30 UTC
Just as an aside. Embedded pod-like text in here-docs can accidentally be extracted from the source file as POD. This happens for me with the above code sample: `714680(1) User Contributed Perl Documentation 7 +14680(1) Imaginary Interpolation This was defined previously: $my_perl_variable perl v5.8.8 2008‐10‐01 + 714680(1)` [download]	[reply] [d/l]


Perl Monk, Perl Meditation
	PerlMonks