what would you like to see in a 2nd edition Nutshell?

[Russell E. Owen]

In article <1gpkxmh.1kvx6ullb2kxsN%aleaxit at yahoo.com>,
 aleaxit at yahoo.com (Alex Martelli) wrote:

>Russell E. Owen <rowen at cesmail.net> wrote:
>
>> In article <1gpjz0o.umrpws1pjdekyN%aleaxit at yahoo.com>,
>>  aleaxit at yahoo.com (Alex Martelli) wrote:
>> 
>> >I'm considering proposing to O'Reilly a 2nd edition of "Python in a
>> >Nutshell", that I'd write in 2005, essentially to cover Python 2.3 and
>> >2.4 (the current 1st edition only covers Python up to 2.2).
>> >...
>> 
>> Since you were kind enough to ask...what I'd really like is a better 
>> better index and better organization, so I can more quickly and easily
>> locate info on a particular topic.
>
>Thanks for the advice!  What I have now is the best organization I was
>able to conceive -- and I have no current ideas on how to enhance it.
>Any _suggestions_ will be truly welcome; somehow, I don't see "make it
>better" as a _suggestion_... if I _knew_ how to organize it better, I
>would, of course.

Fair enough. I was being lazy, but also wanted to be sure the input 
would be considered useful before going into details.

Here are some issues for me:

* A mini table of contents for each major section would be really 
helpful. List the modules, and (if appropriate) sub-modules with maybe a 
one-liner as to what they do, and a page #.

* The discussion of the os module (p171) could especially use such a 
TOC. p171 starts with a nice, thorough explanation of os and all it 
does, but as a quick reference it is tricky; rather than jumping right 
to what I want, I have to get past a discussion of OSError an the errno 
module before any os methods are discussed, and then I have to flip 
through many pages of stuff to find the right section.

* Please cross-reference using page #s, not just chapter #s or "covered 
later in this chapter". For instance the os module text refers one to 
"chapter 14" for a discussion of os's handling of processes. Ouch. I 
hope that modern writing tools make page # references safe and easy.

* Some of the page breaks are awkward. I know it eats paper to fix it 
everywhere, but... for example, it'd help to have the re special 
characters table all on one page (or at least on facing pages).

* Exceptions:
- I beg you to include a ONE-PAGE table of exceptions that shows the 
inheritance hierarchy via indentation (e.g. like Python Essential 
Reference). The detailed info will probably have to follow.

Such a table is a much easier way of figuring out who inherits from who, 
and I usually find such a table sufficient (and very efficient) for 
picking out which exception to use.

Having the detailed info is much appreciated, but it's a poor substitute 
for a quick reference table.

- Some discussion of which standard modules raise errors that inheriit 
directly from Exception instead of StandardError would be helpful.

- (nit-pick) The try statement, bottom of p104. The two basic forms are 
listed, but a page # for the 2nd form would help jump there.

- Exception objects, p109. Using strings as exceptions would make a nice 
footnote instead of cluttering up the main text. They've been deprecated 
for a long time.


Also, two content requests:

* please describe the new subprocess module in gory detail and move 
discussion of the older modules which it can replace to an appendix or 
the back of the same chapter or in some other way keep it from 
cluttering up the main text. (I'm sure popen, etc. still has to be 
discussed, if only for folks dealing with older code, but subprocess is 
clearly the right way to go for new code).

* Please describe numarray instead of Numeric (or both, or discuss 
numarray and list some changes from Numeric?)


I'm looking forward to the next edition!

-- Russell