http://www.perlmonks.org?node_id=714673

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

Just curious here -- this may have been asked before:

Is there a way to interpolate (read: substitute) variables in POD such that it will apply to all Pod::* modules? Perhaps something like:
=head1 Imaginary Interpolation

This was defined previously: X<$my_perl_variable>

=cut

[download]

Basic scalar-lookup substitution would be nice. I use pod2usage() and would like some dynamic capability in POD.

Replies are listed 'Best First'.
Re: Interpolate Perl variables in POD
by toolic (Bishop) on Oct 01, 2008 at 01:46 UTC
[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]
      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]

        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: 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]
      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]

        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]
      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&#8208;10&#8208;01              
+           714680(1)

      [download]
[reply]
[d/l]

Back to Seekers of Perl Wisdom