[Doc-SIG] Some random thoughts

[Laurence Tratt]

"Tony J Ibbs (Tibs)" wrote:

> As to the debate - I don't think there *is* much disagreement. We have three
> cases 
[snip]

Yes, I think I'd agree with that.

> Finally, we clearly need some way of escaping characters (otherwise I can't
> refer to the Python comment character in a doc string's main text, for
> instance!). We can't use \ (backslash) because that's already working as an
> escape character (unless we were to insist on raw strings, which is a
> no-no). I hereby propose, just for something to do, that it be ~,
> so we could have:
> 
>         """This is a test docstring
> 
>         I expect somewhere there's a variable called #fred#, to which
>         I expect to assign integers (e.g., #fred = 3#). However, I'll
>         be sure to comment it when I do, and comments start with ~#
>         (or should that be #~##?).
>         """
> 
> Do I *like* ~ as the character? No. But a proposal people can
> disagree with is better than no proposal (I hope).

~ is plain evil in my opinion as it has a lot of history associated with it.
But you expected that <wink>. I'm not sure what to use, to be honest. At the
moment - until someone comes up with something better - I'd actually be
tempted to suggest that raw strings aren't a bad option either because at
least everyone knows, recognises and understands \ .

I'm presuming that, at least initially, we're going to use a single
character to denote an escape sequence. Looking around my keyboard, one
possibility is the backtick ` but there again, Python already uses that; but
does that preclude it?

> am I being conciliatory or argumentative?

Actually my vote goes for "#" <wink>.


Laurie