Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss
What to do about L<Foo Bar> and L<"Foo Bar">
1 view
Skip to first unread message
Karl Williamson
May 29, 2018, 12:00:03 AM5/29/18
to Perl POD People
podspec says this:
Previous versions of perlpod allowed for a "L<section>" syntax (as in
"L<Object Attributes>"), which was not easily distinguishable from
"L<name>" 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</section>" 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<section>" from "L<name>" 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).
Previous versions of perlpod allowed for a "L<section>" syntax (as in
"L<Object Attributes>"), which was not easily distinguishable from
"L<name>" 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</section>" 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<section>" from "L<name>" 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).
Ron Savage
May 29, 2018, 1:45:02 AM5/29/18
to pod-p...@perl.org
Hi Karl
See below.
On 29/05/18 13:49, Karl Williamson wrote:
> podspec says this:
>
> Previous versions of perlpod allowed for a "L<section>" syntax (as in
> "L<Object Attributes>"), which was not easily distinguishable from
> "L<name>" 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</section>" 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<section>" from "L<name>" 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
See below.
On 29/05/18 13:49, Karl Williamson wrote:
> podspec says this:
>
> Previous versions of perlpod allowed for a "L<section>" syntax (as in
> "L<Object Attributes>"), which was not easily distinguishable from
> "L<name>" 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</section>" 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<section>" from "L<name>" 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.
preference.
> 2) Raise the warnings, either on both cases or just the deprecated
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.
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
Grant McLean
May 29, 2018, 7:00:03 AM5/29/18
to pod-p...@perl.org
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
> 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.
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).
that option 3 is going to solve that problem.
Regards
Grant
Karl Williamson
May 29, 2018, 11:45:02 AM5/29/18
to Grant McLean, pod-p...@perl.org
On 05/29/2018 04:26 AM, Grant McLean wrote:
> 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.
I don't understand how things have changed. Please explain how in fact
> 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.
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.
>>
>>>
>>> 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" :-)
Ah, so you're the one!
>>>
>>> 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.
Core perl development has moved to more of a position that we don't add
>
> I'm not saying don't chose this option, but it's likely some pain will
> ensue.
new warnings unless there's good evidence that the benefit greatly
outweighs the cost of breaking things. I don't see that here, which is
why I brought up the topic, so it could be discussed.
Nor do we deprecate and remove something unless it is causing us hassles
extending and maintaining the core, or perhaps causing significant user
confusion or problems.
The reluctance to make these kinds of changes is because of past bitter
experiences, like Grant's.
>
> 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.
I started this work, and discovered there was a lot of non-compliant
> 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.
POD, even in the perl core. And since I never heard of problems with
this non-compliant POD, is there really a problem. So my question again
comes down to "Is non-compliant POD really a problem?"
>
> Regards
> Grant
>
Russ Allbery
May 29, 2018, 12:45:02 PM5/29/18
to Karl Williamson, Grant McLean, pod-p...@perl.org
Karl Williamson <pub...@khwilliamson.com> 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
> 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.
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<$$<[~||<Juukn{=,<S~|}<Jwx}qn{<Yn{u<Qjltn{ > 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
0 new messages