At 07:23 PM 2001-08-19 -0700, Tim Gim Yee wrote:
>I rewrote some of the rewrite to perlpod. The changes I made include:
>[...]
> Added E<colon> (a literal ":"), to prevent links that look like
> URLs from being interpreted as such. [...]
Hm. What could look like a URL in a L<thing> construct, but not /really/
be something you'd want interpreted as a hyperlink to that URL? I'd
appreciate a good plausable example.
(And I'll mock a bad and ridiculous example! MOCK!)
>[...]
> In addition to =head1..=head4 and =item, one should be able to link
> to X<topic> sequences. So instead of conflating "sec" and "ident"
> in L<> sequences to "sec", it is now conflated to "node", which
> is less descriptive. [...]
I'm tempted to reject this, since I think of X<...> as just for producing
index points, not hyperlink targets -- and these are very different things.
Expanding X's semantics to allow hyperlink targets is good if your only
concern is getting this:
And that's why AUTOLOAD hurts my brain.X<AUTOLOAD hurting brain>
...much later...
Brain hurting is discussed L</"AUTOLOAD hurting brain">.
...to turn into HTML like this:
And that's why AUTOLOAD hurts my brain.<a
name="AUTOLOAD hurting brain"> </a>
...much later...
Brain hurting is discussed in the section
<a href="#AUTOLOAD%20hurting%20brain"
>AUTOLOAD HURTING BRAIN</a>.
However, it's quite unclear how that should render to non-hypertext formats
-- say plaintext. If you just throw away the X<...>, you get:
And that's why AUTOLOAD hurts my brain.
...much later...
Brain hurting is discussed in the section "AUTOLOAD hurting brain".
Problem is, there's no section called "AUTOLOAD hurting brain". If you
call this "node" instead of "section", you leave people even more
perplexed, because what the hell is a node? Saying that L</"foo"> is for
"sections" (whether started by true headings, or by heading-like =items)
means you get to make happy hyperlinks if you're rendering to HTML, but you
can still produce sensible output in plaintext formats -- as opposed to
having to unduly stretch people's idea of what a "section" is, and how to
go eyeballing for a section that has a particular name.
(The fascist explication of this is "If it's important enough to link to,
it's imporant enough to get its own sub(sub)*heading!" But that's not a
real reason.)
I consider the ability to render to non-hypertext formats to be an absolute
requirement for POD, and I'm extremely loathe to introduce any features
whose applicability to nonhypertext formats is difficult, complicated, or
unclear. (The current application of X<...> to many/most formats IS clear
-- ignore it!)
Going the other way, I incidentally also consider the ability to render to
HTML to be an absolute requirement of POD, but that doesn't mean I think
that all of the expressive power of HTML should necesarily be accessible
within POD.
I'm generally not one to argue for constraints just for their own sake, but
I'm basing this pretty directly on what's said in perlpod:
The intent is simplicity, not power. [...]
I'm just trying to make an idiot-proof common source for nroff,
HTML, TeX, and other markup languages, as used for online
documentation.
This admittedly requires a nuanced reading of "simplicity". But one of the
lessons I've learned with markup languages is that some things can make the
spec simpler (increasing one kind of simplicity) while making actual use
harder (reducing another kind of simplicity), and/or complicating the
implementation of parsers/converters.
POD /is/ harder to parse than a minimal dialect of XML. Really, it is, and
nothing can sensibly change that. (L<...> parsing alone is harder than
some languages.) But it is easier to use than such an XML dialect.
So the goal here is to keep the use and rendering of POD pretty simple,
while still not making life too much hardER for the brave suffering souls
who write the POD parser libraries.
--
Sean M. Burke [EMAIL PROTECTED] http://www.spinn.net/~sburke/
