[Doc-SIG] backslashing

[Goodger, David]

Edward D. Loper wrote:
> 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".

I assume you meant that the user should type "\exit", and you doubled-up the
backslashes in order to avoid escaping the "e" in "exit". Correct?

In a nutshell:

- No matter what characters are chosen for markup, some day someone will
want to write documentation *about* that markup (hopefully sooner than later
:). Therefore, any complete markup language must have an escaping or
encoding mechanism.

- If we want a lightweight markup system, encoding mechanisms like
SGML/XML's '*' are out. So an escaping mechanism is in. The backslash is
the only viable candidate IMO.

- However, with carefully chosen markup, it should be necessary to use the
escaping mechanism only infrequently.

- 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.

- In extreme cases, or when we want to be absolutely clear, we can use a
literal block instead::

      When you want to exit the session, simply type::

          \exit

> 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.

Have fun enforcing that! :>

I would change that to: allow markup characters in paragraphs via the
escaping mechanism, but encourage authors to put them in literal blocks
instead.

/DG