[Doc-SIG] rST hyperlink syntax
David Goodger
goodger@users.sourceforge.net
Tue, 09 Oct 2001 22:31:04 -0400
Alan Jaffray wrote:
> Thanks for the thoughtful reply. :)
Any time. As I've said before, the more brains this stuff gets filtered
through, the better the result. Everybody's gray matter catches & releases
different stuff.
> It's good to catch mistakes, but it's even better to avoid them in
> the first place. :)
It's hard to catch spelling errors in variable names in code (the equivalent
of these reference names) without compiling or checking with something like
PyChecker first. Somehow I don't see such checking happening, certainly not
via syntax. Maybe Microsoft will include an integrated reStructuredText
editor with Visual$tudio. (Damn! I forgot to get a patent!)
> > The author is by no means forced to use long hyperlink phrases though.
>
> I disagree here.
It may be good form to use long hyperlink phrases (thanks for the link), but
there's still no *force* involved. ;-)
> So I'd like the link text to go along with a name which is in turn
> associated with the hyperlink, rather than the link text going to
> the hyperlink directly. But you're right that inlining the name is
> intrusive. Maybe we could instead have the link point to the name?
>
> reStructuredText is cool, see the `reStructuredText specification`_
> to see how cool it is.
>
> .. _reStructuredText specification: rtxt-spec_
...
> [800 lines later]
>
> .. _rtxt-spec:
> http://structuredtext.sourceforge.net/spec/reStructuredText.txt
I'm sure that "multiply indirect hyperlinks" have been discussed here
before. Odd; they're not on the To Do list, not even with a "?". I'll look
up the past arguments and add them (but with a "?": I still need to think
the idea through).
> Not sure what to do about ambiguity with URLs ending with an underscore.
> Quote one or the other? Use a different syntax?
If the hyperlink meaning of the trailing underscore is favored, then it
would have to be escaped if a significant part of a relative URI (e.g. a
file called ``rtxt-spec_``)::
.. _reStructuredText specification: rtxt-spec\_
Otherwise, *all* such indirect references would have to be quoted::
.. _reStructuredText specification: `rtxt-spec`_
And even this could be ambiguous, were there a file called "\`rtxt-spec`_"!
I think the former would be the better choice.
> > .. [#] Syntax idea: double underscores::
> >
> > For more info, search the `Python DOC-SIG mailing list archives`__.
> >
> > .. __: http://mail.python.org/pipermail/doc-sig/
>
> Nice idea. I think this would be used often enough in practice that the
> design principles demand a simple syntax. Could we make it even simpler? ::
>
> For more info, search the `Python DOC-SIG mailing list archives`__.
>
> .. __http://mail.python.org/pipermail/doc-sig/
I think orthogonality requires the full ``.. __:`` syntax. Without a colon,
the URI looks too much like a hyperlink name
> assuming links starting with underscore have to be quoted.
A hyperlink (reference) name starting with an underscore would have to be
quoted, but the corresponding target name wouldn't (the ``.. _`` provides
enough context). So the abbreviated syntax would be ambiguous (in artificial
cases, of course, but we don't want any holes at all).
> I'd go with arbitrary subphrase, zero or more full words, as an optional
> extension to the colon-less syntax above. It seems more natural to me -
> more like what a human would normally write - than either substring or
> first/last word.
Perhaps. I'm not ready to pronounce one way or the other. How about writing
a rEP (reStructuredText Enhancement Proposal)?
(gotcha ;-)
But seriously. I'm uncomfortable with the idea of using a hyperlink
subphrase; it seems like an invitation to unintended duplication and
guessing. How about combining the ideas instead? ::
See the `Python Doc-SIG mailing list archives`__
.. __: archives_
[800 lines later:]
.. _archives: http://mail.python.org/pipermail/doc-sig/
> It could help catch maintenance errors getting links
> and targets mixed up.
I don't follow. Please explain.
--
David Goodger goodger@users.sourceforge.net Open-source projects:
- Python Docstring Processing System: http://docstring.sourceforge.net
- reStructuredText: http://structuredtext.sourceforge.net
- The Go Tools Project: http://gotools.sourceforge.net