Guido has pointed out in the past [1]_ that there is an uncomfortable
tension between trying to say both "we can't require people to change
their habits <in this particular way> because we know they don't want to
change their habits" and "then just change your habits <in this other
way> to work around <your particular objection>". I think this is
inevitable - David's job (with "help" from others) is to try to balance
these two.
.. [1] See http://aspn.activestate.com/ASPN/Mail/Message/579315,
but please note that I'm rather hijacking the quote for my own
purposes - Guido's point is different.
> Alan Jaffray wrote:
> I think the hyperlink syntax fails to achieve the stated
> goals in some cases, and improving it could make the markup
> even better.
Strangely enough, he then makes exactly the sort of comment that I would
probably have made if I had come into the debate at *this* stage, rather
than having been around and watching for a while. Take that as
compliment or insult - I'm not sure which!
> Example::
>
> For more info, search the `Python DOC-SIG mailing list
> archives`_.
>
> .. _Python DOC-SIG mailing list archive:
> http://mail.python.org/pipermail/doc-sig/
>
> The repetition of half a line of text has three problems.
> First, it's annoying to enter; not too annoying if you have
> a decent editor, but it's more work than it should be.
This is a valid grumble (and as such David addresses it), *but*...
(excuse the rambling before I find a point to get to)
One of the more important lessons I got from Knuth's TeX is the "if the
result isn't what you want, rewrite it" rule. In the TeX instance (i.e.,
digital typesetting) this means that if you write a document and the
typeset result has (for instance) a bad page break, it *may* be that the
solution is to rewrite the text to obtain the layout you want (read
Knuth himself for a better explanation of this sort of thing). In the
example you've given, one can clearly do the same sort of thing (albeit
without the complexity of doing typesetting!). For instance,
simplistically::
For more info, search the Python DOC-SIG mailing list
archives_.
.. _archives: http://mail.python.org/pipermail/doc-sig/
(i.e., just "emphasising" the last word instead of the whole phrase).
Indeed, if one is only interested in the "raw text" and not its final
rendition by a transformation tool, or if one likes the "call-out" style
of layout, one can even replace this with something like::
For more info, search the Python DOC-SIG mailing list
archives[1]_.
.. [1] http://mail.python.org/pipermail/doc-sig/
- a footnote *may* be more natural to how one sees the text flowing.
A slightly more radical rewriting might give one::
For more info, search the Python Doc-SIG mailing list
archives - either the "official_" archives, or (often
easier to use) those at `Active State`_.
.. _official: http://mail.python.org/pipermail/doc-sig/
.. _Active State: http://aspn.activestate.com/ASPN/Mail/
Browse/Threaded/doc-sig
David has already addressed the more "technical" end of things (and I
think his idea of allowing multiple "names" for a target may be a good
one) - I hope this isn't a daft comment to go alongside that.
Tibs
--
Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)