[docs] proposed improvement to 'else' explanation for try/except/else

[R. Sage]

I suggest changing the following paragraph as annotated (from
http://docs.python.org/2/tutorial/errors.html):

> The use of the else clause is better than adding additional code to the
> try clause because *the else clause is excluded from the try's
> protection.  This* [was "it"] avoids accidentally catching an exception
> that wasn’t raised by the code *that is intended to be* [was "being"]
> protected by the try ... except statement."  I suggest augmenting this
> either with more text or with an example.
>

I initially could not decipher this.

I love the docs!  Cheers,
Randy Sage

PS Original (verbose) email follows in case it is useful - but no need to
read it.  I decided  that anybody who succeeds at such concise
documentation deserves a better effort on my part.

===================================

First, I love the docs!  They are the main reason I'm increasingly moving
my work into Python, currently abandoning ruby/rails, but also migrating
away from MATLAB and bash scripts.

After I read the tutorial on exceptions (
http://docs.python.org/2/tutorial/errors.html), I went looking for a better
explanation of:

> The use of the else clause is better than adding additional code to the
> try clause because it avoids accidentally catching an exception that wasn’t
> raised by the code being protected by the try ... except statement."  I
> suggest augmenting this either with more text or with an example.
>

The supplementary description at
http://stackoverflow.com/a/855764/527489was perfect for me, but is
more verbose than typical python docs, which I
usuallyl find to be about as concise as possible - but no more so.

In this case, I think the issue is that the docs are too concise for those
new to the concept, albeit I now see that they are perfect if you know (at
least approximately) what that the try/except's else is for.  I'm not great
at being concise myself (sorry about the long email), but perhaps something
like this:

The use of the else clause is better than adding additional code to the try
> clause because *the else clause is excluded from the try's protection.
> This* [was "it"] avoids accidentally catching an exception that wasn’t
> raised by the code *that is intended to be* [was "being"] protected by
> the try ... except statement."  I suggest augmenting this either with more
> text or with an example.


Thanks,
Randy Sage
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20131227/0bfe5cd3/attachment-0001.html>