Doc suggestions (was: Why "class exceptions" are not deprecated?)

[Terry Reedy]

<rurpy at yahoo.com> wrote in message 
news:1143574346.354680.136060 at i39g2000cwa.googlegroups.com...
> Fredrik Lundh wrote:
>> rurpy at yahoo.com wrote:
>> where did anyone tell the OP that he can't read?
>
>  "it could be that the tutorial author expected you
>  to read chapter 8 before you read chapter 9,..."

This actually acknowledges an ability to read ;-)
-- that just was not exercised sufficiently (in his opinion) ...

> as good as what is already there.  But what I can do is
> report problems I find when using it, and make suggestions
> about how to avoid those problems.  For example, the
> sentence in question,
>
>  "There are two new valid (semantic) forms for the
>  raise statement: "
>
> could be replaced with
>
>  "There are two other forms for the raise statement
>  in addition to the one described in chapter 8:"

That said, and without looking at the context in the doc, this looks like 
an improvement.

> or
>
>  "Two new forms for the raise statement were introduced
>  in Python verion 2.x:"

This is incorrect, I believe.

> depending on what the meaning of "new" is in the
> original sentence.  (I'm still not sure, but your post
> implies it is the former.)

I agree that the current text seems ambiguous.

> But the perception I get here, from responses like yours,
> is that such suggestions are unwelcome, and unlikely
> to be acted upon.

FL is not the main doc maintainer.  Even if you were to be correct about 
his views, premature generalization is the source of much error.

>  I gather corrections of factual
> errors are welcome, but stylistic, or organizational
> ones are not.  And the latter kind of changes, applied
> extensively to all the docs, are what will make a big
> improvement.  Difficult at best, but absolutely impossible
> if you and the other powers-that-be are happy with
> the status-quo.

If you wish to become a volunteer Python improver, let me know either here 
or privately and I will respond with a suggestion and an offer.

Terry Jan Reedy