[Doc-SIG] rST hyperlink syntax
Garth Kidd
garth@deadlybloodyserious.com
Thu, 11 Oct 2001 10:22:58 +1000
> Read the `Python Reference Guide`__ and `Introduction to Python`__.
>
> .. __reference: http://www.python.org/doc/current/ref/ref.html
> .. __introduction: http://www.python.org/doc/Introduction.html
>
> I change the paragraph to::
>
> Start with `Introduction to Python`__, and if you want the full
> details, check out the `Python Reference Guide`__.
>
> Because of the qualifiers "reference" and "introduction", the links
> still point to the right targets. Without the qualifiers, I might
> forget to change the order of the links.
I have to admit, I'm enjoying this thread. :)
FWIW, if we lose the double-underscore in the text itself, this is something
that (like most specific link resolution tasks, eg handling WikiNames) can
be handled by the consumer. Consider::
Read the `Python Reference Guide`_ and `Introduction to Python`_.
.. __reference: http://www.python.org/doc/current/ref/ref.html
.. __introduction: http://www.python.org/doc/Introduction.html
Becomes::
<document>
<paragraph>
Read the
<link refname="python reference guide">
Python Reference Guide
and
<link refname="introduction to python">
Introduction to Python
.
<target name="_reference">
http://www.python.org/doc/current/ref/ref.html
<target name="_introduction">
http://www.python.org/doc/Introduction.html
All we need to ensure correct matching is a rule somewhat like: if a
target's name doesn't match any link's refname, *and* the target's name
begins with an underscore, use the nearest preceding link whose refname
contains the target's name with the underscore stripped.
How easy is that? :)
> I plan to use rST for my own projects, but my main intended use
> for it is as a standard markup language for my department, which
> is composed primarily of non-programmers.
Amen to that! The good news is, reST's clean separation between parser and
consumer (or whatever we're calling either these days :) means you can
usually include user-friendly features without having to change reST itself.
Regards,
Garth.