In article <[EMAIL PROTECTED]>, [EMAIL PROTECTED] (Alex Martelli) wrote:
>Russell E. Owen <[EMAIL PROTECTED]> wrote: > >> In article <[EMAIL PROTECTED]>, >> [EMAIL PROTECTED] (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 -- http://mail.python.org/mailman/listinfo/python-list
