How to add HTML section in Perl POD using Pod::Weaver

Question

I use Pod::Weaver with Dist::Zilla. It does several good things for me. It adds POD section VERSION, AUTHOR, LICENSE automatically, and in my source code I can use simple POD syntax, I can write "=method new" and it will be converted to correct POD.

Now I wanted to add an image to the POD. To do it I need to add some HTML. So I'm writing in my source code:

=begin HTML

<p>
<a href="http://upload.bessarabov.ru/bessarabov/031VBX4pHw_ALPcxRTVjflnAWuc.png">
<img src="http://upload.bessarabov.ru/bessarabov/VdagpUXEQdMslOqUyOAzwa-DOaU.png" width="500" height="125" alt="Status board graph sample" />
</a>
</p>

=end HTML

Then I write dzil release and release the module on CPAN. After uploading to CPAN I recognize that my HTML POD was changed by Pod::Weaver and now it looks like:

=for HTML <p>
<p>
<a href="http://upload.bessarabov.ru/bessarabov/031VBX4pHw_ALPcxRTVjflnAWuc.png">
<img src="http://upload.bessarabov.ru/bessarabov/VdagpUXEQdMslOqUyOAzwa-DOaU.png" width="500" height="125" alt="Status board graph sample" />
</a>
</p>

And this HTML part has been moved in the POD. I wanted it to be just after SYNOPSIS part, but not it is after the last method.

I still want to use Pod::Weaver, because it does a lot of good things, but I want HTML to be put in the exact place of the POD and not to be converted.

How can I do it?

Answer 1

After much reading of perldoc perlpod and testing, the following things are apparent:

1. According to spec, =begin html segments can be translated safely to =for html segments.
2. However, this may only occur when the body of the segment contains segments that are grouped in paragraphs. So foo\nbar can be translated, but foo\n\nbar cannot.
3. The module that is doing the transformation from =begin to =for, when seeing a double \n in its body, refuses to emit =for, and instead, reverts to emitting =begin.

Given what number 3 Here is, If you want to force it to emit =begin html, simply spicing it up with a few extra \n's will do the trick.

However, the problem remains, that for whatever reason, what appears to be valid POD format given, is not rendering as intended.

Either

• A. The Pod2HTML layer is not coded right to respond to =for ( in which case, a few extra \n's to force an =begin may help.
• B. There's a security level thats preventing you from using complex HTML ( which may entail hyperlinks in images, which could be an XSS security threat )

If the problem is B, then you're not going to get around that by being tricky.

Though I assure you, displaying images IS doable, I do it myself