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
