[Doc-SIG] backslashing

[Goodger, David]

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

So would *any other* convention -- when you print them. The point is, what
do they look like when you read them?

Another point: mark up "x > y" as an inline literal. If you use C<>, you
need to escape. If you use C{}, you need to escape for some other case.

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

[Edward]
> 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 '}'.

No mention of "'" (single quote). I used "`" (backquote). Your email font
can't distinguish the two.

> Guido has objected to `literal`

On 30 March, Guido wrote:
> In many fonts, backtick is hard to distinguish from apostrophe!

Two aspects: reading and writing. If you're reading the raw marked-up
docstring/email/whatever, it doesn't *matter* if it shows up as a backquote
or a single quote. As long as it appears quoted in some manner, the quoting
has served its purpose. If you're reading the processed docstring, the
`inline literal` (note: backquotes used) will be formatted in some way which
makes the context obvious. If you're reading the raw text and debating about
it, you'd better be using a font which distinguishes clearly between all
ASCII characters (there are common fonts in which "(" and "{" are hardly
distinguishable either).

If you're *writing* the markup (or writing *about* it! :) you'd better be
using a suitable font. 

After all, one day you might receive email saying::

    What's wrong with this code?

    >>> hello = 'Dolly'
    >>> print `hello`, 'hello'
    Dolly hello

    It should print "hello Dolly"!

[Guido]
> This seems to come from a confusion between two similar, but
> different goals:
> 
> - It should be easy to read without any knowledge of the markup
>   language
> 
> - It should be possible to author without knowing the whole markup
>   language and without changing your habits
> 
> I can agree with the first one, but I think the second will continue
> to get us into trouble.

Agreed. So change your habits, change your mindset, everyone! Or at least,
change your email font! ;-) Documentation is data, and markup is the
equivalent of code.  

[Edward]
> 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}.

Yes.

/DG