[Doc-SIG] which characters to use for docstring markup
Guido van Rossum
guido@digicool.com
Fri, 06 Apr 2001 17:31:38 -0500
> I definitely prefer C{code} or E<emph> or E{emph} or whatever. (I'm not
> terribly concerned about the shape of the brackets used.)
>
> Guido's point about C<> being OK because the (opening) regex would be
> r'[A-Z]<' missed one nit: code samples like C<x > 5> are ambiguous; the
> ">" would have to be escaped. But then, with curly braces,
> C{d = {'a': 37}} is ambiguous.
Good point!
> So whatever delimiter you pick -- and I can live with <> or {} -- there
> must be a simple escaping mechanism. I definitely prefer backslash to
> POD's E<gt> hack: C<x \> 5> vs. C<x E<gt> 5>. The former is yucky, the
> latter is super-yucky. Backslash also means you can escape anything;
> with POD's E<> escaping mechanism, there has to be alternate spelling
> for any characters you want to escape, eg. "gt" for ">". Yuck.
I think I'd prefer to have to write \> for > than \} for }, so I
*still* prefer C<> over C{}.
--Guido van Rossum (home page: http://www.python.org/~guido/)