Re: Deprecation of alternate text in hyperlinks

"Sean M. Burke" <[email protected]> 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 L<email me!|mailto:[email protected]> 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
L<foo|http://foo.com/> as "foo <http://foo.com/>", 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 L<[email protected]|mailto:[email protected]> now!"
> indeed *can* show up as
>  "I'm at [email protected][mailto:[email protected]] now!"
> but it's so *obviously* redundant that that can just show as:
>  "I'm at [email protected] now!"

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

Related, I think L<mailto:[email protected]> should probably turn into just
[email protected] in a text output format.

> B1) You (pod-writer) could write:
>   "Look at my web site, L<http://stuff.com/>!"
> 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,
>   <a href="http://stuff.com/"></a>
> or
>   <a href="">http://stuff.com/</a>
> don't magically turn into what the output would be of
>   <a href="http://stuff.com/">http://stuff.com/</a>
> 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<http://stuff.com/|http://stuff.com/>

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
>   L<my friend's web site|http://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 <http://stuff.com/>

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 ([email protected])             <http://www.eyrie.org/~eagle/>