Social problems of Python doc [was Re: Python docs disappointing]
xahlee at gmail.com
Mon Aug 17 05:00:23 CEST 2009
I've been out of python community for a couple of years. I've saved
your messages and will study it later when next time i work in python.
Possibly today and will reply in some of your points.
But just wanted to say thanks for improving python.
Also, sometimes ago out of the blue i noticed someone has posted a bug
on python's gzip doc with acknowledgement. http://bugs.python.org/issue2406
Thank you M.-A. DARCHE (madarche).
Also, i noticed python doc now and later has improved a lot since last
i looked around python 2.4. For one thing, the html/xhtml is now valid
html. Good riddence of the fucking TeX. Also, code examples have
syntax coloring on.
On Aug 12, 12:15 pm, Raymond Hettinger <pyt... at rcn.com> wrote:
> [Xah Lee]
> > i've wrote several articles about this issue, total time spend on this
> > is probably more than 2 months full-time work. See:
> > • Python Documentation Problems
> > http://xahlee.org/perl-python/python_doc_index.html
> I just read you post. You did devote a substantial amount of time
> to the project. Some of your criticisms are valid. Wish you had
> posted patches, I think many of them would have been accepted.
> Since you wrote this a few years ago, many examples have
> been added to the docs and more are forthcoming.
> > I often receive thank you emails for 2 particular articles, which are
> > most frequently google searched as indicated by my weblog:
> > • Python Doc Problem Example: gzip
> > http://xahlee.org/perl-python/python_doc_gzip.html
> > • Python Doc Problem Example: sort()
> > http://xahlee.org/perl-python/python_doc_sort.html
> > • Sorting in Python and Perl
> > http://xahlee.org/perl-python/sort_list.html
> Some are the criticisms are valid; others seem off-base.
> Here are a few thoughts on list.sort() for those who are interested:
> * The key= and reversed= parameters are not intended for special
> cases, leaving cmp= for the general case. They were intended to
> be full replacements. In Python3.x, the cmp function is gone.
> * The interaction of the key= and cmp= functions can be made to
> interact (the key function is first applied to every element and
> the cmp function then gets applied to the results of the key
> function). This isn't a normal or intended use case, so the docs
> don't delve into the subject.
> * The reversed parameter does more than list.sort() followed by
> list.reverse(). It also preserves stability in the event of equal
> >>> sorted([(1,2), (1,3)], key=itemgetter(0), reverse=True)
> [(1,2), (1,3)]
> So it was not correct to say that the following are equivalent:
> li.sort(lambda x, y: cmp(x,y), reverse=True)
> li.sort(lambda x, y: cmp(y,x))
> * We should link the sorted() and list.sort() docs to the
> sorting how-to (with a fuller discussion on the art of sorting
> including a discussion of operator.itemgetter() and
> operator.attrgetter() which were designed to work with the key=
More information about the Python-list