[Doc-SIG] Formalizing ST

[Tony J Ibbs (Tibs)]

Peter Funk wrote:
> Tony J Ibbs (Tibs) schrieb:
> > You haven't been following the me and Edward Loper (and Edward
> > Welbourne) flurry of emails over recent weeks, have you?
>
> Yes, I did, but refused to jump in:

Admirable restraint! (and brave man for following it all)

> I believe it was somewhat theoretic.

Well, a mixture of theory and pragmatism, jumbled up to be hard to
distiguish.

> In practice I have never ever seen a URL ending with a
> period.  Please give real world evidence of some useful URL.

Oh, I'm not convinced that we couldn't manage with the ad-hoc use of REs
that I, Ka-Ping Yee, and others have been managing with. But Edward *is*
unhappy with it, and that has become significant to me as he has shown
good "design sense" in other places.

Obvious URIs that fail the test are "." and ".." (both perfectly legal
"local" references within an HTML document, and certainly possible
things for someone to want to use in a docutils context, I'd have
thought - particularly in a package's __init__.py docstring).

> IMO it wouldn't hurt, if detection fails in this case.

The problem isn't with detection *failing*, it's partly to do with
excessive detection (i.e., the pragmatic schemes generally try to
over-identify URIs, just in case), but *mainly* due to a worry about
explaining to a user what they can type that will work, before they type
it.

An explanation that goes:

    "type your URI, but if it ends in one of
     these characters, you'll have to escape
     it, or something, and by the way *this*
     ad-hoc list of characters inside your
     URI also needs escaping"

doesn't seem to be attractive to Edward (put that way, who can blame
him), whereas it's very easy to say:

    "if you want your URI to be recognised,
     highlighted as such, and with a link
     if the application supports it, just
     put '<' and '>' round it, like you're
     used to seeing in email headers"

and expect people to remember it. We might even be able to allow
*spaces* in a URI with the '<..>' scheme, which is seriously neat.

> I don't suggest to forbid the '<' and '>' delimiters.
> Just make them optional.

Edward and I will both grumble at it being optional - he for formal
reasons, and I 'cos its wasted mind space remembering optional things
when you don't need to, and it gives you the worst of both worlds.

> This will work just fine in at least 99.8 % of all cases.

Hmm.

I'd vote for either ad-hoc recognition or '<..>', and Edward makes a
good case for using the latter if we're starting "from scratch".

(Note that, despite your attempts to throw oars into our works (!), I'm
glad to see that at least one of the disputative regulars from last time
round the Doc-SIG loop is listening - please feel free to correct my
"historical comments" if you think I'm getting them wrong.)

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