[Doc-SIG] rST hyperlink syntax

[David Goodger]

[David]
> I think orthogonality requires the full ``.. __:`` syntax. Without a colon,
> the URI looks too much like a hyperlink name

[Alan]
> How about something even simpler and more visually
> distinctive as the anonymous hyperlink target syntax? ::
> 
>     For more info, search the `Python DOC-SIG mailing list archives`__.
> 
>     __ http://mail.python.org/pipermail/doc-sig/

Orthogonality again: two ways of spelling the same thing. I think the only
way such a simplification would be acceptable is if it simplified the
general case, thus becoming the one and only spelling. The general case, a
phrase-named hyperlink target, does require a delimiter between the
hyperlink phrase and the URI. The special case of anonymous hyperlinks isn't
special enough to be exempt from the delimiter.

> I don't think losing unescaped underscore-underscore-space at the
> beginning of a line is a significant loss.

It would add yet another independant markup symbol beginning a construct,
"_". The syntax as it stands is "what you see is what you get (wherever
possible)" plaintext. The only exception is the explicit markup token,
".. ", which covers all the advanced/tricky/behind-the-scenes cases. I'm
loathe to add more exceptions, but let's examine the ramifications.

Generalizing the simplification leads to the idea of dropping the ".. " from
all hyperlink targets. In a sense, this adds complexity. Let's assume the
simplification is worth this added complexity, and that there's no ambiguity
from the new symbol. In addition to "tricky", ".. " also has a connotation
of "hidden". Hyperlink targets are hidden in the final processed document,
as are comments. Directives are likely to be visible in some form, but this
simplification doesn't apply to them. Footnotes *are* visible though, and to
be fair ("orthogonal"), they ought to benefit from the simplification too.
But "[1]" without ".. " *is* absolutely ambiguous. Footnotes *cannot* be
simplified this way.

Does this disqualify the simplification? I don't know (too tired to think it
through right now). I'm sure there are flaws in my logic.

> In exchange, we get far less cumbersome syntax for a very simple and
> frequent construct.

An interesting idea, yes, but I'm not sure about its frequency. It wasn't
missed until now.

> Doing simple things should be simple.  Besides, I question whether
> the string ``.. __: `` has any place in a language which includes
> the goals of being intuitive and readable. :-)

Design goal #2 is the most relevant here:

    2. Unobtrusive: The markup that is used should be as simple and
       unobtrusive as possible. The simplicity of markup constructs
       should be roughly proporional to their frequency of use. The
       most common constructs, with natural and obvious markup, should
       be the simplest and most unobtrusive. Less common contstructs,
       for which there is no natural or obvious markup, should be
       distinctive.

I think directives, comments, footnotes, and hyperlink targets are clearly
part of the "should be distinctive" group.

> (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.  In general, if I find
> something that seems awkward or difficult to me, it's a pretty
> good indication that it'll be even more so for some of them.)

In our realm of human-language text parsing, it's hard to balance the
contradictory desires for simplicity, clarity, consistency, and
orthogonality. Something's gotta give. A little education is all that's
necessary to get past the less-than-ideal bits. A lot less education than if
you standardized on HTML though!

-- 
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