question about the id()

[kyo guan]

HI ALL:

Can someone explain why the id() return the same value, and why these 
values are changing? Thanks you.

Python 2.4.1 (#65, Mar 30 2005, 09:13:57) [MSC v.1310 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> class A(object):
... def f():
... pass
... def g():
... pass
...
>>>
>>> a=A()
>>> id(a.f)
11365872
>>> id(a.g)
11365872
>>>
>>>
>>> class B(object):
... def f():
... print 1
... def g():
... print 3
...
>>> b=B()
>>> id(b.f)
11365872
>>> id(b.g)
11365872
>>> id(a.f), id(a.g), id(b.f), id(b.g)
(11365872, 11365872, 11365872, 11365872)
>>> a.f is a.g
False
>>> id(a.f), id(a.g), id(b.f), id(b.g)
(11492408, 11492408, 11492408, 11492408)
>>> a.f is a.g
False
>>> id(a.f), id(a.g), id(b.f), id(b.g)
(11365872, 11365872, 11365872, 11365872)
>>>

-- 
http://mail.python.org/mailman/listinfo/python-list

About the Python Expert

[[EMAIL PROTECTED]]

Hey, i didnt say i need an expert. wel i did... anyways, i m just 
saying that Fan is not a good python programmer, he doesnt know enough 
python to help those who have joined his group, i know its askin a 
lot, and i m not askin for a private tutor, just someone(s), to pop 
into the group, see the discussions and help the people. but it is ur 
decision.
-- 
 * Posted with NewsLeecher v3.0 Beta 7
 * http://www.newsleecher.com/?usenet
-- 
http://mail.python.org/mailman/listinfo/python-list

Bitching about the documentation...

[skip]

>> Note that the updated version of this is at: http://wiki.python.org/
>> moin/HowTo/Sorting

rurpy> http://wiki.python.org/...
rurpy> Hmmm, lets see, how about Libraries?
rurpy> Nope, don't see anything that looks like it might be about sort
rurpy> there...
rurpy> How about Documentation?
rurpy> Nope
rurpy> Code?
rurpy> Hmm, "sort lists of dicts" doesn't sound like it...
rurpy> I see there a search box, let's try that for "sort"
rurpy> WTF?, these all look like old maillist archives...
rurpy> Maybe I should Goole python.org  What was the google syntax to
rurpy> limit the search to one site?  I forgot.
rurpy> Aww screw it.  

rurpy> Wikis suck.  Update the damn docs.

Gee, I wonder if I typed "sort" into the search box on the wiki it might
turn up something useful?  Well, what do you know?

2 results of about 4571 pages. (0.19 seconds)

1. HowTo/Sorting
2. SortingListsOfDictionaries

Is it as good as Google ("site:wiki.python.org sort")?  Unlikely, but it
works fairly well.  Granted, wikis are a different way of organizing content
than static documentation with their nicely organized chapters, sections and
indexes, but most of us around here are software engineer types, not tech
writers, and since we're not paid to do any of this, we get to do anything
we want.  Most of us choose not to write documentation in our spare time.
Go figure.  If documentation's your thing, be my guest.  Write new
documentation, submit patches for existing documentation, rewrite it in
Word.  I don't care. Do whatever floats your boat.  Just don't show up and
bitch about the documentation if you're not willing to help.

Oh, did I mention that there's an Edit link at the top of almost every page
on the wiki and that creating new pages is pretty simple?  (Try searching
the wiki for "WikiCourse".)  Contributing new content to the existing more
static documentation isn't all that hard either.

If you prefer the latest documentation, bookmark this page:

http://www.python.org/dev/doc/devel/index.html

That's updated every few months, more frequently as new releases approach.

Skip
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: question about the id()

[Skip Montanaro]

kyo> Can someone explain why the id() return the same value, and why
kyo> these values are changing?

Instance methods are created on-the-fly.  In your example the memory
associated with the a.f bound method (not the same as the unbound method
A.f) is freed before you reference a.g.  That chunk of memory just happens
to get reused for the bound method associated with a.g.  Here's a
demonstration:

% python
Python 2.5a0 (#77, May 14 2005, 14:47:06) 
[GCC 3.3 20030304 (Apple Computer, Inc. build 1671)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> class A(object):
...   def f(): pass
...   def g(): pass
... 
>>> a = A()
>>> x = a.f
>>> y = a.g
>>> id(x)
17969240
>>> id(y)
17969440
>>> id(a.f)
17969400
>>> id(a.g)
17969400

Skip
-- 
http://mail.python.org/mailman/listinfo/python-list

RE: question about the id()

[kyo guan]

HI Skip:

I want to check is there any change in the instance 's methods.
>>> a=A()
>>> a2=A()
>>> a.f == a2.f
False
>>> a.f is a2.f
False
>>> a.f is a.f
False
>>>
If the instance methods are create on-the-fly, how to do that? Thanks.

Kyo
 

> -Original Message-
> From: Skip Montanaro [mailto:[EMAIL PROTECTED] 
> Sent: Monday, May 16, 2005 11:09 AM
> To: kyo guan
> Cc: python-list@python.org
> Subject: Re: question about the id()
> 
> 
> kyo> Can someone explain why the id() return the same 
> value, and why
> kyo> these values are changing?
> 
> Instance methods are created on-the-fly.  In your example the 
> memory associated with the a.f bound method (not the same as 
> the unbound method
> A.f) is freed before you reference a.g.  That chunk of memory 
> just happens to get reused for the bound method associated 
> with a.g.  Here's a
> demonstration:
> 
> % python
> Python 2.5a0 (#77, May 14 2005, 14:47:06) 
> [GCC 3.3 20030304 (Apple Computer, Inc. build 1671)] on darwin
> Type "help", "copyright", "credits" or "license" for more 
> information.
> >>> class A(object):
> ...   def f(): pass
> ...   def g(): pass
> ... 
> >>> a = A()
> >>> x = a.f
> >>> y = a.g
> >>> id(x)
> 17969240
> >>> id(y)
> 17969440
> >>> id(a.f)
> 17969400
> >>> id(a.g)
> 17969400
> 
> Skip

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: question about the id()

[Bengt Richter]

On Mon, 16 May 2005 11:28:31 +0800, "kyo guan" <[EMAIL PROTECTED]> wrote:

>HI Skip:
>
>   I want to check is there any change in the instance 's methods.
 a=A()
 a2=A()
 a.f == a2.f
>False
 a.f is a2.f
>False
 a.f is a.f
>False

>   If the instance methods are create on-the-fly, how to do that? Thanks.
You have to define exactly what you mean by "the instance's methods" first ;-)
a.f is an expression that when evaluated creates a bound method according to
the rules of doing that. You can check what function was found for creating
this bound method using the .im_func attribute -- i.e. a.f.im_func -- but that
is only valid for that particular bound method. A bound method is a first class
object that you can pass around or assign, so the function you might get from
a fresh a.f might differ from a previous a.f, e.g.,

 >>> class A(object):
 ... def f(self): return 'f1'
 ...
 >>> a=A()
 >>> a2=A()
 >>> a.f.im_func is a2.f.im_func
 True
Now save the bound method a.f
 >>> af = a.f

And change the class A method
 >>> A.f = lambda self: 'f2'

Both a and a2 dynamically create bound methods based on the new method (lambda 
above)
so the functions are actually the same identical one
 >>> a.f.im_func is a2.f.im_func
 True

But the bound method we saved by binding it to af still is bound to the old 
method function,
so a new dynamically created one is not the same:
 >>> af.im_func is a2.f.im_func
 False
 >>> af.im_func
 
 >>> a.f.im_func
  at 0x02F99B1C>
 >>> a2.f.im_func
  at 0x02F99B1C>

The .im_func function id's are shown in hex through the repr above. I.e., 
compare with:

 >>> '0x%08X' % id(a2.f.im_func)
 '0x02F99B1C'
 >>> '0x%08X' % id(af.im_func)
 '0x02FA3CDC'

HTH

Regards,
Bengt Richter
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: question about the id()

[Andrew Dalke]

kyo guan wrote:
>   Can someone explain why the id() return the same value, and why
> these values are changing? Thanks you.

 a=A()
 id(a.f)
> 11365872
 id(a.g)
> 11365872


The Python functions f and g, inside of a class A, are
unbound methods.  When accessed through an instance what's
returned is a bound method.

>>> A.f

>>> A().f
>
>>> 

In your code you do a.f, which creates a new bound method.
After the id() call its ref-count goes to zero and its
memory is freed.  Next you do a.g which creates a new
bound method.  In this case it reuses the same memory location,
which is why you get the same id.

I know Python keeps free lists for some data types.  I
suspect bound method objects are tracked this way because
they are made/destroyed so frequently.  That would increase
the likelihood of you seeing the same id value.


 a.f is a.g
> False

This is the first time you have two bound methods at
the same time.  Previously a bound method was garbage
collected before the next one was created.

 id(a.f), id(a.g), id(b.f), id(b.g)
> (11492408, 11492408, 11492408, 11492408)
 a.f is a.g
> False
 id(a.f), id(a.g), id(b.f), id(b.g)
> (11365872, 11365872, 11365872, 11365872)


The memory locations changed.  Here's a conjecture that
fits the facts and is useful to help understand.

Suppose the free list is maintained as a stack, with
the most recently freed object at the top of the stack,
which is the first to be used for the next object.

The "a.f is a.g" creates two bound methods, one at
11492408 and the other at 11365872.  Once the 'is'
is done it dec-refs the two methods, a.f first and
a.g second.  In this case the ref counts go to zero
and the memory moved to the free list.  At this point
the stack looks like

[11365872, 11492408,  ... rest of stack ... ]

You then do a.f.  This pulls from the top of the
stack so you get 11365872 again.  The id() tells
you that, and then the object gets decrefed and
put back on the stack.


Andrew
[EMAIL PROTECTED]

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: question about the id()

[Peter Dembinski]

Skip Montanaro <[EMAIL PROTECTED]> writes:

> kyo> Can someone explain why the id() return the same value, and
> kyo> why these values are changing?
>
> Instance methods are created on-the-fly.  

So, the interpreter creates new 'point in address space' every time
there is object-dot-method invocation in program?  

-- 
http://www.peter.dembinski.prv.pl
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: question about the id()

[Andrew Dalke]

Peter Dembinski wrote:
> So, the interpreter creates new 'point in address space' every time
> there is object-dot-method invocation in program?

Yes.  That's why some code hand-optimizes inner loops by hoisting
the bound objection creation, as

data = []
data_append = data.append
for x in some_other_data:
   work with x to make y 
  data_append(y)


Andrew
[EMAIL PROTECTED]

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: question about the id()

[Bengt Richter]

On Mon, 16 May 2005 18:30:47 +0200, Peter Dembinski <[EMAIL PROTECTED]> wrote:

>Skip Montanaro <[EMAIL PROTECTED]> writes:
>
>> kyo> Can someone explain why the id() return the same value, and
>> kyo> why these values are changing?
>>
>> Instance methods are created on-the-fly.  
>
>So, the interpreter creates new 'point in address space' every time
>there is object-dot-method invocation in program?

Yes, but you can save the result of the obj.method expression (that's what it 
is,
an expression). E.g.,

 bound_method = obj.method

after that, you can write

 bound_method()

or
 obj.method()

(of course, you can pass arguments too, depending on the signature,
remembering that the "self" instance parameter is already bound in
and does not need to be passed again to a bound method)

The obj.method() call will re-evaluate the obj.method expression,
and the bound_method() call will just call the previously created
bound method.

BTW, a typical performance optimization (not done automatically by python)
is to hoist unchanging-value expressions out of loops, and obj.method is
often such an expression, so you will this strategy when people try
to squeeze extra performance from their programs.

Regards,
Bengt Richter
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: question about the id()

[Bengt Richter]

On Mon, 16 May 2005 16:57:12 GMT, Andrew Dalke <[EMAIL PROTECTED]> wrote:

>Peter Dembinski wrote:
>> So, the interpreter creates new 'point in address space' every time
>> there is object-dot-method invocation in program?
>
>Yes.  That's why some code hand-optimizes inner loops by hoisting
>the bound objection creation, as
>
>data = []
>data_append = data.append
>for x in some_other_data:
>  .... work with x to make y 
>  data_append(y)
>
Sorry about the me-too. I hadn't seen your post. I should know better ;-)

Regards,
Bengt Richter
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: question about the id()

[Peter Dembinski]

[EMAIL PROTECTED] (Bengt Richter) writes:

[snap]

>>So, the interpreter creates new 'point in address space' every time
>>there is object-dot-method invocation in program?

[optimization]

> BTW, a typical performance optimization (not done automatically by python)
> is to hoist unchanging-value expressions out of loops, and obj.method is
> often such an expression, so you will this strategy when people try
> to squeeze extra performance from their programs.

Good to know.  Is there any advanced optimizer for Python code, which
would do such things for me (or suggest them, like pychecker does 
for readability)?

-- 
http://www.peter.dembinski.prv.pl
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: question about the id()

[Giovanni Bajo]

Peter Dembinski wrote:

>> BTW, a typical performance optimization (not done automatically by
>> python) is to hoist unchanging-value expressions out of loops, and
>> obj.method is often such an expression, so you will this strategy
>> when people try
>> to squeeze extra performance from their programs.
>
> Good to know.  Is there any advanced optimizer for Python code, which
> would do such things for me (or suggest them, like pychecker does
> for readability)?


Prove that a.f() would not change the meaning of "a.f" after its invokation is
close to impossible.
-- 
Giovanni Bajo


-- 
http://mail.python.org/mailman/listinfo/python-list

Re: question about the id()

[Peter Dembinski]

"Giovanni Bajo" <[EMAIL PROTECTED]> writes:

> Peter Dembinski wrote:
>
>>> BTW, a typical performance optimization (not done automatically by
>>> python) is to hoist unchanging-value expressions out of loops, and
>>> obj.method is often such an expression, so you will this strategy
>>> when people try
>>> to squeeze extra performance from their programs.
>>
>> Good to know.  Is there any advanced optimizer for Python code,
>> which would do such things for me (or suggest them, like pychecker
>> does for readability)?
>
>
> Prove that a.f() would not change the meaning of "a.f" after its
> invokation is close to impossible.

Many things in Python programs cannot be proved.  But what about
suggesting optimisations, not doing them automatically?  

The similar case may be found in refactorization -- most things cannot
be proved, so the final decision is left to the programmer (and his
unit tests).

-- 
http://www.peter.dembinski.prv.pl
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: question about the id()

[Dan Sommers]

On Tue, 17 May 2005 13:56:18 +0200,
Peter Dembinski <[EMAIL PROTECTED]> wrote:

> "Giovanni Bajo" <[EMAIL PROTECTED]> writes:
>> Peter Dembinski wrote:
>> 
 BTW, a typical performance optimization (not done automatically by
 python) is to hoist unchanging-value expressions out of loops, and
 obj.method is often such an expression, so you will this strategy
 when people try
 to squeeze extra performance from their programs.
>>> 
>>> Good to know.  Is there any advanced optimizer for Python code,
>>> which would do such things for me (or suggest them, like pychecker
>>> does for readability)?
>> 
>> 
>> Prove that a.f() would not change the meaning of "a.f" after its
>> invokation is close to impossible.

> Many things in Python programs cannot be proved.  But what about
> suggesting optimisations, not doing them automatically?  

At that point, you can do the optimization yourself:

class A:
def method( self ):
pass

a = A( )
m = a.method # optimize runtime lookups for a.method
for x in range( 10 ):
m( )

Regards,
Dan

-- 
Dan Sommers

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: About the Python Expert

[bruno at modulix]

[EMAIL PROTECTED] wrote:
> Hey, i didnt say i need an expert. wel i did... anyways, i m just 
> saying that Fan is not a good python programmer, he doesnt know enough 
> python to help those who have joined his group, i know its askin a 
> lot, and i m not askin for a private tutor, just someone(s), to pop 
> into the group, see the discussions and help the people. but it is ur 
> decision.

Why would someone "pop into the group" when there are already this
newsgroup and the tutor ml ?

And if you are not happy with whatever group you joined, just quit.

-- 
bruno desthuilliers
python -c "print '@'.join(['.'.join([w[::-1] for w in p.split('.')]) for
p in '[EMAIL PROTECTED]'.split('@')])"
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: About the Python Expert

[Grant Edwards]

On 2005-11-02, blahman ([EMAIL PROTECTED]) <> wrote:

> Hey, i didnt say i need an expert. wel i did... anyways, i m just 
> saying that Fan is not a good python programmer, he doesnt know enough 
> python to help those who have joined his group,

They should have "joined a group" that _does_ contain people
who know enough to help.  Comp.lang.python, for example.  Or
the tutor mailing list.

> i know its askin a lot,

Yes it is.  As apparently is spelling and punctuation.

> and i m not askin for a private tutor, just someone(s), to pop
> into the group, see the discussions and help the people. but
> it is ur decision.

There's _already_ a tutor mailing list and a general Python
newsgroup -- both full of knowledgeable and helpful people.

[Since I took a shot at this guy's spelling, there's _got_ to
be a spelling error in my post, but I can't find it...]

-- 
Grant Edwards   grante Yow!  I want a VEGETARIAN
  at   BURRITO to go... with
   visi.comEXTRA MSG!!
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: About the Python Expert

[Steve Holden]

[EMAIL PROTECTED] wrote:
> Hey, i didnt say i need an expert. wel i did... anyways, i m just 
> saying that Fan is not a good python programmer, he doesnt know enough 
> python to help those who have joined his group, i know its askin a 
> lot, and i m not askin for a private tutor, just someone(s), to pop 
> into the group, see the discussions and help the people. but it is ur 
> decision.

If the guy who started the group isn't an appropriate mentor then a more 
advanced programmer would probably find it irritating to have to correct 
his mistakes.

I'd still recommend that you direct the members to the tutor list rather 
than trying to shore up an ineffective initiative.

Good luck either way.

regards
  Steve
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006  www.python.org/pycon/

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[rurpy]

[EMAIL PROTECTED] wrote:

> Gee, I wonder if I typed "sort" into the search box on the wiki it might
> turn up something useful?  Well, what do you know?
>
> 2 results of about 4571 pages. (0.19 seconds)
>
> 1. HowTo/Sorting
> 2. SortingListsOfDictionaries

Are we talking about the same Search box (at the top right of the
wiki page, and labeled "search"?  Well, yes  I did enter "sort" and
got (as I said) a long list of archived maillist postings.

> Is it as good as Google ("site:wiki.python.org sort")?  Unlikely, but it
> works fairly well.  Granted, wikis are a different way of organizing content
> than static documentation with their nicely organized chapters, sections and
> indexes, but most of us around here are software engineer types, not tech
> writers, and since we're not paid to do any of this, we get to do anything
> we want.  Most of us choose not to write documentation in our spare time.
> Go figure.  If documentation's your thing, be my guest.  Write new
> documentation, submit patches for existing documentation, rewrite it in
> Word.  I don't care. Do whatever floats your boat.  Just don't show up and
> bitch about the documentation if you're not willing to help.

Well, I'm not totally sure but I think I would be willing to a least
try
contributing something.  A large amount of the time I waste when
writing Python programs is directly attributable to poor documentation.
(To be fair Python is not the only software with this problem.)

But, the standard responce of "don't complain, fix it yourself" is
bogus
too.  There are plenty of people on this list willing to sing python's
praises,
for balance, there should be people willing to openly point out
python's
flaws.  Documentation is certainly one of them.  And I was correcting a
posting that explicitly said there was exceptionaly good information in
that Howto.  That was just plain wrong.

> Oh, did I mention that there's an Edit link at the top of almost every page
> on the wiki and that creating new pages is pretty simple?  (Try searching
> the wiki for "WikiCourse".)  Contributing new content to the existing more
> static documentation isn't all that hard either.

As I said, I think wiki's suck.  On almost every one I find the
information
disorganised, very spotty in coverage, extremely variable is qualilty
of writing, and often seeming like a conversation walked into in the
middle of.  I still haven't figured out how to get to the Python wiki's
howto's by navigating from the front page.  IMO wikis are best used
to collect information for later editing and inclusion into more formal
documentation.  (That's a little stronger than my actual opinion but
it's too late right now more me to express it any better.)

> If you prefer the latest documentation, bookmark this page:
>
> http://www.python.org/dev/doc/devel/index.html

Thanks I will keep that in mind.  But the obvious risk is that it
will refer to language features and changes not in the current
version.

> That's updated every few months, more frequently as new releases approach.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Peter Hansen]

[EMAIL PROTECTED] wrote:
> [EMAIL PROTECTED] wrote:
>>Gee, I wonder if I typed "sort" into the search box on the wiki it might
>>turn up something useful?  Well, what do you know?
>>
>>2 results of about 4571 pages. (0.19 seconds)
>>
>>1. HowTo/Sorting
>>2. SortingListsOfDictionaries
> 
> Are we talking about the same Search box (at the top right of the
> wiki page, and labeled "search"?  Well, yes  I did enter "sort" and
> got (as I said) a long list of archived maillist postings.

No, he's talking about the *wiki* search box, not the one in the extreme 
upper right which is for the whole site.  Scan down just a tad... it's 
got a yellow background here (in Firefox).

Admittedly not at all obvious, especially sitting next to the "Login" 
link and looking like maybe a text field for a user name or something, 
though it does clearly have the word "Search" in it until you click 
there...

-Peter

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[rurpy]

Peter Hansen wrote:
> [EMAIL PROTECTED] wrote:
> > [EMAIL PROTECTED] wrote:
snip
> > Are we talking about the same Search box (at the top right of the
> > wiki page, and labeled "search"?  Well, yes  I did enter "sort" and
> > got (as I said) a long list of archived maillist postings.
>
> No, he's talking about the *wiki* search box, not the one in the extreme
> upper right which is for the whole site.  Scan down just a tad... it's
> got a yellow background here (in Firefox).
>
> Admittedly not at all obvious, especially sitting next to the "Login"
> link and looking like maybe a text field for a user name or something,
> though it does clearly have the word "Search" in it until you click
> there...

It certainly did fool me.  :-(

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Tony Meyer]

> But, the standard responce of "don't complain, fix it yourself" is
> bogus too.  There are plenty of people on this list willing to sing  
> python's
> praises, for balance, there should be people willing to openly  
> point out
> python's flaws.

This makes no sense.  If you want to complain about Python, try a  
Perl list.  Why would a list dedicated to discussion about/help with  
a language need complaints about the language?

You might want to consider the difference between complaining and  
constructive criticism and suggestions, and which are likely to get  
better responses.

> Documentation is certainly one of them.

FWIW, I have found Python's documentation to generally be excellent.

> And I was correcting a posting that explicitly said there was  
> exceptionaly
> good information in that Howto.  That was just plain wrong.

It is exceptionally good information.  The version that was at that  
link is somewhat dated (but still excellent for anyone using older  
versions of Python, or for those that need to remain compatible with  
older versions, and there are a lot of those people around), but the  
updated version is also excellent.  I'm sure amk will either update  
his page to point to the new one or update the content at some point.

The point is that you're much more likely to improve things if you  
politely point out a problem and suggest a solution than simply make  
a complaint.

=Tony.Meyer
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[skip]

>> Gee, I wonder if I typed "sort" into the search box on the wiki it
>> might turn up something useful?  Well, what do you know?
>> 
>> 2 results of about 4571 pages. (0.19 seconds)
>> 
>> 1. HowTo/Sorting
>> 2. SortingListsOfDictionaries

rurpy> Are we talking about the same Search box (at the top right of the
rurpy> wiki page, and labeled "search"?  Well, yes I did enter "sort"
rurpy> and got (as I said) a long list of archived maillist postings.

Probably.  There are two search buttons, Title and Text.  Always try the
Title search first, as it only searches page titles.  If that is unhelpful,
then try the Text search.  That searches the bodies of the pages.  I
generally never use that search, preferring instead to use Google's
"site:wiki.python.org ..." restricted search which is going to apply their
page rank algorithms to the hits (and be faster to boot).  I don't know how
hard it would be to modify the wiki's Text button so it executes the
appropriate Google search.  Probably not too hard.  I'll look.

rurpy> Well, I'm not totally sure but I think I would be willing to a
rurpy> least try contributing something.  A large amount of the time I
rurpy> waste when writing Python programs is directly attributable to
rurpy> poor documentation.  (To be fair Python is not the only software
rurpy> with this problem.)

rurpy> But, the standard responce of "don't complain, fix it yourself"
rurpy> is bogus too.  There are plenty of people on this list willing to
rurpy> sing python's praises, for balance, there should be people
rurpy> willing to openly point out python's flaws.  Documentation is
rurpy> certainly one of them.  And I was correcting a posting that
rurpy> explicitly said there was exceptionaly good information in that
rurpy> Howto.  That was just plain wrong.

Sure, feel free to point of flaws.  Just don't let that be the only way you
contribute.  Over time the value of your criticism (valid or not) will be
discounted.

The preferred way to correct problems with the documentation is to submit a
bug report to SourceForge.  Many of the active developers (including those
who do write most of documentation) don't necessarily track c.l.py closely,
so postings here often will get lost because people can't attend to them
immediately.

The problem with marching in here and saying "fix the docs" is that you are
an unknown quantity (I certainly don't recognize your email address and as
far as I've seen you never sign your posts.  I don't believe I've ever seen
contributions from you either.  (Can't double-check right now because
SourceForget is basically unresponsive.)  The combination makes you look
suspiciously like a troll.  I doubt that's the case.  Troll detectors are
notorious for generating false positives.  Still, my threat assessment level
got raised.

Operating under the rurpy's-not-a-troll assumption, your posts suggest to me
that you don't understand how Python is developed.  Behind the scenes lots
of documentation *does* get written.  In my experience it hass generally not
been written by people who whine, "fix the docs".  In short, there seems to
be no shortage of people willing to castigate the Python developers for
poor documentation.  There does appear to be a shortage of people willing to
actually roll up their sleeves and help.

The other thing to remember is that most of the people who wind up writing
the documentation don't personally need most of the documentation they
write.  After all, they are generally the authors of code itself and are
thus the experts in its use.  It's tough to put yourself in the shoes of a
novice, so it's tough to write documentation that would be helpful for new
users.  It's extremely helpful if new users submit documentation patches as
they figure things out.  It's generally unnecessary to write large tomes.
Often all that's needed is a few sentences or an example or two.

Skip

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[bonono]

[EMAIL PROTECTED] wrote:
> Sure, feel free to point of flaws.  Just don't let that be the only way you
> contribute.  Over time the value of your criticism (valid or not) will be
> discounted.
> 
That is quite interesting, if it is true.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[skip]

>> Sure, feel free to point of flaws.  Just don't let that be the only
>> way you contribute.  Over time the value of your criticism (valid or
>> not) will be discounted.

bonono> That is quite interesting, if it is true.

Let me rephrase.  The discounting I referred to is largely subconcious.
When it is concious it's a roll of the eyes or a thought like, "Oh that
whiner again.  I don't have time for this right now."  And the 'd' key gets
hit.  I didn't mean to imply some sort of smoke-filled backroom where the
developers decide whose inputs to listen to.

Everybody applies such filters whether they think about it or not.  Here are
a couple of mine:

Xah Lee?  Hit the 'd' key.

Tim Peters? Read it no matter what the subject says.

Skip
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[BartlebyScrivener]

>> It's tough to put yourself in the shoes of a
novice, so it's tough to write documentation that would be helpful for
new
users.  It's extremely helpful if new users submit documentation
patches as
they figure things out.  It's generally unnecessary to write large
tomes.
Often all that's needed is a few sentences or an example or two. <<

Yes, well, regardless of your beef with the person who complained about
documentation, I respectfully submit that it is not so easy to help out
with documentation. I'm a professional writer and author with a keen
interest in open source, but the moment you look to contribute or try
to help with the documentation you are asked to learn LaTex or DocBook,
which, I'm sorry, I am not going to do.  Authors and writers are
usually drawn to open source software by their love of plain text.
Even veteran Linux users have a lot of trouble with LaTex, so the
writers, who perhaps would be willing to help with writing in exchange
for help with programming, are unable to do so without learning yet
another arcane and foreign mark-up language, which frankly won't be
useful in any other writing endeavor. How about a compromise, like
having documents submitted in html or some other system that is more
cross platform than LaTex?

bs

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Aahz]

In article <[EMAIL PROTECTED]>,
 <[EMAIL PROTECTED]> wrote:
>
>Tim Peters? Read it no matter what the subject says.

A-men!
-- 
Aahz ([EMAIL PROTECTED])   <*> http://www.pythoncraft.com/

"Don't listen to schmucks on USENET when making legal decisions.  Hire
yourself a competent schmuck."  --USENET schmuck (aka Robert Kern)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Aahz]

In article <[EMAIL PROTECTED]>,
BartlebyScrivener <[EMAIL PROTECTED]> wrote:
>
>Yes, well, regardless of your beef with the person who complained about
>documentation, I respectfully submit that it is not so easy to help out
>with documentation. I'm a professional writer and author with a keen
>interest in open source, but the moment you look to contribute or try
>to help with the documentation you are asked to learn LaTex or DocBook,
>which, I'm sorry, I am not going to do.

This is not true.  You are welcome to submit plain text patches; reST
patches are even better.  There has been a lot of confusion on this point
in the past (to which I responded by submitting a bug report and getting
the docs about submitting patches changed).  Can you point out where
you're getting this impression from so we can make further improvements
to the process?  Or do I (and others) simply need to keep repeating this
point endlessly?
-- 
Aahz ([EMAIL PROTECTED])   <*> http://www.pythoncraft.com/

"Don't listen to schmucks on USENET when making legal decisions.  Hire
yourself a competent schmuck."  --USENET schmuck (aka Robert Kern)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[BartlebyScrivener]

Go to Python.org

Click on DEVELOPERS

The lead sentence says:

Contributors and potential contributors should read Documenting Python,
which describes in details the conventions and markup used in creating
and maintaining the Python documentation. The CVS trunk version is the
recommended version for contributors, regardless of which Python branch
is being modified.

The link takes you straight to a primer on LaTex.

Did I miss something?

bs

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Scott David Daniels]

BartlebyScrivener wrote:
... ...

> Did I miss something?

At the bottom of most pages of the python docs is a link to:

     About the Python Documentation

where it says (among other things):
 If you find specific errors in this document, please report the bug
at the Python Bug Tracker at SourceForge. If you are able to provide
suggested text, either to replace existing incorrect or unclear
material, or additional text to supplement what's already available,
we'd appreciate the contribution. There's no need to worry about text
markup; our documentation team will gladly take care of that

-- 
-Scott David Daniels
[EMAIL PROTECTED]
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[BartlebyScrivener]

Thank you. I shall try that the next time I see something in the
documentation for beginners. Generally the Python docs are quite good,
in my opinion. I was merely taking issue with the poster who suggested
that Python novices and nonprogrammers should complain less and
contribute more. It's not immediately apparent how to contribute. And
if you go looking via the main page you end up in a LaTex tutorial.

bs

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Bengt Richter]

On 5 Dec 2005 10:53:36 -0800, [EMAIL PROTECTED] (Aahz) wrote:

>In article <[EMAIL PROTECTED]>,
>BartlebyScrivener <[EMAIL PROTECTED]> wrote:
>>
>>Yes, well, regardless of your beef with the person who complained about
>>documentation, I respectfully submit that it is not so easy to help out
>>with documentation. I'm a professional writer and author with a keen
>>interest in open source, but the moment you look to contribute or try
>>to help with the documentation you are asked to learn LaTex or DocBook,
>>which, I'm sorry, I am not going to do.
>
>This is not true.  You are welcome to submit plain text patches; reST
>patches are even better.  There has been a lot of confusion on this point
>in the past (to which I responded by submitting a bug report and getting
>the docs about submitting patches changed).  Can you point out where
>you're getting this impression from so we can make further improvements
>to the process?  Or do I (and others) simply need to keep repeating this
>point endlessly?
With all due respect, ISTM submission of comments and additions to 
docs.python.org
web pages could be made easier. There is a link at the bottom of many/most doc 
pages (all?) to

http://docs.python.org/lib/about.html

ISTM it would be easy to have an addditional clickable submit-comment link to 
e.g. a generated
framed page with the referrer doc page on top and a comment text box at the 
bottom (or whatever
looks good, with scrolling  for view of orig doc page), to make it easy to 
comment. A few check boxes
could categorize as to spelling/typo corrections vs adding helpful links or 
cross references,
vs wiki references, vs just griping, vs adding whole sections, etc.

A little more effort could present the referrer page with clickable paragraphs 
and other elements,
to zoom in to what the commenter wants to comment on. And an automatic diff 
could be prepared for editors,
and the submitted info could go in a structured file for automated secure web 
access by editors to ease review
and presumably sometimes pretty automatic docs update. Adherence to submission 
guidelines could be
enforced somewhat by form checks etc.

For general volunteering, a page could be generated automatically showing 
counts of failed search
subjects. Search could be modified with a form to log a gripe/suggestion about 
a failed search, that would
also be accessible. The failed search-term count display could also show a 
count of associated
comments.

We could agree on newspost tag-lines to enable automatic harvesting of gripes, 
topic suggestions, links,
etc from c.l.p newslist archives. E.g.,

[BeginPythonDocsHarvest]
(automatically harvestable info to go here, format TBD, but maybe
 rfc2822 could be looked for, or XML or rest etc?)
[EndPythonDocsHarvest]


E.g, to add a link to this (the one you are reading) post/thread to a database
of ref links for various doc pages that would ultimately show up as a single
clickable [refs] item at the bottom of pages that have refs, one could
tag a post with something like

[BeginPythonDocsHarvest]
LinkToThisThread: http://docs.python.org/about.html
[EndPythonDocsHarvest]

I guess I better stop ;-)

Regards,
Bengt Richter
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[nick]

"BartlebyScrivener" <[EMAIL PROTECTED]> writes:

> Go to Python.org
>
> Click on DEVELOPERS
>
> The lead sentence says:
>
> Contributors and potential contributors should read Documenting Python,
> which describes in details the conventions and markup used in creating
> and maintaining the Python documentation. The CVS trunk version is the
> recommended version for contributors, regardless of which Python branch
> is being modified.
>
> The link takes you straight to a primer on LaTex.
>
> Did I miss something?
>
The "Documenting Python" link takes you to a page that starts like this
- NB. the last sentence of the abstract:

"""
Documenting Python

Fred L. Drake, Jr.

PythonLabs
Email: [EMAIL PROTECTED]

Release 2.5a0
August 9, 2005

Abstract:

The Python language has a substantial body of documentation, much of
it contributed by various authors. The markup used for the Python
documentation is based on LaTeX and requires a significant set of
macros written specifically for documenting Python. This document
describes the macros introduced to support Python documentation and
how they should be used to support a wide range of output formats.

This document describes the document classes and special markup used
in the Python documentation. Authors may use this guide, in
conjunction with the template files provided with the distribution, to
create or maintain whole documents or sections.

If you're interested in contributing to Python's documentation,
there's no need to learn LaTeX if you're not so inclined; plain text
contributions are more than welcome as well.
"""


-- 
nick  (nicholas dot dokos at hp dot com)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[John J. Lee]

"BartlebyScrivener" <[EMAIL PROTECTED]> writes:

> Thank you. I shall try that the next time I see something in the
> documentation for beginners. Generally the Python docs are quite good,
> in my opinion. I was merely taking issue with the poster who suggested
> that Python novices and nonprogrammers should complain less and
> contribute more. It's not immediately apparent how to contribute. And
> if you go looking via the main page you end up in a LaTex tutorial.

Just by-the-way: Actually the Python docs use a really restricted
range of LaTeX commands, so you really need know *nothing* about LaTeX
even if you *do* go to the trouble of supplying LaTeX markup.  Just
follow what you see in the files in eg. python/trunk/Doc/lib/lib*.tex
(if you scan through the list of markup available in the 'Documenting
Python' manual, even better), and be sure to warn of the fact that
you're a LaTeX newbie when uploading patches so committers know what
they're getting.

(My advice is don't try to *compile* the docs unless you're ready for
some pain, though -- last time I looked it was quite unpleasant to get
it working.)

Also, note that Python is now in SVN, no longer in CVS:

http://svn.python.org/view/python/trunk/Doc/lib/
http://svn.python.org/projects/python/trunk/Doc/lib/
http://www.python.org/dev/devfaq.html#subversion-svn

http://docs.python.org/doc/doc.html


John

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[rurpy]

"Tony Meyer" <[EMAIL PROTECTED]> wrote:
> > But, the standard responce of "don't complain, fix it yourself" is
> > bogus too.  There are plenty of people on this list willing to sing
> > python's
> > praises, for balance, there should be people willing to openly
> > point out
> > python's flaws.
>
> This makes no sense.  If you want to complain about Python, try a
> Perl list.  Why would a list dedicated to discussion about/help with
> a language need complaints about the language?

1. So group readers might have advance warning of problem
  they may run into.
2. To give potential adopters of Python a more even handed view
  of the language.
2. So developers will have a better idea of the problems the
  user base is actually having with Python.
3. To motivate those who are looking for a way to contribute.
3. So that people who want to express an honest opinion in an
  open forum won't feel intimidated.
I could probably think of more but I'm tired of typing.

I propose a couple additions the Zen document:
  Reality beats fantasy.
  Open discussion is better that propaganda.

> You might want to consider the difference between complaining and
> constructive criticism and suggestions, and which are likely to get
> better responses.

I agree within limits, but sometimes "constructive criticism" means
"play by our rules" which for me is outside the limits.  Also
non-constructive
criticism while not as valuable, is not worthless either.

> > Documentation is certainly one of them.
>
> FWIW, I have found Python's documentation to generally be excellent.

FWIW I find Python's docs to be OK at best, with some horrible
parts, and a lot of mediochre to poor parts.

1. I have seen recommendations here to use new-style classes.
I believe classes are at the core of Python, the entire language
is built around and rests on them.  Yet, unless I missed it,
new style classes are almost completely undocumented in
the Language Reference Manual.  This alone is sufficient
to condemn the documentation.

2.Section 2 of the Library Reference should clearly be in the
Language Reference manual.

3.There are way to few examples in the docs.

4.There are way to few cross references in the docs (for example
the datetime module doesn't even mention the existence of the
time" module.) [I double checked before posting and see this is
no longer true, but I think it is still true in many other cases. ]

5.Forward refernces (mention of things explained or defined
later in the manual) are seldom identified as such.  They should
be a link to the appropriate part of the manual.

6.There is often no notational distinction for terms used in a
general sense and a python specific technical sense leading
to confusion.

7.The writing is often too terse.  (To parapharse, it should be as
terse as possible but no terser.  I think it often violates the
that last clause.)

8.There is critical missing info.  (I lost many hours once because
the process module (or popen? I forgot) failed to document it
didn't do unicode.)

9.Many other small details, e.g is it neccesary for the one of the
most frequently used datatypes (string) to not appear in the
table of contents?  (That's not retorical, I really don't know.
Maybe it is, but if things could be arranged to that it did, it would
be better.)

> > And I was correcting a posting that explicitly said there was
> > exceptionaly
> > good information in that Howto.  That was just plain wrong.
>
> It is exceptionally good information.  The version that was at that
> link is somewhat dated (but still excellent for anyone using older
> versions of Python, or for those that need to remain compatible with
> older versions, and there are a lot of those people around), but the
> updated version is also excellent.  I'm sure amk will either update
> his page to point to the new one or update the content at some point.

No, it is not exceptionally good information.  It is outdated
information,
it does not say it is outdated, and it will lead to poor practice when
used
in the version of Python that it documents.  That clearly makes it "not
good".

> The point is that you're much more likely to improve things if you
> politely point out a problem and suggest a solution than simply make
> a complaint.

I did.  As for my original responce I think the suggestion was clear
if implicit: stop referring to outdated documentation as a "treasure".
The suggestion in my "update the damn docs" comment was quite
explicit I think.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[rurpy]

<[EMAIL PROTECTED]> wrote in message
news:[EMAIL PROTECTED]
--snip--
> rurpy> Well, I'm not totally sure but I think I would be willing to a
> rurpy> least try contributing something.  A large amount of the time I
> rurpy> waste when writing Python programs is directly attributable to
> rurpy> poor documentation.  (To be fair Python is not the only software
> rurpy> with this problem.)
>
> rurpy> But, the standard responce of "don't complain, fix it yourself"
> rurpy> is bogus too.  There are plenty of people on this list willing to
> rurpy> sing python's praises, for balance, there should be people
> rurpy> willing to openly point out python's flaws.  Documentation is
> rurpy> certainly one of them.  And I was correcting a posting that
> rurpy> explicitly said there was exceptionaly good information in that
> rurpy> Howto.  That was just plain wrong.
>
> Sure, feel free to point of flaws.  Just don't let that be the only way you
> contribute.  Over time the value of your criticism (valid or not) will be
> discounted.
>
> The preferred way to correct problems with the documentation is to submit a
> bug report to SourceForge.  Many of the active developers (including those
> who do write most of documentation) don't necessarily track c.l.py closely,
> so postings here often will get lost because people can't attend to them
> immediately.
>
> The problem with marching in here and saying "fix the docs" is that you are
> an unknown quantity (I certainly don't recognize your email address and as
> far as I've seen you never sign your posts.

I don't believe my name, etnic heritage, gender, age, employer or
school, or part of the world I live in, have any bearing on the
contents
of my postings.

> I don't believe I've ever seen
> contributions from you either.  (Can't double-check right now because
> SourceForget is basically unresponsive.)

I try to contribute on c.l.p when I can but those times are rare.  I
freely
admit I am a python newbie so in most cases it is more appropriate
for me to read answers than to supply them.  And traffic is so high it
is rare when I see a question I can answer, that someone hasn't
already answered better.

> The combination makes you look
> suspiciously like a troll.  I doubt that's the case.  Troll detectors are
> notorious for generating false positives.  Still, my threat assessment level
> got raised.

I would say I am more than 90% serious and less than 10%
troll. :-)  Perhaps the reason your detector went off is because
I have posted some Politically Incorrect opinions in the same
absolutist, dogmatic, style used by many PC posters?  Sorry,
life is short and I am not interested in sugar coating anything.

> Operating under the rurpy's-not-a-troll assumption, your posts suggest to me
> that you don't understand how Python is developed.  Behind the scenes lots
> of documentation *does* get written.  In my experience it hass generally not
> been written by people who whine, "fix the docs".  In short, there seems to
> be no shortage of people willing to castigate the Python developers for
> poor documentation.  There does appear to be a shortage of people willing to
> actually roll up their sleeves and help.

Well, I guess I would be willing to consider trying to help.  (I say
"try"
because I am lousy at technical writing so my help may not be very
helpful.)  One thing that's not clear to me is exactly what audience
are
the docs aimed at?  If the powers-that-be have declared that the Lang
Ref. Manual is going to be a minimalist reference with an audience that

already has a high level knowledge of Python, there is no point in my
contributing because:
1. I can't write at that level.
2. I have no interest in a manual positioned at that level.
If the audience is some lower level (e.g. programmers with
some familiarity with OO but no Python knowledge) then I
would be much more motivated to help.  (Note that I am NOT
talking about turning the Lang.Ref.Man into a tutorial!!!)

> The other thing to remember is that most of the people who wind up writing
> the documentation don't personally need most of the documentation they
> write.  After all, they are generally the authors of code itself and are
> thus the experts in its use.  It's tough to put yourself in the shoes of a
> novice, so it's tough to write documentation that would be helpful for new
> users.  It's extremely helpful if new users submit documentation patches as
> they figure things out.  It's generally unnecessary to write large tomes.
> Often all that's needed is a few sentences or an example or two.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Fredrik Lundh]

[EMAIL PROTECTED] wrote:

> > The problem with marching in here and saying "fix the docs" is that you are
> > an unknown quantity (I certainly don't recognize your email address and as
> > far as I've seen you never sign your posts.
>
> I don't believe my name, etnic heritage, gender, age, employer or
> school, or part of the world I live in, have any bearing on the
> contents of my postings.

perhaps not, but it's not what you think that's important here.  and I sure
cannot find anything in your posts that I haven't seen before.  this is use-
net, after all; there's no shortage of anonymous posters hiding behind silly
nicknames who think they're somehow smarter than everyone else...

(and frankly, nobody takes people with hotmail.com or yahoo.com addresses
seriously ;-)





-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[rurpy]

Fredrik Lundh wrote:
> [EMAIL PROTECTED] wrote:
>
> > I don't believe my name, etnic heritage, gender, age, employer or
> > school, or part of the world I live in, have any bearing on the
> > contents of my postings.
>
> perhaps not, but it's not what you think that's important here.  and I sure
> cannot find anything in your posts that I haven't seen before.  this is use-
> net, after all; there's no shortage of anonymous posters hiding behind silly
> nicknames who think they're somehow smarter than everyone else...

I don't know what I posted that gave you that false idea about me.

> (and frankly, nobody takes people with hotmail.com or yahoo.com addresses
> seriously ;-)

You can judge people using whatever criteria you want, of course ;-)

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[skip]

> "bs" == BartlebyScrivener  <[EMAIL PROTECTED]> writes:

bs> I'm a professional writer and author with a keen interest in open
bs> source, but the moment you look to contribute or try to help with
bs> the documentation you are asked to learn LaTex or DocBook, which,
bs> I'm sorry, I am not going to do.

Let me repeat this for the umpteenth time: You do not have to learn LaTeX to
contribute to docs.  Submit plain text.  One of us with some LaTeX knowledge
will do the markup.  Content is the hard part.  Markup is nothing, so don't
let it be a barrier for you.

Skip
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[BartlebyScrivener]

>>Let me repeat this for the umpteenth time: You do not have to learn LaTeX to
contribute to docs. <<

Noted. And thanks again to all who responded. The tone of this whole
thing is really antagonistic in parts, which is unfortunate. I'll offer
my services through the proper channels, because I appreciate the
generosity of those who share their programming knowledge. In the
meantime, I think perhaps Bengt Richter's post is probably the most
constructive.

Meanwhile, if you have to keep repeating things for the umpteenth time
then it MIGHT be because the way it is laid out or organized is making
it difficult for the person seeking to VOLUNTEER to help. And we come
full circle to documentation.

Why do people continue getting the impression that they need to learn
LaTex to submit documentation?  A writer would look to his text. A
programmer would probably just accuse his audience of being obtuse.

rpd
www.dooling.com

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Grant Edwards]

On 2005-12-05, [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote:

>>> I don't believe my name, etnic heritage, gender, age, employer
>>> or school, or part of the world I live in, have any bearing on
>>> the contents of my postings.
>>
>> perhaps not, but it's not what you think that's important
>> here.  and I sure cannot find anything in your posts that I
>> haven't seen before.  this is usenet, after all; there's no
>> shortage of anonymous posters hiding behind silly nicknames
>> who think they're somehow smarter than everyone else...
>
> I don't know what I posted that gave you that false idea about
> me.

Hmm, I though he explained it:

  1) Not using your real name.

  2) A yahoo, aol, or hotmail address.

In the ancient and hallowed (by net standards) history of
Usenet, both of these (particularly the first one) have been
pretty good predictors of crankness.  The correlation isn't as
high as it used to be, now that hiding behind silly nicknames
has apparently become socially acceptable in other venues (web
"forums" and "boards" and whatnot).
  
>> (and frankly, nobody takes people with hotmail.com or
>> yahoo.com addresses seriously ;-)
>
> You can judge people using whatever criteria you want, of
> course ;-)

He's just trying to warn you that, on Usenet, by not using your
real name you start out with negative credibility points in the
minds of most of the old-school Usenet denizens -- and having a
yahoo address subtracts a few more points.  That just means
you're going to have to work a bit to get back up to the same
point that somebody with a real name and a "real" ISP would
start at.

-- 
Grant Edwards   grante Yow!  Yow! Am I JOGGING
  at   yet??
   visi.com
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Fredrik Lundh]

Grant Edwards wrote:

> The correlation isn't as high as it used to be, now that hiding
> behind silly nicknames has apparently become socially acceptable
> in other venues (web "forums" and "boards" and whatnot).

on the other hand, hanging out on web forums and boards is in it-
self a good predictor.

(if you read enough blogs, you'll notice that you can use the same
filters for blog commenters as well; people behave in pretty much
the same way, no matter what net protocol they're using...)

> old-school Usenet denizens

if you've been on the Usenet long enough, you've seen it all.





-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[gene tani]

[EMAIL PROTECTED] wrote:
> [EMAIL PROTECTED] wrote:
>
> > Gee, I wonder if I typed "sort" into the search box on the wiki it might
> > turn up something useful?  Well, what do you know?
> >
> > 2 results of about 4571 pages. (0.19 seconds)
> >
> > 1. HowTo/Sorting
> >     2. SortingListsOfDictionaries
>
> Are we talking about the same Search box (at the top right of the
> wiki page, and labeled "search"?  Well, yes  I did enter "sort" and
> got (as I said) a long list of archived maillist postings.
>
> > Is it as good as Google ("site:wiki.python.org sort")?  Unlikely, but it
> > works fairly well.  Granted, wikis are a different way of organizing content
> > than static documentation with their nicely organized chapters, sections and
> > indexes, but most of us around here are software engineer types, not tech
> > writers, and since we're not paid to do any of this, we get to do anything
> > we want.  Most of us choose not to write documentation in our spare time.
> > Go figure.  If documentation's your thing, be my guest.  Write new
> > documentation, submit patches for existing documentation, rewrite it in
> > Word.  I don't care. Do whatever floats your boat.  Just don't show up and
> > bitch about the documentation if you're not willing to help.
>
> Well, I'm not totally sure but I think I would be willing to a least
> try
> contributing something.  A large amount of the time I waste when
> writing Python programs is directly attributable to poor documentation.
> (To be fair Python is not the only software with this problem.)
>
> But, the standard responce of "don't complain, fix it yourself" is
> bogus
> too.  There are plenty of people on this list willing to sing python's
> praises,
> for balance, there should be people willing to openly point out
> python's
> flaws.  Documentation is certainly one of them.  And I was correcting a
> posting that explicitly said there was exceptionaly good information in
> that Howto.  That was just plain wrong.
>
> > Oh, did I mention that there's an Edit link at the top of almost every page
> > on the wiki and that creating new pages is pretty simple?  (Try searching
> > the wiki for "WikiCourse".)  Contributing new content to the existing more
> > static documentation isn't all that hard either.
>
> As I said, I think wiki's suck.  On almost every one I find the
> information
> disorganised, very spotty in coverage, extremely variable is qualilty
> of writing, and often seeming like a conversation walked into in the
> middle of.  I still haven't figured out how to get to the Python wiki's
> howto's by navigating from the front page.  IMO wikis are best used
> to collect information for later editing and inclusion into more formal
> documentation.  (That's a little stronger than my actual opinion but
> it's too late right now more me to express it any better.)
>
> > If you prefer the latest documentation, bookmark this page:
> >
> > http://www.python.org/dev/doc/devel/index.html
>
> Thanks I will keep that in mind.  But the obvious risk is that it
> will refer to language features and changes not in the current
> version.
>
> > That's updated every few months, more frequently as new releases approach.

Well, the docs are what they are, I can find what I need.  Are you
telling us you learned C#, smalltalk, lisp, C, perl, whatever, from 1
website only, without looking at any books, without spending any money
on IDEs or any software?  Cause that's what you're asking here.

So either spend a little money, buy the Nutshell and Cookbook, (or,
look at dozens of books, and many excellent ones:
http://www.amazon.com/exec/obidos/tg/browse/-/285856/ref=dp_brlad_entry/103-3311503-6360648

or spend some time, look at the 2 complete intro books published on the

web, there's also:

http://awaretek.com/tutorials.html
http://www.vex.net/parnassus/
http://directory.google.com/Top/Computers/Programming/Languages/Python/Modules/
http://cheeseshop.python.org/
http://the.taoofmac.com/space/Python/Grimoire
http://dmoz.org/Computers/Programming/Languages/Python/Modules/

http://aspn.activestate.com/ASPN/Cookbook/Python
http://python.codezoo.com/
http://sourceforge.net/softwaremap/trove_list.php?form_cat=178&xdiscrim=178

Here's some FAQ/gotchas:
http://www.ferg.org/projects/python_gotchas.html
http://zephyrfalcon.org/labs/python_pitfalls.html
http://zephyrfalcon.org/labs/beginners_mistakes.html
http://www.python.org/doc/faq/
http://diveintopython.org/appendix/abstracts.html
http://www.onlamp.com/pub/a/python/2004/02/05/learn_python.html
http://www.norvig.com/python-iaq.html
http://www.faqts.com/knowledge_base/index.phtml/fid/245
http://amk.ca/python/writing/warts

So i don't think you ca really say the lang spec, the VM and the dev
environment in general are poorly documented.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Steve Holden]

BartlebyScrivener wrote:
>>>Let me repeat this for the umpteenth time: You do not have to learn LaTeX to
> 
> contribute to docs. <<
> 
> Noted. And thanks again to all who responded. The tone of this whole
> thing is really antagonistic in parts, which is unfortunate. I'll offer
> my services through the proper channels, because I appreciate the
> generosity of those who share their programming knowledge. In the
> meantime, I think perhaps Bengt Richter's post is probably the most
> constructive.
> 
> Meanwhile, if you have to keep repeating things for the umpteenth time
> then it MIGHT be because the way it is laid out or organized is making
> it difficult for the person seeking to VOLUNTEER to help. And we come
> full circle to documentation.
> 
> Why do people continue getting the impression that they need to learn
> LaTex to submit documentation?  A writer would look to his text. A
> programmer would probably just accuse his audience of being obtuse.
> 
> rpd
> www.dooling.com
> 

I'd like to suggest that since you aren't by any means the first person 
to form the impression that Latex knowledge is required, we probably 
*should* be making more effort to publicise the acceptability of plain 
text patches to the documentation.

Thanks for persisting long enough to get to this point: it would be 
unfortunate to lose potential contributions simply because of an 
inadequacy in the documentation. We definitely need to lose the 
antagonistic tone, but I do know from experience that there are whiners 
who, unlike you, aren't really prepared to do much to help.

As a small start I've edited

   http://www.python.org/dev/doc/

and if you can think of other changes that will get Fred and Skip more 
help on the documentation I'll try to make those too.

regards
  Steve
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006  www.python.org/pycon/

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[François Pinard]

[EMAIL PROTECTED]

> Let me repeat this for the umpteenth time: You do not have to learn 
> LaTeX to contribute to docs.  Submit plain text.  One of us with some 
> LaTeX knowledge will do the markup.  Content is the hard part.  Markup 
> is nothing, so don't let it be a barrier for you.

More than LaTeX, the main frozener is when people in charge tell you to 
use bug trackers to speak to them.

This is like standing up with someone, having a conversation, and your 
partner suddenly tells you: "If you want to speak to me, please study 
this form, carefully read the small print, fill it properly and send the 
yellow copy at this address."  Surprised, you ask: "Why should I do 
that?", and he replies: "I might forget our conversation if you don't 
fill a form for me."  Even more suprіsed, you say:  "Gosh, can't you 
manage your own notes yourself, as you see them fit?  Most grown up 
people are able to take care of themselves, you know."  "I just do not 
like filling these forms!  Besides, _my_ time is quite precious."

Astonished, you just cannot believe what you hear.  Life is so short, 
you think, why one would ought to stand with such guys?  As the room is 
full of other interesting people, you happily move on towards them.

-- 
François Pinard   http://pinard.progiciels-bpi.ca
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Paul Rubin]

François Pinard <[EMAIL PROTECTED]> writes:
> > Let me repeat this for the umpteenth time: You do not have to learn
> > LaTeX to contribute to docs.  Submit plain text.  One of us with
> > some LaTeX knowledge will do the markup.  Content is the hard part.
> > Markup is nothing, so don't let it be a barrier for you.
> 
> More than LaTeX, the main frozener is when people in charge tell you
> to use bug trackers to speak to them.

More than latex and bug trackers, the main obstacle is that people
wanting better docs want them for the precise reason that the existing
docs don't make it clear what the code does.  Writing a good doc patch
(and the "patches" needed are often sweeping rewrites) requires
studying and understanding the code being documented, and the
application area that the code tries to implement.  Maybe it also
requires studying relevant standards that the code implements (to note
gaps in the implementation), comparing the implementation to other
implementations in other languages, etc.  For example, writing a good
doc patch for urllib2 would mean checking RFC 2616(?) against the
urllib2 code to see what parts of the RFC got implemented and what
parts didn't.  It might also mean comparing urllib2 with other
libraries like LWP (Perl) or whatever the equivalent is in Java.

By the time the requester/patch writer gets through studying the code
to figure out what it does, maybe s/he has answered his/her own
questions and doesn't need docs any more.  The person best qualified
to know what the code does is the code author, who could answer all
the questions immediately.

The solution is clear: the distro maintainers should require that all
code contributions must come with good docs.  When a code submission
comes in, the distro maintainers should critically review the
accompanying docs, note any shortcomings and constructively ask for
improvements from the contributor until the docs are good.  The distro
committers are all very skilled and experienced people.  So there's a
certain amount of mentoring going on whenever a committer works with a
contributor to accept a code patch.  By communicating what it takes to
bring documentation up to snuff, the committers can share their wisdom
with contributors and thereby raise the quality standard of not just
the distro, but also of the whole contributor community.  Passing
skills on to others is after all what being a community is about.
Many of us who have acquired any skill at putting docs together,
acquired them in precisely this fashion, and should try to pass them on.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[skip]

François> More than LaTeX, the main frozener is when people in charge
François> tell you to use bug trackers to speak to them.

Understood.  I wish either a) SourceForge supported email interaction with
their trackers or b) someone would finish off the Roundup issue tracker
<http://roundup.sourceforge.net/> for python.org.  I doubt if anyone here
can do anything about the first barrier, but if you know something about
Roundup (or would like to learn about it) and would like to contribute
something non-documentational that would really have a direct, positive
impact on the Python community, send a note to [EMAIL PROTECTED]

Skip
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[skip]

Paul> For example, writing a good doc patch for urllib2 would mean
Paul> checking RFC 2616(?) against the urllib2 code to see what parts of
Paul> the RFC got implemented and what parts didn't.  It might also mean
Paul> comparing urllib2 with other libraries like LWP (Perl) or whatever
Paul> the equivalent is in Java.

Sounds like a subject matter expert is needed here, not a garden variety
tech writer or Python programmer.  Documentation of esoteric stuff requires,
well, esoteric knowledge.

Skip
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Ben Finney]

François Pinard <[EMAIL PROTECTED]> wrote:
> More than LaTeX, the main frozener is when people in charge tell you
> to use bug trackers to speak to them.
> 
> This is like standing up with someone, having a conversation,

... in which you informally ask them to do something...

> and your 
> partner suddenly tells you: "If you want to speak to me,

... "to give specific suggestions for improvement"...

> please study this form, carefully read the small print, fill it
> properly and send the yellow copy at this address."

... "so that it can go with all the other requests I get at various
times from various people".

> Surprised, you ask: "Why should I do that?", and he replies: "I
> might forget our conversation if you don't fill a form for me."
> Even more suprіsed, you say:  "Gosh, can't you manage your own notes
> yourself, as you see them fit?  Most grown up people are able to
> take care of themselves, you know."  "I just do not like filling
> these forms!  Besides, _my_ time is quite precious."
> 
> Astonished, you just cannot believe what you hear.  Life is so
> short, you think, why one would ought to stand with such guys?

Perhaps because you have asked them to do something that benefits you,
and they receive multiple requests of that type from many different
people?

> As the room is full of other interesting people, you happily move on
> towards them.

If you just want to have conversations, talk to whomever you like.

If you want someone specific to voluntarily do something, yes, you'll
have to meet them halfway by helping them help you.

-- 
 \  "I put instant coffee in a microwave oven and almost went back |
  `\   in time."  -- Steven Wright |
_o__)  |
Ben Finney
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[BartlebyScrivener]

>>The solution is clear: the distro maintainers should require that all
code contributions must come with good docs.  When a code submission
comes in, the distro maintainers should critically review the
accompanying docs, note any shortcomings and constructively ask for
improvements from the contributor until the docs are good.  <<

Well, that might be asking a bit too much of the programmers, who
perhaps don't exactly enjoy mucking about in the lowlands of English
grammar and syntax. All I was saying is you should court writers and
mid-level programmers with writing skills (not saying I'M mid-level,
I'm still learning) to HELP with creating good documentation. When a
writer thinks about helping they go to a page where they are greeted by
a bug report menu or CSV notices or some such. That's why most of your
really good stuff for beginners is on separately created web pages,
where writers simply take matters into their own hands. Also fine, not
saying it should be different.

Again, taking something like Bengt Richter's suggestion as just one
example. To me the module docs are almost incomprehensible without good
examples. Why not have a button where people could submit nice SHORT
examples illustrating otherwise pure theoretical code and geek-speak.
Of course, the editors would decide in a survival-of-the-fittest
contest which example gets used, but the point is you'd get good free
examples this way.

In general, I'd be happy to help a programmer with writing if it meant
I would learn programming along the way. It should be that easy. 

rd

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Paul Rubin]

[EMAIL PROTECTED] writes:
> Sounds like a subject matter expert is needed here, not a garden variety
> tech writer or Python programmer.  Documentation of esoteric stuff requires,
> well, esoteric knowledge.

Yes, that's what I mean; coding a library module for an esoteric
function requires that same esoteric knowledge, and those are the
modules for which the docs need the most help.  So the person coding
the library module is the logical person to write the doc.  The doc
writing task can't in general be handed off to some random programmer
or writer.  It should be written by the same person who wrote the code.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Steve Holden]

Paul Rubin wrote:
> [EMAIL PROTECTED] writes:
> 
>>Sounds like a subject matter expert is needed here, not a garden variety
>>tech writer or Python programmer.  Documentation of esoteric stuff requires,
>>well, esoteric knowledge.
> 
> 
> Yes, that's what I mean; coding a library module for an esoteric
> function requires that same esoteric knowledge, and those are the
> modules for which the docs need the most help.  So the person coding
> the library module is the logical person to write the doc.  The doc
> writing task can't in general be handed off to some random programmer
> or writer.  It should be written by the same person who wrote the code.

Or, better still, by an accomplished writer who has access to the code's 
author. This was indeed my experience in writing the docs for previously 
undocumented modules. The author was happy to help me by answering 
questions, and this did make the docs better than they'd otherwise have 
been.
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006  www.python.org/pycon/

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[BartlebyScrivener]

>>Or, better still, by an accomplished writer who has access to the code's
author. This was indeed my experience in writing the docs for
previously
undocumented modules. The author was happy to help me by answering
questions, and this did make the docs better than they'd otherwise have
been. <<

Now you're talking. The writer forces the programmer to explain how the
code works, in plain English, until the writer understands it. Then the
writer creates simple sentences written in the active voice with vivid
particular examples to illustrate. Voila. 

rd

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Paul Rubin]

Steve Holden <[EMAIL PROTECTED]> writes:
> Or, better still, by an accomplished writer who has access to the
> code's author. This was indeed my experience in writing the docs for
> previously undocumented modules. The author was happy to help me by
> answering questions, and this did make the docs better than they'd
> otherwise have been.

Yes, this can work pretty well for some modules, especially when
there's in-person contact rather than just email.  The total amount of
work done between the two people may be more than would be needed if
the coder just wrote the docs and got it over with.  But any way that
gets it done is fine.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[rurpy]

"Paul Rubin"  wrote:
> Steve Holden <[EMAIL PROTECTED]> writes:
> > Or, better still, by an accomplished writer who has access to the
> > code's author. This was indeed my experience in writing the docs for
> > previously undocumented modules. The author was happy to help me by
> > answering questions, and this did make the docs better than they'd
> > otherwise have been.
>
> Yes, this can work pretty well for some modules, especially when
> there's in-person contact rather than just email.  The total amount of
> work done between the two people may be more than would be needed if
> the coder just wrote the docs and got it over with.  But any way that
> gets it done is fine.

Redhat's Fedora project seems to have a fairly well developed
program for recruiting and encouraging writers.

I thought when I looked at their material 6-12 months ago, I
read that they formally facilitated contact between a project's
developers and writer(s) doing the documentation.  But I couldn't
find anything specific on that when I looked just now.

They might be a source of some useful ideas though (assuming
you don't already know all this.)
http://www.fedora.redhat.com/projects/docs/
http://fedoraproject.org/wiki/DocsProject/NewWriters

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[François Pinard]

[Ben Finney]

>> please study this form, carefully read the small print, fill it
>> properly and send the yellow copy at this address."

> ... "so that it can go with all the other requests I get at various
> times from various people".

If he wants pink forms with blue borders, let him grant himself with 
pink forms with blue borders.  His way of managing has not to be mine.
If he declares being unable to read information unless it is written on 
a pink form with blue borders, he has a serious communication problem, 
that should not receive encouragement from me.

>> Astonished, you just cannot believe what you hear.  Life is so
>> short, you think, why one would ought to stand with such guys?

> Perhaps because you have asked them to do something that benefits you,

Or perhaps not so specifically.  When I (attempt to) submit a Python 
problem (documentation or otherwise), I'm hoping some benefit to the 
Python community in the long run.  One of those humble drops which, 
accumulated, make oceans.  Most of times, in practice, I already solved 
my actual problem.  I'm merely trying to be a good citizen.  However, 
when people tell me I'm not a good citizen unless _I_ fill pink forms 
with blue borders, I think they lost part of their good judgement.
If they really want pink forms, they should serve themselves by filling 
pink forms, and leave me and the world alone with these forms.

>> As the room is full of other interesting people, you happily move on
>> towards them.

> If you just want to have conversations, talk to whomever you like.
> If you want someone specific to voluntarily do something, yes, you'll
> have to meet them halfway by helping them help you.

I do not want to force anyone to anything.  This is mostly volunteer 
work.  You know that.  The problem I'm reporting here is this pink form 
mania.   _I_ would volunteer something, that they'd ask for pink forms.

I've been in the area of free software maintainance for a very long 
while, collobarated with maybe a hundred of maintainers, and 
corresponded with surely many thousands of users.  No doubt it was a lot 
of work overall, but at least, communication was easy going (usually).
It's a relatively recent phenomenon that maintainers go berzerk, foaming 
at the mouth over forms, borders, colors, and various other mania!  :-)

-- 
François Pinard   http://pinard.progiciels-bpi.ca
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Paul Rubin]

[EMAIL PROTECTED] writes:
> Redhat's Fedora project seems to have a fairly well developed
> program for recruiting and encouraging writers.

Frankly I haven't been that impressed with the Fedora docs I've seen.
The LDP docs have generally been better.  Maybe I'm looking at the
wrong Fedora docs.  Fedora Core 4 also broke or changed a bunch of
code that worked perfectly well in FC3, as a side issue.

For a language environment like Python, the example I'd look to for
quality docs is probably CLtL2:

   http://www.cliki.net/CLtL2

The CMU link seems to be down right now.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[rurpy]

<[EMAIL PROTECTED]> wrote:
> [EMAIL PROTECTED] wrote:
> > [EMAIL PROTECTED] wrote:
--snip--
> > > If you prefer the latest documentation, bookmark this page:
> > >
> > > http://www.python.org/dev/doc/devel/index.html
> >
> > Thanks I will keep that in mind.  But the obvious risk is that it
> > will refer to language features and changes not in the current
> > version.
> >
> > > That's updated every few months, more frequently as new releases approach.
>
> Well, the docs are what they are, I can find what I need.

And so it is with me too.  But it often takes me much longer than it
should to find what I need.  And everytime I (or you) don't find it in
Python's docs, that is evidence of the lack of quality of Python's
docs.

> Are you
> telling us you learned C#, smalltalk, lisp, C, perl, whatever, from 1
> website only, without looking at any books, without spending any money
> on IDEs or any software?  Cause that's what you're asking here.

For perl and C, yes, that's (close to) what I'm telling you.  Perl I
learned
exclusively from the man pages, before WWW.  I used it for 10 years
before I ever bought a printed book.   C I learned exclusively from the

K&R book.  I tried to learn Python from the "official" docs but found
it
impossible.  I bought Beasley's book (I think this may have predated
Martelli's book but I don't remember) which I thought quite good and
which I still turn to before the Python docs in most cases.

> So either spend a little money, buy the Nutshell and Cookbook, (or,

If one is required to buy a book to use free software, it is not
really free, is it?

> look at dozens of books, and many excellent ones:
> http://www.amazon.com/exec/obidos/tg/browse/-/285856/ref=dp_brlad_entry/103-3311503-6360648

Books are no different than anything else.  There are a few good ones,
a lot of average ones, and a few bad ones.  (Actually, the distribution
is probably skewed to the bad side because it is easier to write a bad
book than a good one).  Also most of these books seem to be tutorial
in nature.  That's not what I want.  I want a clear, lucid, *concise*,
compete, accurate, description of Python (i.e. what Python's docs
should be.)  Given that Beazley (and I presume Martelli) did that, and
the reference manuals of other languages did that, I don't see why
Python can't do that (other than the fact that writing documentation
is not fun for most people, and hard to do well.)

> or spend some time, look at the 2 complete intro books published on the

I did.  I thought they both were poor.

> web, there's also:
>
> http://awaretek.com/tutorials.html
> http://www.vex.net/parnassus/
> http://directory.google.com/Top/Computers/Programming/Languages/Python/Modules/
> http://cheeseshop.python.org/
> http://the.taoofmac.com/space/Python/Grimoire
> http://dmoz.org/Computers/Programming/Languages/Python/Modules/
>
> http://aspn.activestate.com/ASPN/Cookbook/Python
> http://python.codezoo.com/
> http://sourceforge.net/softwaremap/trove_list.php?form_cat=178&xdiscrim=178
>
> Here's some FAQ/gotchas:
> http://www.ferg.org/projects/python_gotchas.html
> http://zephyrfalcon.org/labs/python_pitfalls.html
> http://zephyrfalcon.org/labs/beginners_mistakes.html
> http://www.python.org/doc/faq/
> http://diveintopython.org/appendix/abstracts.html
> http://www.onlamp.com/pub/a/python/2004/02/05/learn_python.html
> http://www.norvig.com/python-iaq.html
> http://www.faqts.com/knowledge_base/index.phtml/fid/245
> http://amk.ca/python/writing/warts

That's a very good list and I will save a copy, thanks.  But what
does it have to do with Python's documentation?

> So i don't think you ca really say the lang spec, the VM and the dev
> environment in general are poorly documented.

Are you under the impression that an assortment of pages
out on the internet constitutes (or substitutes for) the "official"
documentation that comes with python?

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Paul Rubin]

"BartlebyScrivener" <[EMAIL PROTECTED]> writes:

> >>The solution is clear: the distro maintainers should require that all
> code contributions must come with good docs.
> Well, that might be asking a bit too much of the programmers, who
> perhaps don't exactly enjoy mucking about in the lowlands of English
> grammar and syntax. 

I've generally found good coders are also good writers, despite the
stereotype of the uncommunicative geek.  Some coders don't like
documenting because it's less exciting than writing code, but that
doesn't mean they're incapable of it.  After a while you learn to just
slog it out.

Docs written by non-native English speakers generally need to be
cleaned up before publication, but that's no big deal.  

> All I was saying is you should court writers and mid-level
> programmers with writing skills (not saying I'M mid-level, I'm still
> learning) to HELP with creating good documentation. When a writer
> thinks about helping they go to a page where they are greeted by a
> bug report menu or CSV notices or some such.

I just don't know to what extent a program like Python can really
benefit from docs written by non-experts in the thing being
documented.  Of course there are other types of programs, like some
desktop applications, which can be documented by non-experts.

> That's why most of your really good stuff for beginners is on
> separately created web pages, where writers simply take matters into
> their own hands. Also fine, not saying it should be different.

I don't know about this.

> Again, taking something like Bengt Richter's suggestion as just one
> example. To me the module docs are almost incomprehensible without good
> examples. Why not have a button where people could submit nice SHORT
> examples illustrating otherwise pure theoretical code and geek-speak.
> Of course, the editors would decide in a survival-of-the-fittest
> contest which example gets used, but the point is you'd get good free
> examples this way.

PHP has a system sort of like that, where each library function has
its own doc page and anyone can submit comments and examples, sort
of like a blog.  E.g.:

  http://us2.php.net/manual/en/function.metaphone.php

There's been some discussion of doing the same thing for Python, but
it hasn't been happening.

Generally, it seems to me, the parts of the docs that can be improved
much by easy additions like an example here and there, are already
usable with a little extra effort.  The docs that need improvement the
most (because they're almost unusable as-is) need extensive additions
and rewrites that really have to to be done by experts.

> In general, I'd be happy to help a programmer with writing if it meant
> I would learn programming along the way. It should be that easy. 

Maybe you'd enjoy going to a user group meeting and trying to find
people to collaborate with.  Doing that kind of thing in person is
much more fun than doing it over the net.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Ben Finney]

[EMAIL PROTECTED] wrote:
> If one is required to buy a book to use free software, it is not
> really free, is it?

If one is required to buy a computer to use free software, is it free?

You should well know that cost and freedom are orthogonal.

-- 
 \"I got fired from my job the other day. They said my |
  `\personality was weird. ... That's okay, I have four more."  -- |
_o__)Bug-Eyed Earl, _Red Meat_ |
Ben Finney
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[skip]

>> Are you telling us you learned C#, smalltalk, lisp, C, perl,
>> whatever, from 1 website only, without looking at any books, without
>> spending any money on IDEs or any software?  Cause that's what you're
>> asking here.

rurpy> For perl and C, yes, that's (close to) what I'm telling you.
rurpy> Perl I learned exclusively from the man pages, before WWW.  I
rurpy> used it for 10 years before I ever bought a printed book.  C I
rurpy> learned exclusively from the K&R book.

That's about the same for me, except Perl never "stuck".

rurpy> I tried to learn Python from the "official" docs but found it
rurpy> impossible.  

I did as well, though the docs as they existed in 1993 or so (that is
pre-Lutz, pre-Beasley).


rurpy> I bought Beasley's book (I think this may have predated
rurpy> Martelli's book but I don't remember) which I thought quite good
rurpy> and which I still turn to before the Python docs in most cases.

Like other free software, you can choose to figure things out yourself (use
the source Luke) or pay someone to help you out.  I'm not using this as an
excuse for poor Python docs.

rurpy> That's a very good list and I will save a copy, thanks.  But what
rurpy> does it have to do with Python's documentation?

I'm sure you could find similar lists for Perl, C, Ruby, Tcl, Java, C++, C#,
etc.  Does that mean their documentation stinks?  Maybe.  Maybe not.  It
just means a lot of people have somewhat different ways of tackling the same
problem.

Skip
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[gene tani]

[EMAIL PROTECTED] wrote:
> >> Are you telling us you learned C#, smalltalk, lisp, C, perl,
> >> whatever, from 1 website only, without looking at any books, without
> >> spending any money on IDEs or any software?  Cause that's what you're
> >> asking here.
>
> rurpy> For perl and C, yes, that's (close to) what I'm telling you.
> rurpy> Perl I learned exclusively from the man pages, before WWW.  I
> rurpy> used it for 10 years before I ever bought a printed book.  C I
> rurpy> learned exclusively from the K&R book.
>
> That's about the same for me, except Perl never "stuck".
>
> rurpy> I tried to learn Python from the "official" docs but found it
> rurpy> impossible.
>
> I did as well, though the docs as they existed in 1993 or so (that is
> pre-Lutz, pre-Beasley).
>
>
> rurpy> I bought Beasley's book (I think this may have predated
> rurpy> Martelli's book but I don't remember) which I thought quite good
> rurpy> and which I still turn to before the Python docs in most cases.
>
> Like other free software, you can choose to figure things out yourself (use
> the source Luke) or pay someone to help you out.  I'm not using this as an
> excuse for poor Python docs.
>
> rurpy> That's a very good list and I will save a copy, thanks.  But what
> rurpy> does it have to do with Python's documentation?
>
> I'm sure you could find similar lists for Perl, C, Ruby, Tcl, Java, C++, C#,
> etc.  Does that mean their documentation stinks?  Maybe.  Maybe not.  It
> just means a lot of people have somewhat different ways of tackling the same
> problem.
>
> Skip

Skip: good points

orig qvetcher: Well, I won't have time til, maybe early 2007 to debate
the meaning of "free software","official docs", is buying K&R buying a
book?  In the meantime, use the resources, Luke (i think i've been on
usenet too long... signing out)

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[A.M. Kuchling]

On Mon, 05 Dec 2005 20:56:50 GMT, 
Bengt Richter <[EMAIL PROTECTED]> wrote:
> A little more effort could present the referrer page with clickable
> paragraphs and other elements, to zoom in to what the commenter
> wants to comment on. And an automatic diff could be prepared for
> editors, and the submitted info could go in a structured file for
> automated secure web access by editors to ease review and presumably
> sometimes pretty automatic docs update. Adherence to submission
> guidelines could be enforced somewhat by form checks etc.

"A *little* more effort"?  This is obviously some strange new
definition of "little".  I'd love to see such a system, but it would
be a significant effort to build such a system, and the Python
developers do not have the spare manpower to do it.  It would be a
great volunteer project for someone to undertake, but I don't think
Fred Drake or anyone else has the spare CPU cycles to work on it.

--amk
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[A.M. Kuchling]

On Tue, 6 Dec 2005 00:05:38 -0500, 
François Pinard <[EMAIL PROTECTED]> wrote:
> It's a relatively recent phenomenon that maintainers go berzerk, foaming 
> at the mouth over forms, borders, colors, and various other mania!  :-)

It's largely to ensure that the ideas aren't lost.  E-mail sits around
in an inbox until it gets deliberately deleted or gets lost in a disk
crash or system upgrade gone wrong.  Usenet posts fall out of the news
spool and get buried in Google's archives.

For example, here are the oldest messages in my mailbox:

   1 Mar 24 Whitesell, Ken  (3.5K) [PyCON-Organizers] Feedback from a first-
   2 Mar 28 Martin Maney(1.4K) Improving "The Python DB-API interface"
   3   T Mar 28 MW Mike Weiner  (1.0K) RE: [Pycon2005-attendees] Found items
   4   + Mar 28 Mark Wittner(0.8K)  *¬>
   5   + Mar 29 Anna Ravenscrof (0.9K)   >
   6  s+ Mar 28 David Goodger   (1.4K) Re: Q. about Emacs on MacOS
   7   + Apr 04 Neal Norwitz(250K) Re: PyCon treasury question
   8 Apr 28 Thorsten Leemhu (0.7K) python-crypto RIPEMD160 and SHA256 not 64
   9   + May 01 nemir nemiria   (0.4K) regular expression how-to suggestion.
  10 May 07 Brian Hook  (0.3K) pycrypto
  11 May 23 John Lambert (W (3.7K) python howto: regular expressions - issue
  12   T Jun 01 Tim Parkin  (2.5K) pydotorg redesign
  13   T Jun 02 Neal Norwitz(2.3K) Re: [Python-Dev] Vestigial code in thread
  14   + Jun 09 Jacob Rus   (0.5K) python regular expression howto
  15 Jun 17 Zed Lopez   (0.5K) [pct] decrypting a ciphertext with an RSA
  16 Jun 21 Skip Montanaro  (1.3K) Re: [Pydotorg] Python Homepage: possible
  17 Jun 27 Osvaldo Santana (0.7K) [marketing-python] Python Powered in Core
  18   + Jul 09 Martin Kirst(0.3K) pycrypto pre build binaries for windows,
  19 Jul 10 Jeff Rush   (0.9K) [PyCON-Organizers] Two Good Developments
  20 Jul 13 [EMAIL PROTECTED]  (2.5K) Re: [Quixote-users] Quixote 2 Docs
  21   T Jul 15 Nick Jacobson   (0.4K) py3k

#2 from Martin Maney is a suggestion about a web page I have on the DB-API.  
#8 is a pycrypto bug report; I think the bug is fixed now, but would have 
to check.
#9 and #11 are suggestions for the regex HOWTO.
#10, #15, #18 could be suggestions, bug reports, or questions; hope
they're not questions or bugs, because the chance of them being
answered is zero at this point.

You may suggest that I should process my e-mail more promptly.  True,
but that's very hard; there's always newer e-mail coming in.  Do less?
I'd love to, but that doesn't seem to be a viable option.

I could just delete all this mail, but I still have the hope of
someday doing a rewrite pass on, say, the regex howto, going through
all the suggestions and making some changes accordingly.  I am,
however, drifting toward the Linus Torvalds approach of mail handling:
delete messages after six months.  If the message was important,
they'll resend it.  A pity that it means Martin's suggestions, and
Thorsten's bug, and Nemir's suggestion, get discarded.

This is why things need to go into public trackers, or wiki pages.
There, at least their content is available to someone else; if
someday, someone else does a new regex howto, they could use the
suggestions and patches that have accumulated over time.  

--amk
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[François Pinard]

[A.M. Kuchling]
>On Tue, 6 Dec 2005 00:05:38 -0500, 
>   François Pinard <[EMAIL PROTECTED]> wrote:

>> It's a relatively recent phenomenon that maintainers go berzerk, foaming 
>> at the mouth over forms, borders, colors, and various other mania!  :-)

> It's largely to ensure that the ideas aren't lost.  E-mail sits around
> in an inbox until it gets deliberately deleted or gets lost in a disk
> crash or system upgrade gone wrong.

Or sorted properly by the recipient, the way he sees best fit, in the 
tracker of his own choice.

I know I'm repeating myself, but my point just does not seem to get 
through.  The maintainer should manage his way as a grown up, instead of 
expecting the world to learn his ways and manage in his place.

> You may suggest that I should process my e-mail more promptly.

No, I'm not suggesting you how to work, no more that I would accept that 
you force me into working your way.  If any of us wants to force the 
other to speak through robots, that one is not far from unspeakable...

> If the message was important, they'll resend it.

This is despising contributions.  If someone sends me a message which 
I find important, I do take means so that message does not get lost, and 
that it will even suvive me for some while.

> This is why things need to go into public trackers, or wiki pages.

Whatever means the maintainer wants to fill his preservation needs, he 
is free to use them.  The problem arises when the maintainer wants 
imposing his own work methods on others.  Let contributors be merely
contributors, and learn how to recognise contributions as such and say 
thank you, instead of trying to turn contributors into maintainers.

-- 
François Pinard   http://pinard.progiciels-bpi.ca
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Paul Rubin]

François Pinard <[EMAIL PROTECTED]> writes:
> > You may suggest that I should process my e-mail more promptly.
> 
> No, I'm not suggesting you how to work, no more that I would accept
> that you force me into working your way.  If any of us wants to force
> the other to speak through robots, that one is not far from
> unspeakable...

In the old days, it was possible to post stuff to Python's sourceforge
pages without logging in.  That was turned off for various reasons
that weren't bogus, but that didn't strike me as overwhelmingly
compelling.  Maybe that could be revisited, at least for the category
of documentation bugs and patches.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Steve Holden]

François Pinard wrote:
> [A.M. Kuchling]
> 
>>On Tue, 6 Dec 2005 00:05:38 -0500, 
>>  François Pinard <[EMAIL PROTECTED]> wrote:
> 
> 
>>>It's a relatively recent phenomenon that maintainers go berzerk, foaming 
>>>at the mouth over forms, borders, colors, and various other mania!  :-)
> 
> 
>>It's largely to ensure that the ideas aren't lost.  E-mail sits around
>>in an inbox until it gets deliberately deleted or gets lost in a disk
>>crash or system upgrade gone wrong.
> 
> 
> Or sorted properly by the recipient, the way he sees best fit, in the 
> tracker of his own choice.
> 
> I know I'm repeating myself, but my point just does not seem to get 
> through.  The maintainer should manage his way as a grown up, instead of 
> expecting the world to learn his ways and manage in his place.
> 
> 
>>You may suggest that I should process my e-mail more promptly.
> 
> 
> No, I'm not suggesting you how to work, no more that I would accept that 
> you force me into working your way.  If any of us wants to force the 
> other to speak through robots, that one is not far from unspeakable...
> 
> 
>>If the message was important, they'll resend it.
> 
> 
> This is despising contributions.  If someone sends me a message which 
> I find important, I do take means so that message does not get lost, and 
> that it will even suvive me for some while.
> 
> 
>>This is why things need to go into public trackers, or wiki pages.
> 
> 
> Whatever means the maintainer wants to fill his preservation needs, he 
> is free to use them.  The problem arises when the maintainer wants 
> imposing his own work methods on others.  Let contributors be merely
> contributors, and learn how to recognise contributions as such and say 
> thank you, instead of trying to turn contributors into maintainers.
> 
François, you talk of "the maintainer" as though each piece of code is 
owned by a single individual. In Python's case this is far from the truth.

So, what you say *seems* to equate to "If there's a problem with Python 
that I think should be fixed, I should be able to mail the person I 
suspect is most likely to maintain that code, and they should be obliged 
to log the bug or enhancement request in the tracking system".

There's also a philosophical question here about who is helping who. One 
might choose to believe that the contributor is assisting the developer, 
by pointing out a defect in the developer's code. One might 
alternatively regard the contributor as a supplicant, who needs the 
assistance of the developer to get a problem fixed. Finally one might 
regard the contributor (who benefits from having Python available) and 
the developer (who gets the kudos of having developed something "cool") 
to be members of a community, prepared to collaborate to achieve 
something that benefits them both.

In the real world people's opinions will have all kinds of other shades 
as well, of course, but as far as *I'm* concerned, if the developers say 
"please contribute bug reports through Sourceforge" then I am happy to 
do so to make sure they don't fall between the cracks and get lost. YMMV.

Obviously the developers are in charge here, but I really don't see how 
putting more load on them by requiring them to collectively be the only 
sources of bug input to the tracking system will help get more work out 
of them.

If you wanted to build a better tracking system than the one on 
SourceForge I could certainly support that, but historically there 
hasn't been much volunteer effort available to switch to something like 
Roundup which might be preferred.

regards
  Steve
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006  www.python.org/pycon/

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Steven D'Aprano]

On Mon, 05 Dec 2005 19:36:58 -0800, BartlebyScrivener wrote:

> Well, that might be asking a bit too much of the programmers, who
> perhaps don't exactly enjoy mucking about in the lowlands of English
> grammar and syntax.

Oh come on now! For the kinds of minds who enjoy obfuscated C or Perl,
English is just par for the course.

One of my favourite examples of obfuscated English is this grammatically
correct sentence:

"Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo."

And they say English is a hard language to understand :-)

On the other hand, for programmers who don't like obfuscated anything,
English can be as precise and elegant as anything in Lisp or Python. Treat
English as a programming language: learn the rules of syntax and grammar,
and read examples of master writers to learn the best idioms, and you
can't go wrong.

But if you try to learn English from Usenet... *shudders*


-- 
Steven.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Fredrik Lundh]

Steven D'Aprano wrote:

> "Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo."

Did you mean: Badger badger Badger badger badger badger Badger badger Mushroom! 
Mushroom!





-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Steven D'Aprano]

On Mon, 05 Dec 2005 21:05:46 -0800, rurpy wrote:

> If one is required to buy a book to use free software, 

One is *not* required to buy a book to use free software. It isn't
compulsory.

> it is not really free, is it?

What part of "you may use this FREE software for FREE" is too difficult
for you to understand?

If you want to calculate the total cost of ownership for (say) using
Python, then by all means include the cost of labour, electricity to run
your computer, depreciation on that computer, courses to learn how to
program, etc. All these are valid costs.

But none of them are the cost of Python, which is free. It really isn't a
scam, nobody is going to come knocking at your door with a surprise bill
for using Python.



-- 
Steven.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[skip]

>> This is why things need to go into public trackers, or wiki pages.

François> Whatever means the maintainer wants to fill his preservation
François> needs, he is free to use them.  The problem arises when the
François> maintainer wants imposing his own work methods on others.

François, that's not it at all.  It's not our fault that SF doesn't support
email-based tracker interaction.  It's our fault that we chose SF, but it
was the best overall choice at the time (there were more considerations than
just bug tracking) and now we're sort of stuck with it because for a number
of reasons we've been unable to move away from it.

Here's the scenario we have to use today to collect emailed requests and put
them in SF:

* Kind user notices a problem and posts a message somewhere, maybe to c.l.py
  or to another Python-related list or by direct email to a developer.

* Someone - maybe nobody, but maybe more than one person - notices the
  request and thinks, "better add that to SF so it doesn't get lost".

* That person visits SF and submits a ticket.

Now, consider some of the problems this scheme is fraught with:

* Maybe nobody notices it at all.  It might have been buried deep in another
  thread that no Python developer happened to read in its entirety.  Bummer.
  It's been lost until the next time someone notices and posts a similar
  request.

* Maybe more than one person notices.  Bummer.  Now we have duplicates.
  Worse yet, some might have been posted as feature requests, some as bug
  reports.  It also may not be obvious that they are duplicate without
  careful checking.

* The multiple reports might contain different useful perspectives on the
  problem.  Bummer.  SF doesn't allow you to easily merge two requests.  You
  have to manually transfer the information from one to the other and close
  the one.

* Maybe the original post generates further responses in that venue that
  would have been useful to have with the original report.  Most will
  probably never find their way to the tracker.  Bummer.  They got lost.

* Maybe the original requester's email gets missed in the process (or the
  problem isn't addressed immediately and the user has discarded the
  original address because it's spammed so heavily and moved on to a new
  one) and the Python developers need more info but they can't contact the
  requester.  Bummer.  The problem isn't adequately addressed.

* Finally, instead of one person spending a couple minutes submitting a
  report, several people will have spent their volunteer time, and there's a
  good chance that the report is not any better (perhaps even worse) than if
  the original requester had simply submitted the request directly to SF.

I know, we have to take these steps occasion.  When bug reports have to be
moved from another tracker to the Python tracker some of these issues arise.
We've incorportated bug reports from the Debian bug tracker that way and
have migrated python-mode requests from the Python project to the
python-mode project (both on SF).  It can be a pain.

The Python developers are not being lazy.  I would love it if there was an
email interaction mode with the SF trackers, but there isn't.  I'll repeat
what I wrote yesterday in response to an earlier message in this thread:

I wish either a) SourceForge supported email interaction with their
trackers or b) someone would finish off the Roundup issue tracker
<http://roundup.sourceforge.net/> for python.org.  I doubt if anyone
here can do anything about the first barrier, but if you know something
about Roundup (or would like to learn about it) and would like to
contribute something non-documentational that would really have a
direct, positive impact on the Python community, send a note to
[EMAIL PROTECTED]

Skip
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Simon Brunning]

On 12/7/05, Steven D'Aprano <[EMAIL PROTECTED]> wrote:
> But none of them are the cost of Python, which is free. It really isn't a
> scam, nobody is going to come knocking at your door with a surprise bill
> for using Python.

Well, there is the PSU's "Spanish Inquisition" division. Last week
they barged into my office, quite unexpectedly, armed with cushions
and
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Jon Perez]

Tony Meyer wrote:

> This makes no sense.  If you want to complain about Python, try a  
> Perl list.  Why would a list dedicated to discussion about/help with  
> a language need complaints about the language?

Huh?!?  Usually people complain because they need help or feel
that things can be improved.

> You might want to consider the difference between complaining and  
> constructive criticism and suggestions, and which are likely to get  
> better responses.

In the case of programming languages, I don't see any real difference
between something being a 'constructive criticism' and a 'complaint'.

Why, oh why, do so many programmers insist on elevating software tools
they are using to the status of a *religion* such that they feel personally
offended when someone badmouths the language or tool they are using???

Anyone can badmouth Python and things associated with all they want, the
only time it would even begin to bother me is only if these were false
accusations or there is a dishonest agenda behind it.

If the complaints are untrue, then I'd just be laughing at others'
ignorance, not be offended by it.  If it is an honest complaint
arising out of personal experience with the language, then certainly
there is a need to examine what can be improved.

I generally don't see any need to feel uncomfortable with strident
whining against Python because the only thing being attacked here is a
software tool, not persons.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Christopher Subich]

Fredrik Lundh wrote:
> Steven D'Aprano wrote:
> 
> 
>>"Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo."
> 
> 
> Did you mean: Badger badger Badger badger badger badger Badger badger 
> Mushroom! Mushroom!

Thank you, I really needed that stuck in my head. :)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Grant Edwards]

On 2005-12-07, Steven D'Aprano <[EMAIL PROTECTED]> wrote:
> On Mon, 05 Dec 2005 19:36:58 -0800, BartlebyScrivener wrote:
>
>> Well, that might be asking a bit too much of the programmers, who
>> perhaps don't exactly enjoy mucking about in the lowlands of English
>> grammar and syntax.
>
> Oh come on now! For the kinds of minds who enjoy obfuscated C or Perl,
> English is just par for the course.
>
> One of my favourite examples of obfuscated English is this grammatically
> correct sentence:
>
> "Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo."

Why the goofy-looking capitalization?  Are the 2nd and 3rd
occurances of "Buffalo" referring to the city?

-- 
Grant Edwards   grante Yow!  All of life is a blur
  at   of Republicans and meat!
   visi.com
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Alex Martelli]

Steven D'Aprano <[EMAIL PROTECTED]> wrote:

> On Mon, 05 Dec 2005 19:36:58 -0800, BartlebyScrivener wrote:
> 
> > Well, that might be asking a bit too much of the programmers, who
> > perhaps don't exactly enjoy mucking about in the lowlands of English
> > grammar and syntax.
> 
> Oh come on now! For the kinds of minds who enjoy obfuscated C or Perl,
> English is just par for the course.

As it happens, there appears to be pretty weak correlation between
proficiency in programming and proficiency in writing -- SOME excellent
programmers are great writers too, but, I would guess, just roughly the
same percentage as in the general popularion (i.e., deucedly few).


Alex
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Jon Perez]

[EMAIL PROTECTED] wrote:

> FWIW I find Python's docs to be OK at best, with some horrible
> parts, and a lot of mediochre to poor parts.

I myself have no big beef about Python's docs, but you're certainly
not the first one to complain about them.  Xah Lee rants very
heavily against the quality against Python's docs and considers
many sections of it as written in a manner more to show-off one's
knowledge of jargon rather than to explain things properly.

I don't really notice that but this could be because I'm already
quite comfortable with jargon at the level it is used in the
Python docs (or maybe I'm one of those highfalutin' chaps as well
;-D).  Seriously though, sometimes jargon is necessary in order to
put across a point concisely and accurately so its use cannot always
be considered gratuitous.

The only problem I have with Python docs is that for most of
the the standard library API documentation, the function calls
are not organized very well (i.e. I don't believe they are
alphabetized or ordered in any intutive manner).

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Steven D'Aprano]

On Wed, 07 Dec 2005 07:50:14 -0800, Alex Martelli wrote:

> Steven D'Aprano <[EMAIL PROTECTED]> wrote:
> 
>> On Mon, 05 Dec 2005 19:36:58 -0800, BartlebyScrivener wrote:
>> 
>> > Well, that might be asking a bit too much of the programmers, who
>> > perhaps don't exactly enjoy mucking about in the lowlands of English
>> > grammar and syntax.
>> 
>> Oh come on now! For the kinds of minds who enjoy obfuscated C or Perl,
>> English is just par for the course.
> 
> As it happens, there appears to be pretty weak correlation between
> proficiency in programming and proficiency in writing -- SOME excellent
> programmers are great writers too, but, I would guess, just roughly the
> same percentage as in the general popularion (i.e., deucedly few).


If you know any links to real research on this, I'd love to learn more.
I'm always amazed and perplexed at how hot-shot programmers who would
never forget a colon or a brace can be so slap-dash about using proper
punctuation and grammar in English.


-- 
Steven.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Steven D'Aprano]

On Wed, 07 Dec 2005 15:29:07 +, Grant Edwards wrote:

> On 2005-12-07, Steven D'Aprano <[EMAIL PROTECTED]> wrote:
>> On Mon, 05 Dec 2005 19:36:58 -0800, BartlebyScrivener wrote:
>>
>>> Well, that might be asking a bit too much of the programmers, who
>>> perhaps don't exactly enjoy mucking about in the lowlands of English
>>> grammar and syntax.
>>
>> Oh come on now! For the kinds of minds who enjoy obfuscated C or Perl,
>> English is just par for the course.
>>
>> One of my favourite examples of obfuscated English is this grammatically
>> correct sentence:
>>
>> "Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo."
> 
> Why the goofy-looking capitalization?  Are the 2nd and 3rd
> occurances of "Buffalo" referring to the city?

The punctuation is important. Yes, they refer to the city.

(Which reminds me of the old joke about capitalisation being the
difference between "I helped my Uncle Jack off a horse" and "I helped my
Uncle jack off a horse".)

For those who don't know, "buffalo" is also a verb meaning to overwhelm
or intimidate.



S
P
O
I
L
E
R
 
S
P
A
C
E



"Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo."

Buffalo from the city of Buffalo, which are intimidated by buffalo
from Buffalo, also intimidate buffalo from Buffalo.


I didn't say it was *good* English, but it is *legal* English.



-- 
Steven.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Steven D'Aprano]

On Wed, 07 Dec 2005 11:45:04 +0100, Fredrik Lundh wrote:

> Steven D'Aprano wrote:
> 
>> "Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo."
> 
> Did you mean: Badger badger Badger badger badger badger Badger badger 
> Mushroom! Mushroom!

Er... no, I can't parse that. I suffered a Too Much Recursion error about
the third Badger (I only have a limited runtime stack).

I asked my missus about this one, she being much better at English grammar
than I am, and she thinks the badger/mushroom sentence is a wind-up. Is
she right?


-- 
Steven.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Christopher Subich]

Steven D'Aprano wrote:

> S
> P
> O
> I
> L
> E
> R
>  
> S
> P
> A
> C
> E
> 
> 
> 
> "Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo."
> 
> Buffalo from the city of Buffalo, which are intimidated by buffalo
> from Buffalo, also intimidate buffalo from Buffalo.

And to do a small simplification on it, to illustrate just how painful 
that sentence really is, the semantically equivalent version:

N = buffalo from Buffalo

(N [that] N buffalo) buffalo N.

The dropping of the [that] is legal, if sometimes ambiguous, in English.

> I didn't say it was *good* English, but it is *legal* English.

Which is why natural language programming's never going to take off. :)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Fredrik Lundh]

Steven D'Aprano wrote:

> S
> P
> O
> I
> L
> E
> R
>
> S
> P
> A
> C
> E
>
>
>
> Buffalo from the city of Buffalo, which are intimidated by buffalo
> from Buffalo, also intimidate buffalo from Buffalo.

Did you mean:  Bagder from the city of Badger, who is pestered by
a badger from Badger, also pesters badger from Badger.  Mushroom
expands rapidly!

(Argh! Snake!)





-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Christopher Subich]

Steven D'Aprano wrote:
> On Wed, 07 Dec 2005 11:45:04 +0100, Fredrik Lundh wrote:
> 
>>Did you mean: Badger badger Badger badger badger badger Badger badger 
>>Mushroom! Mushroom!
> 
> 
> Er... no, I can't parse that. I suffered a Too Much Recursion error about
> the third Badger (I only have a limited runtime stack).

http://www.badgerbadgerbadger.com/

And now back to your regularly scheduled newsgroup, already in progress.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Fredrik Lundh]

Steven D'Aprano wrote:

> > Did you mean: Badger badger Badger badger badger badger Badger badger 
> > Mushroom! Mushroom!
>
> Er... no, I can't parse that. I suffered a Too Much Recursion error about
> the third Badger (I only have a limited runtime stack).
>
> I asked my missus about this one, she being much better at English grammar
> than I am, and she thinks the badger/mushroom sentence is a wind-up. Is
> she right?

http://www.badgerbadgerbadger.com/ (make sure your speakers are on)





-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[skip]

Steven> I'm always amazed and perplexed at how hot-shot programmers who
Steven> would never forget a colon or a brace can be so slap-dash about
Steven> using proper punctuation and grammar in English.

That's because there's no equivalent to a compiler or interpreter preventing
them from speaking or writing.

Skip
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Rocco Moretti]

>>>One of my favourite examples of obfuscated English is this grammatically
>>>correct sentence:
>>>
>>>"Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo."
> 
> The punctuation is important. 

Reminds me of this old classic:

Insert punctuation & capitalization to make the following a correct and 
coherent (if not a little tourtured).

fred where guido had had had had had had had had had had had a better 
effect on the reader
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Fredrik Lundh]

Rocco Moretti wrote:

> Insert punctuation & capitalization to make the following a correct and
> coherent (if not a little tourtured).
>
> fred where guido had had had had had had had had had had had a better
> effect on the reader

punctuation, including quote marks, I presume?

it's not time to bring out "d'ä ä e å, å i åa ä e ö" yet, I hope?





-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Aahz]

In article <[EMAIL PROTECTED]>,
Rocco Moretti  <[EMAIL PROTECTED]> wrote:
>
>Reminds me of this old classic:
>
>Insert punctuation & capitalization to make the following a correct and 
>coherent (if not a little tourtured).
>
>fred where guido had had had had had had had had had had had a better 
>effect on the reader

"I'd like to thank my parents, Ayn Rand and God."
-- 
Aahz ([EMAIL PROTECTED])   <*> http://www.pythoncraft.com/

"Don't listen to schmucks on USENET when making legal decisions.  Hire
yourself a competent schmuck."  --USENET schmuck (aka Robert Kern)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Michael Spencer]

Fredrik Lundh wrote:
> Rocco Moretti wrote:
> 
>> Insert punctuation & capitalization to make the following a correct and
>> coherent (if not a little tourtured).
>>
>> fred where guido had had had had had had had had had had had a better
>> effect on the reader
> 
> punctuation, including quote marks, I presume?
> 
> it's not time to bring out "d'ä ä e å, å i åa ä e ö" yet, I hope?
> 
> 
> 
> 
> 
Allowing quotation, almost anything is possible, e.g.,


Fred! Where Guido had had "had", Had had had "had had".  "Had had" had a better 
effect on the reader

or simply

"fred", where Guido had "had had had had had had had had had", had a better
effect on the reader

M

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Mike Meyer]

"Fredrik Lundh" <[EMAIL PROTECTED]> writes:
>> Er... no, I can't parse that. I suffered a Too Much Recursion error about
>> the third Badger (I only have a limited runtime stack).

I always loved the demonstration that English requires backtracking:
"The old man the ship."

   http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Steven D'Aprano]

On Wed, 07 Dec 2005 17:15:03 -0500, Mike Meyer wrote:

> "Fredrik Lundh" <[EMAIL PROTECTED]> writes:
>>> Er... no, I can't parse that. I suffered a Too Much Recursion error about
>>> the third Badger (I only have a limited runtime stack).
> 
> I always loved the demonstration that English requires backtracking:
> "The old man the ship."

Linguists call that "garden path sentences", because they lead the
reader/listener up the garden path.

Here are some more examples:

The horse raced past the barn fell.

The man who hunts ducks out on weekends.

The cotton clothing is usually made of grows in Mississippi.

The prime number few.

Fat people eat accumulates.

The tycoon sold the offshore oil tracts for a lot of money wanted to kill
JR.



-- 
Steven.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Dan Sommers]

On Thu, 08 Dec 2005 12:19:13 +1100,
Steven D'Aprano <[EMAIL PROTECTED]> wrote:

> Linguists call that "garden path sentences", because they lead the
> reader/listener up the garden path.

> Here are some more examples:

[ examples snipped ]

And the ever-popular, ever-ambiguous:

Women can fish.

Regards,
Dan

-- 
Dan Sommers

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Steve Holden]

Michael Spencer wrote:
[...]
> Allowing quotation, almost anything is possible, e.g.,
> 
> 
> Fred! Where Guido had had "had", Had had had "had had".  "Had had" had a 
> better 
> effect on the reader
> 
> or simply
> 
> "fred", where Guido had "had had had had had had had had had", had a better
> effect on the reader
> 
> M
> 
All this remind me about the Member of Parliament who was required to 
apologise for calling one of his opposite numbers a liar. He did so by 
reading out the statement

"I called the Honorable member a liar it is true and I am sorry for it", 
adding that the Honorable member could insert the punctuation wherever 
he so chose.

regards
  Steve
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006  www.python.org/pycon/

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Rocco Moretti]

Fredrik Lundh wrote:
> Rocco Moretti wrote:
> 
> 
>>Insert punctuation & capitalization to make the following a correct and
>>coherent (if not a little tourtured).
>>
>>fred where guido had had had had had had had had had had had a better
>>effect on the reader
> 
> 
> punctuation, including quote marks, I presume?

Quote marks are acceptable, but no more than two words are inside each set.


B
A
D
G
E
R

.
.
.

E
R


S
P
O
I
L
E
R

W
A
R
N
I
N
G

The "accepted" way to do it is:

Fred, where Guido had had "had", had had "had had." "Had had" had had a 
better effect on the reader.

meaning approximately

In the place where Guido previously put the word "had", Fred had 
previously put the phrase "had had." Fred's choice of phrasing was more 
appreciated by the reder.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Dave Hansen]

On Wed, 07 Dec 2005 12:33:07 -0600 in comp.lang.python, Rocco Moretti
<[EMAIL PROTECTED]> wrote:

[...]

>fred where guido had had had had had had had had had had had a better 
>effect on the reader

I've seen this before as

bill had had had but will had had had had had had or had had been
correct had had had

Regards,
-=Dave

-- 
Change is inevitable, progress is not.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Sion Arrowsmith]

Steven D'Aprano  <[EMAIL PROTECTED]> wrote:
>>> "Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo."
>
>S
>P
>O
>I
>L
>E
>R
> 
>S
>P
>A
>C
>E
>


(Good grief, I've not done that in *years*.)

>Buffalo from the city of Buffalo, which are intimidated by buffalo
>from Buffalo, also intimidate buffalo from Buffalo.
>
>I didn't say it was *good* English, but it is *legal* English.

I *think* that's similar to the one I know about the cannibalistic
behaviour of some oysters, which split open other oysters (to eat
them). It starts:

"Oysters oysters split split."

Oysters which oysters split become split.

But there's nothing to stop a third set of oysters predating on the
ones doing the splitting:

"Oysters oysters oysters split split split."

And so on. My brain hurts too much to work out if you can do the
same to the buffaloes.

And here endeth today's lesson in recursion.

-- 
\S -- [EMAIL PROTECTED] -- http://www.chaos.org.uk/~sion/
  ___  |  "Frankly I have no feelings towards penguins one way or the other"
  \X/  |-- Arthur C. Clarke
   her nu becomeþ se bera eadward ofdun hlæddre heafdes bæce bump bump bump
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[Neil Schemenauer]

François Pinard <[EMAIL PROTECTED]> wrote:
>[AMK]
>> You may suggest that I should process my e-mail more promptly.
>
> No, I'm not suggesting you how to work, no more that I would accept that 
> you force me into working your way.  If any of us wants to force the 
> other to speak through robots, that one is not far from unspeakable...
>
>> This is why things need to go into public trackers, or wiki pages.
>
> Whatever means the maintainer wants to fill his preservation needs, he 
> is free to use them.  The problem arises when the maintainer wants 
> imposing his own work methods on others.  Let contributors be merely
> contributors, and learn how to recognise contributions as such and say 
> thank you, instead of trying to turn contributors into maintainers.

Either I don't understand what you are saying or you are being a
hypocrite.  Andrew is saying that he doesn't have time to detail
with all the messages that get sent to him personally.  What do you
propose he should do?  I think people expect more that a message
saying "Thanks for you contribution.  PS: Since I don't have time to
do anything with it, your message will now be discarded.".

  Neil
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[BartlebyScrivener]

The actress Margaret Anglin left this note in the dressing froom of
another actress:

'Margaret Anglin says Mrs. Fiske is the best actress in America.'

Mrs. Fiske added two commas and returned the note: 'Margaret Anglin,
says Mrs. Fiske, is the best actress in America.'

Or this, from a George Will column:

Huge doctrinal consequences flow from the placing of a comma in what
Jesus, when on the cross, said to the thief (Luke 23:43): 'Verily, I
say unto thee, This day thou shalt be with me in Paradise' or 'Verily,
I say unto thee this day, Thou shalt be with me in Paradise.' The
former leaves little room for purgatory.

-- 
http://mail.python.org/mailman/listinfo/python-list

Question about the 'code' module

[Thomas Heller]

I'm using the code module to implement an interactive interpreter
console in a GUI application, the interpreter running in a separate
thread.  To provide clean shutdown of the application, I have to make
sure that objects used in the interpreter thread are deleted when the
thread ends.

I delete the sys.last_type, sys.last_value, and sys.last_traceback
attributes which are set when an exception occured in the interpreter
thread (*).  To clean up the '_' symbol that the interpreter maintains,
I have found no other solution than to execute 'console.runsource("0")'
at the end of the thread.  Where is this symbol stored? How can I delete
it without the .runsource() call?

(*) It seems to me that the code modules usage of the sys.last_type,
sys.last_value, and sys.last_traceback attributes is not thread safe.
The docs mention that this doesn't matter because there's only one
interactive thread - which does not need to be true when using the code
module.  You could easily run several interactive interpreters at the
same time, which is exactly the purpose of this module.

Why is the (non thread-safe) sys.last_traceback used at all?  Couldn't
it be replaced with the (thread-safe) sys.exc_info()[2]?

Thomas
-- 
http://mail.python.org/mailman/listinfo/python-list

Questions about the event loop

[egbert]

What does a gui_event_loop know ?

My gui is based on pygtk, 
but i suppose the mechanism is the same everywhere.

The gui is created within a class-instance within a function.
Normally, ie without a gui, everything that happens within
a function is forgotten as soon the function ends.

But in a gui_event_loop the callback-method within the function
can be called, and this callbacks calls another function
also within the same first function.
And that function already stopped.

Maybe somebody can explain what is going on, or where I can find
further explanations.

The structure of my gui script is as follows:
import gtk
def func():
def callback_helper():
...
class Klas(object):
def __init__(self):
...
# create gui with self.callback()
...
def callback(self, widget):
callback_helper()
...
klas = Klas()

func()
gtk.main()

egbert
-- 
Egbert Bouwman - Keizersgracht 197 II - 1016 DS  Amsterdam - 020 6257991

-- 
http://mail.python.org/mailman/listinfo/python-list