[Doc-SIG] using the same delimiter on the left and right..

[Guido van Rossum]

> I agree, and I intend to pare it down to the bare essentials. For example,
> descriptive lists are problematic. In the past I *have* noticed your [and
> others'] use of ' -- ' for em-dashes. According to the Chicago Manual of
> Style, you're not supposed to use spaces on either side of em-dashes, but
> people do use this construct and we've gotta live with it.

I own the CMoS, but almost never read it.  I've learned my English and
writing style mostly by assimilation -- this is what I see people do,
so this is what I do.  So yes, we've got to live with it. :-)

> Trying to enforce rules on people for a supposedly 'transparent' markup
> system like ST is ass-backwards. The markup must abide by common usage, not
> the other way around. That's the strongest argument against using
> single-quotes for inline literals I know of. We can use `backticks` or
> `symmetric quotes' or <gasp!> *both*! (I see problems with symmetric, like:
> "string assignment: `s = 'this is a string''". Single-quotes are just too
> common in all contexts, IMHO.)

I would suggest that if you can't find a good existing idiom, and you
have to invent something, it's better to invent something that's
drastically different (like POD's C<...> and =foo) rather than
something that uses a character so small and easily mistaken as
backtick.  In many fonts, backtick is hard to distinguish from
apostrophe!

> > I also like that you define the escaping mechanism
> > upfront.  (Using \ to escape means that we're going to have to make
> > our docstrings raw strings.  Big deal. :-)
> 
> Anti-escape-mechanism people claim that it's not needed.

I think the ST experience shows what BS this is.

> They say
> backslashes are hard to use because of overloading (ya gotta double 'em up
> sometimes). But if they're not needed, why complain about how difficult it
> is to use them? And the only people who will actually use them (in order to
> document REs or ST itself) ought to know about raw strings anyhow.

'nuff said.  Backslash it is.  (MoinMoin shows the insanity of
doubling to quote.)

--Guido van Rossum (home page: http://www.python.org/~guido/)