Re: What to do about L and L<"Foo Bar">
On Tue, 29 May 2018 09:40:08 -0700 Russ Allbery wrote: > So I'm tentatively on the side of just leaving things alone, but I > don't maintain any of the code that tries to generate links and cares > about the places where this ambiguity might cause problems. Leave the code alone (for now) but update the documentation to best practice. If necessary, put documentation for the old style in `perlpoddeprecated`. -- Don't stop where the ink does. Shawn H Corey
Re: What to do about L and L<"Foo Bar">
Karl Williamson writes:
> I don't understand how things have changed. Please explain how in fact
> they have. My belief is that things haven't changed for a long time
> now, and things continue to work, without complaint. There are no
> tickets against Pod::Simple for any cases of it using its heuristics in
> these situations and getting things wrong.
There were a few things like this that Sean ran across when writing
Pod::Simple and perlpodspec and formalizing POD, which I would classify as
artifacts of the fact that POD started life as underspecified and
ambiguous and defined mostly by its implementations. Folks may also
remember the long back and forth about anchor text in L<>. (In general,
L<> was way more complicated than it looked.)
I think this is one of the cases where we ended up with a cleaner
specification and then an exception for supporting old behavior, but the
old behavior, although formally ambiguous, seems to have not caused enough
heartburn in the past for people to care that much about fixing it. In
this case, I think the most likely problem would be with trying to
generate links in output formats like HTML and having those links go to
the wrong place. But, honestly, the linking strategy for L<> short of a
full URL is kind of an ad hoc mess anyway, and I'm not sure this makes
things a lot worse.
So I'm tentatively on the side of just leaving things alone, but I don't
maintain any of the code that tries to generate links and cares about the
places where this ambiguity might cause problems.
--
#!/usr/bin/perl -- Russ Allbery, Just Another Perl Hacker
$^=q;@!>~|{>krw>yn{u<$$<[~|| 0gFzD gD,
00Fz, 0,,( 0hF 0g)F/=, 0> "L$/GEIFewe{,$/ 0C$~> "@=,m,|,(e 0.), 01,pnn,y{
rw} >;,$0=q,$,,($_=$^)=~y,$/ C-~><@=\n\r,-~$:-u/ #y,d,s,(\$.),$1,gee,print
Re: What to do about L and L<"Foo Bar">
On Tue, 2018-05-29 at 15:20 +1000, Ron Savage wrote: > On 29/05/18 13:49, Karl Williamson wrote: > > 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. I agree that this *sounds* like the sensible thing to do, but the reality is that it will causes tests to fail. The Test::Pod module is used extensively throughout CPAN and it's function is to take any errors or warnings in the file under test and turn them into test failures. Distributions which passed their tests when uploaded will suddenly start to fail tests on install. A few years back I added a warning about non-ASCII characters in POD without an =encoding declaration - the fallout continues to this day. I'm still smarting from being accused of "breaking half of CPAN" :-) I'm not saying don't chose this option, but it's likely some pain will ensue. A number of people wisely pointed out that Test::Pod should only be used in author tests and should not be run at install time. Who knows, perhaps enough people have since taken that advice and it won't be a problem. If not, regularly breaking things in this way is really the only way to get that message out. Perhaps a doc patch to POD::Test might help. > > 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 tend to agree. If non-compliant POD is a problem then I'm not sure that option 3 is going to solve that problem. Regards Grant
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
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).
