3

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?

Jonas
  • 121,568
  • 97
  • 310
  • 388
bessarabov
  • 11,151
  • 10
  • 34
  • 59
  • I don't see `=end HTML` in the generated Pod? – Slaven Rezic Sep 22 '13 at 16:57
  • Yep, my mistake. I've edited the post. And here is the link to the generated pod: https://metacpan.org/source/BESSARABV/StatusBoard-Graph-1.0.0/lib/StatusBoard/Graph.pm#L408 – bessarabov Sep 22 '13 at 20:44
  • 2
    `=begin html`..`=end html` and `=for html` are basically synonymous, so nothing to worry about. However, the relocation of this paragraph might be a bug in `Pod::Weaver` and should probably be reported. – Slaven Rezic Sep 23 '13 at 06:50
  • "Basically" is not quite the problem, `=for html` requires all the html content occur on the same line before the `\n` at the end of line, while `=begin html` supports multiple `\n` in the content. Blithly translating one, to the other, while preserving `\n` causes invalid syntax. – Kent Fredric Nov 09 '13 at 21:59

1 Answers1

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

Kent Fredric
  • 56,416
  • 14
  • 107
  • 150