[Doc-SIG] Hyperlink targets and roles

[David Goodger]

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

[Garth]
> 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=
...
>     Look out for the fnords_!
> 
>     .. _fnords: dictionary:fnord
...
> 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.

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. It reads
better, which is the whole point of indirect hyperlinks in the first
place. However, there is a problem with the above approach: 'dictionary:'
looks just like a URI scheme ('http:', 'mailto:', etc.). It needs
differenct syntax. Something like::

    .. _fnords: (dictionary)fnord

or an optional first argument::

    .. _fnords: dictionary fnord

And I would parse this into something like::

    <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. I've implemented hyperlink
targets to collect all text on the same line as the markup start and
on subsequent indented lines, up to the first blank line, strip them
of whitespace left & right, and concatenate. For example, these are
all equivalent::

    .. _target: http://a.very.
                long.host.name.com/
                index.html
                #fragment

    .. _target:
       http://a.very.
       long.host.name.com/
       index.html
       #fragment

    .. _target: http://a.very.long.host.name.com/index.html#fragment

The namespace/linkbase/baseref/etc. directive can do the same.

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

I'm coming to prefer the former (role outside of the quotes). Of
course, with a properly implemented interpreted text resolver, we
won't *need* to explicitly specify roles much anyhow. In Python
docstring mode, identifiers won't need roles; they can reliably be
inferred from context. I see the need for explicit roles with such
concepts as index entries and inline graphics.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net