Re: Removal of specific Pod::Checker warnings

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