Bug#839167: perl: pod2man generates empty man page when pod file begins with =begin pod

[Russ Allbery]

Dominique Dumont <dod at debian.org> writes:

> Unfortunately, pod2man from perl 5.24 generates empty man page when pod
> file begins with =begin pod.  This worked fine with perl 5.22

> To reproduce:

> $ wget https://anonscm.debian.org/cgit/pkg-rakudo/pkg-rakudo.git/plain/docs/running.pod
> $ pod2man running.pod | nroff -man

> Only the header and footer are shown

> Workaround:
> $ perl -n -i -e 'print unless /=begin pod/' running.pod

> Then pod2man shows normal output.

> This behavior causes #839059 (empty man pages delivered by rakudo).
> Other packages may be affected.

> In the meantime I'll patch rakudo source to workaround this problem.

I believe the upstream author has fallen victim to relying on undocumented
behavior in Pod::Simple that's changed.

=begin pod does not do what they thought it was supposed to do.  (The
command they're looking for is =pod, not =begin pod.)  =begin starts a
block that should be ignored by any formatter that isn't producing the
output named by the argument to =begin, and generally the contents should
be used verbatim in the output.  The normal use is something like =begin
html followed by raw HTML that should be included in HTML-generated output
but not in any other format.

I believe that Pod::Simple internally treated =begin pod as a no-op and
interpreted the contents as regular POD at some point in the past, which
is why this was previously working.  (I haven't verified this, but I have
vague memories of it coming up before.)  But I don't think this was ever
documented (I just did a brief check of perlpod and perlpodspec), and it
appears to have changed.

Anyway, it doesn't seem to be serving any purpose here.  It seems to just
be a simple mistake, and =pod was intended.

-- 
Russ Allbery (rra at debian.org)               <http://www.eyrie.org/~eagle/>