Search code examples
perlperl-pod

When are blank lines needed in Perl POD documentation


I have noticed that a lot of Pod has blank lines between the lines such as

    code

    =head1 DESCRIPTION

    text

Are these blank lines strictly needed, do specific parsers get upset if it is missing.

The description for cut in perlpod helps a little but I was wondering about other constructs :

To end a Pod block, use a blank line, then a line beginning with "=cut", and a blank line after it. This lets Perl (and the Pod formatter) know that this is where Perl code is resuming. (The blank line before the "=cut" is not technically necessary, but many older Pod processors require it.)


Solution

  • perldoc perlpod says that "every command needs the blank line after it, to end its paragraph" and "Many older Pod translators require the lines before every Pod command and after every Pod command (including "=cut"!) to be a blank line".

    Paragraphs are delineated by blank lines, so I find it difficult to imagine starting a command paragraph without a blank line immediately preceding it. Maybe at the start of a file?

    Note that in Perl 6, Pod is redefined so that blank lines around commands (before and after) are no longer necessary.