Dominique Dumont <d...@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 (r...@debian.org) <http://www.eyrie.org/~eagle/>
