errors

CHANGES.rst

@@ -5704,22 +5704,18 @@ was last updated, see the repository revision history:
     change, any attempt to modify a memory-mapped image resulted in a
     core dump...)
 
-- Added special cases for lists everywhere PIL expects a sequence.
+- Added special cases for lists everywhere PIL expects a sequence. This should speed up things like "putdata" and drawing operations.
-    This should speed up things like "putdata" and drawing operations.
 
-- The Image.offset method is deprecated.  Use the ImageChops.offset
+- The Image.offset method is deprecated.  Use the ImageChops.offset function instead.
-    function instead.
 
-- Changed ImageChops operators to copy palette and info dictionary
+- Changed ImageChops operators to copy palette and info dictionary from the first image argument.
-    from the first image argument.
 
 1.1.1
 --------------
 
 - Additional fixes for Python 1.6/2.0, including TIFF "save" bug.
 
-- Changed "init" to properly load plugins when PIL is used as a
+- Changed "init" to properly load plugins when PIL is used as a package.
-    package.
 
 - Fixed broken "show" method (on Unix)
 
@@ -5728,38 +5724,27 @@ was last updated, see the repository revision history:
 
 - Adapted to Python 1.6 ("append" and other method changes)
 
-- Fixed Image.paste when pasting with solid colour and matte
+- Fixed Image.paste when pasting with solid colour and matte layers ("L" or "RGBA" masks) (bug reported by Robert Kern)
-    layers ("L" or "RGBA" masks) (bug reported by Robert Kern)
 
-- To make it easier to distribute prebuilt versions of PIL,
+- To make it easier to distribute prebuilt versions of PIL, the tkinit binding stuff has been moved to a separate extension module, named "_imagingtk".
-    the tkinit binding stuff has been moved to a separate
-    extension module, named "_imagingtk".
 
 0.3b2 to 1.0 final
 -------------------
 
-- If there's no 16-bit integer (like on a Cray T3E), set
+- If there's no 16-bit integer (like on a Cray T3E), set INT16 to the smallest integer available.  Most of the library works just fine anyway (from Bill Crutchfield)
-    INT16 to the smallest integer available.  Most of the
-    library works just fine anyway (from Bill Crutchfield)
 
 - Tweaks to make drawing work on big-endian platforms.
 
 1.0c2
 -------
 
-- If PIL is built with the WITH_TKINTER flag, ImageTk can
+- If PIL is built with the WITH_TKINTER flag, ImageTk can automatically hook into a standard Tkinter build.  You no longer need to build your own Tkinter to use the ImageTk module.
-    automatically hook into a standard Tkinter build.  You
-    no longer need to build your own Tkinter to use the
-    ImageTk module.
 
-    The old way still works, though.  For more information,
+    The old way still works, though.  For more information, see Tk/install.txt.
-    see Tk/install.txt.
 
-- Some tweaks to ImageTk to support multiple Tk interpreters
+- Some tweaks to ImageTk to support multiple Tk interpreters (from Greg Couch).
-    (from Greg Couch).
 
-- ImageFont "load_path" now scans directory mentioned in .pth
+- ImageFont "load_path" now scans directory mentioned in .pth files (from Richard Jones).
-    files (from Richard Jones).
 
 1.0c1
 --------------
@@ -5779,15 +5764,11 @@ was last updated, see the repository revision history:
 1.0b2
 --------------
 
-- Major speedups for rotate, transform(EXTENT), and transform(AFFINE)
+- Major speedups for rotate, transform(EXTENT), and transform(AFFINE) when using nearest neighbour resampling.
-    when using nearest neighbour resampling.
 
-- Modified ImageDraw to be compatible with the Arrow graphics
+- Modified ImageDraw to be compatible with the Arrow graphics interface.  See the handbook for details.
-    interface.  See the handbook for details.
 
-- PIL now automatically loads file codecs when used as a package
+- PIL now automatically loads file codecs when used as a package (from The Dragon De Monsyne).  Also included an __init__.py file in the standard distribution.
-    (from The Dragon De Monsyne).  Also included an __init__.py file
-    in the standard distribution.
 
 - The GIF encoder has been modified to produce much smaller files.
 
@@ -5801,8 +5782,7 @@ was last updated, see the repository revision history:
 
 - Added "bitmap" and "textsize" methods to ImageDraw.
 
-- Improved font rendering code.  Fixed a bug or two, and moved
+- Improved font rendering code.  Fixed a bug or two, and moved most of the time critical stuff to C.
-    most of the time critical stuff to C.
 
 - Removed "bdf2pil.py".  Use "pilfont.py" instead!
 
@@ -5817,167 +5797,107 @@ was last updated, see the repository revision history:
 
     NOTE: ALL other operations are still UNDEFINED on 16-bit images.
 
-- The "paste" method now supports constant sources.
+- The "paste" method now supports constant sources. Just pass a colour value (a number or a tuple, depending on the target image mode) instead of the source image. This was in fact implemented in an inefficient way in earlier versions (the "paste" method generated a temporary source image if you passed it a colour instead of an image). In this version, this is handled on the C level instead.
-
-    Just pass a colour value (a number or a tuple, depending on
-    the target image mode) instead of the source image.
-
-    This was in fact implemented in an inefficient way in
-    earlier versions (the "paste" method generated a temporary
-    source image if you passed it a colour instead of an image).
-    In this version, this is handled on the C level instead.
 
 - Added experimental "RGBa" mode support.
 
-    An "RGBa" image is an RGBA image where the colour components
+    An "RGBa" image is an RGBA image where the colour components have have been premultiplied with the alpha value.  PIL allows you to convert an RGBA image to an RGBa image, and to paste RGBa images on top of RGB images.  Since this saves a bunch of multiplications and shifts, it is typically about twice as fast an ordinary RGBA paste.
-    have have been premultiplied with the alpha value.  PIL allows
-    you to convert an RGBA image to an RGBa image, and to paste
-    RGBa images on top of RGB images.  Since this saves a bunch
-    of multiplications and shifts, it is typically about twice
-    as fast an ordinary RGBA paste.
 
-- Eliminated extra conversion step when pasting "RGBA" or "RGBa"
+- Eliminated extra conversion step when pasting "RGBA" or "RGBa" images on top of "RGB" images.
-    images on top of "RGB" images.
 
 - Fixed Image.BICUBIC resampling for "RGB" images.
 
-- Fixed PCX image file handler to properly read 8-bit PCX
+- Fixed PCX image file handler to properly read 8-bit PCX files (bug introduced in 1.0b1, reported by Bernhard Herzog)
-    files (bug introduced in 1.0b1, reported by Bernhard
-    Herzog)
 
-- Fixed PSDraw "image" method to restore the coordinate
+- Fixed PSDraw "image" method to restore the coordinate system.
-    system.
 
-- Fixed "blend" problem when applied to images that was
+- Fixed "blend" problem when applied to images that was not already loaded (reported by Edward C. Jones)
-    not already loaded (reported by Edward C. Jones)
 
 - Fixed -f option to "pilconvert.py" (from Anthony Baxter)
 
 1.0b1
 --------------
 
-- Added Toby J. Sargeant's quantization package.  To enable
+- Added Toby J. Sargeant's quantization package.  To enable quantization, use the "palette" option to "convert":
-    quantization, use the "palette" option to "convert":
 
     imOut = im.convert("P", palette=Image.ADAPTIVE)
 
-    This can be used with "L", "P", and "RGB" images.  In this
+    This can be used with "L", "P", and "RGB" images.  In this version, dithering cannot be used with adaptive palettes.
-    version, dithering cannot be used with adaptive palettes.
 
-    Note: ADAPTIVE currently maps to median cut quantization
+    Note: ADAPTIVE currently maps to median cut quantization with 256 colours.  The quantization package also contains a maximum coverage quantizer, which will be supported by future versions of PIL.
-    with 256 colours.  The quantization package also contains
-    a maximum coverage quantizer, which will be supported by
-    future versions of PIL.
 
-- Added Eric S. Raymond's "pildriver" image calculator to the
+- Added Eric S. Raymond's "pildriver" image calculator to the distribution.  See the docstring for more information.
-    distribution.  See the docstring for more information.
 
-- The "offset" method no longer dumps core if given positive
+- The "offset" method no longer dumps core if given positive offsets (from Charles Waldman).
-    offsets (from Charles Waldman).
 
-- Fixed a resource leak that could cause ImageWin to run out of
+- Fixed a resource leak that could cause ImageWin to run out of GDI resources (from Roger Burnham).
-    GDI resources (from Roger Burnham).
 
-- Added "arc", "chord", and "pieslice" methods to ImageDraw (inspired
+- Added "arc", "chord", and "pieslice" methods to ImageDraw (inspired by code contributed by Richard Jones).
-    by code contributed by Richard Jones).
 
-- Added experimental 16-bit support, via modes "I;16" (little endian
+- Added experimental 16-bit support, via modes "I;16" (little endian data) and "I;16B" (big endian).  Only a few methods properly support such images (see above).
-    data) and "I;16B" (big endian).  Only a few methods properly support
-    such images (see above).
 
 - Added XV thumbnail file handler (from Gene Cash).
 
-- Fixed BMP image file handler to handle palette images with small
+- Fixed BMP image file handler to handle palette images with small palettes (from Rob Hooft).
-    palettes (from Rob Hooft).
 
-- Fixed Sun raster file handler for palette images (from Charles
+- Fixed Sun raster file handler for palette images (from Charles Waldman).
-    Waldman).
 
 - Improved various internal error messages.
 
-- Fixed Path constructor to handle arbitrary sequence objects.  This
+- Fixed Path constructor to handle arbitrary sequence objects.  This also affects the ImageDraw class (from Richard Jones).
-    also affects the ImageDraw class (from Richard Jones).
 
-- Fixed a bug in JpegDecode that caused PIL to report "decoder error
+- Fixed a bug in JpegDecode that caused PIL to report "decoder error -2" for some progressive JPEG files (reported by Magnus Källström, who also provided samples).
-    -2" for some progressive JPEG files (reported by Magnus Källström,
-    who also provided samples).
 
-- Fixed a bug in JpegImagePlugin that caused PIL to hang when loading
+- Fixed a bug in JpegImagePlugin that caused PIL to hang when loading JPEG files using 16-bit quantization tables.
-    JPEG files using 16-bit quantization tables.
 
-- The Image "transform" method now supports Image.QUAD transforms.
+- The Image "transform" method now supports Image.QUAD transforms. The data argument is an 8-tuple giving the upper left, lower left, lower right, and upper right corner of the source quadri-lateral.  Also added Image.MESH transform which takes a list of quadrilaterals.
-    The data argument is an 8-tuple giving the upper left, lower
-    left, lower right, and upper right corner of the source quadri-
-    lateral.  Also added Image.MESH transform which takes a list
-    of quadrilaterals.
 
-- The Image "resize", "rotate", and "transform" methods now support
+- The Image "resize", "rotate", and "transform" methods now support Image.BILINEAR (2x2) and Image.BICUBIC (4x4) resampling filters. Filters can be used with all transform methods.
-    Image.BILINEAR (2x2) and Image.BICUBIC (4x4) resampling filters.
-    Filters can be used with all transform methods.
 
-- The ImageDraw "rectangle" method now includes both the right
+- The ImageDraw "rectangle" method now includes both the right and the bottom edges when drawing filled rectangles.
-    and the bottom edges when drawing filled rectangles.
 
-- The TGA decoder now works properly for runlength encoded images
+- The TGA decoder now works properly for runlength encoded images which have more than one byte per pixel.
-    which have more than one byte per pixel.
 
 - "getbands" on an YCbCr image now returns ("Y", "Cb", "Cr")
 
-- Some file drivers didn't handle the optional "modify" argument
+- Some file drivers didn't handle the optional "modify" argument to the load method.  This resulted in exceptions when you used "paste" (and other methods that modify an image in place) on a newly opened file.
-    to the load method.  This resulted in exceptions when you used
-    "paste" (and other methods that modify an image in place) on a
-    newly opened file.
 
 0.3b2
 --------------
 
 The test suite includes 825 individual tests.
 
-- An Image "getbands" method has been added.  It returns a tuple
+- An Image "getbands" method has been added.  It returns a tuple containing the individual band names for this image.  To figure out how many bands an image has, use "len(im.getbands())".
-    containing the individual band names for this image.  To figure
-    out how many bands an image has, use "len(im.getbands())".
 
 - An Image "putpixel" method has been added.
 
-- The Image "point" method can now be used to convert "L" images
+- The Image "point" method can now be used to convert "L" images to any other format, via a lookup table.  That table should contain 256 values for each band in the output image.
-    to any other format, via a lookup table.  That table should
-    contain 256 values for each band in the output image.
 
-- Some file drivers (including FLI/FLC, GIF, and IM) accidentally
+- Some file drivers (including FLI/FLC, GIF, and IM) accidentally overwrote the offset method with an internal attribute.  All drivers have been updated to use private attributes where possible.
-    overwrote the offset method with an internal attribute.  All
-    drivers have been updated to use private attributes where
-    possible.
 
-- The Image "histogram" method now works for "I" and "F" images.
+- The Image "histogram" method now works for "I" and "F" images. For these modes, PIL divides the range between the min and max values used in the image into 256 bins.
-    For these modes, PIL divides the range between the min and
+    
-    max values used in the image into 256 bins.  You can also
+    You can also pass in your own min and max values via the "extrema" option:
-    pass in your own min and max values via the "extrema" option:
 
     h = im.histogram(extrema=(0, 255))
 
-- An Image "getextrema" method has been added.  It returns the
+- An Image "getextrema" method has been added.  It returns the min and max values used in the image. In this release, this works for single band images only.
-    min and max values used in the image. In this release, this
-    works for single band images only.
 
-- Changed the PNG driver to load and save mode "I" images as
+- Changed the PNG driver to load and save mode "I" images as 16-bit images.  When saving, values outside the range 0..65535 are clipped.
-    16-bit images.  When saving, values outside the range 0..65535
-    are clipped.
 
 - Fixed ImageFont.py to work with the new "pilfont" compiler.
 
 - Added JPEG "save" and "draft" support for mode "YCbCr" images.
-    Note that if you save an "YCbCr" image as a JPEG file and read
+
-    it back, it is read as an RGB file.  To get around this, you
+    Note that if you save an "YCbCr" image as a JPEG file and read it back, it is read as an RGB file.  To get around this, you can use the "draft" method:
-    can use the "draft" method:
 
     im = Image.open("color.jpg")
     im.draft("YCbCr", im.size)
 
-- Read "RGBA" TGA images.  Also fixed the orientation bug; all
+- Read "RGBA" TGA images.  Also fixed the orientation bug; all images should now come out the right way.
-    images should now come out the right way.
+
+- Changed mode name (and internal representation) from "YCrCb" to "YCbCr" (!)
 
-- Changed mode name (and internal representation) from "YCrCb"
-    to "YCbCr" (!)
     *** WARNING: MAY BREAK EXISTING CODE ***
 
 0.3b1
@@ -5985,17 +5905,12 @@ The test suite includes 825 individual tests.
 
 The test suite includes 750 individual tests.
 
-- The "pilfont" package is now included in the standard PIL
+- The "pilfont" package is now included in the standard PIL distribution.  The pilfont utility can be used to convert X BDF and PCF raster font files to a format understood by the ImageFont module.
-    distribution.  The pilfont utility can be used to convert
-    X BDF and PCF raster font files to a format understood by
-    the ImageFont module.
 
-- GIF files are now interlaced by default.  To write a
+- GIF files are now interlaced by default.  To write a non-interlaced file, pass interlace=0 to the "save" method.
-    non-interlaced file, pass interlace=0 to the "save"
+
-    method.
+- The default string format has changed for the "fromstring" and "tostring" methods.
 
-- The default string format has changed for the "fromstring"
-    and "tostring" methods.
     *** WARNING: MAY BREAK EXISTING CODE ***
 
     NOTE: If no extra arguments are given, the first line in
@@ -6010,35 +5925,23 @@ The test suite includes 750 individual tests.
     data = im.tostring("raw", "RGBX", 0, -1)
     im.fromstring(data, "raw", "RGBX", 0, -1)
 
-- "new" no longer gives a MemoryError if the width or height
+- "new" no longer gives a MemoryError if the width or height is zero (this only happened on platforms where malloc(0) or calloc(0) returns NULL).
-    is zero (this only happened on platforms where malloc(0)
-    or calloc(0) returns NULL).
 
 - "new" now adds a default palette object to "P" images.
 
-- You can now convert directly between all modes supported by
+- You can now convert directly between all modes supported by PIL.  When converting colour images to "P", PIL defaults to a "web" palette and dithering.  When converting greyscale images to "1", PIL uses a thresholding and dithering.
-    PIL.  When converting colour images to "P", PIL defaults to
-    a "web" palette and dithering.  When converting greyscale
-    images to "1", PIL uses a thresholding and dithering.
 
-- Added a "dither" option to "convert".  By default, "convert"
+- Added a "dither" option to "convert".  By default, "convert" uses floyd-steinberg error diffusion for "P" and "1" targets, so this option is only used to *disable* dithering. Allowed values are NONE (no dithering) or FLOYDSTEINBERG (default).
-    uses floyd-steinberg error diffusion for "P" and "1" targets,
-    so this option is only used to *disable* dithering. Allowed
-    values are NONE (no dithering) or FLOYDSTEINBERG (default).
 
     imOut = im.convert("P", dither=Image.NONE)
 
-- Added a full set of "I" decoders.  You can use "fromstring"
+- Added a full set of "I" decoders.  You can use "fromstring" (and file decoders) to read any standard integer type as an "I" image.
-    (and file decoders) to read any standard integer type as an
-    "I" image.
 
-- Added some support for "YCbCr" images (creation, conversion
+- Added some support for "YCbCr" images (creation, conversion from/to "L" and "RGB", IM YCC load/save)
-    from/to "L" and "RGB", IM YCC load/save)
 
 - "getpixel" now works properly with fractional coordinates.
 
-- ImageDraw "setink" now works with "I", "F", "RGB", "RGBA",
+- ImageDraw "setink" now works with "I", "F", "RGB", "RGBA", "RGBX", "CMYK", and "YCbCr" images.
-    "RGBX", "CMYK", and "YCbCr" images.
 
 - ImImagePlugin no longer attaches palettes to "RGB" images.
 
@@ -6049,19 +5952,15 @@ The test suite includes 750 individual tests.
 
 - Added experimental IPTC/NAA support.
 
-- Eliminated AttributeError exceptions after "crop" (from
+- Eliminated AttributeError exceptions after "crop" (from Skip Montanaro)
-    Skip Montanaro)
 
-- Reads some uncompressed formats via memory mapping (this
+- Reads some uncompressed formats via memory mapping (this is currently supported on Win32 only)
-    is currently supported on Win32 only)
 
-- Fixed some last minute glitches in the last alpha release
+- Fixed some last minute glitches in the last alpha release (Types instead of types in Image.py, version numbers, etc.)
-    (Types instead of types in Image.py, version numbers, etc.)
 
 - Eliminated some more bogus compiler warnings.
 
-- Various fixes to make PIL compile and run smoother on Macs
+- Various fixes to make PIL compile and run smoother on Macs (from Jack Jansen).
-    (from Jack Jansen).
 
 - Fixed "fromstring" and "tostring" for mode "I" images.
 
@@ -6070,39 +5969,29 @@ The test suite includes 750 individual tests.
 
 The test suite includes 530 individual tests.
 
-- Eliminated unexpected side-effect in "paste" with matte.  "paste"
+- Eliminated unexpected side-effect in "paste" with matte.  "paste" now works properly also if compiled with "gcc".
-    now works properly also if compiled with "gcc".
 
 - Adapted to Python 1.5 (build issues only)
 
-- Fixed the ImageDraw "point" method to draw also the last
+- Fixed the ImageDraw "point" method to draw also the last point (!).
-    point (!).
 
 - Added "I" and "RGBX" support to Image.new.
 
-- The plugin path is now properly prepended to the module search
+- The plugin path is now properly prepended to the module search path when a plugin module is imported.
-    path when a plugin module is imported.
 
-- Added "draw" method to the ImageWin.Dib class.  This is used by
+- Added "draw" method to the ImageWin.Dib class.  This is used by Topaz to print images on Windows printers.
-    Topaz to print images on Windows printers.
 
 - "convert" now supports conversions from "P" to "1" and "F".
 
-- "paste" can now take a colour instead of an image as the first argument.
+- "paste" can now take a colour instead of an image as the first argument. The colour must match the colour argument given to the new function, and match the mode of the target image.
-    The colour must match the colour argument given to the new function, and
-    match the mode of the target image.
 
 - Fixed "paste" to allow a mask also for mode "F" images.
 
-- The BMP driver now saves mode "1" images.  When loading images, the mode
+- The BMP driver now saves mode "1" images.  When loading images, the mode is set to "L" for 8-bit files with greyscale palettes, and to "P" for other 8-bit files.
-    is set to "L" for 8-bit files with greyscale palettes, and to "P" for
-    other 8-bit files.
 
 - The IM driver now reads and saves "1" images (file modes "0 1" or "L 1").
 
-- The JPEG and GIF drivers now saves "1" images.  For JPEG, the image
+- The JPEG and GIF drivers now saves "1" images.  For JPEG, the image is saved as 8-bit greyscale (it will load as mode "L").  For GIF, the image will be loaded as a "P" image.
-    is saved as 8-bit greyscale (it will load as mode "L").  For GIF, the
-    image will be loaded as a "P" image.
 
 - Fixed a potential buffer overrun in the GIF encoder.
 
@@ -6214,8 +6103,7 @@ The test suite includes 400 individual tests.
 
 - Added predictor support (TIFF 6.0 section 14) to the TIFF decoder.
 
-- Fixed palette and padding problems in BMP driver.  Now properly
+- Fixed palette and padding problems in BMP driver.  Now properly writes "1", "L", "P" and "RGB" images.
-writes "1", "L", "P" and "RGB" images.
 
 - Fixed getpixel()/getdata() to return correct pixel values.
 
@@ -6223,32 +6111,23 @@ writes "1", "L", "P" and "RGB" images.
 
 - Added GIF write support (writes "uncompressed" GIF files only, due to unresolvable licensing issues).  The "gifmaker.py" script can be used to create GIF animations.
 
-- Reads 8-bit "L" and "P" TGA images.  Also reads 16-bit "RGB"
+- Reads 8-bit "L" and "P" TGA images.  Also reads 16-bit "RGB" images.
-images.
 
 - Added FLI read support.  This driver has only been tested on a few FLI samples.
 
 - Reads 2-bit and 4-bit PCX images.
 
-- Added MSP read and write support.  Both version 1 and 2 can be
+- Added MSP read and write support.  Both version 1 and 2 can be read, but only version 1 (uncompressed) files are written.
-read, but only version 1 (uncompressed) files are written.
 
-- Fixed a bug in the FLI/FLC identification code that caused the
+- Fixed a bug in the FLI/FLC identification code that caused the driver to raise an exception when parsing valid FLI/FLC files.
-driver to raise an exception when parsing valid FLI/FLC files.
 
-- Improved performance when loading file format plugins, and when
+- Improved performance when loading file format plugins, and when opening files.
-opening files.
 
-- Added GIF animation support, via the "seek" and "tell" methods.
+- Added GIF animation support, via the "seek" and "tell" methods. You can use "player.py" to play an animated GIF file.
-You can use "player.py" to play an animated GIF file.
 
-- Removed MNG support, since the spec is changing faster than I
+- Removed MNG support, since the spec is changing faster than I can change the code.  I've added support for the experimental ARG format instead.  Contact me for more information on this format.
-can change the code.  I've added support for the experimental
-ARG format instead.  Contact me for more information on this
-format.
 
-- Added keyword options to the "save" method.  The following options
+- Added keyword options to the "save" method.  The following options are currently supported:
-are currently supported:
 
     Format    Option          Description
     --------------------------------------------------------
@@ -6268,100 +6147,78 @@ are currently supported:
     PNG       optimize        Minimize output file at the
                                 expense of compression speed.
 
-Expect more options in future releases.  Also note that
+Expect more options in future releases.  Also note that file writers silently ignore unknown options.
-file writers silently ignore unknown options.
 
 - Plugged memory leaks in the PNG and TIFF decoders.
 
 - Added PNG write support.
 
-- (internal) RGB unpackers and converters now set the pad byte
+- (internal) RGB unpackers and converters now set the pad byte to 255 (full opacity).
-to 255 (full opacity).
 
-- Properly handles the "transparency" property for GIF, PNG
+- Properly handles the "transparency" property for GIF, PNG and XPM files.
-and XPM files.
 
-- Added a "putalpha" method, allowing you to attach a "1" or "L"
+- Added a "putalpha" method, allowing you to attach a "1" or "L" image as the alpha layer to an "RGBA" image.
-image as the alpha layer to an "RGBA" image.
 
 - Various improvements to the sample scripts:
 
-"pilconvert"  Carries out some extra tricks in order to make
+    "pilconvert"  Carries out some extra tricks in order to make
-                the resulting file as small as possible.
+                    the resulting file as small as possible.
 
-"explode"     (NEW) Split an image sequence into individual frames.
+    "explode"     (NEW) Split an image sequence into individual frames.
 
-"gifmaker"    (NEW) Convert a sequence file into a GIF animation.
+    "gifmaker"    (NEW) Convert a sequence file into a GIF animation.
-                Note that the GIF encoder create "uncompressed" GIF
+                    Note that the GIF encoder create "uncompressed" GIF
-                files, so animations created by this script are
+                    files, so animations created by this script are
-                rather large (typically 2-5 times the compressed
+                    rather large (typically 2-5 times the compressed
-                sizes).
+                    sizes).
 
-"image2py"    (NEW) Convert a single image to a python module.  See
+    "image2py"    (NEW) Convert a single image to a python module.  See
-                comments in this script for details.
+                    comments in this script for details.
 
-"player"      If multiple images are given on the command line,
+    "player"      If multiple images are given on the command line,
-                they are interpreted as frames in a sequence.  The
+                    they are interpreted as frames in a sequence.  The
-                script assumes that they all have the same size.
+                    script assumes that they all have the same size.
-                Also note that this script now can play FLI/FLC
+                    Also note that this script now can play FLI/FLC
-                and GIF animations.
+                    and GIF animations.
 
-        This player can also execute embedded Python
+            This player can also execute embedded Python
-        animation applets (ARG format only).
+            animation applets (ARG format only).
 
-"viewer"  Transparent images ("P" with transparency property,
+    "viewer"  Transparent images ("P" with transparency property,
-            and "RGBA") are superimposed on the standard Tk back-
+                and "RGBA") are superimposed on the standard Tk back-
-            ground.
+                ground.
 
-- Fixed colour argument to "new".  For multilayer images, pass a
+- Fixed colour argument to "new".  For multilayer images, pass a tuple: (Red, Green, Blue), (Red, Green, Blue, Alpha), or (Cyan, Magenta, Yellow, Black).
-tuple: (Red, Green, Blue), (Red, Green, Blue, Alpha), or (Cyan,
-Magenta, Yellow, Black).
 
 - Added XPM (X pixmap) read support.
 
 0.2b3
 --------------
 
-- Added MNG (multi-image network graphics) read support.  "Ming"
+- Added MNG (multi-image network graphics) read support.  "Ming" is a proposed animation standard, based on the PNG file format.
-    is a proposed animation standard, based on the PNG file format.
 
-    You can use the "player" sample script to display some flavours
+    You can use the "player" sample script to display some flavours of this format.  The MNG standard is still under development, as is this driver.  More information, including sample files, can be found at <ftp://swrinde.nde.swri.edu/pub/mng>
-    of this format.  The MNG standard is still under development,
-    as is this driver.  More information, including sample files,
-    can be found at <ftp://swrinde.nde.swri.edu/pub/mng>
 
-- Added a "verify" method to images loaded from file.  This method
+- Added a "verify" method to images loaded from file.  This method scans the file for errors, without actually decoding the image data, and raises a suitable exception if it finds any problems. Currently implemented for PNG and MNG files only.
-    scans the file for errors, without actually decoding the image
-    data, and raises a suitable exception if it finds any problems.
-    Currently implemented for PNG and MNG files only.
 
 - Added support for interlaced GIF images.
 
-- Added PNG read support -- if linked with the ZLIB compression library,
+- Added PNG read support -- if linked with the ZLIB compression library, PIL reads all kinds of PNG images, except interlaced files.
-    PIL reads all kinds of PNG images, except interlaced files.
 
-- Improved PNG identification support -- doesn't mess up on unknown
+- Improved PNG identification support -- doesn't mess up on unknown chunks, identifies all possible PNG modes, and verifies checksum on PNG header chunks.
-    chunks, identifies all possible PNG modes, and verifies checksum
-    on PNG header chunks.
 
-- Added an experimental reader for placable Windows Meta Files (WMF).
+- Added an experimental reader for placable Windows Meta Files (WMF). This reader is still very incomplete, but it illustrates how PIL's drawing capabilities can be used to render vector and metafile formats.
-    This reader is still very incomplete, but it illustrates how PIL's
-    drawing capabilities can be used to render vector and metafile
-    formats.
 
-- Added restricted drivers for images from Image Tools (greyscale
+- Added restricted drivers for images from Image Tools (greyscale only) and LabEye/IFUNC (common interchange modes only).
-    only) and LabEye/IFUNC (common interchange modes only).
 
-- Some minor improvements to the sample scripts provided in the
+- Some minor improvements to the sample scripts provided in the "Scripts" directory.
-    "Scripts" directory.
 
 - The test images have been moved to the "Images" directory.
 
 0.2b2, 0.2b1 released; Windows only
 -----------------------------------
 
-- Fixed filling of complex polygons.  The ImageDraw "line" and
+- Fixed filling of complex polygons.  The ImageDraw "line" and "polygon" methods also accept Path objects.
-    "polygon" methods also accept Path objects.
 
 - The ImageTk "PhotoImage" object can now be constructed directly
     from an image.  You can also pass the object itself to Tkinter,
@@ -6374,110 +6231,64 @@ Magenta, Yellow, Black).
     BitmapImage class; use the "foreground" option to set the colour
     of the overlay.
 
-- Added a "putdata" method to the Image class.  This can be used to
+- Added a "putdata" method to the Image class.  This can be used to load a 1-layer image with data from a sequence object or a string. An optional floating point scale and offset can be used to adjust the data to fit into the 8-bit pixel range.  Also see the "getdata" method.
-    load a 1-layer image with data from a sequence object or a string.
-    An optional floating point scale and offset can be used to adjust
-    the data to fit into the 8-bit pixel range.  Also see the "getdata"
-    method.
 
-- Added the EXTENT method to the Image "transform" method.  This can
+- Added the EXTENT method to the Image "transform" method.  This can be used to quickly crop, stretch, shrink, or mirror a subregion from another image.
-    be used to quickly crop, stretch, shrink, or mirror a subregion
-    from another image.
 
 - Adapted to Python 1.4.
 
-- Added a project makefile for Visual C++ 4.x.  This allows you to
+- Added a project makefile for Visual C++ 4.x.  This allows you to easily build a dynamically linked version of PIL for Windows 95 and NT.
-    easily build a dynamically linked version of PIL for Windows 95
-    and NT.
 
-- A Tk "booster" patch for Windows is available.  It gives dramatic
+- A Tk "booster" patch for Windows is available.  It gives dramatic performance improvements for some displays.  Has been tested with Tk 4.2 only, but is likely to work with Tk 4.1 as well.  See the Tk subdirectory for details.
-    performance improvements for some displays.  Has been tested with
-    Tk 4.2 only, but is likely to work with Tk 4.1 as well.  See the Tk
-    subdirectory for details.
 
-- You can now save 1-bit images in the XBM format.  In addition, the
+- You can now save 1-bit images in the XBM format.  In addition, the Image class now provides a "tobitmap" method which returns a string containing an XBM representation of the image.  Quite handy to use with Tk.
-    Image class now provides a "tobitmap" method which returns a string
-    containing an XBM representation of the image.  Quite handy to use
-    with Tk.
 
 - More conversions, including "RGB" to "1" and more.
 
 0.2a1
 --------------
 
-- Where earlier versions accepted lists, this version accepts arbitrary
+- Where earlier versions accepted lists, this version accepts arbitrary Python sequences (including strings, in some cases).  A few resource leaks were plugged in the process.
-    Python sequences (including strings, in some cases).  A few resource
-    leaks were plugged in the process.
 
-- The Image "paste" method now allows the box to extend outside
+- The Image "paste" method now allows the box to extend outside the target image.  The size of the box, the image to be pasted, and the optional mask must still match.
-    the target image.  The size of the box, the image to be pasted,
-    and the optional mask must still match.
 
-- The ImageDraw module now supports filled polygons, outlined and
+- The ImageDraw module now supports filled polygons, outlined and filled ellipses, and text.  Font support is rudimentary, though.
-    filled ellipses, and text.  Font support is rudimentary, though.
 
-- The Image "point" method now takes an optional mode argument,
+- The Image "point" method now takes an optional mode argument, allowing you to convert the image while translating it.  Currently, this can only be used to convert "L" or "P" images to "1" images (creating thresholded images or "matte" masks).
-    allowing you to convert the image while translating it.  Currently,
-    this can only be used to convert "L" or "P" images to "1" images
-    (creating thresholded images or "matte" masks).
 
-- An Image "getpixel" method has been added.  For single band images,
+- An Image "getpixel" method has been added.  For single band images, it returns the pixel value at a given position as an integer. For n-band images, it returns an n-tuple of integers.
-    it returns the pixel value at a given position as an integer.
-    For n-band images, it returns an n-tuple of integers.
 
-- An Image "getdata" method has been added.  It returns a sequence
+- An Image "getdata" method has been added.  It returns a sequence object representing the image as a 1-dimensional array.  Only len() and [] can be used with this sequence.  This method returns a reference to the existing image data, so changes in the image will be immediately reflected in the sequence object.
-    object representing the image as a 1-dimensional array.  Only len()
-    and [] can be used with this sequence.  This method returns a
-    reference to the existing image data, so changes in the image
-    will be immediately reflected in the sequence object.
 
 - Fixed alignment problems in the Windows BMP writer.
 
-- If converting an "RGB" image to "RGB" or "L", you can give a second
+- If converting an "RGB" image to "RGB" or "L", you can give a second argument containing a colour conversion matrix.
-    argument containing a colour conversion matrix.
 
-- An Image "getbbox" method has been added.  It returns the bounding
+- An Image "getbbox" method has been added.  It returns the bounding box of data in an image, considering the value 0 as background.
-    box of data in an image, considering the value 0 as background.
 
-- An Image "offset" method has been added.  It returns a new image
+- An Image "offset" method has been added.  It returns a new image where the contents of the image have been offset the given distance in X and/or Y direction.  Data wraps between edges.
-    where the contents of the image have been offset the given distance
-    in X and/or Y direction.  Data wraps between edges.
 
-- Saves PDF images.  The driver creates a binary PDF 1.1 files, using
+- Saves PDF images.  The driver creates a binary PDF 1.1 files, using JPEG compression for "L", "RGB", and "CMYK" images, and hex encoding (same as for PostScript) for other formats.
-    JPEG compression for "L", "RGB", and "CMYK" images, and hex encoding
-    (same as for PostScript) for other formats.
 
-- The "paste" method now accepts "1" masks.  Zero means transparent,
+- The "paste" method now accepts "1" masks.  Zero means transparent, any other pixel value means opaque.  This is faster than using an "L" transparency mask.
-    any other pixel value means opaque.  This is faster than using an
-    "L" transparency mask.
 
-- Properly writes EPS files (and properly prints images to PostScript
+- Properly writes EPS files (and properly prints images to PostScript printers as well).
-    printers as well).
 
-- Reads 4-bit BMP files, as well as 4 and 8-bit Windows ICO and CUR
+- Reads 4-bit BMP files, as well as 4 and 8-bit Windows ICO and CUR files.  Cursor animations are not supported.
-    files.  Cursor animations are not supported.
 
 - Fixed alignment problems in the Sun raster loader.
 
-- Added "draft" and "thumbnail" methods.  The draft method is used
+- Added "draft" and "thumbnail" methods.  The draft method is used to optimize loading of JPEG and PCD files, the thumbnail method is used to create a thumbnail representation of an image.
-    to optimize loading of JPEG and PCD files, the thumbnail method is
-    used to create a thumbnail representation of an image.
 
-- Added Windows display support, via the ImageWin class (see the
+- Added Windows display support, via the ImageWin class (see the handbook for details).
-    handbook for details).
 
-- Added raster conversion for EPS files.  This requires GNU or Aladdin
+- Added raster conversion for EPS files.  This requires GNU or Aladdin Ghostscript, and probably works on UNIX only.
-    Ghostscript, and probably works on UNIX only.
 
-- Reads PhotoCD (PCD) images.  The base resolution (768x512) can be
+- Reads PhotoCD (PCD) images.  The base resolution (768x512) can be read from a PhotoCD file.
-    read from a PhotoCD file.
 
-- Eliminated some compiler warnings.  Bindings now compile cleanly in C++
+- Eliminated some compiler warnings.  Bindings now compile cleanly in C++ mode.  Note that the Imaging library itself must be compiled in C mode.
-    mode.  Note that the Imaging library itself must be compiled in C mode.
 
-- Added "bdf2pil.py", which converts BDF fonts into images with associated
+- Added "bdf2pil.py", which converts BDF fonts into images with associated metrics.  This is definitely work in progress.  For info, see description in script for details.
-    metrics.  This is definitely work in progress.  For info, see description
-    in script for details.
 
 - Fixed a bug in the "ImageEnhance.py" module.
 
@@ -6489,65 +6300,45 @@ Magenta, Yellow, Black).
 
 - Reads plane separated RGB and CMYK TIFF images.
 
-- Added driver debug mode.  This is enabled by setting Image.DEBUG
+- Added driver debug mode.  This is enabled by setting Image.DEBUG to a non-zero value.  Try the -D option to "pilfile.py" and see what happens.
-    to a non-zero value.  Try the -D option to "pilfile.py" and see what
-    happens.
 
 - Don't crash on "atend" constructs in PostScript files.
 
-- Only the Image module imports _imaging directly.  Other modules
+- Only the Image module imports _imaging directly.  Other modules should refer to the binding module as "Image.core".
-    should refer to the binding module as "Image.core".
 
 0.0 to 0.1 (b1)
 ------------
 
 - A handbook is available (distributed separately).
 
-- The coordinate system is changed so that (0,0) is now located
+- The coordinate system is changed so that (0,0) is now located in the upper left corner.  This is in compliancy with ISO 12087 and 90% of all other image processing and graphics libraries.
-    in the upper left corner.  This is in compliancy with ISO 12087
-    and 90% of all other image processing and graphics libraries.
 
-- Modes "1" (bilevel) and "P" (palette) have been introduced.  Note
+- Modes "1" (bilevel) and "P" (palette) have been introduced.  Note that bilevel images are stored with one byte per pixel.
-    that bilevel images are stored with one byte per pixel.
 
-- The Image "crop" and "paste" methods now accepts None as the
+- The Image "crop" and "paste" methods now accepts None as the box argument, to refer to the full image (self, that is).
-    box argument, to refer to the full image (self, that is).
 
 - The Image "crop" method now works properly.
 
-- The Image "point" method is now available.  You can use either a
+- The Image "point" method is now available.  You can use either a lookup table or a function taking one argument.
-    lookup table or a function taking one argument.
 
 - The Image join function has been renamed to "merge".
 
-- An Image "composite" function has been added.  It is identical
+- An Image "composite" function has been added.  It is identical to copy() followed by paste(mask).
-    to copy() followed by paste(mask).
 
-- An Image "eval" function has been added.  It is currently identical
+- An Image "eval" function has been added.  It is currently identical to point(function); that is, only a single image can be processed.
-    to point(function); that is, only a single image can be processed.
 
-- A set of channel operations has been added.  See the "ImageChops"
+- A set of channel operations has been added.  See the "ImageChops" module, test_chops.py, and the handbook for details.
-    module, test_chops.py, and the handbook for details.
 
-- Added the "pilconvert" utility, which converts image files.  Note
+- Added the "pilconvert" utility, which converts image files.  Note that the number of output formats are still quite restricted.
-    that the number of output formats are still quite restricted.
 
-- Added the "pilfile" utility, which quickly identifies image files
+- Added the "pilfile" utility, which quickly identifies image files (without loading them, in most cases).
-    (without loading them, in most cases).
 
-- Added the "pilprint" utility, which prints image files to PostScript
+- Added the "pilprint" utility, which prints image files to PostScript printers.
-    printers.
 
-- Added a rudimentary version of the "pilview" utility, which is
+- Added a rudimentary version of the "pilview" utility, which is simple image viewer based on Tk.  Only File/Exit and Image/Next works properly.
-    simple image viewer based on Tk.  Only File/Exit and Image/Next
-    works properly.
 
-- An interface to Tk has been added.  See "Lib/ImageTk.py" and README
+- An interface to Tk has been added.  See "Lib/ImageTk.py" and README for details.
-    for details.
 
-- An interface to Jack Jansen's Img library has been added (thanks to
+- An interface to Jack Jansen's Img library has been added (thanks to Jack).  This allows you to read images through the Img extensions file format handlers.  See the file "Lib/ImgExtImagePlugin.py" for details.
-    Jack).  This allows you to read images through the Img extensions file
-    format handlers.  See the file "Lib/ImgExtImagePlugin.py" for details.
 
-- PostScript printing is provided through the PSDraw module.  See the
+- PostScript printing is provided through the PSDraw module.  See the handbook for details.
-    handbook for details.