G'day Corion,

++ For the technique.

However, there is a problem with that code as written:

$ cat pm_1185726_heredoc_pod.pl
my $str = <<=cut;

=head2 Some documentation

=cut
$
[download]

$ perl -MO=Deparse pm_1185726_heredoc_pod.pl
Use of bare << to mean <<"" is deprecated. Its use will be fatal in Pe
+rl 5.28 at pm_1185726_heredoc_pod.pl line 1.
Can't modify scalar in scalar assignment at pm_1185726_heredoc_pod.pl 
+line 1, near "cut;"
pm_1185726_heredoc_pod.pl had compilation errors.
my $str = "" = 'cut';
$
[download]

Changing the <<=cut; to either <<"=cut"; or <<'=cut'; fixes the problem.

$ perl -MO=Deparse pm_1185726_heredoc_pod.pl
my $str = "\n=head2 Some documentation\n\n";
pm_1185726_heredoc_pod.pl syntax OK
[download]

[The POD is rendered fine in all cases with: perldoc pm_1185726_heredoc_pod.pl]

You can't interpolate variables into the POD text, only the value being assigned to the variable:

$ cat pm_1185726_heredoc_pod.pl
our $VERSION = '1.234';

my $str = <<"=cut";

=head2 Some documentation

Doco for version: $VERSION

=cut

print $str;
[download]

$ perldoc pm_1185726_heredoc_pod.pl
[download]

  Some documentation
    Doco for version: $VERSION

$ perl -wMstrict pm_1185726_heredoc_pod.pl

=head2 Some documentation

Doco for version: 1.234
[download]

Any sample code in the POD may well contain undeclared variables. These will generate "Global symbol "%s" requires explicit package name" compilation errors (when strict is in use) if the heredoc is interpolated.

For these two reasons, I'd suggest <<'=cut'; as the better default option (for code being used in the way shown).