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

I have a perl script (generatePODs.pl) to generate POD files for a set of other perl scripts. In the script, I do something like the following: 
    print DOCFILE <<"DOCS";
=pod

=head1 NAME

$programName
...

DOCS

[download]
However, when do a perldoc on my script itself 
perldoc generatePODs.pl

[download]
perldoc picks up the POD inside the heredocs and puts it before the POD for the generation script. 
GENERATEPODS(1)       User Contributed Perl Documentation      GENERAT
+EPODS(1)

NAME
       $programName
......

NAME
       generatePODs.pl

DESCRIPTION
       This program generates PODs

[download]
I looked at the perldoc and pod2man man pages and it was not clear to me as to how to make perldoc ignore the POD embedded inside the heredoc. How can I do that?

Replies are listed 'Best First'.
Re: Ignoring embedded POD
by toolic (Bishop) on Jul 18, 2013 at 13:57 UTC
    I can't think of a way to get perldoc to ignore your embedded POD, but here are a couple of possible workarounds.

    1. Store your POD in a separate file, then read that file into your script.

    2. Create pseudo-POD in a variable, then process the variable before using it: 

    use warnings;
use strict;

my $p = '
==pod

==head1 NAME

programName
...

==cut
';

$p =~ s/^==/=/g;

print "$p\n";

    [download]
[reply]
[d/l]
      Let me see if I can do the workarounds. Thanks
[reply]
Re: Ignoring embedded POD
by BrowserUk (Patriarch) on Jul 18, 2013 at 14:37 UTC

    Put a leading space (or multiple) on your heredoc lines and regex them away before printing: 

    $_ = <<"DOC"; s/^ //msg; print;
 =pod
 stuff here
 =cut
DOC
;;
=pod
stuff here
=cut

    [download]

    Or maybe comment cards would be better? 

    $_ = <<"DOC"; s/^#//msg; print;
#=pod
#stuff here
#=cut
DOC
;;
=pod
stuff here
=cut

    [download]
    With the rise and rise of 'Social' network sites: 'Computers are making people easier to use everyday'
    Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
    "Science is about questioning the status quo. Questioning authority".
    In the absence of evidence, opinion is indistinguishable from prejudice.
[reply]
[d/l]
[select]
Re: Ignoring embedded POD
by choroba (Cardinal) on Jul 18, 2013 at 20:10 UTC
    If you are using double quotes for the heredoc, you can just store the pod directives in scalar variables: 
    my $pod   = '=pod';
my $head1 = '=head1'; 
print DOCFILE <<"DOCS";
$pod

$head1 NAME

$programName
...

DOCS

    [download]
    لսႽ† ᥲᥒ⚪⟊Ⴙᘓᖇ Ꮅᘓᖇ⎱ Ⴙᥲ𝇋ƙᘓᖇ
[reply]
[d/l]
      Hashified... perlpod 
      use warnings;
use strict;

my %pod = map { $_ => "=$_" } qw(
    pod head1 head2 head3 head4 over item
    back begin end for encoding cut
);

print <<"DOCS";
$pod{pod}

$pod{head1} NAME

programName
...

DOCS

      [download]
[reply]
[d/l]
Re: Ignoring embedded POD
by rjt (Curate) on Jul 18, 2013 at 14:20 UTC
    I looked at the perldoc and pod2man man pages and it was not clear to me as to how to make perldoc ignore the POD embedded inside the heredoc. How can I do that?

    I'm not aware of any way to do so. Creating a parser that could ignore POD in quoted text would require a way to recognize quoted text, which would require parsing Perl source. Even if one succeeded in such an effort, it would only work for tools that used it. Syntax highlighting in most text editors would still barf, as would most any other POD-aware tool. I personally wouldn't want to maintain a source file with two or more sets of POD in it, either.

    What I would suggest is to store the POD file as an external template and use Text::Template for easy flexible interpolation.

[reply]
Re: Ignoring embedded POD
by derobert (Initiate) on Jan 25, 2020 at 19:06 UTC
    As of Perl 5.26, heredocs can be indented without tricks to strip them: 
    use 5.026;
my $something = <<~'HERE';
    =head1 Ignore me

    This doesn't look like pod to perldoc anymore.

        $var = 'foo'; # you can still indent things

    =cut

    HERE
print $something;

    [download]
    Perl determines how much whitespace to remove by the indent of the end-of-heredoc marker ("HERE" in the example).
[reply]
[d/l]

Back to Seekers of Perl Wisdom