Removal of specific Pod::Checker warnings

[Marc Green]

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?

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 "..." 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.

What do you guys think?

Thanks,
Marc

Re: Removal of specific Pod::Checker warnings

[Russ Allbery]

Marc Green  writes:

> 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'd remove it.  It seems like a style thing to me, and while I personally
prefer =item *, I don't see a good reason to require that.

> 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
> "..." 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.

I agree -- this one should definitely go.

Thank you for your work on this!

-- 
Russ Allbery (r...@stanford.edu) 

Re: Removal of specific Pod::Checker warnings

[Shawn H Corey]

On 11/08/11 10:37 AM, Russ Allbery wrote:

Marc Green  writes:


>  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'd remove it.  It seems like a style thing to me, and while I personally
prefer =item *, I don't see a good reason to require that.



I'm not sure about that.  Although a POD parser should be forgiving, a 
checker should not.  I think it should report things that are not spec 
even if the parsers accept them.



--
Just my 0.0002 million dollars worth,
  Shawn

Confusion is the first step of understanding.

Programming is as much about organization and communication
as it is about coding.

The secret to great software:  Fail early & often.

Eliminate software piracy:  use only FLOSS.

"Make something worthwhile."  -- Dear Hunter

Re: Removal of specific Pod::Checker warnings

[Marc Green]

On Thu, Aug 11, 2011 at 10:41 AM, Shawn H Corey wrote:

> On 11/08/11 10:37 AM, Russ Allbery wrote:
>
>> Marc Green  writes:
>>
>>  >  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'd remove it.  It seems like a style thing to me, and while I personally
>> prefer =item *, I don't see a good reason to require that.
>>
>>
> I'm not sure about that.  Although a POD parser should be forgiving, a
> checker should not.  I think it should report things that are not spec even
> if the parsers accept them.
>

I agree that a POD checker should report *all* errors/warnings, but is
having an argumentless =item really a warning?

By Pod::Checker's defintion, a warning indicates bad style, so that would
mean that having an argumentless =item is bad style. Personally, I don't
think it is; I find it a convenient shorthand. Do you disagree?

Re: Removal of specific Pod::Checker warnings

[David E. Wheeler]

On Aug 11, 2011, at 7:37 AM, Russ Allbery wrote:

>> "=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'd remove it.  It seems like a style thing to me, and while I personally
> prefer =item *, I don't see a good reason to require that.

+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.
> 
> I agree -- this one should definitely go.

+1

I had no idea one could do block quotes like this. Seems a bit too overloaded, 
frankly (what if I want my block quote to contain a list, just nest them?), but 
if the spec says that's what it is, then I wouldn't warn about it.

Best,

David

Re: Removal of specific Pod::Checker warnings

[Shawn H Corey]

On 11/08/11 11:45 AM, Marc Green wrote:


I agree that a POD checker should report *all* errors/warnings, but is
having an argumentless =item really a warning?

By Pod::Checker's defintion, a warning indicates bad style, so that
would mean that having an argumentless =item is bad style. Personally, I
don't think it is; I find it a convenient shorthand. Do you disagree?


You're correct.  Under "Pod Commands", =item is listed as a bare item. 
I don't know why there is a note for being forgiving for a valid 
structure, but it's confusing.  And, of course, if it's valid, it can't 
be bad style.



--
Just my 0.0002 million dollars worth,
  Shawn

Confusion is the first step of understanding.

Programming is as much about organization and communication
as it is about coding.

The secret to great software:  Fail early & often.

Eliminate software piracy:  use only FLOSS.

"Make something worthwhile."  -- Dear Hunter

Re: Removal of specific Pod::Checker warnings

[Shawn H Corey]

On 11/08/11 12:17 PM, David E. Wheeler wrote:

what if I want my block quote to contain a list, just nest them?


Yup.


--
Just my 0.0002 million dollars worth,
  Shawn

Confusion is the first step of understanding.

Programming is as much about organization and communication
as it is about coding.

The secret to great software:  Fail early & often.

Eliminate software piracy:  use only FLOSS.

"Make something worthwhile."  -- Dear Hunter

Re: Removal of specific Pod::Checker warnings

[Ronald J Kimball]

On Thu, Aug 11, 2011 at 12:19:45PM -0400, Shawn H Corey wrote:
> You're correct.  Under "Pod Commands", =item is listed as a bare item. 
> I don't know why there is a note for being forgiving for a valid 
> structure, but it's confusing.  And, of course, if it's valid, it can't 
> be bad style.

What?  Valid syntax can most definitely be bad style.  That's why we have
style checkers in the first place.

Ronald

Re: Removal of specific Pod::Checker warnings

[Russ Allbery]

Ronald J Kimball  writes:
> On Thu, Aug 11, 2011 at 12:19:45PM -0400, Shawn H Corey wrote:

>> You're correct.  Under "Pod Commands", =item is listed as a bare item.
>> I don't know why there is a note for being forgiving for a valid
>> structure, but it's confusing.  And, of course, if it's valid, it can't
>> be bad style.

> What?  Valid syntax can most definitely be bad style.  That's why we
> have style checkers in the first place.

Yeah, but is Pod::Checker really intended to be a style checker?  My
impression was that it was more intended to be like the warnings flag to a
compiler or like use warnings in Perl: something to warn about stuff
that's technically syntactically valid but probably in error.

-- 
Russ Allbery (r...@stanford.edu) 

Re: Removal of specific Pod::Checker warnings

[Ricardo Signes]

* Marc Green  [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.

> 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.

-- 
rjbs