Re: Removal of specific Pod::Checker warnings

On 08/11/2011 12:54 PM, Ricardo Signes wrote:
> * Marc Green<[email protected]>  [2011-08-11T06:40:17]
>>
>> perlpodspec states "Pod processors must tolerate a bare "=item" as if it
>> were "=item *"." Is Pod::Checker's behavior still in line with perlpodspec?
>> Is the use of '=item' without any parameters deprecated? Or should that
>> warning be removed from Pod::Checker?
>
> Pod::Checker's behavior isn't wrong, but its claims are.  It says:
>
>    "=item" without any parameters is deprecated
>
> No, it isn't.  Maybe somebody wishes that it was, but it isn't.  It sounds like
> nobody thinks it needs to be.  I think it's fine for Pod::Checker to have
> opinions of style, in some cases, but I don't think this makes any sense.  The
> meaning of "=item" is well-documented.  I think the warning can and should go.

+1

>
>> Given that there is clearly a use for =itemless =over/=back blocks, should
>> it still be a warning? I think no, and instead, Pod::Checker should warn
>> about an empty =over/=back block, one that contains nothing but whitespace.
>
> You've already heard my opinion on this one, but for everyone else:  I think
> this warning is bogus.  =over/=back without =item is well-documented.  Some
> formatters don't handle it correctly, but better to fix them than to suggest
> that this is in any way problematic Pod.
>
> If someone wants to come forward and tell us that, say, the four most-used Pod
> formatters will actually *lose* these sections, that's a different matter.  But
> that isn't my experience.
>

I agree with this that there shouldn't be a warning if there are things 
within the =over/=back that aren't =item's.  I'm not sure about if there 
is only white space.  I could be persuaded it is a useful warning, which 
Marc was originally going to implement; or I could be persuaded it is 
not worth warning about.  The Perl core has several cases where 
machine-generated pods have empty =over/=back sections.  These mean only 
that there was a potential section that the generating code wasn't smart 
enough to realize was empty here, and omit the surrounding pod directives.

Just FYI, I implemented several additional checks in the core's pod test 
program, podcheck.t, that I think may warrant being used everywhere. 
These are:
  Should have =encoding statement because have non-ASCII
  =encoding must be first command (if present)
  There is no NAME