[Doc-SIG] References in the same line as the target text

[David Goodger]

Ken Manheimer wrote:
> Come to think of it, how does reST handle something like:
> 
>   You can find more info about life `here`_ and `here`_
> 
> ?  I assume you're not forced to use different text for your
> references just so they unambiguously couple with their links.
> (That might not be so bad in my contrived example, but would be a
> nuisance for more distantly situated references that happen to have
> identical text.)

Actually, named references *do* have to have different text if they're
to refer to different targets.  In a situation like the above,
currently you'd have to use anonymous hyperlinks like this::

    You can find more info about life here__ and here__

    __ http://www.example.com/first
    __ http://www.example.com/second

Using the embedded variation of inline external targets (#4 in the
"summary" post), it would look like this::

    You can find more info about life `here
    <http://www.example.com/first>`__ and `here
    <http://www.example.com/second>`__

BTW, you don't need to use backquotes for single-word references
("`here`_"), although they don't hurt.

> I really think the readability in this case is a judgement call, and
> the author should have the opportunity to choose the style they
> think is most appropriate for the situation.

Noted.  But on the other hand, we can't cater to everyone's taste; the
result would be an uncoordinated mess.  I'm torn on this issue.  The
proposed syntax offers convenience, but I don't know if the
convenience is worth the cost in ugliness.  Perhaps if the syntax is
*allowed* but its use strongly *discouraged*, for aesthetic reasons?
Or would that just be hypocritical?  Dilemma.

-- 
David Goodger  <goodger@users.sourceforge.net>  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/