perlperl-pod

Pod::Usage: `=begin :text`/`=end :text` messes up formatting


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.


Solution

  • 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!