[Doc-SIG] which characters to use for docstring markup

[Greg Ward]

On 06 April 2001, Edward D. Loper said:
> I'm leaning towards using either::
> 
>     C{code}, E{emph} etc.
> 
> or::
> 
>     `literal` and *one* *word* *emph* (and that's it)
> 
> to color code in my markup.  Any comments?

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.

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.

        Greg
-- 
Greg Ward - programmer-at-big                           gward@python.net
http://starship.python.net/~gward/
I used to be a FUNDAMENTALIST, but then I heard about the HIGH
RADIATION LEVELS and bought an ENCYCLOPEDIA!!