Documentation suggestions

[Michael Spencer]

A.M. Kuchling wrote:
> On Tue, 06 Dec 2005 10:29:33 -0800, 
> 	Michael Spencer <mahs at telcopartners.com> wrote:
>> not that helpful.  "Miscellaneous Services", in particular, gives no clue to 
>> treasures it contains.  I would prefer, for example, to see the data 
>> structure modules: collections, heapq, array etc... given their own section. 
>> Documentation/testing, cmd/options might be other candidates to draw together
>> currently related material more meaningfully.
> 
> You're right; "Miscellaneous Services" is a grab-bag of stuff, and so
> are 'Generic OS Services' and 'Optional OS Services'.  These chapters
> should be rearranged into more, smaller chapters.  
> 
> A patch for a draft reorganization is at http://www.python.org/sf/1375417
> 
> --amk
Thanks!  That looks like a good start.

I experimented with some more re-organization, but I don't see away to attach 
the resulting file in the SF comments, so I'll post it here instead.

Michael



% experimental re-organization of lib.tex,
% from http://www.python.org/sf/1375417

\tableofcontents

                                 % Chapter title:

\input{libintro}                % Introduction


% =============
% BUILT-INs
% =============

\input{libobjs}                 % Built-in Types, Exceptions and Functions
\input{libfuncs}
\input{libstdtypes}
\input{libexcs}
\input{libconsts}



% =============
% BASIC/GENERAL-PURPOSE OBJECTS
% =============

% General object services
\input{libtypes}
\input{libnew}
\input{libweakref}
\input{libcopy}
\input{libpprint}
\input{librepr}

% Strings
\input{libstrings}              % String Services
\input{libstring}
\input{libre}
\input{libreconvert}
\input{libstruct}   % also/better in File Formats?
\input{libdifflib}
\input{libfpformat}
\input{libstringio}
\input{libtextwrap}
\input{libcodecs}
\input{libunicodedata}
\input{libstringprep}

% Data types and structures
%\input{libdata}			% Data types and structures
\input{libdatetime}
\input{libcalendar}
\input{libcollections}
\input{libheapq}
\input{libarray}
\input{libsets}
\input{libsched}
\input{libmutex}
\input{libqueue}
\input{libuserdict}   % From runtime.  What happened to UserList and UserString?

% Numeric/Mathematical modules
\input{libdecimal}
\input{libmath}
\input{libcmath}
\input{librandom}
\input{libbisect} % is this needed here - more useful in Data types, like heapq?

% Functions, Functional, Generators and Iterators
\input{libitertools}
\input{libfunctional}
\input{liboperator}       % from runtime - better with itertools and functional


%\input{libmisc}                 % Miscellaneous Services


% =============
% DATA FORMATS
% =============

%                                % File formats
\input{libcfgparser}
\input{libnetrc}
\input{librobotparser}
\input{libcsv}
\input{libstruct}   % and in string?

% Big move - include all the markup and internet formats here

% MIME & email stuff
\input{email}
\input{libmailcap}
\input{libmailbox}
\input{libmhlib}
\input{libmimetools}
\input{libmimetypes}
\input{libmimewriter}
\input{libmimify}
\input{libmultifile}
\input{librfc822}

% encoding stuff
\input{libbase64}
\input{libbinascii}
\input{libbinhex}
\input{libquopri}
\input{libuu}
\input{libxdrlib}

\input{markup}                  % Structured Markup Processing Tools
\input{libhtmlparser}
\input{libsgmllib}
\input{libhtmllib}
\input{libpyexpat}
\input{xmldom}
\input{xmldomminidom}
\input{xmldompulldom}
\input{xmlsax}
\input{xmlsaxhandler}
\input{xmlsaxutils}
\input{xmlsaxreader}
% \input{libxmllib}

\input{libcrypto}               % Cryptographic Services
\input{libhmac}
\input{libhashlib}
\input{libmd5}
\input{libsha}

% =============
% FILE & DATABASE STORAGE
% =============

\input{liballos}                % File-system services (XXX change header)
\input{libos}
\input{libposixpath}            % os.path
\input{libfileinput}
\input{libstat}
\input{libstatvfs}
\input{libfilecmp}
\input{libtempfile}
\input{libglob}
\input{libfnmatch}
\input{liblinecache}
\input{libshutil}
\input{libdircache}

%                                % Data compression and archiving
\input{libzlib}
\input{libgzip}
\input{libbz2}
\input{libzipfile}
\input{libtarfile}

%\input{libpersistence}          % Persistent storage
\input{libpickle}
\input{libcopyreg}              % really copy_reg % from runtime...
\input{libshelve}
\input{libmarshal}
\input{libanydbm}
\input{libwhichdb}
\input{libdbm}
\input{libgdbm}
\input{libdbhash}
\input{libbsddb}
\input{libdumbdbm}


% =============
% OS
% =============


\input{liballos}                % Generic Operating System Services
\input{libtime}
\input{libgetpass}
\input{libcurses}
\input{libascii}                % curses.ascii
\input{libcursespanel}
\input{libplatform}
\input{liberrno}

%				 % Interprocess communication/networking
\input{libsubprocess}
\input{libsocket}
\input{libsignal}
\input{libpopen2}
\input{libasyncore}
\input{libasynchat}

\input{libsomeos}               % Optional Operating System Services
\input{libselect}
\input{libthread}
\input{libthreading}
\input{libdummythread}
\input{libdummythreading}
\input{libmmap}
\input{libreadline}
\input{librlcompleter}

\input{libunix}                 % UNIX Specific Services
\input{libposix}
\input{libpwd}
\input{libspwd}
\input{libgrp}
\input{libcrypt}
\input{libdl}
\input{libtermios}
\input{libtty}
\input{libpty}
\input{libfcntl}
\input{libpipes}
\input{libposixfile}
\input{libresource}
\input{libnis}
\input{libsyslog}
\input{libcommands}


% =============
% NETWORK & COMMUNICATIONS
% =============

\input{internet}                % Internet Protocols
\input{libwebbrowser}
\input{libcgi}
\input{libcgitb}
\input{liburllib}
\input{liburllib2}
\input{libhttplib}
\input{libftplib}
\input{libgopherlib}
\input{libpoplib}
\input{libimaplib}
\input{libnntplib}
\input{libsmtplib}
\input{libsmtpd}
\input{libtelnetlib}
\input{liburlparse}
\input{libsocksvr}
\input{libbasehttp}
\input{libsimplehttp}
\input{libcgihttp}
\input{libcookielib}
\input{libcookie}
\input{libxmlrpclib}
\input{libsimplexmlrpc}
\input{libdocxmlrpc}

\input{netdata}                 % Internet Data Handling
\input{libformatter}

% =============
% MULTIMEDIA
% =============

\input{libmm}                   % Multimedia Services
\input{libaudioop}
\input{libimageop}
\input{libaifc}
\input{libsunau}
\input{libwave}
\input{libchunk}
\input{libcolorsys}
\input{librgbimg}
\input{libimghdr}
\input{libsndhdr}
\input{libossaudiodev}



% =============
% PROGRAM FRAMEWORKS/OPTIONS/GUI
% =============
\input{libgetopt}
\input{liboptparse}
\input{libcmd}
\input{libshlex}
\input{liblogging}
\input{tkinter}
%                                % Internationalization
\input{libgettext}


% =============
% DEVELOPMENT TOOLS
% =============
%                                % Software development support
\input{libpydoc}
\input{libdoctest}
\input{libunittest}
\input{libtest}

\input{libpdb}                  % The Python Debugger

\input{libprofile}              % The Python Profiler
\input{libhotshot}              % New profiler
\input{libtimeit}


% =============
% PYTHON ENGINE
% =============
\input{libpython}               % Python Runtime Services

% Runtime services
\input{libsys}
\input{libbltin}                % really __builtin__
\input{libmain}                 % really __main__
\input{libtraceback}
\input{libinspect}
\input{libgc}

% Custom interpreter
\input{libcode}
\input{libcodeop}
\input{librestricted}           % Restricted Execution
\input{librexec}
\input{libbastion}

% Runtime environment
\input{libfpectl}
\input{libatexit}
\input{libsite}
\input{libuser}
\input{libfuture}               % really __future__
\input{libwarnings}
\input{liblocale}      % also in Internationalization

% modules
\input{libimp}
\input{libzipimport}
\input{libpkgutil}
\input{libmodulefinder}


% =============
% PYTHON LANGUAGE & COMPILER
% =============

\input{language}                % Python Language Services
\input{libparser}
\input{libsymbol}
\input{libtoken}
\input{libkeyword}
\input{libtokenize}
\input{libtabnanny}
\input{libpyclbr}
\input{libpycompile}            % really py_compile
\input{libcompileall}
\input{libdis}
\input{libpickletools}
\input{distutils}

\input{compiler}                % compiler package


% =============
% OTHER PLATFORM-SPECIFIC STUFF
% =============

%\input{libamoeba}              % AMOEBA ONLY

%\input{libstdwin}              % STDWIN ONLY

\input{libsgi}                  % SGI IRIX ONLY
\input{libal}
\input{libcd}
\input{libfl}
\input{libfm}
\input{libgl}
\input{libimgfile}
\input{libjpeg}
%\input{libpanel}

\input{libsun}                  % SUNOS ONLY
\input{libsunaudio}

\input{windows}                 % MS Windows ONLY
\input{libmsvcrt}
\input{libwinreg}
\input{libwinsound}

\appendix
\input{libundoc}

%\chapter{Obsolete Modules}
%\input{libcmpcache}
%\input{libcmp}
%\input{libni}
%\input{libregex}
%\input{libregsub}

\chapter{Reporting Bugs}
\input{reportingbugs}

\chapter{History and License}
\input{license}