3

I have some POD documentation with a section that should be rendered differently in Latex (using pod2latex) and plain text/man. For this purpose, I have a =begin :text/=end :text section.

Now, I want to show individual sections of the POD on the command line (using Pod::Usage). And this is where the problem comes in: All the sections after the :text block come out garbled in this mode.

Here's a minimal example:

pod2usage(-verbose => 99, -sections => 'Two');

=head1 One

=begin text

For I<non-Latex> only.

=end text

=head1 Two

C<Formatting> all I<messed> up!

Output:

Two:
"Formatting"*messed*     all up!

Note that printing the whole POD (pod2usage(-verbose => 2); or just running perldoc on the file) works fine.

I have tried all the Pod::Usage options that I could find (including selecting a different Formatter class), but to now avail. If I remove the :text from the block (plain =begin/=end), it comes out all right with the section selection, but this is actually a POD syntax error, and perldoc complains about it when rendering the whole POD.

NB: My Perl is quite old (v5.18.2), but I am stuck with that version.

xebtl
  • 450
  • 4
  • 11
  • 3
    I can confirm, and no tweaking helped (adding text before/after the =begin...=end, removing formatting from inside it...). That's very unpleasant and I don't see how to circumvent it at all. It looks to me every bit as a bug (in `Pod::Usage`?). – zdim Jul 30 '21 at 19:13
  • 2
    Tried to figure it out by looking at the source but it is quite complicated. The code even warns you against it :) see [line 3](https://metacpan.org/release/KHW/Pod-Simple-3.43/source/lib/Pod/Simple/BlackBox.pm#L3) and [line 802](https://metacpan.org/release/KHW/Pod-Simple-3.43/source/lib/Pod/Simple/BlackBox.pm#L802) – Håkon Hægland Jul 30 '21 at 22:35
  • 2
    Added [bug report](https://github.com/Dual-Life/Pod-Usage/issues/18) – Håkon Hægland Aug 03 '21 at 12:34

1 Answers1

3

This looks like a bug in Pod::Usage. I found a workaround by looking at the source code. It seems that the internal stack of Pod::Simple gets messed up due to a missing sub cmd_for. By adding a dummy sub cmd_for manually it seems to work:

use feature qw(say);
use strict;
use warnings;

use Pod::Usage;
{
    no warnings 'once';
    *Pod::Usage::cmd_for = sub { };
}

pod2usage(-verbose => 99, -sections => 'Two');

=head1 One

=begin text

For I<non-Latex> only.

=end text

=head1 Two

C<Formatting> all I<messed> up!

Output:

Two:
    "Formatting" all messed up!
Håkon Hægland
  • 39,012
  • 21
  • 81
  • 174
  • Nice! How do you get it to print text under `=begin text ... =end text`? I remove `-sections` option and change verbose to `2` -- trying to print all documentation -- but the `text` isn't printed? – zdim Aug 02 '21 at 17:06
  • @zdim Yes you are right it does not work for all the text. I have updated my answer with another approach. – Håkon Hægland Aug 02 '21 at 18:18
  • Wow, you really went all out, thanks! The earlier solution also worked for me, sort of, but required an ugly hack to get the `text` section to print where it was needed. I will try the new approach soon. – xebtl Aug 03 '21 at 15:56