[Doc-SIG] Hyperlink targets and roles

[Garth T Kidd]

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

Can we call namespaces something... well, less spacey? They're named
link target bases, and I'm not sure "space" gives us much of a benefit.
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 but just in case you have documents created by
aggregation you can give each chapter its own link target namespace to
avoid collision.

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. Just look for linkbase directives and then parse link targets to
see if they begin with a particular	base name and a colon. Let's say
someone specifies the following text:

    .. linkbase:: dictionary=http://www.dictionary.com/cgi-bin/\
       dict.pl?term=

    .. Hmmm. If we adopt backslashed line extension, we should trim
       whitespace up to the indentation level of the block.

    Look out for the fnords_!

    .. _fnords: dictionary:fnord

What you get back from reST (assuming backslashed line continuation and
ignoring the comment)::

  <document>
    <block_quote>
      <directive
data="dictionary=http://www.dictionary.com/cgi-bin/dict.pl?term="
type="linkbase"/>
      <paragraph>
        Look out for the
        <link refname="fnords">
          fnords
        </link>
        !
      </paragraph>
      <target name="fnords">
        dictionary:fnord
      </target>
    </block_quote>
  </document>

When you see the linkbase directive, add the linkbase to your table.
When you see the ``<target>``, note that it starts with a valid
identifier followed by a colon and that identifier matches a linkbase,
and parse it accordingly.

Wikis would pre-load their linkbase tables with the InterWiki list.

Yet again, reST's clean design has ensured that you can implement what
you need without having to change a line of parser code. :)

Regards,
Garth.

--
Garth T Kidd <garth@netapp.com>            Mobile:     +61-411-596-593
Consulting Systems Engineer, Aust/NZ       Direct:     +61-2-9779-5614
Network Appliance                          http://www.netapp.com/