Python docs [was: function with a state]

[Sean Blakey]

On 8 Mar 2005 17:07:31 -0800, Xah Lee <xah at xahlee.org> wrote:
> thanks for the help...
> 
> -------
> the python doc is stilted. It tried to organized the thing and with a
> style around some highbrow inane "computer science" outlook.
> 
> i found the little section on global
> (http://python.org/doc/2.4/ref/global.html)
>  and can't make out what shit it is trying to say without having read
> and figured out the entire doc of its style and contexts and
> definitions. (formalization varies and computing model and jargons mean
> different things.)
> 
> Python doc writers needs to re-organize and re-style their docs so that
> its organization is towards programing, as opposed to how the
> implementation works (as in the Lib Reference), or a formalization of
> the language spec. (e.g. the fucking semi-joke of "(for language
> lawyers)" and BNF and those Runtime "Service" shits.) Its style
> needs to shift from highbrowism to pragmatic and exemplary.
> 
> I've addressed some of the jargon-riding ills common in industry with
> examples from the Python doc, archived here:
> http://xahlee.org/Periodic_dosage_dir/t2/xlali_skami_cukta.html
> 
> as to the way of its stiltedenss and academicism, which make it hard
> for programers to find or apply any info, i'll expound later.
> 
> PS just so that there is no misunderstanding: The docs of unix and
> Perl, are fucking criminally incompetent. Python docs, although stilted
> in a academic way, but nevertheless is solid, and its writers are
> educated, and tried best to make it a quality one, albeit sometimes
> inevitably showed some masterbation and jargonization. While the unix
> and Perl docs, (and essentially all things out of unix, e.g. Apache
> docs), are fucking incompetent drivels and in many cases exorbitant
> lies, and they semi-present it as humor and want and brainwash people
> to take them as norm. In a nutshell, these people are spreading
> untruths and indirectly are causing massive harm in the computing
> industry. People, we need to stop it. This each of us can do by not
> accepting their attitudes or behavior. In online forums, work place,
> conventions, conversations etc., raise questions or otherwise voice
> your opinion whenever you can.
> 
>  Xah
>  xah at xahlee.org
>  http://xahlee.org/PageTwo_dir/more.html
> 
> --
> http://mail.python.org/mailman/listinfo/python-list
> 

Have you submitted a patch? I'm curious how you would document "global".

-- 
Sean Blakey
Saint of Mild Amusement, Evil Genius, Big Geek
Python/Java/C++/C(Unix/Windows/Palm/Web) developer
quine = ['print "quine =",quine,"; exec(quine[0])"'] ; exec(quine[0])