[Doc-SIG] Hyperlink targets and roles

[Garth T Kidd]

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

Why restrict it? Once you get used to using InterWiki to let you say
WikiName:WikiPage to refer to any page on another Wiki, you get annoyed
when you have to go to any more effort than Amazon::B00000F169 to refer
to Dark Star on DVD, Google:Goodger to search for Goodgers on the
Internet, reSTBug:443275 to refer to a tracker item, Jargon:fnord to
look up "fnord" in the Jargon File, and so on.

If reST linkbases turned out to be exclusively for the use of referring
to a named A element in a destination HTML document, I think any
potential WikiUsers would go just a little batty. :)

Of course, if this is an extension then it's up to the application to
make the rules. If linkbases become a part of the reST spec, however, I
feel we should just append the trailing part to the base and let the
user specifiy any required delimiter at the tail end of the base.

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

:)

I don't think this needs a role::

  .. linkbase:: reSTBug = http://sf.net/tracker/\
     index.php?func=detail&group_id=7050&atid=107050&aid=

  Check out `reSTBug:443275`_ for details.

  Or, check out the `test refactoring tracker entry`_.

  .. _test refactoring tracker entry: reSTBug:443275

> Trying to implement all the wonders of queries in URIs and so
> on is too much ambition for reST (now, and maybe forever),

That's why we dodge entirely and just let the user specify some leading
text as the base to which we'll directly append whatever else they
specify later. We don't have to understand any of it at all.

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

For some reason, I immediately thought the solution was to just call it
``base``. :)

> What you're saying is that one can adopt conventions that allow one to
> parse this after reST has finished with the document.

... or, now that I've figured I can abuse non-URI links as automatically
numbered footnotes, figure it out whilst reST is still parsing the
document.

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

Hmmm.

You never know, you might convince me. :)

> Maybe we need to be more explicit::
>
>     .. linkrole:: "fred" means "fred.txt"

I'll meet you half way::

  .. linkrole:: fred=fred.txt#

  .. linkrole:: reSTBug=http://sf.net/tracker/\
     index.php?func=detail&group_id=7050&atid=107050&aid=

  Check out `reSTBug:443275`_ for details.

  Or, check out the `test refactoring tracker entry`_.

  .. _test refactoring tracker entry: `reSTBug:443275`_

  Or, check the documentation under `fred:test refactoring`_

Seem reasonable? Well, except for worrying about how roles get in the
way of people linking to `ST: TNG`?

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

Yep.

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

Amen! Some more stuff to roll around:

* Can we deal with roled links with no backquotes? ::

    reSTBug:443275_

* If our trailing portion has spaces, where do we put the backquotes? ::

    fred:`this part of the document`_

  or ::

    `fred:this part of the document`_

Regards,
Garth.