Hi Sean,
You are right that Pod::Simple has problems with multiline POD strings
contained into a variable or heredoc section:
https://rt.cpan.org/Ticket/Display.html?id=36404
https://rt.cpan.org/Ticket/Display.html?id=69390
In that second link, David Wheeler wrote that the simplest workaround is
to escape POD directives in the string, as in:
> my $var =<<EOS;
>
> \=head1 FAKE_POD_ENTRY_HERE
>
> This should not be extracted as POD since it is the content of a variable
>
> \=cut
>
> EOS
This workaround works great for me. See for example
http://getopt-euclid.git.sourceforge.net/git/gitweb.cgi?p=getopt-euclid/getopt-euclid;a=blob;f=t/std_arguments.t;h=716cf0f8241018328c8e5a04c4878f16a299df54;hb=refs/heads/0.2.x
Regards,
Florent
On 21/02/12 10:30, Sean M. Burke wrote:
As I look in Pod::Simple's ./t/ dir...
Gawd those tests I made with \n\n's in them, with like ten lines
squooshed into one blob with \n\n\n etc, like this:
print "#\n# Tests for simple =item *'s\n";
ok( $x->_out("\n=over\n\n=item *\n\nStuff\n\n=item *\n\nBar
I<baz>!\n\n=back\n\n"),
'<Document><over-bullet
indent="4"><item-bullet>Stuff</item-bullet><item-bullet>Bar
<I>baz</I>!</item-bullet></over-bullet></Document>'
);
...are horrible!!
I mean, I guess this is okay:
ok( Pod::Simple::XMLOutStream->_out("\n=head1 =head1\n"),
'<Document><head1>=head1</head1></Document>'
);
But it started with that and just kinda went down that path and kept going.
Now, THERE IS A REASON. But not a great one!
I think I *wanted* to be a sane person and use
q{
=over
=item *...
...
=back
}
But:
1) I worried that Perl, in running the program that constitutes this
test, would try to parse that as actual pod! It's not supposed to, I
think, but... But but but.
Ditto with <<EOPOD stuff, which (come to think of it) looks better than
a many-line q{...} thing.
2) Especially: I think was I worried about what newline format this test
file might be in, and so, I worried what newline format would appear in
that q{...}. Recall that MacPerl = \cm, Unix = \cj, some other stuff =
\cm\cj, and it's all messy and hurts my head.
However, NOW it occurs to me that I could have worked around BOTH
problems by just having a dummy | or whatever (a backtick, a ~,
anything) in the first column of every line, like so...
And to an inverse problem, the trouble of XML blobs that contain
newlines...
Here, this should be a cure for what ails ya.
First pod as a straight string literal, then as a |-thing in a q{...},
then as a |-thing inside a HERE-doc, calling unbar.
Then XML as a straight string literal (well, three concatted together),
then as a |-thing in a q{...}, then as a |-thing inside a HERE-doc,
calling no_nls.
use strict; use warnings;
my $pod_really =
"\n\n=over\n\n=item *...\n...\n\n=back\n\nStuff whatever.\n\n";
my $pod_q_ish = unbar( q{
|
|=over
|
|=item *...
|...
|
|=back
|
|Stuff whatever.
|
}
);
my $pod_here_ish = unbar( <<EOP
|
|=over
|
|=item *...
|...
|
|=back
|
|Stuff whatever.
|
EOP
);
# Trying |-initial lines
print "Pod_Really and Pod_Q_ish differ!\n\n",
"{$pod_really}\n\n{$pod_q_ish}\n\n" unless
$pod_really eq $pod_q_ish;
print "Pod_Really and Pod_Here_ish differ!\n\n",
"{$pod_really}\n\n{$pod_here_ish}\n\n" unless
$pod_really eq $pod_here_ish;
# Now XML
my $xml_really =
qq[<Document><over-bullet indent="4"><item-bullet>]
.qq[Stuff</item-bullet><item-bullet>Bar <I>baz</I>!]
.qq[</item-bullet></over-bullet></Document>]
;
my $xml_q_ish = no_nls( q[
<Document><over-bullet indent="4"><item-bullet>
Stuff</item-bullet><item-bullet>Bar <I>baz</I>!
</item-bullet></over-bullet></Document>
]);
my $xml_here_ish = no_nls( <<EOX
<Document><over-bullet indent="4"><item-bullet>
Stuff</item-bullet><item-bullet>Bar <I>baz</I>!
</item-bullet></over-bullet></Document>
EOX
);
print "XML_Really and XML_Q_ish differ!\n\n",
"{$xml_really}\n\n{$xml_here_ish}\n\n" unless
$xml_really eq $xml_q_ish;
print "XML_Really and XML_Here_ish differ!\n\n",
"{$xml_really}\n\n{$xml_here_ish}\n\n" unless
$xml_really eq $xml_here_ish;
print "End."; # <--- should be the only thing said.
sub unbar {
my($x) = join '', @_;
for($x) {
#Break where a '|' follows anything newline-ish:
#
s<\A\|><\n\|>;
# ^^ Degen case: where a | is the very first character.
s<[\cm\cj]+\|><\n>g; # Now for real.
}
return $x
}
sub no_nls { # returns, minus any newlines
my $n = join '', @_;
$n =~ s/[\cm\cj]+//g;
return $n;
}
__END__
That should run without saying anything about differing.
Use it, adapt it, or not, it's up to you to figure out what makes things
less like Lovecraftian camouflage to your programmery eyes.
(As with vast vast areas of my life, I have to mark this unbar and
no_nls things as another (now decade-old) pesky occurrence of: "Now,
you'd THINK that I would have thought of that!")
But whether the subject is myself, or anything else in the world, I have
noticed that the phrase "Now, you'd THINK..." have had a pretty sad
track record lately AMIRITE??
