I kinda passed off perlpodspec to... whoever...
I'm pretty sure I did, to somebody....
But I'll chip in about L<guh|http://...> in perlpodspec.
Long story short, about L<guh|http://stuff.com/hditfn> and modding
perlpodspec to say it's okay: DOIT!
There *were* three things that I thought were stumbling blocks with
supporting L<guh|http://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<text|http://...> 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
L<guh|http://whatever> is fine, is fine by me.
Long story long:
I think my motivations, a decade ago, for deprecating
L<guh|http://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<Perlport's section on NL's|perlport/Newlines>
...and somehow the slashes in (http) URLs screwing with that, by
producing an ordering paradox-- something like parsing
L<guh|thing/zuh> meant that splitting the text had to happen at one
stage, but L<guh|http://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 L<guh|http://zuh> working, and
no instances of screwed-up parsing have been reported, so... probably
as long as nobody does L<E<45678>|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 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.
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<guh|http://....> :
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:[email protected]]! 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 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!"
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<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/>
B2) You (pod-writer) could write:
"Look at my web site, L<stuff.com|http://stuff.com/>!"
If the module rendering that to non-hypertext is type A1, no problem:
"Look at my web site, stuff.com!"
If the module rendering that to non-hypertext is type merely-A2, well,
it's a ugly:
"Look at my web site, stuff.com[http://stuff.com]!";
...but it never loses any information.
But maybe it's not a strict type A2, but has some DWIM making it a A2.5:
"Look at my web site, stuff.com!"
B3) Now, suppose you wrote:
"Look at L<my friend's web site|http://stuff.com/>!"
If your non-hypertext renderer is type A2 or A2.5, then you'll get:
"Look at my friend's web site[http://stuff.com/]!";
Ah, but IF your non-hypertext renderer is type A1, it will show, VERY
unhelpfully:
"Look at my friend's web site!"
THAT is what I reallyp...
really...
really...
REALLY wanted to avoid any possibility of happening.
At all.
So the problem, in my mind, was: we can't be sure that you're writing
in style B3 and the end-user's (well, end-reader's) renderer is type A1.
(And remember, a "non-hypertext format" might include hitting Print on
what you're looking at in your browser.)
But instead of trying to avoid *any possibility* of it, I now think
the best solution is two bits of shouting:
HEY, non-hypertext module writer! Don't write a type A1. Instead,
write an A2.5! It'll require only a bit more work, and will be as
pretty as A1 *most of the time*, except in the apparently actually
rare cases where the URL isn't just the link text with a little or no
extra stuff. The ugliness of a just-A2 won't come up as often as you
might worry.
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.
I might like to browse the docs at search.cpan.org. But that might be
showing the *current* version of a module, whereas my local version isn't.
I might like to browse a batch-HTML-conversion of the pod of all the
modules on my system. I also might forget to re-generate that batch
when I add/upgrade modules.
I might perldoc set to spit out an HTML temp file and open my browser
on that file... but I can't remember how to do that, and looking it up
is harder than me just using perldoc plaintext to look up one thing.
I might like to use podwebserver. What's not to love there? Except a
total lack of searchability.
But first off, it's manymany years of muscle memory for me to do
[three magic keys] "perldoc modulename" Enter.
Also, vanilla perldoc is the *only* easy way to get at the docs on a
*remote* system (unless I open podwebserver's port 8020 on a router,
or two, and and and...)
And, except for search.cpan.org, I *wrote* all of the above
alternatives to default perldoc, but I (!!!) forget about them, and I
just use vanilla perldoc -> nroff -> less.
So, folks: be nice when using
L<link text|http://encyclopediadramatica.ch/Smile.jpg>,
and then all will be well.
Naptime!
