[Doc-SIG] Hyperlink targets and roles

[Tony J Ibbs (Tibs)]

Ok - first of the first batch of comments. I'll try to split things out
into sensible threads. If I don't reply to one of your own comments,
please feel (moderately) free to assume enthusiastic agreement...

David Goodger wrote:
> So you're suggesting a "namespace" (working name) directive which
> dynamically defines a base hyperlink, to which the hyperlink itself
> is appended? Would this apply to hyperlinks only, or also to
> interpreted text roles?

Well, *actually* I'm not proposing something I'd describe in those
terms.

I'd describe it as defining a role, from the point of definition onwards
in the document, which can be used as "shorthand" to indicate that the
hyperlink given is actually in another document, and not in this one. So
the term "namespace" is really a bit misleading.

I'm *not* convinced this is something we need to worry about in the
first release of DPS/reST - it's just convenient when commenting on
stuff.

Anyway, what I had was essentially of the form::

    .. namespace:: <hyperlink-role> is <some other file or URI>

(you can already see it wasn't very thoroughly thought out! - and I
still think "namespace" is the wrong term). And yes, I guess that we
would then see::

    <hyperlink-role>:`somelink`_

as translating (in HTML terms) to::

    <some other file or URI>#<somelink>

(although modulo the "normal translation rules" for <somelink> that are
imposed by the output formatter - e.g., the "name" for footnote ``[1]``
might be "footnote1").

> I think something like this would be useful. Garth Kidd brought it up
> recently as well. I don't know how it could be implemented
> though.

I think that what I want could be implemented just as simply as above -
it would *assume* that there were appropriate targets defined in the
referenced document, and this (in turn) would assume that the output
formatter for HTML put in all the implied targets (i.e., title links,
etc.) even if they weren't used *within the document*.

I am *not* proposing something as complex as XLink and XPointer - *that*
should wait until (a) we see that we have a *need* for something so
complex, and (b) we have a mature reST to put them into (I personally
doubt we'll need it).

Hmm - maybe we need to do the definition more like::

    .. lookup:: <role> in <URI>

or even::

    .. role:: lookup <role> in <URI>

(you can see why I'd rather not worry about it for the moment)

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)