[Doc-SIG] rST hyperlink syntax

[Tony J Ibbs (Tibs)]

Alan Jaffray wrote a good description of two alternate proposals for
handling hyperlinks, comments and directives somewhat differently.

One caveat - Alan says, in reference to things starting with ``..``:
> All of them start with a comment syntax intended
> to imply "hidden",

That's not my reading - I read them as "special" things, not "hidden"
things. Anyway, here we go. I'm afraid the following is very much
"stream of consciousness", rather than a reasoned discussion...

Current scheme, scheme 0:
>     .. __: http://somewhere       anonymous uri
>     .. _blah: http://somewhere    named uri
>     .. _blah:                     anchor
>     .. [blah] http://somewhere    footnote
>     .. blah: http://somewhere     comment
>     .. blah:: http://somewhere    directive

Alan's scheme 1 [1]_:
>     __ http://somewhere           anonymous uri
>     __ blah: http://somewhere     named uri
>     __ _blah                      anchor
>     __ [blah] blah blah           footnote
>     .. blah: http://somewhere     comment
>     .. blah:: foo                 directive

Alan's scheme 2 [1]_:
>     .. http://somewhere           anonymous uri
>     .. blah: http://somewhere     named uri
>     .. _blah                      anchor
>     .. [blah] blah blah           footnote
>     ## blah: http://somewhere     comment
>     !! blah: foo                  directive

    .. [1] I took the liberty of replacing "directive" by "blah" to
       make comparison more blatant.

For what it's worth, I am almost totally unable to decide whether his
Scheme 1 is a good idea or not - his arguments are good, and it really
comes down to style (and I remember when I thought what David was
proposing was odd). I think I'd give it a cautious +0 (but I have to
bear in mind, given Alan's later comments, that I'm the sort of person
who is happy to write HTML and TeX, not to mention several different
programming languages, so may not be a good judge in his constituency).

Scheme 2 I find less "nice" - partly because "##" is **TOO** intrusive
(I want comments to be that - stuff that can be ignored, because it's
extra), and partly because "!!" *doesn't* jump out at me in most fonts I
am likely to be using to read raw reST text - ".." is actually much more
visible. The *idea* of separating the one form of ".." into three forms
I don't *particularly* object to, but I suspect that David will have
cogent arguments about "learning 3 things instead of 1". And if we can't
*find* 3 things that everyone is happy with...

I still remember when I finally got David's idea that "we'll delimit the
*odd* stuff about a document with one symbol, so that the eye can spot
it easily" (and, implicitly, just by running down the left margin of the
text, which is a fairly natural thing to do). One does have to be
careful about diluting that ability too much.

Hmm - having just pasted the three schemes next to each other at the top
of this email (interactivity, this is!), I must admit that scheme 1 just
doesn't *look* as nice to me - those underscores feel fairly intrusive.

I must admit that I don't particularly see the advantage, in scheme 2,
of:

>     .. blah: http://somewhere     named uri
>     .. _blah                      anchor

over the equivalent entries in scheme 0 - I think that scheme 0
definitely scores here in having consistency for targets. And that
begins to lead me back to David's argument - that consistency is a Good
Thing (since it gives fewer odd cases to rememeber). In which case,
maybe ``#_`` and ``.. _#:`` would be better cases for anononymity, for
consistency with "anonymous" footnotes. Hmm.

No, for myself I think I've worked back around to liking David's
compromise, scheme 0 (albeit I can't remember if ``#_`` was discussed
earlier, so perhaps modulo that discussion). But that doesn't address
Alan's problem of users with *lots* of hyperlinks, and a reluctance to
type a longer sequence of (apparently, to them) meaningless punctuation
characters.

*Maybe* the "correct" solution, to satisfy Alan's userbase's perceived
reluctance to type (and that's evidently a common human flaw - I cite
Unix shell commands!) is yet another variant:

Tibs' proposal, scheme 3:
     .. http://somewhere           anonymous uri
     .. _blah: http://somewhere    named uri
     .. _blah:                     anchor
     .. [blah] http://somewhere    footnote
     .. blah: http://somewhere     comment
     .. blah:: http://somewhere    directive

The sole change that this makes to scheme 0 is to say that comments may
not start with (something that looks like) a URI. We already know they
may not start with something that looks like a directive, so this may
not be *too* onerous.

The disadvantage is that we've lost the initial "_", which served as a
hint that this was a target URI - but then we don't have that for
footnotes (in that case, because losing the underscore makes the
footnote look more like a footnote).

OK. So my currrent stance is probably:

  - scheme 0 - status quo - status quo is good
  - scheme 1 - not sure
  - scheme 2 - not sure
  - scheme 3 - prefer this to schemes 1 and 2

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"Bounce with the bunny. Strut with the duck.
 Spin with the chickens now - CLUCK CLUCK CLUCK!"
BARNYARD DANCE! by Sandra Boynton
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)