Re: Removal of specific Pod::Checker warnings
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
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
Re: Removal of specific Pod::Checker warnings
On Thu, Aug 11, 2011 at 10:41 AM, Shawn H Corey shawnhco...@gmail.comwrote: On 11/08/11 10:37 AM, Russ Allbery wrote: Marc Greenpongu...@gmail.com 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
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
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
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
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
* Marc Green pongu...@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. 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
