http://www.perlmonks.org?node_id=904813


in reply to Re^3: POD troubles
in thread POD troubles

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?

Replies are listed 'Best First'.
Re^5: POD troubles (RTFM)
by LanX (Saint) on May 14, 2011 at 11:21 UTC
    sigh ... thank you for wasting my time!

    Cheers Rolf

      I don't follow. This passage implies that this is supposed to work (except on "some old translators"), but it contradicts the bulk of the document which states that paragraphs must be followed by (actually, terminated with) a blank line.

      I was indeed reading the fine manual, read it end to end several times, and cross-checked versions 10.1 and the current 12.whatever. My observation stands: the example which is implied to work as-is on current translators contradicts the description given earlier. If it's not intended to work, why explain that it must be changed for "older" parsers? If it never works at all, it's a silly thing to say.

      I think I can afford the -- vote. But I think it's unwarranted, after re-reading my post.

        see Counterexample

        Cheers Rolf

        UPDATE:

        Hints for Writing Pod

        ...

        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.

        Instead, have it like this:

        # - - - - - - - - - - - - =item $firecracker->boom() This noisily detonates the firecracker object. =cut sub boom { ...

        from perlpod, underlines added

        UPDATE:

        > perldoc perlpod |grep -2n " empty "|sed 's/ / /' 488- 489- You can embed Pod documentation in your Perl modules and scripts +. 490: Start your documentation with an empty line, a "=head1" command +at the 491: beginning, and end it with a "=cut" command and an empty line. +Perl 492- will ignore the Pod text. See any of the supplied library modul +es for 493- examples. If you’re going to put your Pod at the end of the fil +e, and -- 501- Time::Local - efficiently compute time from local and GMT time 502- 503: Without that empty line before the "=head1", many translators wo +uldn’t 504- have recognized the "=head1" as starting a Pod block. 505- -- 553- · Some older Pod translators require paragraphs (including com +mand 554- paragraphs like "=head2 Functions") to be separated by compl +etely 555: empty lines. If you have an apparently empty line with some + spaces 556- on it, this might not count as a separator for those transla +tors, 557- and that could cause odd formatting.