[Doc-SIG] formalizing StructuredText

[Tony J Ibbs (Tibs)]

> > Well, prepare to be well miffed (ST has never supported differing
> > starting and ending quotes). So hey.
>
> Although now we have [...] (or "..."[...] or "...":[...] or whatever
> it really is).

Oh, OK. Point taken (I'd already sensed you don't like those, but they
seem to me so uncontentious).

> Of course, you can't reasonably forbid '#' in URLs, so you'll have
> to put URL recognition before inline recognition *anyway*.. :)

No, that's not a problem. A '#' in a URL cannot be a starting or ending
quote, at least not if I have the URL RE right, because it won't meet
the correct conditions (for instance, it can't have a space before or
after it). A little messy, but that's how ST works.

> I think there's a serious problem here if we are allowing URLs to
> appear in arbitrary places.  For example, consider::
>
>     foo://no#good bar://parse#for this.
>
> It seems perfectly reasonable for #good bar...# to be a literal..

No, that case is unambiguous. The '#' characters are parts of URLs -
they definitely are not quotes. The RE for Python literals (wait a
moment whilst I reconstruct the bits together) is::

	(?P<space> ^ | [ \n] )
	\# (?P<python> [^\#\n]+ ) \#
	(?= [ \n] | $ | [).,;:!?"] )

So the first '#' isn't the start of a literal, because it isn't preceded
by <space>, nor is it the end of a previous literal, because it isn't
followed by space or punctuation (broadly speeking).

The second '#' isn't the end of a literal, because it isn't followed by
space or punctuation, nor is it the start of a literal.

It is *just* possible that I need to worry about the terminating
punctuation and the contents of a URL (and maybe it shouldn't be
#_endpunc#, but #_safe_endpunc# in the Python literal URL - that would
enforce more context after the punctuation, for safety).

Now, I have a sneaky feeling that you don't like that sort of approach,
but so far as I can tell it fits *exactly* the "philosophy" of ST, which
is to make what the user types, in general, come out as they would
naively expect - I *think* a naive user would expect the above not to be
doing quoting.

>    1. Say that the opening '#' must have whitespace to its left,
>       and the closing '#' must have whitespace to its right.  Of
>       course, that forbids saying things like #Object#s, but I
>       guess I could live with that

As you can see, that's the approach taken - and it is taken that way to
be as near identical to the way that single quote literals work as
possible (which also have that same problem).

>    2. Use some special demarkation for URLs!  :)  I'm for this,
>       but am worried about trying to convince the STNG people,
>       esp. if we're proposing using <..>.. Since they're currently
>       saying that such things should be ignored.  Of course, they're
>       clearly wrong on that point, too, but it means that I'll have
>       to argue 2 different points at once. :)  Also, if we do this,
>       we have to be sure to stress in the PEP/ST docs that math
>       must go in literals like: 'x*y>z'.  (Of course, we'll probably
>       want to stress that anyway).

I would also like to delimit URLs - it would make life so much simpler.
But I also suspect the STNG people won't agree (of course, we might both
be wrong!). I still don't see why 'x*y>z' *has* to go in literals,
though - clearly by the current and possible future rules it would work
(if we do introduce quoting characters for URLs, I would want to insist
they act with the same sort of rules as literals and Python literals, so
that maths would be no problem).

> Are there any objections in principle for using <...> to delimit
> URLs?  (Other than that it will be hard to convince STNG people).
> If not, I think we should start trying to convince STNG people to
> use <...> for URLs, and to give up on ignoring <...> tokens.

I think it would be a marvellous idea - people already are used to it in
emails, and it makes life simpler all round. Yes, by all means open
talks on this matter on the STNG arena.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)