mass changes; fix titles; add examples; correct typos; clarifications;

 unified style; etc.

1 files changed, 28 insertions, 4 deletions

diff --git a/Doc/lib/libmarshal.tex b/Doc/lib/libmarshal.tex
index 2b0a400..319c195 100644
--- a/Doc/lib/libmarshal.tex
+++ b/Doc/lib/libmarshal.tex
@@ -4,9 +4,9 @@
 This module contains functions that can read and write Python
 values in a binary format.  The format is specific to Python, but
 independent of machine architecture issues (e.g., you can write a
-Python value to a file on a VAX, transport the file to a Mac, and read
-it back there).  Details of the format not explained here; read the
-source if you're interested.%
+Python value to a file on a PC, transport the file to a Sun, and read
+it back there).  Details of the format are undocumented on purpose;
+it may change between Python versions (although it rarely does).%
 \footnote{The name of this module stems from a bit of terminology used
 by the designers of Modula-3 (amongst others), who use the term
 ``marshalling'' for shipping of data around in a self-contained form.
@@ -14,6 +14,14 @@ Strictly speaking, ``to marshal'' means to convert some data from
 internal to external form (in an RPC buffer for instance) and
 ``unmarshalling'' for the reverse process.}
 
+This is not a general ``persistency'' module.  For general persistency
+and transfer of Python objects through RPC calls, see the modules
+\code{pickle} and \code{shelve}.  The \code{marshal} module exists
+mainly to support reading and writing the ``pseudo-compiled'' code for
+Python modules of \samp{.pyc} files.
+\stmodindex{pickle}
+\stmodindex{shelve}
+\obindex{code}
 
 Not all Python object types are supported; in general, only objects
 whose value is independent from a particular invocation of Python can
@@ -23,7 +31,22 @@ strings, tuples, lists, dictionaries, and code objects, where it
 should be understood that tuples, lists and dictionaries are only
 supported as long as the values contained therein are themselves
 supported; and recursive lists and dictionaries should not be written
-(they will cause an infinite loop).
+(they will cause infinite loops).
+
+{\bf Caveat:} On machines where C's \code{long int} type has more than
+32 bits (such as the DEC Alpha or the HP Precision Architecture), it
+is possible to create plain Python integers that are longer than 32
+bits.  Since the current \code{marshal} module uses 32 bits to
+transfer plain Python integers, such values are silently truncated.
+This particularly affects the use of very long integer literals in
+Python modules --- these will be accepted by the parser on such
+machines, but will be silently be truncated when the module is read
+from the \code{.pyc} instead.%
+\footnote{A solution would be to refuse such literals in the parser,
+since they are inherently non-portable.  Another solution would be to
+let the \code{marshal} module raise an exception when an integer value
+would be truncated.  At least one of these solutions will be
+implemented in a future version.}
 
 There are functions that read/write files as well as functions
 operating on strings.
@@ -31,6 +54,7 @@ operating on strings.
 The module defines these functions:
 
 \renewcommand{\indexsubitem}{(in module marshal)}
+
 \begin{funcdesc}{dump}{value\, file}
   Write the value on the open file.  The value must be a supported
   type.  The file must be an open file object such as