[Doc-SIG] Hyperlink targets and roles

[Garth T Kidd]

> Name: maybe "baselink" or "basedoc" or "baseref"?

``baseref`` is good, yeah.

> I like the idea of putting the base document reference in the target
> rather than in the text as a prefix to the hyperlink itself.
...
> However, there is a problem with the above approach:
> 'dictionary:' looks just like a URI scheme ('http:', 'mailto:',
> etc.).

True.

I don't think the WikiTeemingHordes will be much worried about the
camelcased WikiName of an InterWiki target potentially clashing with the
name of a new URI scheme, so I suspect they'll not be too concerned
about using InterWiki targets as "phantom" URI schemes. That's their
application, though, and their problem []_.

.. _[] If we insist upon lowercase scheme names, that might actually
   help them. Any InterWiki link will fail the "is this a URI?" test
   and sit there unresolved waiting for the Wiki to save it.

More generic document handlers won't support such behaviour. Moreover, I
can't see WikiUsers employing baseref -- they have their own mechanism
for that kind of thing -- so I'm comfortable with your second alternate
syntax for baseref::

>     .. _fnords: dictionary fnord

>     <target baseref="dictionary" name="fnords">
>         fnord
>     </target>


> >     .. Hmmm. If we adopt backslashed line extension, we should trim
> >        whitespace up to the indentation level of the block.
>
> We don't need backslashed line extension.

... for link targets (I now find out :), or for any directive which
takes a single URI as its only argument, but what about directives
supporting spaces in their arguments? ::


  .. indexterms:: extension, line extension, extension of lines,
     and it just occurred to me that you're about to say that it's
     up to any directive to parse its own block and if that
     directive wants line extension it can bloody well do it itself. :)

> I've implemented hyperlink targets to collect all text, strip them
> of whitespace left & right, and concatenate.

That's very nifty, by the way.

> >     role:`thing`
>
> I'm coming to prefer the former (role outside of the quotes).

Good. :)

> I see the need for explicit roles with such concepts as index
> entries and inline graphics.

How do you see inline graphics handled?
inlinepicture:`externalsite.gif`?

Regards,
Garth.