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

What do you guys think?

Thanks,
Marc

Search Discussions

  • Michael Stevens at Aug 11, 2011 at 11:03 am

    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
  • Russ Allbery at Aug 11, 2011 at 2:37 pm

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

    Thank you for your work on this!

    --
    Russ Allbery (rra@stanford.edu) <http://www.eyrie.org/~eagle/>
  • Shawn H Corey at Aug 11, 2011 at 2:42 pm

    On 11/08/11 10:37 AM, Russ Allbery wrote:
    Marc Green<ponguile@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.


    --
    Just my 0.00000002 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
  • Marc Green at Aug 11, 2011 at 3:45 pm

    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<ponguile@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?
  • Shawn H Corey at Aug 11, 2011 at 4:19 pm

    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.00000002 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
  • Ronald J Kimball at Aug 11, 2011 at 5:00 pm

    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
  • Russ Allbery at Aug 11, 2011 at 5:38 pm

    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 (rra@stanford.edu) <http://www.eyrie.org/~eagle/>
  • David E. Wheeler at Aug 11, 2011 at 4:17 pm

    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
  • Shawn H Corey at Aug 11, 2011 at 4:20 pm

    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.00000002 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
  • Ricardo Signes at Aug 11, 2011 at 6:55 pm
    * 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
  • Karl Williamson at Aug 12, 2011 at 4:18 pm

    On 08/11/2011 12:54 PM, Ricardo Signes wrote:
    * 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.
    +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
  • David E. Wheeler at Aug 12, 2011 at 4:29 pm

    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
  • Shawn H Corey at Aug 12, 2011 at 5:32 pm

    On 12/08/11 12:17 PM, Karl Williamson wrote:
    =encoding must be first command (if present)
    Except of =pod, of course.


    --
    Just my 0.00000002 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

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
grouppod-people @
categoriesperl
postedAug 11, '11 at 10:40a
activeAug 12, '11 at 5:32p
posts14
users8
websiteperl.org

People

Translate

site design / logo © 2019 Grokbase