in reply to Re^6: POD troubles (RTFM)
in thread POD troubles

see Counterexample

Cheers Rolf


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


> 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.

Replies are listed 'Best First'.
Re^8: POD troubles (RTFM)
by John M. Dlugosz (Monsignor) on May 14, 2011 at 12:08 UTC
    Right. older translators don't like that. Write it as below if you intend such older translators to be able to swallow it.

    It doesn't say "POD files can't do this." It says "Many older Pod translators...". Meaning that others don't. "will make such Pod". Not "will never work", but will make (only) those old nasty ones fail. That is, it's not backward compatible.

    I don't see it meaning anything else. It's not like one of those cube pictures where it snaps into something different once you realize what was meant... it's saying that this example is not backward compatible, NOT that it's illegal.

    Arguing is pointless. Clearly it is either wrong or at least capable of being misinterpreted by someone who read it carefully.

      The documentation can't be clearer, it says that newer translators try to be more fault tolerant and is also explicit with counterexamples.

      See my last post for according passages.

      your problems are

      1. that you didn't expect core pod2html to be one of such older translators ... well welcome in the world of a >20 years old open-source project where backwards compatibility dominates.

      2. that you want that a tunnel view on a single paragraph already includes the information of a whole man-page.

      Cheers Rolf

      PS: I'm off!