[Doc-SIG] backslashing

[Edward D. Loper]

Backslashing has been coming up lately.  So let's go over it again. :)

I used to be strongly in favor of backslashing, using '\'.  After all,
it's *the* standard backslashing character, and clearly we need a
backslashing character, etc. etc...

Now I'm not so sure anymore.  The one big problem with backslashing, as
I see it, arises from the following principle, which has been guiding
a lot of docstring ML design:

      * Intuitiveness: The meaning of a well-formed formatted
        documentation string should be obvious to a reader, even if
        that reader is not familiar with the formatting conventions.

Now consider what happens if a newbie user prints out a formatted
docstring::

  >>> print somefunc.__doc__
  Somefunc will start an interactive session.  When you want
  to exit the session, simply type "\\exit"
  >>> 

Now, the user gets confused, and types "\\exit" instead of "\exit".

Anoter reasonable example might be::

  >>> print otherfunc.__doc__
  [...]
  C<re_str> should use "\\d" for digits and "\\s" for
  whitespace.  C<re_str> should not include "\\w".
  Example use:

      >>> otherfunc("\\s\\d")
      hi there!

  >>>

Note that this is entirely separate from issues of whether to use
r"..." strings for docstrings, etc..  The problem is that, when a
docstring is *printed*, it should be easy to interpret it.

Of course, this problem might very well go away if people stopped
printed docstrings, and started using tools (pydoc, etc), and those
tools decided to take care of these things for them..  But that's
probably a bit distant in the future right now.

So what's the alternative?  Don't allow markup characters in
paragraphs, and force docstring writers to put them in literal
blocks if they want to use them.  Instead of::
    def f(s):
        """
        Return the number of occurances of the string "{}"
        in s.

you would have to write::

    def f(s):
        """
        Return the number of occurances of the string::
           {}
        in s.

Is this better?  I'm not sure.  As someone else mentioned, it's
possible (like perldoc does?) to say {lb} and {rb} or <lt> and <gt>
or some such.  But that would probably be just as non-intuitive
as using backslashes..

Of course, if we decide that "intuitiveness" is not as important to
us, then maybe we can go ahead and use backslashing anyway...

-Edward