The long-lost question of "Why can't we have L<text|href>?" came up this week
on p5p. David Wheeler and I spoke about the issue briefly, because we couldn't
find anything in perlpod or perlpodspec that really specifically addressed the
reason other than "because it would be difficult."
I did a fair big of archive-diving and found two basic arguments:
(1) Sean Burke was fighting against very painful parsing code and wanted to
keep things as simple as possible, which was "not very simple" to begin
with. Adding this seemed too hard, and it was declared off limits.
(2) It was unclear how non-hypertext formatters would choose to render links
with text.
As to (2), I think it's up to the formatter, many of them already deal with
this problem, and I do not think any formatter author will be terribly
inconvenienced by it.
As for (1), I think that it is actually not difficult, and merely appeared so
due to the software involved at the time. David and I whipped up what I
believe is a fairly complete and mostly unambiguous grammar:
# Grammar for L<> in Pod5
link-code = "L<"
( link-text "|" ) ?
(link-target)
">"
link-text = [^|]+
link-target = pod-target
| man-target
| internal-target
| url-target
pod-target = perl-module-name
( "/" section-name ) ?
man-target = [-\w]+ ( "(" digit ")" ) ?
( "/" section-name ) ?
internal-target = "/" section-name
| "/" quoted-sec-name
| quoted-sec-name
section-name = [^|/]+
quoted-sec-name = DQUOTE section-name DQUOTE
url-target = \w+ ":" [^:\s] \S+
The only ambiguity that is obvious to me is also obvious to perlpodspec.
L<xyzzy> could mean either xyzzy.pm in @INC or the man page for xyzzy. The
L<xyzzy(6)> form disambiguates in favor of man. This is already a known issue
and is not complicated by allowing L<foo|http://foo.com>
So... what's the problem?
--
rjbs
