[Doc-SIG] reserved characters

[Edward D. Loper]

> Edward D. Loper wrote:
> > The idea would be that specific ST's would be allowed to use
> > reserved characters if they want, or remove them from the reserved
> > character list if they want.  So in STminus, we would have::
> >
> >    ReservedChars = # | @
> >
> > And in STpy, we would have::
> >
> >    ReservedChars = #
> 
> Hmm - I think I'd be happier calling them "special" characters, because
> they *aren't* "globally" reserved 

I don't mind calling them special.

> - they can always be used freely in
> contexts where they aren't keying their special action - for instance::
> 
> 	First we have a #Python literal#, but # this looks like some sort of
> comment
> 
> - that third '#' is NOT treated specially.

Ack, no!  :)  This is potentially the type of "non-safe" behavior
I want to avoid..  This leads to people saying::

     x = y*z

in their comments, and then later adding::

     I *like* multiplication

to the same comment, and getting everything from z...I in bold,
and an asterisk after like.

I think that the use of mismatched delimiters should be undefined.
In particular, it should *not* be defined to produce those
delimiters as plain text.  So in any parser I would write, it 
would give an error for the string you gave..

Currently, the *only* character that I think should count
"only in special circumstances" is the single quote.  I don't
see any way around that, because of words like "don't."  But
in my formalization, I'm planning to make "non-markup" use
of (most?) other special characters undefined (except when they
appear in 'literals' or #inlines#).

(Well, "...":.. is also "special," but I'm strongly considering
requiring that all double quotes be matched (except in literals
and inlines)

> Ah, well, that *does* make more sense - but I'd still prefer to call
> them "special" so you can, erm, unreserve them slightly in future
> versions if you wish. And also so they are clearly related in use to
> other special characters, like '*'.
> 
> > > '[' and ']' are "force a reference" characters in Zwiki, and will be
> > > used for similar purpose in STpy. But again, it depends on context.
> >
> > Hm.  I'm not sure I like the sound of that.  Care to elaborate?
> 
> It's much the same as the way PEPs work, with '[fred]' keying a
> reference to an item "labelled" 'fred' (in some way), but being a Wiki
> page, references off-page are meant to be *very* easy to generate, and
> the way one does that is by the CapitalLettersInWords convention.
> However, sometimes that needs circumventing (for instance, 'Tibs' won't
> trigger such an event, so I would need to type '[Tibs]'). It's OK,
> honest, it works well.

This means that we can no longer say '[a, b, c]' without quotes.
What types of things would you refer to in this way?  Why can't
we just use #fred#, when referring to docstrings of other objects?
This is yet another 2 characters that are given meaning, and taken
away from the documenter as possible text characters.. I want to
make sure that whatever we're getting is worth that.

-Edward