[Doc-SIG] Implicit Link Targets

[David Goodger]

on 2001-06-20 7:53 AM, castor@snafu.de (castor@snafu.de) wrote:
> Reading the `specification docs`_ once more, I realized it
> might be pretty desirable to have implicit link targets.

Having implicit link targets for titles is a good idea. Note that the
'figure' directive was just an example, and isn't an 'official' part of the
spec.

> It might be desirable to issue
> warnings in case non-unique titles/captions are actually
> referred to within the text.
> 
> Implicit targets could be supplemented/overridden by explicit
> targets; their use would obliterate the need for most explicit
> targets seen in a text like the specification itself.
> 
> Is that desirable/implementable?

Yes, just as you specify. I spent a few minutes coming up with some simple
rules:

1. Keep track of implicit & explicit links in separate dictionaries.

2. In case of:

   - duplicate explicit & implicit targets: priority to explicit
   - duplicate implicit targets: disable all of them, don't warn
   - duplicate explicit targets: warn & diable all of them

   'Disable' means to remove link names from targets. System warning
   elements can be inserted where target links are disabled.

The DPS won't care whether links are implicit or explicit. The parser must
deliver a set of *unique* target links (as attributes on elements). The DPS
can warn of unresolvable links, even giving reasons for the warnings.

It will certainly make cross-reference-rich documents (like the spec :-)
easier to read, and won't detract from understandability. "See 'Details'
below" is a very common prose idiom, the literary hyperlink exactly. Just so
long as there's a zero-tolerance policy on implicit hyperlink ambiguity in
place, I don't see why it can't fly.

Does this allay your misgivings, Tony?

Thanks, Wolf.

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