CODEWITHSUNDEEP
perlperl-pod
justintime
justintime

Reputation: 3631

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

Upvotes: 1

Views: 680

Answers (2)

Nikhil Jain
Nikhil Jain

Reputation: 8342

Please note that POD has the notion of "paragraphs": this is something starting after a blank (read: empty) line, with the single exception of the file start, which is also starting a paragraph. That means that especially a command (e.g. =head1 ) must be preceded with a blank line; END is not a blank line.

  • see perlpodspec also, you will find the reason why blank lines needed.

Upvotes: 4

ephemient
ephemient

Reputation: 204778

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.

Upvotes: 6

Related Questions