[Doc-SIG] References in the same line as the target text
Fri, 12 Jul 2002 00:39:24 -0400
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__
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
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 <firstname.lastname@example.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/