[Doc-SIG] in-line hyperlinks

[David Goodger]

Sorry about the delay replying.

[David]
>> But the whole point is that
>> 
>>     The underscore can be thought of as a right-pointing arrow.
>>     The trailing underscores point away from hyperlink references,
>>     and the leading underscores point toward `hyperlink targets`_.

[Brett]
> I don't view the underscores like that (might be my training in
> philosophy and symbolic logic).  I see them more just as visual
> delineators for the reST parser and not as a metaphorical pointer.

Of course they're "visual delineators"; so is *all* syntax.  In the
end, everything is just pixels on a screen or ink on paper.  The point
is that in reStructuredText's terms, the underscores *act* as if
they're right-pointing arrows, pointing away from references and
toward targets.  Example below.  The existing forms of hyperlinks use
underscores in this way, and I don't see any value in adding new
syntax ("->") to do the same conceptual job.  Also, the underscore
syntax (which originated with Setext) was chosen because underscores
are unobtrusive; "->" stands out more.

>> Just thought of a better name for this beast: "embedded targets".
>
> Using "embedded" works for me, but not targets.

This is in terms of the reStructuredText vocabulary, in which a
"hyperlink" is made up of two parts, a "reference" and a "target".
The vocabulary is established, and it's not going to change without a
good strong reason.

Putting them together, we have a reference::

    name_

and a target::

    .. _name: URL

The reference name is what ties the two together.

In any case, I'm going to call it "embedded URI", which is very
specific.

> I vote for general feature or a directive.  Either was I want the
> feature.

I'm going to make it a general feature.

-- 
David Goodger  <goodger@python.org>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/