Re: What to do about L and L<"Foo Bar">
Hi Karl See below. On 29/05/18 13:49, Karl Williamson wrote: podspec says this: Previous versions of perlpod allowed for a "L" syntax (as in "L"), which was not easily distinguishable from "L" syntax and for "L<"section">" which was only slightly less ambiguous. This syntax is no longer in the specification, and has been replaced by the "L" syntax (where the slash was formerly optional). Pod parsers should tolerate the "L<"section">" syntax, for a while at least. The suggested heuristic for distinguishing L" from "L" is that if it contains any whitespace, it's a section. Pod processors should warn about this being deprecated syntax. Pod:Simple accepts these without complaint. If I change things to complain, a bunch of things in the perl core are found to be in violation, even of the deprecated syntax. The question is what to do? 1) We could leave things as they always have been, to let sleeping dogs lie. It's worked for so long that we're not seriously going to stop accepting these. This pretends things have not changed when in fact they have, so not my preference. 2) Raise the warnings, either on both cases or just the deprecated Raise warnings on deprecated structures, so uses can fix problems, is my choice here. 3) Don't raise warnings, but change Pod::Checker to do so, under the theory that you won't be using that unless you want to know the iffy things. Maybe make the deprecated come out always, and the tolerated only for level 2 warnings. This imposes a burden on users. Tasks: (a) Change to Pod::Checker, to find problems; (b) Fix problems. Not my preference since it's simpler for the end user to find the same problems under (2). I'm leaning towards option 3). -- Ron Savage - savage.net.au
Re: Bug #98326 for Pod-Checker: Can we make “A non-empty Z<>” a warning and not an error
On 05/22/2018 07:18 PM, Dan Muey wrote: Greetings! Per Karl Williamson’s request[1] before he makes any changes we’d like to run the idea past you all and get your feedback: 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 . Whether or not it complains, the potatoes text should ignored.” Z 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 # without error and without hacking Z<>. (it would be like Z<> but barf if it was empty) After the RT discussion “making non-empty Z<> merely warn” seems OK, we just wanted it to be discussed here first. Thanks! — Dan Muey [1] https://rt.cpan.org/Ticket/Display.html?id=98326#txn-1787110 It does seem to me that treating this condition as a fatal error is wrong, and likely to be an accident of implementation. Pod::Checker makes all but a very few of the warnings generated by Pod::Simple fatal. Each such is listed as an exception. My guess is that the exceptions were added one by one as needed, and this one just didn't come up. Saying Z as opposed to Z<> makes no difference in the pod that gets generated, so making it fatal just seems wrong. So I think we should accommodate this request, and I intend to issue a PR to do so, if no objections are raised here.
What to do about L and L<"Foo Bar">
podspec says this: Previous versions of perlpod allowed for a "L" syntax (as in "L"), which was not easily distinguishable from "L" syntax and for "L<"section">" which was only slightly less ambiguous. This syntax is no longer in the specification, and has been replaced by the "L" syntax (where the slash was formerly optional). Pod parsers should tolerate the "L<"section">" syntax, for a while at least. The suggested heuristic for distinguishing L" from "L" is that if it contains any whitespace, it's a section. Pod processors should warn about this being deprecated syntax. Pod:Simple accepts these without complaint. If I change things to complain, a bunch of things in the perl core are found to be in violation, even of the deprecated syntax. The question is what to do? 1) We could leave things as they always have been, to let sleeping dogs lie. It's worked for so long that we're not seriously going to stop accepting these. 2) Raise the warnings, either on both cases or just the deprecated 3) Don't raise warnings, but change Pod::Checker to do so, under the theory that you won't be using that unless you want to know the iffy things. Maybe make the deprecated come out always, and the tolerated only for level 2 warnings. I'm leaning towards option 3).
