Re: Deprecation of alternate text in hyperlinks

[David E. Wheeler]

On Feb 20, 2012, at 7:33 PM, Sean M. Burke wrote:

> I kinda passed off perlpodspec to... whoever...
> I'm pretty sure I did, to somebody….

I believe it is now part of the core Perl distribution; I don't believe it 
ships with Pod::Simple anymore. Which I think is the right thing to do.

> But I'll chip in about L in perlpodspec.

It has been in for a couple of years now, and I've heard no complaints. :-)

David

Re: Deprecation of alternate text in hyperlinks

[Russ Allbery]

"Sean M. Burke"  writes:

> 3) Point 3 is a problem in theory, and possibly in practice, but for which
> the *solution* is "SO DON'T DO SCREW IT UP!".

> I had this in mind: supporting linktext could mean:
>  "You can just Lmailto:sbu...@cpan.org> Now!"
> which, outside of hypertext, *could* be rendered as
>  "You can just email me! Now!"
> ...which makes me all frowny-face.

For what it's worth, both Pod::Text and Pod::Man always display
Lhttp://foo.com/> as "foo ", which I think generally
does the right thing.

> A few bits of DWIM would probably cover most cases, I bet!

> * Suppressing the URL if it's identical to the link text.

They already do this, although it always surrounds the link text with <>
in this case, following the informal standard for how to express URLs in
text.

> * Suppressing the URL if it says "perl.com" and the URL
> (case-insensitively compared) is http://www.perl.com, http://perl.com, or
> http://perl.com/

This I've not done.  I'm not sure if this is a good idea or not.  Hm.

> * Suppressing the URL if the text has a "@" in it and the URL is just the
> text with a "mailto:"; in front of it.  So
>  "I'm at Lmailto:sbu...@cpan.org> now!"
> indeed *can* show up as
>  "I'm at sbu...@cpan.org[mailto:sbu...@cpan.org] now!"
> but it's so *obviously* redundant that that can just show as:
>  "I'm at sbu...@cpan.org now!"

That's a good idea.  I'll add that to the to-do list.

Related, I think L should probably turn into just
sbu...@cpan.org in a text output format.

> B1) You (pod-writer) could write:
>   "Look at my web site, L!"
> In that case, it's not a problem for anyone or anything.
> It dodges ANY problem with link text by simply not using it.

> BUT a lot of people will use link text because they think of hypertext as
> always having a linktext and a URL, with NO INFERENCE of one from the
> other if it's missing.  I mean,
>   http://stuff.com/";>
> or
>   http://stuff.com/
> don't magically turn into what the output would be of
>   http://stuff.com/";>http://stuff.com/
> So, by analogy, however technically unnecessarily it is, I find it
> entirely understandable that people would just reflexively go for *even* a
> totally vacuous case of linktext, namely:
>   L

I'd kind of like to produce a warning about this, though, since it looks
ugly and creates the lurking potential for bugs (updating one URL and not
the other).

> HEY, documentation-writer! Maybe you're thinking of doing
>   Lhttp://stuff.com/>!
> ...but: DON'T DO THAT!
> Why?
> Because a lot of people are using perldoc and the default behavior of it,
> which is to page thru nroff-formatted non-hypertext.
> Yes, it's the lowest common denominator.

> It's also a *very* common denominator.

No, actually, please *do* that, as Pod::Text and Pod::Man (including
perldoc) have handled this properly since forever.  This will render as:

my friend's web site 

which is just fine.

Really, please, start using this right now.  I think the tools will be
fine.  The core tools are already fine.

-- 
Russ Allbery (r...@stanford.edu) 

Re: Deprecation of alternate text in hyperlinks

[Sean M. Burke]

I kinda passed off perlpodspec to... whoever...
I'm pretty sure I did, to somebody
But I'll chip in about L in perlpodspec.

Long story short, about Lhttp://stuff.com/hditfn> and modding 
perlpodspec to say it's okay: DOIT!


There *were* three things that I thought were stumbling blocks with 
supporting Lhttp://zuh>, but they haven't... stumbled... anyone, 
as far as I've heard.


So I'm in favor of changing that part of Perlpodspec to say, I dunno:
  The syntax L used to be deprecated, but
  is no longer deprecated.  You can use it with no trouble.

I could say something like "but authors are reminded not to..." and 
list some abstruse use of it (see below), but no general module author 
would be reading perlpodspec anyway, so who cares, and so far no harm 
no foul.


That's the long story short: modding perlpodspec to say that 
Lhttp://whatever> is fine, is fine by me.





Long story long:

I think my motivations, a decade ago, for deprecating 
Lhttp://zuh> were:


1) It complicated the L<> parsing system which is already unbearably 
tangled


2) In fact, in doing so, it could produce some paradox I can't 
remember anymore, but wasn't ridiculously abstruse, I dunno, like 
having a sea of Z<>s would be.)  I think it might have been 
*something* to do with the fact that "/" occurs meaningfully in 
non-URL links to mean "the section called".  Like:

  L
...and somehow the slashes in (http) URLs screwing with that, by 
producing an ordering paradox-- something like parsing 
L meant that splitting the text had to happen at one 
stage, but Lhttp://thing/zuh> meant that splitting the text had 
to happen at a different stage.  Maybe that's another problem just in 
theory but not so much in practice.



But people gritted their teeth and got Lhttp://zuh> working, and 
no instances of screwed-up parsing have been reported, so... probably 
as long as nobody does L|http://zuhE<876>> or whatever crazy 
thing would break it, then Point 1 and Point 2 are no problem.

Tally ho!


3) Point 3 is a problem in theory, and possibly in practice, but for 
which the *solution* is "SO DON'T DO SCREW IT UP!".


I had this in mind: supporting linktext could mean:
 "You can just Lmailto:sbu...@cpan.org> Now!"
which, outside of hypertext, *could* be rendered as
 "You can just email me! Now!"
...which makes me all frowny-face.


There's two sides to producing that: the person who writes a 
non-hypertext pod renderer, and a person writing a document who wants 
to use linktext "guh" in L :


For someone writing a module to render the code to a *non-hypertext* 
format:


A1) That renderer-author can just ditch the hyperlink and show only 
the link-text:

   "You can just email me! Now!"

A2) That renderer-author can show the link-text and somehow also show 
the URL:

   "You can just email me[mailto:sbu...@cpan.org]! Now!"
(with it being a given that if the URL might be
 broken across lines, no "-" should be introduced.
 Introducing zero-width spaces every few characters
 might be a feasible acceptable hack in some formats
 to keep that from happening.  Your mileage may vary.
)

A2.5) That renderer-author can do A2 but can also add however much 
DWIM he wants, to suppress the URL when it's obviously just a 
reiteration of the text.

A few bits of DWIM would probably cover most cases, I bet!

* Suppressing the URL if it's identical to the link text.

* Suppressing the URL if it says "perl.com" and the URL 
(case-insensitively compared) is http://www.perl.com, http://perl.com, 
or http://perl.com/


* Suppressing the URL if the text has a "@" in it and the URL is just 
the text with a "mailto:"; in front of it.  So

 "I'm at Lmailto:sbu...@cpan.org> now!"
indeed *can* show up as
 "I'm at sbu...@cpan.org[mailto:sbu...@cpan.org] now!"
but it's so *obviously* redundant that that can just show as:
 "I'm at sbu...@cpan.org now!"
The minor amount of DWIM that I'm suggesting, would actually kick in 
and keep uncluttered the current vast majority of cases, I bet.



That minor amount of DWIM might also easily be put into a module, for 
all to share and enjoy, and confer upon!




Now, the other side:
For someone writing docs, I'll consider the possible non-use, or uses, 
of L<...> as they would appear in a non-hypertext format:


B1) You (pod-writer) could write:
  "Look at my web site, L!"
In that case, it's not a problem for anyone or anything.
It dodges ANY problem with link text by simply not using it.

BUT a lot of people will use link text because they think of hypertext 
as always having a linktext and a URL, with NO INFERENCE of one from 
the other if it's missing.  I mean,

  http://stuff.com/";>
or
  http://stuff.com/
don't magically turn into what the output would be of
  http://stuff.com/";>http://stuff.com/
So, by analogy, however technically unnecessarily it is, I find it 
entirely understandable that people would just reflexively go for 
*even* a totally vacuous case of linktext, namely

Re: Deprecation of alternate text in hyperlinks

[Marek Rouchal]

Well guys,

if this is the case, then it will be up to me again to remove this
error detection from Pod::Parser and release a 1.51. Would be nice
if this was the final verdict on this matter...

Stay tuned...

-Marek

 Original-Nachricht 
> Datum: Mon, 23 Jan 2012 11:27:54 -0700
> Von: Karl Williamson 
> An: "David E. Wheeler" 
> CC: pod-people@perl.org, Perl5 Porters , 
> marek.rouc...@gmx.net
> Betreff: Re: Deprecation of alternate text in hyperlinks

> On 01/23/2012 11:03 AM, David E. Wheeler wrote:
> > On Jan 23, 2012, at 9:26 AM, Karl Williamson wrote:
> >
> >> So, you're saying I believe the text in perlpodspec that was the
> motivation for these changes should be removed, and that Pod::Parser should
> revert to its old behavior of not checking for this.
> >>
> >> Is that so?
> >
> > I can’t parse that sentence, but if you’re asking if this bit should
> be removed:
> >
> >> "Authors wanting to link to a particular (absolute) URL, must do so
> >> only with "LEscheme:...>" codes (like
> >> LEhttp://www.perl.org>), and must not attempt "LESome Site
> >> Name|scheme:...>" codes.  This restriction avoids many problems
> >> in parsing and rendering LE...>  codes."
> >
> > Then the answer is “yes.” And Pod::Parser should be modified to
> allow or support L.
> >
> > Best,
> >
> > David
> >
> >
> >
> 
> Sorry for the confusing text.  You did parse it correctly, and blead now 
> has the text from perlpodspec removed.

-- 
Empfehlen Sie GMX DSL Ihren Freunden und Bekannten und wir
belohnen Sie mit bis zu 50,- Euro! https://freundschaftswerbung.gmx.de

Re: Deprecation of alternate text in hyperlinks

[Leon Timmermans]

On Tue, Jan 24, 2012 at 7:14 PM, Russ Allbery  wrote:
> Your rant against man pages is somewhat undermined by the fact that I, as
> maintainer of Pod::Man, have supported anchor text for URL L<> links from
> the beginning and opposed this restriction from the start.
>
> The restriction has nothing to do with targetting man pages.

Then I was mistakenly assuming it was because of the manpages, my apologies.

Leon

Re: Deprecation of alternate text in hyperlinks

[Russ Allbery]

Leon Timmermans  writes:

> The problem of us treating manpages as our designated documentation
> medium strikes us once again. IMO, it's time for perl's documentation to
> enter the 21st century and accept that hypertext has taken over.  This
> kind of trouble keeps popping up (think of the lack of tables or proper
> support for images).

> I'm fine with reading my documentation on the console (I do it
> regularly), but by targeting the lowest common denominator we're cutting
> ourselves short.

Your rant against man pages is somewhat undermined by the fact that I, as
maintainer of Pod::Man, have supported anchor text for URL L<> links from
the beginning and opposed this restriction from the start.

The restriction has nothing to do with targetting man pages.

-- 
Russ Allbery (r...@stanford.edu) 

Re: Deprecation of alternate text in hyperlinks

[David E. Wheeler]

On Jan 23, 2012, at 9:26 AM, Karl Williamson wrote:

> So, you're saying I believe the text in perlpodspec that was the motivation 
> for these changes should be removed, and that Pod::Parser should revert to 
> its old behavior of not checking for this.
> 
> Is that so?

I can’t parse that sentence, but if you’re asking if this bit should be removed:

> "Authors wanting to link to a particular (absolute) URL, must do so
> only with "LEscheme:...>" codes (like
> LEhttp://www.perl.org>), and must not attempt "LESome Site
> Name|scheme:...>" codes.  This restriction avoids many problems
> in parsing and rendering LE...> codes."

Then the answer is “yes.” And Pod::Parser should be modified to allow or 
support L.

Best,

David

Re: Deprecation of alternate text in hyperlinks

[David E. Wheeler]

On Jan 23, 2012, at 8:06 AM, Karl Williamson wrote:

> The new Pod:Parser has just been installed in blead, and about 10 pods run 
> afoul of this new check, including things like
> 
> Lmailto:perl...@perl.org>
> 
> My question is should there really be a message for this kind of use, and if 
> so, should it extend to mailto: links?

No. Suport for L was added to perlpodspec in 2009. Pod::Simple 
has supported it for years; Test::Pod started officially allowing it in v1.41, 
IIRC.

Relevant changes:

  
https://github.com/theory/pod-simple/commit/1e61e819debf9c7c23907d7bb9e37855665fd595
  
http://perl5.git.perl.org/perl.git/commit/f6e963e4dd62b8e3c01b31f4a4dd57e47e104997
  
https://github.com/theory/test-pod/commit/ae6a44894eda4fd09fb412d837efe543628cd7d6

Discussion:

  http://code.activestate.com/lists/perl-pod-people/1393/

Best,

David

Re: Deprecation of alternate text in hyperlinks

[Leon Timmermans]

On Mon, Jan 23, 2012 at 5:06 PM, Karl Williamson
 wrote:
> Version 1.50 of Pod::Parser adds a check and message indicating that
> L is deprecated.  This is based on the following sentences
> in perlpodspec, which has been there since its inception in 2001:
>
> "Authors wanting to link to a particular (absolute) URL, must do so
> only with "LEscheme:...>" codes (like
> LEhttp://www.perl.org>), and must not attempt "LESome Site
> Name|scheme:...>" codes.  This restriction avoids many problems
> in parsing and rendering LE...> codes."
>
> Elsewhere in the document, it says that the handler should handle these, as
> in the example
>
>  Lhttp://www.perl.org/>
>
> The new Pod:Parser has just been installed in blead, and about 10 pods run
> afoul of this new check, including things like
>
> Lmailto:perl...@perl.org>
>
> My question is should there really be a message for this kind of use, and if
> so, should it extend to mailto: links?

The problem of us treating manpages as our designated documentation
medium strikes us once again. IMO, it's time for perl's documentation
to enter the 21st century and accept that hypertext has taken over.
This kind of trouble keeps popping up (think of the lack of tables or
proper support for images).

I'm fine with reading my documentation on the console (I do it
regularly), but by targeting the lowest common denominator we're
cutting ourselves short.

Leon

Re: Deprecation of alternate text in hyperlinks

[Russ Allbery]

Karl Williamson  writes:

> Version 1.50 of Pod::Parser adds a check and message indicating that
> L is deprecated.  This is based on the following
> sentences in perlpodspec, which has been there since its inception in
> 2001:

> "Authors wanting to link to a particular (absolute) URL, must do so
> only with "LEscheme:...>" codes (like
> LEhttp://www.perl.org>), and must not attempt "LESome Site
> Name|scheme:...>" codes.  This restriction avoids many problems
> in parsing and rendering LE...> codes."

> Elsewhere in the document, it says that the handler should handle these,
> as in the example

>  Lhttp://www.perl.org/>

> The new Pod:Parser has just been installed in blead, and about 10 pods
> run afoul of this new check, including things like

> Lmailto:perl...@perl.org>

> My question is should there really be a message for this kind of use,
> and if so, should it extend to mailto: links?

I disagree with this change, and disagreed with the statement in
perlpodspec in 2001 as well.  There's really no good reason to disallow
anchor text for hyperlinks in L<> codes.  The parsing issues are not that
serious.

I think this syntax should be undeprecated and declared officially
blessed.

-- 
Russ Allbery (r...@stanford.edu) 

Re: Deprecation of alternate text in hyperlinks

[Karl Williamson]

On 01/23/2012 11:03 AM, David E. Wheeler wrote:

On Jan 23, 2012, at 9:26 AM, Karl Williamson wrote:


So, you're saying I believe the text in perlpodspec that was the motivation for 
these changes should be removed, and that Pod::Parser should revert to its old 
behavior of not checking for this.

Is that so?


I can’t parse that sentence, but if you’re asking if this bit should be removed:


"Authors wanting to link to a particular (absolute) URL, must do so
only with "LEscheme:...>" codes (like
LEhttp://www.perl.org>), and must not attempt "LESome Site
Name|scheme:...>" codes.  This restriction avoids many problems
in parsing and rendering LE...>  codes."


Then the answer is “yes.” And Pod::Parser should be modified to allow or support 
L.

Best,

David





Sorry for the confusing text.  You did parse it correctly, and blead now 
has the text from perlpodspec removed.

Re: Deprecation of alternate text in hyperlinks

[Ricardo Signes]

* Karl Williamson  [2012-01-23T12:26:27]
> So, you're saying I believe the text in perlpodspec that was the
> motivation for these changes should be removed, and that Pod::Parser
> should revert to its old behavior of not checking for this.

After all the care taken to be sure that the original fears about
L<...|http:///> were unfounded, I think we should stick to it and allow it.
Pod::Parser should probably not be warning on these, unless it somehow can't
handle them, in which case the better fix is to handling them, not warning.

-- 
rjbs


signature.asc
Description: Digital signature

Re: Deprecation of alternate text in hyperlinks

[Karl Williamson]

On 01/23/2012 10:05 AM, David E. Wheeler wrote:

On Jan 23, 2012, at 8:06 AM, Karl Williamson wrote:


The new Pod:Parser has just been installed in blead, and about 10 pods run 
afoul of this new check, including things like

Lmailto:perl...@perl.org>

My question is should there really be a message for this kind of use, and if 
so, should it extend to mailto: links?


No. Suport for L  was added to perlpodspec in 2009. 
Pod::Simple has supported it for years; Test::Pod started officially allowing it in 
v1.41, IIRC.

Relevant changes:

   
https://github.com/theory/pod-simple/commit/1e61e819debf9c7c23907d7bb9e37855665fd595
   
http://perl5.git.perl.org/perl.git/commit/f6e963e4dd62b8e3c01b31f4a4dd57e47e104997
   
https://github.com/theory/test-pod/commit/ae6a44894eda4fd09fb412d837efe543628cd7d6

Discussion:

   http://code.activestate.com/lists/perl-pod-people/1393/

Best,

David




So, you're saying I believe the text in perlpodspec that was the 
motivation for these changes should be removed, and that Pod::Parser 
should revert to its old behavior of not checking for this.


Is that so?

Deprecation of alternate text in hyperlinks

[Karl Williamson]

Version 1.50 of Pod::Parser adds a check and message indicating that 
L is deprecated.  This is based on the following 
sentences in perlpodspec, which has been there since its inception in 2001:


"Authors wanting to link to a particular (absolute) URL, must do so
only with "LEscheme:...>" codes (like
LEhttp://www.perl.org>), and must not attempt "LESome Site
Name|scheme:...>" codes.  This restriction avoids many problems
in parsing and rendering LE...> codes."

Elsewhere in the document, it says that the handler should handle these, 
as in the example


 Lhttp://www.perl.org/>

The new Pod:Parser has just been installed in blead, and about 10 pods 
run afoul of this new check, including things like


Lmailto:perl...@perl.org>

My question is should there really be a message for this kind of use, 
and if so, should it extend to mailto: links?