[Doc-SIG] quoting

[Edward D. Loper]

> I also feel we *probably* want some means of quoting.
> 
> *But* before introducing one, I want an exhaustive example of other
> cases than the need to quote a single quote within literal texts (and
> this would include, if people want it, a *really* careful argument for
> why one needs to be able to quote '#' in '#..#', although I feel this is
> probably needed too).

I think there are two issues here:
    1. #..# and '..' have *semantically* different meaning.  Although
       we *can* do #'# or '#', is it always appropriate?  
    2. Any string containing both "'" and '#' can't be written in
       current ST.  Those are the only strings that can't be written
       in current ST (as either literals or inlines).  (They can 
       actually be written, but only in a literal block).

I think that the first issue is an important one.  It bothers me
to have to say #'til# when I'm talking about an English word, because
the markup suggests that I'm talking about Python code.

> *After* we have an exhaustive list of all the places we *need* text
> escaping, *then* we can try to define an STpy-like manner of doing it.

I think that (2) is an exhaustive list of the places we *need* text
escaping, if you don't mind making people use apostrophes to quote
things like '*' and '"a":http://foo'.

> The difficulty of coming up with something "natural to read" (and I'm
> still not convinced that '\' fits the tag!) makes this an item I want to
> defer, probably until after release 1.0 of STpy and STminus.

I personally think that '\' is the most natural backslashing character,
especially if the audience is programmers.  But maybe I'm alone in 
thinking that...

> (Yes, I know it *feels* like something one must have, and not having it
> makes STpy and STminus difficult to self-document, but the ST-lesson is
> that, in general, difficult cases don't actually come up in real life.)

This is the ST-lesson from using ST to make web pages, not to 
document source code.. I fear we may find that documenting source
code requires a number of things you could avoid in writing web
pages..

-Edward