Skip Menu |
 

This queue is for tickets about the Pod-Checker CPAN distribution.

Report information
The Basics
Id: 98326
Status: open
Estimated: 10 min
Worked: 10 min
Priority: 0/
Queue: Pod-Checker

People
Owner: Nobody in particular
Requestors: dmuey [...] cpan.org
Cc:
AdminCc:

Bug Information
Severity: Unimportant
Broken in: (no value)
Fixed in: (no value)



Subject: Can we make “A non-empty Z<>” a warning and not an error (or any of three other suggestions)
Howdy, http://perldoc.perl.org/perlpodspec.html says about Z<>: “This code is unusual is that it should have no content. That is, a processor may complain if it sees Z<potatoes> . Whether or not it complains, the potatoes text should ignored.” Z<potatoes> seems to fit under warnings (i.e. “may complain” not “should explode”) better because it “may not necessarily cause trouble, but indicate mediocre style.” I have an edge case where I essentially need inline comments in POD for some parser notation (https://rt.cpan.org/Public/Bug/Display.html?id=98322) and the only option ATM is “mediocre style” of hacking Z<>. Or, if not by default, can we have a way, a flag maybe, to ignore certain errors that we grok and are OK with? Alternatively, a way to inhibit 'POD ERRORS' section from being rendered as part of the POD (e.g. send it to STDERR). A fourth option would be to add a specific inline-comment formatter so you could #<potatoes> without error and without hacking Z<>. (it would be like Z<> but barf if it was empty) Thanks!
Download (untitled) / with headers
text/plain 1.4k
Why not use something like... =for comment Hm, I wonder what it would look like if you tried to write a BNF for Pod from this. (quoted from perlpodspec) ... for inserting comments into POD. perlpodspec is the reference, and you are more than welcome to propose changes to perlpodspec on pod-people at perl.org. Cheers, Marek Am Di 26. Aug 2014, 09:22:33, DMUEY schrieb: Show quoted text
> Howdy, > > http://perldoc.perl.org/perlpodspec.html says about Z<>: > > “This code is unusual is that it should have no content. That is, a > processor may complain if it sees Z<potatoes> . Whether or not it > complains, the potatoes text should ignored.” > > Z<potatoes> seems to fit under warnings (i.e. “may complain” not > “should explode”) better because it “may not necessarily cause > trouble, but indicate mediocre style.” > > I have an edge case where I essentially need inline comments in POD > for some parser notation > (https://rt.cpan.org/Public/Bug/Display.html?id=98322) and the only > option ATM is “mediocre style” of hacking Z<>. > > Or, if not by default, can we have a way, a flag maybe, to ignore > certain errors that we grok and are OK with? > > Alternatively, a way to inhibit 'POD ERRORS' section from being > rendered as part of the POD (e.g. send it to STDERR). > > A fourth option would be to add a specific inline-comment formatter so > you could #<potatoes> without error and without hacking Z<>. (it would > be like Z<> but barf if it was empty) > > Thanks!
Download (untitled) / with headers
text/plain 626b
Show quoted text
> Why not use something like... > > =for comment
That works most of the time for general comments, but we have an edge case that requires inline (end of line really) comments. Show quoted text
> ... for inserting comments into POD. perlpodspec is the reference, > and you are more than welcome to propose changes to perlpodspec > on pod-people at perl.org.
Thanks I may do that, in the mean time I'd still like to follow up on at least making this POD::Checker check a warning instead of fatal. Would you be willing to accept a pull request that leaves the default behavior as is and allows for known non-empty Z<> to be ignored or warn?
Subject: AW: [rt.cpan.org #98326] Can we make “A non-empty Z<>” a warning and not an error (or any of three other suggestions)
Date: Mon, 02 Feb 2015 16:17:10 +0100
To: bug-Pod-Checker [...] rt.cpan.org
From: "Marek Rouchal" <marek [...] rouchal.net>
Download (untitled) / with headers
text/plain 497b
Actually, no. Z<> is not there to be abused for comments, sorry. Pod::Checker implements perpodspec and I do not want to deviate too much. Sent from my Samsung Galaxy Alpha Smartphone, powered by Intel's 7260 LTE chipset. Show quoted text
-------- Ursprüngliche Nachricht -------- Von: Daniel Muey via RT <bug-Pod-Checker@rt.cpan.org> Datum:02.02.2015 14:29 (GMT+01:00) An: Betreff: [rt.cpan.org #98326] Can we make “A non-empty Z<>” a warning and not an error (or any of three other suggestions)
Download (untitled) / with headers
text/plain 454b
On Mon Feb 02 10:17:25 2015, marek@rouchal.net wrote: Show quoted text
> Actually, no. Z<> is not there to be abused for comments, sorry. > Pod::Checker implements perpodspec and I do not want to deviate too > much.
I understand, however it says “a processor may complain” about a non empty Z<> not that it must or even that it is fatal. So if we left the default behavior and had a way for a caller to make it a warning it'd still be on-spec and discourage mis-use.
Subject: AW: [rt.cpan.org #98326] Can we make “A non-empty Z<>” a warning and not an error (or any of three other suggestions)
Date: Mon, 02 Feb 2015 21:06:11 +0100
To: "bug-Pod-Checker [...] rt.cpan.org" <bug-Pod-Checker [...] rt.cpan.org>
From: "Marek Rouchal" <marek [...] rouchal.net>
Neither there is a fatal (exception) thrown, nor does Pod-Checker endorse non-standard syntax. And why should a user have the choice of bending the syntax rules? No thank you, but if you insist, you are free to let the larger community discuss this (pod-people). Show quoted text
-----Ursprüngliche Nachricht----- Von: Daniel Muey via RT [mailto:bug-Pod-Checker@rt.cpan.org] Gesendet: Montag, 2. Februar 2015 16:23 Betreff: [rt.cpan.org #98326] Can we make “A non-empty Z<>” a warning and not an error (or any of three other suggestions) Queue: Pod-Checker Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=98326 > On Mon Feb 02 10:17:25 2015, marek@rouchal.net wrote:
> Actually, no. Z<> is not there to be abused for comments, sorry. > Pod::Checker implements perpodspec and I do not want to deviate too > much.
I understand, however it says “a processor may complain” about a non empty Z<> not that it must or even that it is fatal. So if we left the default behavior and had a way for a caller to make it a warning it'd still be on-spec and discourage mis-use.
Download (untitled) / with headers
text/plain 481b
Show quoted text
> Neither there is a fatal (exception) thrown,
I am sorry if I was unclear, what I mean is that it could be considered a warning not an error (in terms of “Errors” and “Warnings” under the DIAGNOSTICS section of Pod::Checker). Show quoted text
> nor does Pod-Checker endorse non-standard syntax.
It wouldn’t be, its all in line with the perlpod doc. Show quoted text
> And why should a user have the choice of bending the syntax rules?
They wouldn't since it'd still be following the syntax rules.
Download (untitled) / with headers
text/plain 263b
First, I agree that there is no violation of syntax to warn only on a non-empty Z code. Secondly, I wonder why you don't just use X? Unless you're building an index of your Pod, which you almost certainly aren't (?), it should just work as you'd like. -- rjbs
Download (untitled) / with headers
text/plain 566b
On Tue Feb 03 11:21:39 2015, RJBS wrote: Show quoted text
> First, I agree that there is no violation of syntax to warn only on a > non-empty Z code. > > Secondly, I wonder why you don't just use X? Unless you're building > an index of your Pod, which you almost certainly aren't (?), it should > just work as you'd like.
Thanks for taking time to reply Ricardo. I could achieve the same result w/ X but I don't know how that would affect anyone actually building indexes. In other words I was thinking hijacking Z won't affect anyone, its just ugly, while hijacking X might.
Subject: AW: [rt.cpan.org #98326] Can we make “A non-empty Z<>” a warning and not an error (or any of three other suggestions)
Date: Wed, 04 Feb 2015 17:31:19 +0100
To: bug-Pod-Checker [...] rt.cpan.org
From: "Marek Rouchal" <marek [...] rouchal.net>
Download (untitled) / with headers
text/plain 781b
So you are worrying about impacting someone with a bad X<> but you don't worry about annoying someone with a bad Z<> ... does not make much sense to me. And lacking a proper example what would be the actual reason to put Z<> instead of =for I am not motivated to change Pod::Checker. As far as I can see, it probably would mean modifying Pod::Simple which Checker builds on ... Maybe a fellow maintainer is more motivated? Sent from my Samsung Galaxy Alpha Smartphone, powered by Intel's 7260 LTE chipset. Show quoted text
-------- Ursprüngliche Nachricht -------- Von: Daniel Muey via RT <bug-Pod-Checker@rt.cpan.org> Datum:04.02.2015 17:25 (GMT+01:00) An: Betreff: [rt.cpan.org #98326] Can we make “A non-empty Z<>” a warning and not an error (or any of three other suggestions)
Download (untitled) / with headers
text/html 1024b
Download (untitled) / with headers
text/plain 780b
On Wed Feb 04 11:31:41 2015, marek@rouchal.net wrote: Show quoted text
> So you are worrying about impacting someone with a bad X<> but you > don't worry about annoying someone with a bad Z<> ... does not make > much sense to me.
because its not as bad, and will have zero impact. Plus its just about making it a warning instead of an error (not removing the check or advocating anything) which is inline with how it is documented. Show quoted text
> And lacking a proper example what would be the > actual reason to put Z<> instead of =for
I linked to one in the original post. Show quoted text
> I am not motivated to change > Pod::Checker. As far as I can see, it probably would mean modifying > Pod::Simple which Checker builds on ... > Maybe a fellow maintainer is more motivated?
I'd be happy to submit a pull request.
Download (untitled) / with headers
text/plain 103b
Setting this to stalled until clarification is reached. Like putting this for discussion on pod-people.
RT-Send-CC: marek [...] rouchal.net, dmuey [...] cpan.org
Download (untitled) / with headers
text/plain 340b
I am working on updating Pod::Simple, and Pod::Checker, and am going through the queue of bug reports in each. I personally don't see any harm in making non-empty Z<> merely warn. But I agree that it should be discussed on pod-people. If the originator still wants this done, now is the time to start a discussion on that mailing list.
Download (untitled) / with headers
text/plain 489b
On Sun May 20 01:40:23 2018, khw wrote: Show quoted text
> I am working on updating Pod::Simple, and Pod::Checker, and am going > through the queue of bug reports in each. > > I personally don't see any harm in making non-empty Z<> merely warn. > But I agree that it should be discussed on pod-people. > > If the originator still wants this done, now is the time to start a > discussion on that mailing list.
Thanks Karl :) Here we go: https://www.mail-archive.com/pod-people@perl.org/msg01854.html


This service is sponsored and maintained by Best Practical Solutions and runs on Perl.org infrastructure.

Please report any issues with rt.cpan.org to rt-cpan-admin@bestpractical.com.