[doc] perldoc misses a single =pod

[jidanni]

perlpod says

  "=pod"
      The "=pod" command by itself doesn't do much of  anything,  but  it
     signals  to Perl (and Pod formatters) that a Pod block starts here.
     A Pod block starts with any command paragraph, so a "=pod"  command
     is  usually  used  just  when you want to start a Pod block with an

$ cat e.pl
=pod

bla

=cut
$ podchecker e.pl
e.pl pod syntax OK.
$ touch f.pl
$ podchecker f.pl
$ f.pl does not contain any pod commands.
$ perldoc e.pl
No documentation found for "/tmp/e.pl".

One needs e.g., a =head1 to wake perldoc up that there are =pod's on
the page. Then is prints them all like it should. Even the ones before
the =head1.

[jkeenan]

perlpod says

  "=pod"
      The "=pod" command by itself doesn't do much of  anything,  but  it
     signals  to Perl (and Pod formatters) that a Pod block starts here.
     A Pod block starts with any command paragraph, so a "=pod"  command
     is  usually  used  just  when you want to start a Pod block with an

$ cat e.pl
=pod

bla

=cut
$ podchecker e.pl
e.pl pod syntax OK.
$ touch f.pl
$ podchecker f.pl
$ f.pl does not contain any pod commands.
$ perldoc e.pl
No documentation found for "/tmp/e.pl".

One needs e.g., a =head1 to wake perldoc up that there are =pod's on the page. Then is prints them all like it should. Even the ones before the =head1.

Are you claiming that podchecker is giving misleading results? Or that the perldoc executable is defective in some way? Both? Please clarify.

Note that whichever case it is, this ticket will probably have to be re-filed upstream, as both the Pod-Perldoc and Pod-Checker distributions are primarily maintained on CPAN.

[jidanni]

OK, I made perldoc bug https://rt.cpan.org/Public/Bug/Display.html?id=150659

[briandfoy]

Each pod translator decides what it wants to handle. Pod::Perldoc has decided not to handle bare Pod like this, and it wouldn't be good to change that since =pod is one way that we fake multiline comments. People would be suddenly surprised to see these processed.

[jidanni]

and it wouldn't be good to change that since =pod is one way that we fake multiline comments. People would be suddenly surprised to see these processed.

OK, but that surprise is exactly what will happen to people, who, comforted by this example on perlpod,

        =pod

         Remember to check its return value, as in:

if one day the put a "=head1" etc. into their file.

Then voosh, all the stuff they thought "=pod" would keep quiet then all becomes quite public.

Therefore the perlpod man page needs to mention that

The use of "=pod" for comment blocks only is guaranteed if there is no =head1 through 6 in your file. Once a =head1 through 6 appears in the file, the power of =pod to keep comments out of the output is gone, even on the part of the file preceding the =head1 through 6. So don't count on it to hide things in all cases.

[briandfoy]

This repo is the wrong place to track this issue. You can make an issue in briandfoy/pod-perldoc.