Remove gibberish paragraph from variable substitution section (was this ever true?), correct next paragraph to reflect current example.

The 'if not self._valid(ref)' branch is *always* executed because ref still includes the ${} substitution marker around it. Update the _valid regular expression to include the markers, shaving off 4 tests for every substitution.

with PyPI URLs (the old ones no more working)

version #. Grrrr.

selecting Python tests without Python 2.3 available, since I've lost
Python 2.3 in my upgrade to Mac OS X 2.5. :(

extra uses.

easier to test multiple versions at once.

1.0 coming soon. :)

zc.sourcedistribution.

leading to test failures.  The change also caused buildout to fail
with Python 2.3, which lacks a set builtin.

(just replaced the code-block with block, and added a Contents)

The list of eggs in generated scripts is sorted and duplicates removed. This prevents problems in WingIDE and makes it easier for humans to look at and use the list of eggs.

Added a configuration option that causes buildout to error if a
  version is picked. This is a nice safety belt when fixing all
  versions is intented, especially whan creating releases.

(This already-desired feature made it easier to write the test for
  the bug fix below. :)

Bug Fixed:

When installing from source releases, a version specification (via a
  buildout versions section) for setuptools was ignored when deciding
  which setuptools to use to build an egg from the source release.

Oops, forgot CHANGES.txt entry for r81245

151820: Add the distribution directory to sys.path when running
the setup.py script so that the setup.py script can import modules
from the distribution directory.

Fix verbose option handling of debug logging message

Now there's a buildout option (use-dependency-links) that allows you to 
disable setuptool dependency_links metadata.

When using a local find links or index, distributions weren't copied
 to the download cache.

Improved error message when no arguments are given to the setup
command.

The setup command no-longer requires a config file.

ref: https://bugs.launchpad.net/bugs/149352

  existing buildouts.  Use::

[buildout]
    prefer-final = true

to get the new policy.  The new policy will go into effect in
  buildout 2.

  both final and non-final versions satisfy a requirement, then the
  final version will be used even if it is older.  The normal way to
  override this for specific packages is to specifically require a
  non-final version, either specifically or via a lower bound.

- There is a buildout prefer-final version that can be used with a
  value of "false"::

prefer-final = false

To prefer newer versions, regardless of whether or not they are
  final, buildout-wide.

to work with recent change changes to use expanduser rather than
reading $HOME directly.