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 {
            ...
[download]

...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 {
            ...
[download]

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.
[download]