[Doc-SIG] backslashing

[Edward D. Loper]

> - As in many systems with escaping, we can define the escape
> character to have the "escaping" meaning only for specific
> characters (the markup characters themselves). (Example: in Python,
> len('\t') == 1, len('\T') == 2.) So '\*' would escape the asterisk
> (evaluates to '*', but not processed as markup), but '\e' would be a
> backslash and an 'e', two characters. No '\\e' required.

I can see this getting rediculously complicated if we're talking
about any regexps inline..  And regexps are hard enough to read 
anyway.. :)  

  >>> print my_confusing_docstring
  ...
  ...defaults to the regexp "\s\*", which will match zero or
  more spaces...

:)  Of course, I'm currently planning to use E{emph} instead of
*emph*, but you ge the idea.. :)

Hm..  So in my current markup language, there are two coloring
characters ('{' and '}' or '<' and '>') and the following
structuring characters:
  - '-': a bullet, when it occurs at the start of a line
  - '([0-9]+.)+': a bullet, when at the start of a line
  - '::': introduces a literal lock, when at the end of a para
  - '=': used for underlining headings
  - '-': used for underlining headings
  - '~': used for underlining headings

If we're doing escaping, then clearly we need to be able to escape '{'
and '}'.  We might be able to get away with not escaping any of the
structuring characters by saying that when they appear within a
colored region, they don't count.  So, for example, in::

  Find the value of C{x
  - y}.

The second line wouldn't be a list item because it's in a colored
region..  We might also need a new "null" coloring that could be used
in examples like::

  This is a sentence that ends in the number
  N{1.}  

Is this better or worse than::

  This is a sentence that ends in the number
  \1.

Of course, if we require bullets to be in a special colored region,
then we don't have to worry abou them..  And we don't have to 
worry about '::', since it's only interpreted when it comes at the
end of a paragraph (not at the end of a line)...  And presumably 
people will never write::

  x = y

as::

  x
  =
  y

(which would be read as a heading "x" followed by a paragraph
containing "y").  In that case, we could say that the only characters
that you can backslash are '\{' and '\}'.  So then I might feel better
about saying that '\' is interpreted as a literal backslash except
before '\', '{', or '}'.. Although I would still be worried that
people would get confused with regexps::

  >>> print another_confusing_docstring
  ...
  The regexp r"\\." matches a literal period.

-Edward