http://qs321.pair.com?node_id=904799


in reply to Re: POD troubles
in thread POD troubles

Simply searching perlpod for the word "empty" will show you more detailed information and should answer your questions.
Actually, no. The body of the doc indicates that pod paragraphs of all kinds are terminated by a blank line, but it doesn't say that you need a blank line before one in embedded POD. The end of the page does show the bit about "some older translators", but the first example that is implied to work on current translators shows =head paragraphs immediately after "plain" paragraph text (Correction: it's actually an =end, not a =head, but I meant to say "some command paragraph" and didn't recall which exactly), which contradicts the bulk of the documentation. Presumably the bulk of the document was not updated with new rules, when this example was tacked on to the end.

Other than passing reference in that appendix about apparently blank lines, it never states what a "blank line" is.

Searching through module versions and stuff on CPAN Search, it seems that pod2html is "core", so I don't know why I have "some old version". I don't know why the various POD checking doesn't report this as a problem.

It appears that I need an empty (not "blank"!) line in the host file before the embedded POD directive, and that a "command" paragraph (like =cut) cannot be run up against a "plain" paragraph. This is indicative of "some old parsers". But it's the one that matches the version of the documentation that makes that claim, isn't it?

Replies are listed 'Best First'.
Re^3: POD troubles
by LanX (Saint) on May 14, 2011 at 10:37 UTC
    > but the first example that is implied to work on current translators shows =head paragraphs immediately after "plain" paragraph text, which contradicts the bulk of the documentation. Presumably the bulk of the document was not updated with new rules, when this example was tacked on to the end.

    could you please post this "wrong" example, I can't find it.

    Cheers Rolf

      OK, it states:


      • Many older Pod translators require the lines before every Pod command and after every Pod command (including "=cut"!) to be a blank line. Having something like this:
          # - - - - - - - - - - - -
          =item $firecracker->boom()
          This noisily detonates the firecracker object.
          =cut
          sub boom {
          ...
      
      ...will make such Pod translators completely fail to see the Pod block at all.


      So, "many older translators" don't like that, but current ones do? Otherwise why bother mentioning it?

        sigh ... thank you for wasting my time!

        Cheers Rolf