[Patch #1375417] Massive rearrangement of the Library Reference.

Fred approved just checking it in; he may make further fixes.

The change shrinks the 'Generic OS' and other OS chapters, which had become
something of a dumping ground for random modules.  It differs from the
last version of the patch: 1) I've added introductions for the new chapters (still missing a few -- search for 'intro')
2) a few modules have been rearranged slightly from the version in the patch

1 files changed, 230 insertions, 136 deletions

diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 1401c40..9e4dcb5 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -12,7 +12,7 @@
                                 % .idx file
 \makemodindex                   % ... and the module index as well.
 
-
+ 
 \begin{document}
 
 \maketitle
@@ -66,129 +66,192 @@ and how to embed it in other applications.
 
 \input{libintro}                % Introduction
 
+
+% =============
+% BUILT-INs
+% =============
+
 \input{libobjs}                 % Built-in Types, Exceptions and Functions
 \input{libfuncs}
 \input{libstdtypes}
 \input{libexcs}
 \input{libconsts}
 
-\input{libpython}               % Python Runtime Services
-\input{libsys}
-\input{libgc}
-\input{libweakref}
-\input{libfpectl}
-\input{libatexit}
-\input{libtypes}
-\input{libuserdict}
-\input{liboperator}
-\input{libinspect}
-\input{libtraceback}
-\input{liblinecache}
-\input{libpickle}
-\input{libcopyreg}              % really copy_reg
-\input{libshelve}
-\input{libcopy}
-\input{libmarshal}
-\input{libwarnings}
-\input{libimp}
-\input{libzipimport}
-\input{libpkgutil}
-\input{libmodulefinder}
-\input{libcode}
-\input{libcodeop}
-\input{libpprint}
-\input{librepr}
-\input{libnew}
-\input{libsite}
-\input{libuser}
-\input{libbltin}                % really __builtin__
-\input{libmain}                 % really __main__
-\input{libfuture}               % really __future__
 
+
+% =============
+% BASIC/GENERAL-PURPOSE OBJECTS
+% =============
+
+% Strings
 \input{libstrings}              % String Services
 \input{libstring}
 \input{libre}
 \input{libreconvert}
-\input{libstruct}
+\input{libstruct}   % XXX also/better in File Formats?
 \input{libdifflib}
-\input{libfpformat}
 \input{libstringio}
 \input{libtextwrap}
 \input{libcodecs}
 \input{libunicodedata}
 \input{libstringprep}
+\input{libfpformat}
 
-\input{libmisc}                 % Miscellaneous Services
-\input{libpydoc}
-\input{libdoctest}
-\input{libunittest}
-\input{libtest}
-\input{libdecimal}
-\input{libmath}
-\input{libcmath}
-\input{librandom}
-\input{libbisect}
+
+\input{datatypes}		% Data types and structures
+\input{libdatetime}
+\input{libcalendar}
 \input{libcollections}
 \input{libheapq}
+\input{libbisect}
 \input{libarray}
 \input{libsets}
+\input{libsched}
+\input{libmutex}
+\input{libqueue}
+\input{libweakref}
+\input{libuserdict}
+
+% General object services
+% XXX intro
+\input{libtypes}
+\input{libnew}
+\input{libcopy}
+\input{libpprint}
+\input{librepr}
+
+
+\input{numeric}			% Numeric/Mathematical modules
+\input{libmath}
+\input{libcmath}
+\input{libdecimal}
+\input{librandom}
+
+% Functions, Functional, Generators and Iterators
+% XXX intro functional
 \input{libitertools}
 \input{libfunctional}
+\input{liboperator}       % from runtime - better with itertools and functional
+
+
+% =============
+% DATA FORMATS
+% =============
+
+% Big move - include all the markup and internet formats here
+
+% MIME & email stuff
+\input{netdata}                 % Internet Data Handling
+\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{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{fileformats}		% Miscellaneous file formats
+\input{libcsv}
 \input{libcfgparser}
-\input{libfileinput}
-\input{libcalendar}
-\input{libcmd}
-\input{libshlex}
+\input{librobotparser}
+\input{libnetrc}
+\input{libxdrlib}
 
-\input{liballos}                % Generic Operating System Services
-\input{libos}
+\input{libcrypto}               % Cryptographic Services
+\input{libhashlib}
+\input{libhmac}
+\input{libmd5}
+\input{libsha}
+
+% =============
+% FILE & DATABASE STORAGE
+% =============
+
+\input{filesys}			% File/directory support
 \input{libposixpath}            % os.path
-\input{libdircache}
+\input{libfileinput}
 \input{libstat}
 \input{libstatvfs}
 \input{libfilecmp}
-\input{libsubprocess}
-\input{libpopen2}
-\input{libdatetime}
-\input{libtime}
-\input{libsched}
-\input{libmutex}
-\input{libgetpass}
-\input{libcurses}
-\input{libascii}                % curses.ascii
-\input{libcursespanel}
-\input{libgetopt}
-\input{liboptparse}
 \input{libtempfile}
-\input{liberrno}
 \input{libglob}
 \input{libfnmatch}
+\input{liblinecache}
 \input{libshutil}
-\input{liblocale}
-\input{libgettext}
+\input{libdircache}
+
+
+\input{archiving}		% Data compression and archiving
+\input{libzlib}
+\input{libgzip}
+\input{libbz2}
+\input{libzipfile}
+\input{libtarfile}
+
+
+\input{persistence}		% 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{libos}
+\input{libtime}
+\input{liboptparse}
+\input{libgetopt}
 \input{liblogging}
+\input{libgetpass}
+\input{libcurses}
+\input{libascii}                % curses.ascii
+\input{libcursespanel}
 \input{libplatform}
+\input{liberrno}
 
 \input{libsomeos}               % Optional Operating System Services
-\input{libsignal}
-\input{libsocket}
 \input{libselect}
 \input{libthread}
 \input{libthreading}
 \input{libdummythread}
 \input{libdummythreading}
-\input{libqueue}
 \input{libmmap}
-\input{libanydbm}
-\input{libdbhash}
-\input{libwhichdb}
-\input{libbsddb}
-\input{libdumbdbm}
-\input{libzlib}
-\input{libgzip}
-\input{libbz2}
-\input{libzipfile}
-\input{libtarfile}
 \input{libreadline}
 \input{librlcompleter}
 
@@ -199,8 +262,6 @@ and how to embed it in other applications.
 \input{libgrp}
 \input{libcrypt}
 \input{libdl}
-\input{libdbm}
-\input{libgdbm}
 \input{libtermios}
 \input{libtty}
 \input{libpty}
@@ -212,11 +273,18 @@ and how to embed it in other applications.
 \input{libsyslog}
 \input{libcommands}
 
-\input{libpdb}                  % The Python Debugger
 
-\input{libprofile}              % The Python Profiler
-\input{libhotshot}              % New profiler
-\input{libtimeit}
+% =============
+% NETWORK & COMMUNICATIONS
+% =============
+
+\input{ipc}                     % Interprocess communication/networking
+\input{libsubprocess}
+\input{libsocket}
+\input{libsignal}
+\input{libpopen2}
+\input{libasyncore}
+\input{libasynchat}
 
 \input{internet}                % Internet Protocols
 \input{libwebbrowser}
@@ -243,51 +311,10 @@ and how to embed it in other applications.
 \input{libxmlrpclib}
 \input{libsimplexmlrpc}
 \input{libdocxmlrpc}
-\input{libasyncore}
-\input{libasynchat}
 
-\input{netdata}                 % Internet Data Handling
-\input{libformatter}
-
-% 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}
-
-% file formats
-\input{libnetrc}
-\input{librobotparser}
-\input{libcsv}
-
-\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{xmletree}
-% \input{libxmllib}
+% =============
+% MULTIMEDIA
+% =============
 
 \input{libmm}                   % Multimedia Services
 \input{libaudioop}
@@ -302,18 +329,78 @@ and how to embed it in other applications.
 \input{libsndhdr}
 \input{libossaudiodev}
 
-\input{libcrypto}               % Cryptographic Services
-\input{libhmac}
-\input{libhashlib}
-\input{libmd5}
-\input{libsha}
-
+% Tkinter is a chapter in its own right.
 \input{tkinter}
 
+%                                % Internationalization
+\input{i18n}
+\input{libgettext}
+\input{liblocale}
+
+% =============
+% PROGRAM FRAMEWORKS
+% =============
+\input{frameworks}
+\input{libcmd}
+\input{libshlex}
+
+
+% =============
+% DEVELOPMENT TOOLS
+% =============
+%                                % Software development support
+\input{development}
+\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
+% =============
+
+% Runtime services
+\input{libpython}               % Python Runtime Services
+\input{libsys}
+\input{libbltin}                % really __builtin__
+\input{libmain}                 % really __main__
+\input{libwarnings}
+\input{libatexit}
+\input{libtraceback}
+\input{libfuture}               % really __future__
+\input{libgc}
+\input{libinspect}
+\input{libsite}
+\input{libuser}
+\input{libfpectl}
+
+
+\input{custominterp}		% Custom interpreter
+\input{libcode}
+\input{libcodeop}
 \input{librestricted}           % Restricted Execution
 \input{librexec}
 \input{libbastion}
 
+
+\input{modules}			% Importing Modules
+\input{libimp}
+\input{libzipimport}
+\input{libpkgutil}
+\input{libmodulefinder}
+
+
+% =============
+% PYTHON LANGUAGE & COMPILER
+% =============
+
 \input{language}                % Python Language Services
 \input{libparser}
 \input{libsymbol}
@@ -330,6 +417,13 @@ and how to embed it in other applications.
 
 \input{compiler}                % compiler package
 
+\input{libmisc}                 % Miscellaneous Services
+\input{libformatter}
+
+% =============
+% OTHER PLATFORM-SPECIFIC STUFF
+% =============
+
 %\input{libamoeba}              % AMOEBA ONLY
 
 %\input{libstdwin}              % STDWIN ONLY