Re: Removal of specific Pod::Checker warnings

On Thu, Aug 11, 2011 at 06:40:17AM -0400, Marc Green wrote:
> Hello Pod People,
> 
> I am emailing to provoke discussion on two warnings that Pod::Checker
> displays that I think should be removed.
> 
> Pod::Checker currently warns if there is an '=item' directive with no
> argument (as opposed to '=item *', for example). The description of the
> warning is:
> 
> "=item without any parameters is deprecated. It should either be followed by
> * to indicate an unordered list, by a number (optionally followed by a dot)
> to indicate an ordered (numbered) list or simple text for a definition
> list."
> 
> 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?

I think raw =item sounds useful and should probably be supported.

However from previous podchecker experiments I don't think it's common.

> The second Pod::Checker warning I am emailing about is "No =items in =over",
> which is explained as "The list opened with =over does not contain any
> items." The relevant perlpodspec section states:
> 
> "An "=over" ... "=back" region containing no "=item" paragraphs at all, and
> containing only some number of ordinary/verbatim paragraphs, and possibly
> also some nested "=over" ... "=back" regions, "=for..." paragraphs, and
> "=begin"..."=end" regions. Such an itemless "=over" ... "=back" region in
> Pod is equivalent in meaning to a "<blockquote>...</blockquote>" element in
> HTML."
> 
> 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.

Sounds good.

> What do you guys think?

Personally my priority is to get the tools and docs all in agreement.
The precise details of what does what is less important to me.

Michael