mass changes; fix titles; add examples; correct typos; clarifications;
unified style; etc.
diff --git a/Doc/libmarshal.tex b/Doc/libmarshal.tex
index 2b0a400..319c195 100644
--- a/Doc/libmarshal.tex
+++ b/Doc/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 @@
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 @@
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 @@
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