1

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

Jonas
  • 121,568
  • 97
  • 310
  • 388
justintime
  • 3,601
  • 4
  • 22
  • 37

2 Answers2

6

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.

ephemient
  • 198,619
  • 38
  • 280
  • 391
  • @justintime, @ephemient: Indeed, once upon a time one could use this to trick things into going to both the compiler and to the podlator, since they have different criteria for deciding whether and how to consider podagraphs. – tchrist Nov 27 '10 at 14:35
  • =D@tchrist: man, in 1993 that was the coolest thing ever to have a perl script that was also its own manpage! =D – Ether Nov 27 '10 at 16:07
  • @Ether: Or in 1989. Notice the way `"ignite" while 1` elicits no warnings. It’s for `troff` support via `wrapman`. – tchrist Nov 27 '10 at 19:01
4

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.
Nikhil Jain
  • 8,232
  • 2
  • 25
  • 47