[Doc-SIG] Hyperlink targets and roles

[Tony J Ibbs (Tibs)]

Garth T Kidd wrote (in reply to me):
> > 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>
>
> My experience with InterWiki links tells me that we don't want a
> delimiter between the namespace base and the extension. The
> user can put the ``#`` at the tail-end of the base if appropriate.
> If we implement namespaces, I expect to often see ``/``, ``?``,
> ``?something=`` and ``&something=`` at the tail end of the base.

Gosh - that's altogether more ambitious than I wanted to be - you're
clearly trying to allow the full flurry of HTML references to be done
via reST, whereas I was just wanting to allow someone to reference a
*specific* label in a different file.

To my mind, if someone wants to do::

    http://whatever/thing?fred

then they can either included it as an explicit reference, or use the
indirection mechanisms. But I've not used InterWiki - why and how do
people do this there?

Anyway, my proposed new role *does* just identify a file, and the role
translation and the label *can* be separeted by "#" in the resultant
HTML, 'cos that's the limit of my ambition.

Trying to implement all the wonders of queries in URIs and so on is too
much ambition for reST (now, and maybe forever), I think - and if I
*did* want to do that, I'd be looking at leveraging off
Xlink/Xpointer/etc anyway, not off the URI specs (they're *so* much more
powerful, especially in the neat ability to regard the target document
as tree and/or stream at the same time - if you haven't looked at them,
I recommend it. Thinking of XML documents as two differing structures at
the same time is fun!).


> Can we call namespaces something... well, less spacey?

Yes, namespace is a poor choice - I've been doing XML related stuff
lately, is my only excuse, and couldn't come up with something
(anything) better at the speed I was typing.

> They're named link target bases,

Well, actually I think they're documents, and I think we should perhaps
try to eschew the low level description (link, etc) in the directive.
Perhaps::

     .. reference:: fred is "fred.txt"

might work. Anyway, since I'm not *particularly* proposing to ask for
these in early versions of reST, I'm not worrying too much about this.

"linkbase" sounds too low level to me - "base" is very non-obvious to
me.

> When I hear you talk about namespaces being involved with
> links in reST, I start thinking that there's a footnote namespace
> and a default link target namespace

Erm - no, that's a different use of the word namespace. As you say. Ho
hum.

> I'll call 'em linkbases for the rest of this message to see how it
> sounds.
>
> If your application needs linkbases, currently you don't even need
> roles.
[explanation omitted]

What you're saying is that one can adopt conventions that allow one to
parse this after reST has finished with the document. Which is so
(indeed, if reST works *at all* like stpy worked, it will be doing a
succession of refinements of its own internal datastructure, one by one,
and this is equivalent to just another one).

But we've *got* roles, and they are thus an obvious thing to use for
this purpose - a role amends its associated interpreted text, and if
that interpreted text is being used as a link, then the obvious thing
for a role to do is to amend that link. And one of those obvious things
is saying "look in another document".

Maybe we need to be more explicit::

    .. linkrole:: "fred" means "fred.txt"

(in case you hadn't guessed, I *much* prefer words to symbols in the
body of the definiton of such things - but that's a separate argument).

Of course, this was also all gist to my argument that role *use* should
be done as::

    role:`thing`

rather than::

    `role: thing`

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.)