Reformat prior to editing.

Doc/c-api/marshal.rst

@@ -5,25 +5,26 @@
 Data marshalling support
 ========================
 
-These routines allow C code to work with serialized objects using the same data
+These routines allow C code to work with serialized objects using the same
-format as the :mod:`marshal` module.  There are functions to write data into the
+data format as the :mod:`marshal` module.  There are functions to write data
-serialization format, and additional functions that can be used to read the data
+into the serialization format, and additional functions that can be used to
-back.  Files used to store marshalled data must be opened in binary mode.
+read the data back.  Files used to store marshalled data must be opened in
+binary mode.
 
 Numeric values are stored with the least significant byte first.
 
-The module supports two versions of the data format: version 0 is the historical
+The module supports two versions of the data format: version 0 is the
-version, version 1 (new in Python 2.4) shares interned strings in the file, and
+historical version, version 1 (new in Python 2.4) shares interned strings in
-upon unmarshalling.  Version 2 (new in Python 2.5) uses a binary format for
+the file, and upon unmarshalling.  Version 2 (new in Python 2.5) uses a binary
-floating point numbers.
+format for floating point numbers.  *Py_MARSHAL_VERSION* indicates the current
-*Py_MARSHAL_VERSION* indicates the current file format (currently 2).
+file format (currently 2).
 
 
 .. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
 
-   Marshal a :ctype:`long` integer, *value*, to *file*.  This will only write the
+   Marshal a :ctype:`long` integer, *value*, to *file*.  This will only write
-   least-significant 32 bits of *value*; regardless of the size of the native
+   the least-significant 32 bits of *value*; regardless of the size of the
-   :ctype:`long` type.
+   native :ctype:`long` type.
 
    .. versionchanged:: 2.4
       *version* indicates the file format.
@@ -48,24 +49,24 @@ floating point numbers.
 The following functions allow marshalled values to be read back in.
 
 XXX What about error detection?  It appears that reading past the end of the
-file will always result in a negative numeric value (where that's relevant), but
+file will always result in a negative numeric value (where that's relevant),
-it's not clear that negative values won't be handled properly when there's no
+but it's not clear that negative values won't be handled properly when there's
-error.  What's the right way to tell? Should only non-negative values be written
+no error.  What's the right way to tell? Should only non-negative values be
-using these routines?
+written using these routines?
 
 
 .. cfunction:: long PyMarshal_ReadLongFromFile(FILE *file)
 
-   Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened for
+   Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened
-   reading.  Only a 32-bit value can be read in using this function, regardless of
+   for reading.  Only a 32-bit value can be read in using this function,
-   the native size of :ctype:`long`.
+   regardless of the native size of :ctype:`long`.
 
 
 .. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file)
 
-   Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened for
+   Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened
-   reading.  Only a 16-bit value can be read in using this function, regardless of
+   for reading.  Only a 16-bit value can be read in using this function,
-   the native size of :ctype:`short`.
+   regardless of the native size of :ctype:`short`.
 
 
 .. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
@@ -78,17 +79,18 @@ using these routines?
 .. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
 
    Return a Python object from the data stream in a :ctype:`FILE\*` opened for
-   reading.  Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function assumes
+   reading.  Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function
-   that no further objects will be read from the file, allowing it to aggressively
+   assumes that no further objects will be read from the file, allowing it to
-   load file data into memory so that the de-serialization can operate from data in
+   aggressively load file data into memory so that the de-serialization can
-   memory rather than reading a byte at a time from the file.  Only use these
+   operate from data in memory rather than reading a byte at a time from the
-   variant if you are certain that you won't be reading anything else from the
+   file.  Only use these variant if you are certain that you won't be reading
-   file.  On error, sets the appropriate exception (:exc:`EOFError` or
+   anything else from the file.  On error, sets the appropriate exception
-   :exc:`TypeError`) and returns *NULL*.
+   (:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
 
 
 .. cfunction:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
 
-   Return a Python object from the data stream in a character buffer containing
+   Return a Python object from the data stream in a character buffer
-   *len* bytes pointed to by *string*.  On error, sets the appropriate exception
+   containing *len* bytes pointed to by *string*.  On error, sets the
-   (:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
+   appropriate exception (:exc:`EOFError` or :exc:`TypeError`) and returns
+   *NULL*.