what would you like to see in a 2nd edition Nutshell?
Russell E. Owen
rowen at cesmail.net
Thu Dec 30 00:51:02 CET 2004
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).
- 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!
More information about the Python-list