Bug #98326 for Pod-Checker: Can we make “A non-empty Z<>” a warning and not an error (or any of three other suggestions)

Tue Aug 26 09:22:33 2014 dmuey [...] cpan.org - Ticket created

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!

Sun Feb 01 16:46:12 2015 Marek.Rouchal [...] gmx.net - Correspondence added

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!

Sun Feb 01 16:46:13 2015 The RT System itself - Status changed from 'new' to 'open'

Sun Feb 01 16:46:45 2015 Marek.Rouchal [...] gmx.net - TimeEstimated changed from (no value) to '10'

Sun Feb 01 16:46:45 2015 Marek.Rouchal [...] gmx.net - TimeWorked changed from (no value) to '5'

Sun Feb 01 16:46:46 2015 Marek.Rouchal [...] gmx.net - Status changed from 'open' to 'rejected'

Sun Feb 01 16:46:46 2015 Marek.Rouchal [...] gmx.net - Severity Unimportant added

Sun Feb 01 16:46:46 2015 Marek.Rouchal [...] gmx.net - Fixed in 1.71 added

Mon Feb 02 08:22:23 2015 dmuey [...] cpan.org - Correspondence added

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?

Mon Feb 02 08:22:28 2015 dmuey [...] cpan.org - Status changed from 'rejected' to 'open'

Mon Feb 02 10:17:25 2015 marek [...] rouchal.net - Correspondence added

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>

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)

Mon Feb 02 10:23:15 2015 dmuey [...] cpan.org - Correspondence added

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.

Mon Feb 02 15:06:28 2015 marek [...] rouchal.net - Correspondence added

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.

Mon Feb 02 15:43:06 2015 dmuey [...] cpan.org - Correspondence added

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.

Tue Feb 03 11:21:39 2015 rjbs [...] cpan.org - Correspondence added

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

Wed Feb 04 11:17:36 2015 dmuey [...] cpan.org - Correspondence added

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.

Wed Feb 04 11:31:41 2015 marek [...] rouchal.net - Correspondence added

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>

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)

Wed Feb 04 12:00:02 2015 dmuey [...] cpan.org - Correspondence added

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.

Mon May 30 15:16:34 2016 Marek.Rouchal [...] gmx.net - Correspondence added 5 min

Setting this to stalled until clarification is reached. Like putting this for discussion on pod-people.

Mon May 30 15:16:40 2016 Marek.Rouchal [...] gmx.net - Status changed from 'open' to 'stalled'

Mon May 30 15:16:40 2016 Marek.Rouchal [...] gmx.net - Fixed in 1.71 deleted

Sun May 20 01:40:23 2018 khw [...] cpan.org - Correspondence added

RT-Send-CC:

marek [...] rouchal.net, dmuey [...] cpan.org

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.

Sun May 20 01:40:24 2018 The RT System itself - Status changed from 'stalled' to 'open'

Tue May 22 21:21:43 2018 dmuey [...] cpan.org - Correspondence added

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

Fri May 01 08:41:52 2020 Marek.Rouchal [...] gmx.net - Correspondence added

Am Di 22. Mai 2018, 21:21:43, DMUEY schrieb: Show quoted text

> On Sun May 20 01:40:23 2018, khw wrote:

> > I am working on updating Pod::Simple, and Pod::Checker, and am going > > through the queue of bug reports in each.

> > Here we go: https://www.mail-archive.com/pod-people@perl.org/msg01854.html

I am not sure I saw any replies - anyway, I would like to unblock this thread and state that I am not opposing any longer to make Z<…> (non-empty content) merely a warning in the POD parsers and checker, and not an error. -Marek

Fri May 01 09:29:43 2020 dmuey [...] cpan.org - Correspondence added

thanks Marek ;)

Mon Sep 21 15:39:14 2020 Marek.Rouchal [...] gmx.net - Correspondence added

Maybe I was too quick - it is more complicated than I thought: Yes, I can make a change to Pod::Checker which will make Z<foo> a warning only. However, the source of the complaint is Pod::Simple, and all I can do is to catch that specific complaint, and "downgrade" it to a warning. But then, when you to perldoc/tkpod/... or whatever uses Pod::Simple, you'll encounter that very same ERROR being flagged. I see two options: a) I am ready to downgrade Z<foo> to be a warning in Pod::Checker, but mind the caveats above b) You change this ticket to be directed at Pod::Simple, and when Pod::Simple makes this a warning, so will Pod::Checker (implicitly) Thank you for your patience, and let me know your preference. -Marek

Sun Oct 04 10:25:55 2020 Marek.Rouchal [...] gmx.net - TimeWorked changed from '10' to '60'

Sun Oct 04 10:25:55 2020 Marek.Rouchal [...] gmx.net - Status changed from 'open' to 'resolved'

Sun Oct 04 10:25:56 2020 Marek.Rouchal [...] gmx.net - Taken

Sun Oct 04 10:25:56 2020 Marek.Rouchal [...] gmx.net - Fixed in 1.74 added

Sun Oct 04 10:25:56 2020 Marek.Rouchal [...] gmx.net - Broken in 1.60 added

Sun Oct 04 10:25:56 2020 Marek.Rouchal [...] gmx.net - Broken in 1.70 added

Sun Oct 04 10:25:56 2020 Marek.Rouchal [...] gmx.net - Broken in 1.71 added

Sun Oct 04 10:25:56 2020 Marek.Rouchal [...] gmx.net - Broken in 1.72 added

Sun Oct 04 10:25:56 2020 Marek.Rouchal [...] gmx.net - Broken in 1.72_01 added

Sun Oct 04 10:25:56 2020 Marek.Rouchal [...] gmx.net - Broken in 1.73 added

Tue Oct 06 16:55:05 2020 dmuey [...] cpan.org - Correspondence added

Thanks Marek! Would this work? Downgrade it in Pod::Checker and I’ll create an issue for Pod::Simple to also do the the same. That way Pod::Checker will always be a warning regardless of Pod::Simple and then when Pod::Simple catches up even better, win win :) What do you think? On Mon Sep 21 15:39:14 2020, MAREKR wrote: Show quoted text

> Maybe I was too quick - it is more complicated than I thought: > Yes, I can make a change to Pod::Checker which will make Z<foo> a > warning only. > However, the source of the complaint is Pod::Simple, and all I can do > is to catch that specific complaint, and "downgrade" it to a warning. > But then, when you to perldoc/tkpod/... or whatever uses Pod::Simple, > you'll encounter that very same ERROR being flagged. > I see two options: > a) I am ready to downgrade Z<foo> to be a warning in Pod::Checker, but > mind the caveats above > b) You change this ticket to be directed at Pod::Simple, and when > Pod::Simple makes this a warning, so will Pod::Checker (implicitly) > > Thank you for your patience, and let me know your preference. > > -Marek