| Subject: | pod2usage() -sections omits marked-up text from =head lines |
| Date: | Sat, 17 Jan 2015 00:55:02 GMT |
| To: | bug-Pod-Usage [...] rt.cpan.org |
| From: | karl [...] freefriends.org (Karl Berry) |
Hi - running this small self-contained program, including a little pod
at the end:
--------------------------------------------------
#!/usr/bin/env perl
use strict;
use warnings;
use Pod::Usage;
pod2usage(-exitstatus => 0,
-verbose => 99,
-sections => 'ACTIONS/back.*',
-noperldoc => 1);
__END__
=head1 ACTIONS
Para for actions.
=head2 backup I<pkg> B<please> dest
Para for backup.
--------------------------------------------------
gives me this unexpected output, with the marked-up "pkg" and "please"
text on the head2 line missing:
--------------------------------------------------
backup dest:
Para for backup.
--------------------------------------------------
That is, I'm trying to use markup on a head2 line, and then select it
with pod2usage's -section option. The marked-up text is omitted from
the output, while the regular text comes out fine.
Perhaps this is beyond the scope of what pod2usage is intended to do,
but I couldn't find anything either explicitly disallowing or allowing
it in the Pod::Usage documentation, and the POD documentation does
explicitly say that formatting codes are allowed on header lines.
Incidentally, the -noperldoc => 1 is there just to eliminate the
possibility of interactions with pagers or the like. It doesn't actually
change the behavior, so far as I can see.
This is only about the pod2usage() function. The output from the
pod2text and pod2html utilities, for example, correctly includes the
marked-up text (again, "pkg" and "please" in the above). (Well, the
table of contents from the pod2html output has the text without any
actual markup ("pkg" rather than "<i>pkg</>"), but that seems fine.)
I tried enabling the use constant DEBUG => 7 in Pod/Simple/BlackBox.pm
and could see that the markup got parsed and returned as nested lists
(as expected). At what level the marked-up text gets elided, I could
not discern without putting in lots more effort. I submitted the
questions to perlmonks (http://perlmonks.org/index.pl?node_id=1113163)
and the only suggestion was to report it as a bug, so here I am.
This was on i686-linux with perl 5.20.1, compiled (with gcc 4.9.2) and
installed from the original source; Pod/Usage.pm has $VERSION='1.63'.
I tried a variety of older Perl versions, both distro-supplied and my
compilations, with the same results (or, if old enough, -sections is not
supported).
Of course I'm happy to supply more information or help debug in any way
I can, etc. Thanks for all your work.
Karl (karl@freefriends.org)