Re: Removal of specific Pod::Checker warnings

[Karl Williamson]

On 08/11/2011 12:54 PM, Ricardo Signes wrote:

* Marc Greenpongu...@gmail.com  [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

Re: Removal of specific Pod::Checker warnings

[David E. Wheeler]

On Aug 12, 2011, at 9:17 AM, Karl Williamson wrote:

 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.

I think warning on a completely empty =over/=back block is reasonable.

 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

Can one not change the encoding throughout a document by using multiple 
=encoding tags? This tag just means everything after this tag is in the named 
encoding.

Er, reading perlpodspec:

A document having more than one =encoding line should be
considered an error.  Pod processors may silently tolerate this if
the not‐first =encoding lines are just duplicates of the first
one (e.g., if there’s a =encoding utf8 line, and later on another
=encoding utf8 line).  But Pod processors should complain if
there are contradictory =encoding lines in the same document
(e.g., if there is a =encoding utf8 early in the document and
=encoding big5 later).  Pod processors that recognize BOMs may
also complain if they see an =encoding line that contradicts the
BOM (e.g., if a document with a UTF−16LE BOM has an =encoding
shiftjis line).

That seems like an unnecessary limitation to me, though it is perhaps sanest.

Anyway, I think it might be worth integrating such changes into Pod::Checker 
later. Maybe once Marc's done with the conversion to Pod::Simple you'd like to 
adapt podcheck.t to use it?

Best,

David