Huh? Whassup with perldoc?

locked_user sundialsvc4 has asked for the wisdom of the Perl Monks concerning the following question:

I put comments in my module, like this:


=head2 $identity = identify_file($filename)

Returns a string that identifies what kind of file the parser thinks a
+ file is.  Returns one of:

=over
=item 'SCHEDULE'
=item 'JOB'
=item C<undef>
=back

This is the most amazing software known to man.
        
=cut
(blah blah blah)
=head2 Another amazing routine
[download]

But perldoc is unhappy:

POD ERRORS
  Hey! The above document had some coding errors, which are
  explained below:

  Around line 199:
    =over should be: '=over' or '=over positive_number'

  Around line 228:
    You forgot a '=back' before '=head2'
[download]

The trouble is... I didn’t. I have no earthly idea why perldoc does not like the =over clause as-written; nor why it thinks that the =back statement isn’t there. These messages appear to me to be “nonsense.”

...But I know that I am “merely unenlightened.” And so I humbly beseech the Monks for wisdom on this matter...

Replies are listed 'Best First'.
Re: Huh? Whassup with perldoc? by MidLifeXis (Monsignor) on Sep 28, 2010 at 14:39 UTC
See the section on `=cut` in perlpod. The blank line after the pod command is required. --MidLifeXis	[reply] [d/l]
Re: Huh? Whassup with perldoc? by ig (Vicar) on Sep 28, 2010 at 18:31 UTC
From perlpod near the end of section Command Paragraph And don’t forget, when using any command, that the command lasts up until the end of its paragraph, not its line. So in the examples below, you can see that every command needs the blank line after it, to end its paragraph.	[reply]
Re: Huh? Whassup with perldoc? by ikegami (Patriarch) on Sep 28, 2010 at 14:37 UTC
Like the error message says, `=over` must be followed by a positive number. See perlpod. As for the second error, it might be caused by the parser being messed up by the first error. Whenever something issues more than one error message, error messages after the first are often unreliable.	[reply] [d/l]
Re^2: Huh? Whassup with perldoc? by MidLifeXis (Monsignor) on Sep 28, 2010 at 14:43 UTC
if there is no indentlevel option, it defaults to four. It should default to 4 according to perlpod. I am not finding a requirement for newlines before and after the POD commands~~, so apparently I have been cargo culting that in my code~~. However, I seem to remember some POD formatters working incorrectly if the newlines were omitted. Update: Perhaps calling the `=FOO` commands command paragraphs implies that there is a blank line before and after. The documentation for cut explicitly states that The blank line before the "=cut" is not technically necessary, but many older Pod processors require it.. I can not find any other language in my brief scan for other command paragraphs that speaks to whitespace before and after. If this is truly the intent, perhaps a POD change is in order. I will put this on my (long) todo list. If someone else gets to it ahead of me (probably very easy to do), I will not take offense ;-). Update 2: Per ig's post, paragraphs are defined as having newlines between them. So it is in the docs, it just could possibly be clearer. --MidLifeXis	[reply] [d/l]
Re: Huh? Whassup with perldoc? by locked_user sundialsvc4 (Abbot) on Sep 28, 2010 at 19:06 UTC
“Behold, I have seen the error of my ways,” he said, with a curiously `blank` expression. `;-)` “I humbly thank the Monks, once again.”