[Python-checkins] r70438 - python/trunk/Doc/library/functions.rst

[Georg Brandl]

Benjamin Peterson schrieb:
> 2009/3/17 Raymond Hettinger <python at rcn.com>:
>> FWIW, I think the examples need to be *very* short.
>> The functions.rst page is growing hard to read because
>> of all of the lengthy examples, caveats, warnings, and
>> saying verbosity.  We don't want to turn the main docs
>> into a tutorial.  It makes them harder to use.   If someone
>> just wants to scan what the builtin functions do, they now
>> face a very lengthy page of reading.  It's getting too fat.
> 
> I think what really needs to happen is that function.rst and
> stdtypes.rst need to split up into multiple pages. I believe Georg had
> some intentions of doing that one day. It might make a good sprint
> project.

stdtypes.rst, yes.  functions.rst is harder because there is no obvious
splitting point.  "Functions from A to M" is bad IMO.  Grouping by
categories too.

So what remains is the "hide some content and show on request" way, and
to trim down examples to what's absolutely needed to show valid usage.

I don't care so much about the printable version -- you'll use the index
there anyway to get to the right place.

Georg


-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.