Python docs [was: function with a state]

[axel at white-eagle.invalid.uk]

In comp.lang.perl.misc Xah Lee <xah at xahlee.org> wrote:
> The Python doc is relatively lousy, from content organization to the
> tech writing quality.

Which has precisely what to do with most of the groups to which you
cross-posted?

> Problem: They all have the same priority (which is higher than that of
> the Boolean operations).
 
> However, the ?they? pronoun from the context of previous sentence,
> refers to ?the comparison operation?, not ?operator?. So, it
> conjures the reader to think about some ?operation precedence?,
> which in itself cannot be ruled out as nonsense depending on the
> context. Very fucking stupid confusional writing.

The meaning is perfectly plain. By the way did you perhaps mean
'confusing' or 'confused'? I normally regard language flames
otiose but here, since you are trying to correct other people's
writing, fair game.

> And, from pure writing aspect, the sentence ?...(which is ...)?  is
> some kind of a juvenile latch on. If the author intent to make that

Do you mean... 'if the author's intent is to make' or 'if the author
intends to'?

> point, say it in its own sentence. e.g. The comparison operators have
> higher precedence than boolean operators. It would be better to not
> mention this at all. For practical considerations, very rare is the
> case of mixing boolean and comparison operators, and if so, parenthesis
> are likely used and is indeed a good practice. The proper place for

Should that not be 'parentheses are likely to be used'?

It is not rare at all. Besides, little asides like this are an ideal
way to reinforce thoughts about operator preference and more helpful
then memorising a table.

> Problem: Comparisons can be chained arbitrarily; for example, x < y <=
> z is equivalent to x < y and y <= z, except that y is evaluated only
> once (but in both cases z is not evaluated at all when x < y is found
> to be false).
 
> Drop the word ?arbitrarily?. It has no meaning here.

I suggest you look up the meaning of the word.
 
> the whole sentence is one fucked up verbiage of pell-mell thinking and
> writing. Here's one example of better:
 
> Comparisons can be chained, and is evaluated from left to right. For
> example, x < y <= z is equivalent to (x < y) <= z.

You mean 'are evaluated'. Your rephrasing is also incomplete since
it doesn't note that z will not be evaulated if x < y is false.

> With respect to documentation style, it is questionable that this
> aspect needs to be mentioned at all. In practice, if programers need to
> chain comparisons, they will readily do so. This is not out of ordinary
> in imperative languages, and evaluation from left to right is also not
> extraordinary to cost a mention.

Really? In a reference manual such matters should be fully specified
regardless of what happens in other languages.
 
> Problem: <> and != are alternate spellings for the same operator. != is
> the preferred spelling; <> is obsolescent
 
> In general, when something is obsolete or might go defunct in the
> future, consider not even mentioning that construct. If necessary, add
> it in a obscure place, and not adjacent to critical info. In many
> places of Python documentation, this is breached.

Really? Actually it is very important to mention it in the correct
place in a reference manual. Do you understand the concept of
maintaining old code?
 
> I'm in fact somewhat surprised by this poor quality in writing. The

Really? The writing in the manual seems simple, straight-forward and
clear to me (knowing no Python). Unlike your writing.

> more egregious error is the hardware-oriented organization aka
> technical drivel.

What on earth does this mean?

> The Python doc, though relatively incompetent, but the author have
> tried the best. This is in contrast to documentations in unix related
> things (unix tools, perl, apache, and so on etc), where the writers
> have absolutely no sense of clear writing, and in most cases don't give
> a damn and delight in drivel thinking of it as literary.

I think that this is an excellent description of your own writing.

Axel