[Doc-SIG] backslashing

[Edward D. Loper]

> Any inline regexps will be complicated, no matter what escaping
> mechanism you choose. It's the nature of the beast!

If you used E<lt> and E<gt> or E{lb} and E{rb} or something like that,
then regexps would generally look how they're supposed to (at least
when you print them).

> Inline literals would be better::
> 
>     The regexp `r"\."` matches a literal period.

But then we have to say that inline literals can't ever contain "'"..
which in my mind is no better than saying that you can't backslash
'{' and '}'.

> I haven't spoken up about this, but: ugh! Somewhat dismayed to see
> the X<> type of construct being taken seriously. It works fine for
> POD: long live POD! Want to use it in docstrings? Implement a POD
> parser for HappyDoc or pydoc. In my estimation, readability is the
> most important criterion; X<> fails miserably.

I asked about this before, and didn't get any negative feedback.
Basically, I'd be happy to not use X<...> markup (or X{..} markup) if
we restrict ourselves to only using:
  - either 'literal' or `literal`
  - maybe *single* *word* *emph*
  - no nesting

Guido has objected to `literal` (which doesn't mean we can't do it, of
course).  I think that if the reason we're rejecting X{} or X<> is
because it's "not readable," then there's no reason to accept #code#,
which to me is signifigantly less intuitive than C{code}.

> Recently, I've come to the conclusion that requiring a blank line
> before the start of a list is reasonable and correct, even if we
> don't require blank lines between items. Minimizing ambiguity trumps
> minimizing vertical space.

That would make things easier.  But we would also have to require that
sublists are surrounded by blank lines.  So instead of::

   text

     - item1
       - subitem 1.1
       - subitem 1.2
     - item2
     - item3

   text

We would have::

   text

     - item1

       - subitem 1.1
       - subitem 1.2

     - item2
     - item3

   text

Any objections to that?  The way my markup language currently works,
we don't have to worry about how to detect when a new list item
starts, because list item contents are required to be indented::

  - this is a valid list
    item.

  - This is not a valid
  list item.

-Edward