Removed some extra indentation that slipped in at some point

src/zc/buildout/easy_install.txt

@@ -107,7 +107,7 @@ We have a link server that has a number of eggs:
     <a href="other-1.0-py2.4.egg">other-1.0-py2.4.egg</a><br>
     </body></html>
 
- Let's make a directory and install the demo egg to it, using the demo:
+Let's make a directory and install the demo egg to it, using the demo:
 
     >>> dest = tmpdir('sample-install')
     >>> import zc.buildout.easy_install
@@ -115,28 +115,28 @@ We have a link server that has a number of eggs:
     ...     ['demo==0.2'], dest,
     ...     links=[link_server], index=link_server+'index/')
 
- We requested version 0.2 of the demo distribution to be installed into
- the destination server.  We specified that we should search for links
- on the link server and that we should use the (empty) link server
- index directory as a package index.
+We requested version 0.2 of the demo distribution to be installed into
+the destination server.  We specified that we should search for links
+on the link server and that we should use the (empty) link server
+index directory as a package index.
 
- The working set contains the distributions we retrieved.
+The working set contains the distributions we retrieved.
 
     >>> for dist in ws:
     ...     print_(dist)
     demo 0.2
     demoneeded 1.1
 
- We got demoneeded because it was a dependency of demo.
+We got demoneeded because it was a dependency of demo.
 
- And the actual eggs were added to the eggs directory.
+And the actual eggs were added to the eggs directory.
 
     >>> ls(dest)
     d  demo-0.2-py2.4.egg
     d  demoneeded-1.1-py2.4.egg
 
- If we remove the version restriction on demo, but specify a false
- value for newest, no new distributions will be installed:
+If we remove the version restriction on demo, but specify a false
+value for newest, no new distributions will be installed:
 
     >>> ws = zc.buildout.easy_install.install(
     ...     ['demo'], dest, links=[link_server], index=link_server+'index/',
@@ -145,7 +145,7 @@ We have a link server that has a number of eggs:
     d  demo-0.2-py2.4.egg
     d  demoneeded-1.1-py2.4.egg
 
- If we leave off the newest option, we'll get an update for demo:
+If we leave off the newest option, we'll get an update for demo:
 
     >>> ws = zc.buildout.easy_install.install(
     ...     ['demo'], dest, links=[link_server], index=link_server+'index/')
@@ -154,15 +154,15 @@ We have a link server that has a number of eggs:
     d  demo-0.3-py2.4.egg
     d  demoneeded-1.1-py2.4.egg
 
- Note that we didn't get the newest versions available.  There were
- release candidates for newer versions of both packages. By default,
- final releases are preferred.  We can change this behavior using the
- prefer_final function:
+Note that we didn't get the newest versions available.  There were
+release candidates for newer versions of both packages. By default,
+final releases are preferred.  We can change this behavior using the
+prefer_final function:
 
     >>> zc.buildout.easy_install.prefer_final(False)
     True
 
- The old setting is returned.
+The old setting is returned.
 
     >>> ws = zc.buildout.easy_install.install(
     ...     ['demo'], dest, links=[link_server], index=link_server+'index/')
@@ -178,14 +178,14 @@ We have a link server that has a number of eggs:
     d  demoneeded-1.1-py2.4.egg
     d  demoneeded-1.2c1-py2.4.egg
 
- Let's put the setting back to the default.
+Let's put the setting back to the default.
 
     >>> zc.buildout.easy_install.prefer_final(True)
     False
 
- We can supply additional distributions.  We can also supply
- specifications for distributions that would normally be found via
- dependencies.  We might do this to specify a specific version.
+We can supply additional distributions.  We can also supply
+specifications for distributions that would normally be found via
+dependencies.  We might do this to specify a specific version.
 
     >>> ws = zc.buildout.easy_install.install(
     ...     ['demo', 'other', 'demoneeded==1.0'], dest,
@@ -208,15 +208,15 @@ We have a link server that has a number of eggs:
 
     >>> rmdir(dest)
 
- Specifying version information independent of requirements
- ----------------------------------------------------------
+Specifying version information independent of requirements
+----------------------------------------------------------
 
- Sometimes it's useful to specify version information independent of
- normal requirements specifications.  For example, a buildout may need
- to lock down a set of versions, without having to put put version
- numbers in setup files or part definitions.  If a dictionary is passed
- to the install function, mapping project names to version numbers,
- then the versions numbers will be used.
+Sometimes it's useful to specify version information independent of
+normal requirements specifications.  For example, a buildout may need
+to lock down a set of versions, without having to put put version
+numbers in setup files or part definitions.  If a dictionary is passed
+to the install function, mapping project names to version numbers,
+then the versions numbers will be used.
 
     >>> ws = zc.buildout.easy_install.install(
     ...     ['demo'], dest, links=[link_server], index=link_server+'index/',
@@ -224,12 +224,12 @@ We have a link server that has a number of eggs:
     >>> [d.version for d in ws]
     ['0.2', '1.0']
 
- In this example, we specified a version for demoneeded, even though we
- didn't define a requirement for it.  The versions specified apply to
- dependencies as well as the specified requirements.
+In this example, we specified a version for demoneeded, even though we
+didn't define a requirement for it.  The versions specified apply to
+dependencies as well as the specified requirements.
 
- If we specify a version that's incompatible with a requirement, then
- we'll get an error:
+If we specify a version that's incompatible with a requirement, then
+we'll get an error:
 
     >>> from zope.testing.loggingsupport import InstalledHandler
     >>> handler = InstalledHandler('zc.buildout.easy_install')
@@ -252,8 +252,8 @@ We have a link server that has a number of eggs:
 
     >>> handler.clear()
 
- If no versions are specified, a debugging message will be output
- reporting that a version was picked automatically:
+If no versions are specified, a debugging message will be output
+reporting that a version was picked automatically:
 
     >>> ws = zc.buildout.easy_install.install(
     ...     ['demo'], dest, links=[link_server], index=link_server+'index/',
@@ -300,12 +300,12 @@ We have a link server that has a number of eggs:
     >>> handler.uninstall()
     >>> logging.getLogger('zc.buildout.easy_install').propagate = True
 
- We can request that we get an error if versions are picked:
+We can request that we get an error if versions are picked:
 
     >>> zc.buildout.easy_install.allow_picked_versions(False)
     True
 
- (The old setting is returned.)
+(The old setting is returned.)
 
     >>> ws = zc.buildout.easy_install.install(
     ...     ['demo'], dest, links=[link_server], index=link_server+'index/',
@@ -317,23 +317,23 @@ We have a link server that has a number of eggs:
     >>> zc.buildout.easy_install.allow_picked_versions(True)
     False
 
- The function default_versions can be used to get and set default
- version information to be used when no version information is passes.
- If called with an argument, it sets the default versions:
+The function default_versions can be used to get and set default
+version information to be used when no version information is passes.
+If called with an argument, it sets the default versions:
 
     >>> zc.buildout.easy_install.default_versions(dict(demoneeded='1'))
     ... # doctest: +ELLIPSIS
     {...}
 
- It always returns the previous default versions.  If called without an
- argument, it simply returns the default versions without changing
- them:
+It always returns the previous default versions.  If called without an
+argument, it simply returns the default versions without changing
+them:
 
     >>> zc.buildout.easy_install.default_versions()
     {'demoneeded': '1'}
 
- So with the default versions set, we'll get the requested version even
- if the versions option isn't used:
+So with the default versions set, we'll get the requested version even
+if the versions option isn't used:
 
     >>> ws = zc.buildout.easy_install.install(
     ...     ['demo'], dest, links=[link_server], index=link_server+'index/',
@@ -342,8 +342,8 @@ We have a link server that has a number of eggs:
     >>> [d.version for d in ws]
     ['0.3', '1.0']
 
- Of course, we can unset the default versions by passing an empty
- dictionary:
+Of course, we can unset the default versions by passing an empty
+dictionary:
 
     >>> zc.buildout.easy_install.default_versions({})
     {'demoneeded': '1'}
@@ -355,43 +355,43 @@ We have a link server that has a number of eggs:
     >>> [d.version for d in ws]
     ['0.3', '1.1']
 
- Dependency links
- ----------------
+Dependency links
+----------------
 
- Setuptools allows metadata that describes where to search for package
- dependencies. This option is called dependency_links. Buildout has its
- own notion of where to look for dependencies, but it also uses the
- setup tools dependency_links information if it's available.
+Setuptools allows metadata that describes where to search for package
+dependencies. This option is called dependency_links. Buildout has its
+own notion of where to look for dependencies, but it also uses the
+setup tools dependency_links information if it's available.
 
- Let's demo this by creating an egg that specifies dependency_links.
+Let's demo this by creating an egg that specifies dependency_links.
 
- To begin, let's create a new egg repository. This repository hold a
- newer version of the 'demoneeded' egg than the sample repository does.
+To begin, let's create a new egg repository. This repository hold a
+newer version of the 'demoneeded' egg than the sample repository does.
 
     >>> repoloc = tmpdir('repo')
     >>> from zc.buildout.tests import create_egg
     >>> create_egg('demoneeded', '1.2', repoloc)
     >>> link_server2 = start_server(repoloc)
 
- Turn on logging on this server so that we can see when eggs are pulled
- from it.
+Turn on logging on this server so that we can see when eggs are pulled
+from it.
 
     >>> _ = get(link_server2 + 'enable_server_logging')
     GET 200 /enable_server_logging
 
- Now we can create an egg that specifies that its dependencies are
- found on this server.
+Now we can create an egg that specifies that its dependencies are
+found on this server.
 
     >>> repoloc = tmpdir('repo2')
     >>> create_egg('hasdeps', '1.0', repoloc,
     ...            install_requires = "'demoneeded'",
     ...            dependency_links = [link_server2])
 
- Let's add the egg to another repository.
+Let's add the egg to another repository.
 
     >>> link_server3 = start_server(repoloc)
 
- Now let's install the egg.
+Now let's install the egg.
 
     >>> example_dest = tmpdir('example-install')
     >>> workingset = zc.buildout.easy_install.install(
@@ -400,11 +400,11 @@ We have a link server that has a number of eggs:
     GET 200 /
     GET 200 /demoneeded-1.2-pyN.N.egg
 
- The server logs show that the dependency was retrieved from the server
- specified in the dependency_links.
+The server logs show that the dependency was retrieved from the server
+specified in the dependency_links.
 
- Now let's see what happens if we provide two different ways to retrieve
- the dependencies.
+Now let's see what happens if we provide two different ways to retrieve
+the dependencies.
 
     >>> rmdir(example_dest)
     >>> example_dest = tmpdir('example-install')
@@ -414,14 +414,14 @@ We have a link server that has a number of eggs:
     GET 200 /
     GET 200 /demoneeded-1.2-pyN.N.egg
 
- Once again the dependency is fetched from the logging server even
- though it is also available from the non-logging server. This is
- because the version on the logging server is newer and buildout
- normally chooses the newest egg available.
+Once again the dependency is fetched from the logging server even
+though it is also available from the non-logging server. This is
+because the version on the logging server is newer and buildout
+normally chooses the newest egg available.
 
- If you wish to control where dependencies come from regardless of
- dependency_links setup metadata use the 'use_dependency_links' option
- to zc.buildout.easy_install.install().
+If you wish to control where dependencies come from regardless of
+dependency_links setup metadata use the 'use_dependency_links' option
+to zc.buildout.easy_install.install().
 
     >>> rmdir(example_dest)
     >>> example_dest = tmpdir('example-install')
@@ -430,19 +430,19 @@ We have a link server that has a number of eggs:
     ...     links=[link_server, link_server3],
     ...     use_dependency_links=False)
 
- Notice that this time the dependency egg is not fetched from the
- logging server. When you specify not to use dependency_links, eggs
- will only be searched for using the links you explicitly provide.
+Notice that this time the dependency egg is not fetched from the
+logging server. When you specify not to use dependency_links, eggs
+will only be searched for using the links you explicitly provide.
 
- Another way to control this option is with the
- zc.buildout.easy_install.use_dependency_links() function. This
- function sets the default behavior for the zc.buildout.easy_install()
- function.
+Another way to control this option is with the
+zc.buildout.easy_install.use_dependency_links() function. This
+function sets the default behavior for the zc.buildout.easy_install()
+function.
 
     >>> zc.buildout.easy_install.use_dependency_links(False)
     True
 
- The function returns its previous setting.
+The function returns its previous setting.
 
     >>> rmdir(example_dest)
     >>> example_dest = tmpdir('example-install')
@@ -450,8 +450,8 @@ We have a link server that has a number of eggs:
     ...     ['hasdeps'], example_dest, index=link_server+'index/',
     ...     links=[link_server, link_server3])
 
- It can be overridden by passing a keyword argument to the install
- function.
+It can be overridden by passing a keyword argument to the install
+function.
 
     >>> rmdir(example_dest)
     >>> example_dest = tmpdir('example-install')
@@ -461,7 +461,7 @@ We have a link server that has a number of eggs:
     ...	    use_dependency_links=True)
     GET 200 /demoneeded-1.2-pyN.N.egg
 
- To return the dependency_links behavior to normal call the function again.
+To return the dependency_links behavior to normal call the function again.
 
     >>> zc.buildout.easy_install.use_dependency_links(True)
     False
@@ -473,50 +473,50 @@ We have a link server that has a number of eggs:
     GET 200 /demoneeded-1.2-pyN.N.egg
 
 
- Script generation
- -----------------
+Script generation
+-----------------
 
- The easy_install module provides support for creating scripts from
- eggs.  It provides a function similar to setuptools except that it
- provides facilities for baking a script's path into the script.  This
- has two advantages:
+The easy_install module provides support for creating scripts from
+eggs.  It provides a function similar to setuptools except that it
+provides facilities for baking a script's path into the script.  This
+has two advantages:
 
- - The eggs to be used by a script are not chosen at run time, making
+- The eggs to be used by a script are not chosen at run time, making
   startup faster and, more importantly, deterministic.
 
- - The script doesn't have to import pkg_resources because the logic
+- The script doesn't have to import pkg_resources because the logic
   that pkg_resources would execute at run time is executed at
   script-creation time.
 
- The scripts method can be used to generate scripts. Let's create a
- destination directory for it to place them in:
+The scripts method can be used to generate scripts. Let's create a
+destination directory for it to place them in:
 
     >>> import tempfile
     >>> bin = tmpdir('bin')
 
- Now, we'll use the scripts method to generate scripts in this directory
- from the demo egg:
+Now, we'll use the scripts method to generate scripts in this directory
+from the demo egg:
 
     >>> import sys
     >>> scripts = zc.buildout.easy_install.scripts(
     ...     ['demo'], ws, sys.executable, bin)
 
- the three arguments we passed were:
+the three arguments we passed were:
 
- 1. A sequence of distribution requirements.  These are of the same
+1. A sequence of distribution requirements.  These are of the same
    form as setuptools requirements.  Here we passed a single
    requirement, for the version 0.1 demo distribution.
 
- 2. A working set,
+2. A working set,
 
- 3. The destination directory.
+3. The destination directory.
 
- The bin directory now contains a generated script:
+The bin directory now contains a generated script:
 
     >>> ls(bin)
     -  demo
 
- The return value is a list of the scripts generated:
+The return value is a list of the scripts generated:
 
     >>> import os, sys
     >>> if sys.platform == 'win32':
@@ -526,12 +526,12 @@ We have a link server that has a number of eggs:
     ...     scripts == [os.path.join(bin, 'demo')]
     True
 
- Note that in Windows, 2 files are generated for each script.  A script
- file, ending in '-script.py', and an exe file that allows the script
- to be invoked directly without having to specify the Python
- interpreter and without having to provide a '.py' suffix.
+Note that in Windows, 2 files are generated for each script.  A script
+file, ending in '-script.py', and an exe file that allows the script
+to be invoked directly without having to specify the Python
+interpreter and without having to provide a '.py' suffix.
 
- The demo script run the entry point defined in the demo egg:
+The demo script run the entry point defined in the demo egg:
 
     >>> cat(bin, 'demo') # doctest: +NORMALIZE_WHITESPACE
     #!/usr/local/bin/python2.7
@@ -547,15 +547,15 @@ We have a link server that has a number of eggs:
     if __name__ == '__main__':
         sys.exit(eggrecipedemo.main())
 
- Some things to note:
+Some things to note:
 
- - The demo and demoneeded eggs are added to the beginning of sys.path.
+- The demo and demoneeded eggs are added to the beginning of sys.path.
 
- - The module for the script entry point is imported and the entry
+- The module for the script entry point is imported and the entry
   point, in this case, 'main', is run.
 
- Rather than requirement strings, you can pass tuples containing 3
- strings:
+Rather than requirement strings, you can pass tuples containing 3
+strings:
 
   - A script name,
 
@@ -563,8 +563,8 @@ We have a link server that has a number of eggs:
 
   - An attribute expression for an entry point within the module.
 
- For example, we could have passed entry point information directly
- rather than passing a requirement:
+For example, we could have passed entry point information directly
+rather than passing a requirement:
 
     >>> scripts = zc.buildout.easy_install.scripts(
     ...     [('demo', 'eggrecipedemo', 'main')], ws,
@@ -584,14 +584,14 @@ We have a link server that has a number of eggs:
     if __name__ == '__main__':
         sys.exit(eggrecipedemo.main())
 
- Passing entry-point information directly is handy when using eggs (or
- distributions) that don't declare their entry points, such as
- distributions that aren't based on setuptools.
+Passing entry-point information directly is handy when using eggs (or
+distributions) that don't declare their entry points, such as
+distributions that aren't based on setuptools.
 
- The interpreter keyword argument can be used to generate a script that can
- be used to invoke the Python interactive interpreter with the path set
- based on the working set.  This generated script can also be used to
- run other scripts with the path set on the working set:
+The interpreter keyword argument can be used to generate a script that can
+be used to invoke the Python interactive interpreter with the path set
+based on the working set.  This generated script can also be used to
+run other scripts with the path set on the working set:
 
     >>> scripts = zc.buildout.easy_install.scripts(
     ...     ['demo'], ws, sys.executable, bin, interpreter='py')
@@ -611,8 +611,8 @@ We have a link server that has a number of eggs:
     ...                 os.path.join(bin, 'py')]
     True
 
- The py script simply runs the Python interactive interpreter with
- the path set:
+The py script simply runs the Python interactive interpreter with
+the path set:
 
     >>> cat(bin, 'py') # doctest: +NORMALIZE_WHITESPACE
     #!/usr/local/bin/python2.7
@@ -651,7 +651,7 @@ We have a link server that has a number of eggs:
         del _interactive
         __import__("code").interact(banner="", local=globals())
 
- If invoked with a script name and arguments, it will run that script, instead.
+If invoked with a script name and arguments, it will run that script, instead.
 
     >>> write('ascript', r'''
     ... "demo doc"
@@ -664,8 +664,8 @@ We have a link server that has a number of eggs:
     ['ascript', 'a', 'b', 'c']
     ('__main__', 'ascript', 'demo doc')
 
- For Python 2.5 and higher, you can also use the -m option to run a
- module:
+For Python 2.5 and higher, you can also use the -m option to run a
+module:
 
     >>> if sys.version_info < (2, 5):
     ...    print ('usage: pdb.py blah blah blah')
@@ -677,9 +677,9 @@ We have a link server that has a number of eggs:
     >>> print_(system(join(bin, 'py')+' -m pdb what'), end='')
     Error: what does not exist
 
- An additional argument can be passed to define which scripts to install
- and to provide script names. The argument is a dictionary mapping
- original script names to new script names.
+An additional argument can be passed to define which scripts to install
+and to provide script names. The argument is a dictionary mapping
+original script names to new script names.
 
     >>> bin = tmpdir('bin2')
     >>> scripts = zc.buildout.easy_install.scripts(
@@ -697,11 +697,11 @@ We have a link server that has a number of eggs:
     >>> print_(system(os.path.join(bin, 'run')), end='')
     3 1
 
- Including extra paths in scripts
- --------------------------------
+Including extra paths in scripts
+--------------------------------
 
- We can pass a keyword argument, extra paths, to cause additional paths
- to be included in the a generated script:
+We can pass a keyword argument, extra paths, to cause additional paths
+to be included in the a generated script:
 
     >>> foo = tmpdir('foo')
     >>> scripts = zc.buildout.easy_install.scripts(
@@ -723,12 +723,12 @@ We have a link server that has a number of eggs:
     if __name__ == '__main__':
         sys.exit(eggrecipedemo.main())
 
- Providing script arguments
- --------------------------
+Providing script arguments
+--------------------------
 
- An "argument" keyword argument can be used to pass arguments to an
- entry point.  The value passed is a source string to be placed between the
- parentheses in the call:
+An "argument" keyword argument can be used to pass arguments to an
+entry point.  The value passed is a source string to be placed between the
+parentheses in the call:
 
     >>> scripts = zc.buildout.easy_install.scripts(
     ...    ['demo'], ws, sys.executable, bin, dict(demo='run'),
@@ -747,10 +747,10 @@ We have a link server that has a number of eggs:
     if __name__ == '__main__':
         sys.exit(eggrecipedemo.main(1, 2))
 
- Passing initialization code
- ---------------------------
+Passing initialization code
+---------------------------
 
- You can also pass script initialization code:
+You can also pass script initialization code:
 
     >>> scripts = zc.buildout.easy_install.scripts(
     ...    ['demo'], ws, sys.executable, bin, dict(demo='run'),
@@ -773,13 +773,13 @@ We have a link server that has a number of eggs:
     if __name__ == '__main__':
         sys.exit(eggrecipedemo.main(1, 2))
 
- Relative paths
- --------------
+Relative paths
+--------------
 
- Sometimes, you want to be able to move a buildout directory around and
- have scripts still work without having to rebuild them.  We can
- control this using the relative_paths option to install.  You need
- to pass a common base directory of the scripts and eggs:
+Sometimes, you want to be able to move a buildout directory around and
+have scripts still work without having to rebuild them.  We can
+control this using the relative_paths option to install.  You need
+to pass a common base directory of the scripts and eggs:
 
     >>> bo = tmpdir('bo')
     >>> ba = tmpdir('ba')
@@ -819,15 +819,15 @@ We have a link server that has a number of eggs:
     if __name__ == '__main__':
         sys.exit(eggrecipedemo.main())
 
- Note that the extra path we specified that was outside the directory
- passed as relative_paths wasn't converted to a relative path.
+Note that the extra path we specified that was outside the directory
+passed as relative_paths wasn't converted to a relative path.
 
- Of course, running the script works:
+Of course, running the script works:
 
     >>> print_(system(join(bo, 'bin', 'run')), end='')
     3 1
 
- We specified an interpreter and its paths are adjusted too:
+We specified an interpreter and its paths are adjusted too:
 
     >>> cat(bo, 'bin', 'py')
     #!/usr/local/bin/python2.7
@@ -875,12 +875,12 @@ We have a link server that has a number of eggs:
         __import__("code").interact(banner="", local=globals())
 
 
- Installing distutils-style scripts
- ----------------------------------
+Installing distutils-style scripts
+----------------------------------
 
- Most python libraries use the console_scripts entry point nowadays.  But
- several still have a ``scripts=['bin/something']`` in their setup() call.
- Buildout also installs those:
+Most python libraries use the console_scripts entry point nowadays.  But
+several still have a ``scripts=['bin/something']`` in their setup() call.
+Buildout also installs those:
 
     >>> distdir = tmpdir('distutilsscriptdir')
     >>> distbin = tmpdir('distutilsscriptbin')
@@ -892,7 +892,7 @@ We have a link server that has a number of eggs:
     >>> ls(distbin)
     -  distutilsscript
 
- It also works for zipped eggs:
+It also works for zipped eggs:
 
     >>> distdir2 = tmpdir('distutilsscriptdir2')
     >>> distbin2 = tmpdir('distutilsscriptbin2')
@@ -904,10 +904,10 @@ We have a link server that has a number of eggs:
     >>> ls(distbin2)
     -  distutilsscript
 
- Distutils copies the script files verbatim, apart from a line at the top that
- looks like ``#!/usr/bin/python``, which gets replaced by the actual python
- interpreter.  Buildout does the same, but additionally also adds the sys.path
- like for the console_scripts:
+Distutils copies the script files verbatim, apart from a line at the top that
+looks like ``#!/usr/bin/python``, which gets replaced by the actual python
+interpreter.  Buildout does the same, but additionally also adds the sys.path
+like for the console_scripts:
 
     >>> cat(distbin, 'distutilsscript')
     #!/usr/local/bin/python2.7
@@ -920,37 +920,37 @@ We have a link server that has a number of eggs:
     <BLANKLINE>
     import sys; sys.stdout.write("distutils!\n")
 
- Due to the nature of distutils scripts, buildout cannot pass arguments as
- there's no specific method to pass them to.
+Due to the nature of distutils scripts, buildout cannot pass arguments as
+there's no specific method to pass them to.
 
 
- Handling custom build options for extensions provided in source distributions
- -----------------------------------------------------------------------------
+Handling custom build options for extensions provided in source distributions
+-----------------------------------------------------------------------------
 
- Sometimes, we need to control how extension modules are built.  The
- build function provides this level of control.  It takes a single
- package specification, downloads a source distribution, and builds it
- with specified custom build options.
+Sometimes, we need to control how extension modules are built.  The
+build function provides this level of control.  It takes a single
+package specification, downloads a source distribution, and builds it
+with specified custom build options.
 
- The build function takes 3 positional arguments:
+The build function takes 3 positional arguments:
 
- spec
+spec
    A package specification for a source distribution
 
- dest
+dest
    A destination directory
 
- build_ext
+build_ext
    A dictionary of options to be passed to the distutils build_ext
    command when building extensions.
 
- It supports a number of optional keyword arguments:
+It supports a number of optional keyword arguments:
 
- links
+links
    a sequence of URLs, file names, or directories to look for
    links to distributions,
 
- index
+index
    The URL of an index server, or almost any other valid URL. :)
 
    If not specified, the Python Package Index,
@@ -961,25 +961,25 @@ We have a link server that has a number of eggs:
    we'll just point to an empty directory on our link server.  This
    will make our examples run a little bit faster.
 
- path
+path
    A list of additional directories to search for locally-installed
    distributions.
 
- newest
+newest
    A boolean value indicating whether to search for new distributions
    when already-installed distributions meet the requirement.  When
    this is true, the default, and when the destination directory is
    not None, then the install function will search for the newest
    distributions that satisfy the requirements.
 
- versions
+versions
    A dictionary mapping project names to version numbers to be used
    when selecting distributions.  This can be used to specify a set of
    distribution versions independent of other requirements.
 
 
- Our link server included a source distribution that includes a simple
- extension, extdemo.c::
+Our link server included a source distribution that includes a simple
+extension, extdemo.c::
 
   #include <Python.h>
   #include <extdemo.h>
@@ -998,11 +998,11 @@ We have a link server that has a number of eggs:
   #endif
   }
 
- The extension depends on a system-dependent include file, extdemo.h,
- that defines a constant, EXTDEMO, that is exposed by the extension.
+The extension depends on a system-dependent include file, extdemo.h,
+that defines a constant, EXTDEMO, that is exposed by the extension.
 
- We'll add an include directory to our sample buildout and add the
- needed include file to it:
+We'll add an include directory to our sample buildout and add the
+needed include file to it:
 
     >>> mkdir('include')
     >>> write('include', 'extdemo.h',
@@ -1010,8 +1010,8 @@ We have a link server that has a number of eggs:
     ... #define EXTDEMO 42
     ... """)
 
- Now, we can use the build function to create an egg from the source
- distribution:
+Now, we can use the build function to create an egg from the source
+distribution:
 
     >>> zc.buildout.easy_install.build(
     ...   'extdemo', dest,
@@ -1019,9 +1019,9 @@ We have a link server that has a number of eggs:
     ...   links=[link_server], index=link_server+'index/')
     ['/sample-install/extdemo-1.4-py2.4-unix-i686.egg']
 
- The function returns the list of eggs
+The function returns the list of eggs
 
- Now if we look in our destination directory, we see we have an extdemo egg:
+Now if we look in our destination directory, we see we have an extdemo egg:
 
     >>> ls(dest)
     d  demo-0.2-py2.4.egg
@@ -1030,7 +1030,7 @@ We have a link server that has a number of eggs:
     d  demoneeded-1.1-py2.4.egg
     d  extdemo-1.4-py2.4-unix-i686.egg
 
- Let's update our link server with a new version of extdemo:
+Let's update our link server with a new version of extdemo:
 
     >>> update_extdemo()
     >>> print_(get(link_server), end='')
@@ -1050,13 +1050,13 @@ We have a link server that has a number of eggs:
     <a href="other-1.0-py2.4.egg">other-1.0-py2.4.egg</a><br>
     </body></html>
 
- The easy_install caches information about servers to reduce network
- access. To see the update, we have to call the clear_index_cache
- function to clear the index cache:
+The easy_install caches information about servers to reduce network
+access. To see the update, we have to call the clear_index_cache
+function to clear the index cache:
 
     >>> zc.buildout.easy_install.clear_index_cache()
 
- If we run build with newest set to False, we won't get an update:
+If we run build with newest set to False, we won't get an update:
 
     >>> zc.buildout.easy_install.build(
     ...   'extdemo', dest,
@@ -1072,8 +1072,8 @@ We have a link server that has a number of eggs:
     d  demoneeded-1.1-py2.4.egg
     d  extdemo-1.4-py2.4-unix-i686.egg
 
- But if we run it with the default True setting for newest, then we'll
- get an updated egg:
+But if we run it with the default True setting for newest, then we'll
+get an updated egg:
 
     >>> zc.buildout.easy_install.build(
     ...   'extdemo', dest,
@@ -1089,10 +1089,10 @@ We have a link server that has a number of eggs:
     d  extdemo-1.4-py2.4-unix-i686.egg
     d  extdemo-1.5-py2.4-unix-i686.egg
 
- The versions option also influences the versions used.  For example,
- if we specify a version for extdemo, then that will be used, even
- though it isn't the newest.  Let's clean out the destination directory
- first:
+The versions option also influences the versions used.  For example,
+if we specify a version for extdemo, then that will be used, even
+though it isn't the newest.  Let's clean out the destination directory
+first:
 
     >>> import os
     >>> for name in os.listdir(dest):
@@ -1108,29 +1108,29 @@ We have a link server that has a number of eggs:
     >>> ls(dest)
     d  extdemo-1.4-py2.4-unix-i686.egg
 
- Handling custom build options for extensions in develop eggs
- ------------------------------------------------------------
+Handling custom build options for extensions in develop eggs
+------------------------------------------------------------
 
- The develop function is similar to the build function, except that,
- rather than building an egg from a source directory containing a
- setup.py script.
+The develop function is similar to the build function, except that,
+rather than building an egg from a source directory containing a
+setup.py script.
 
- The develop function takes 2 positional arguments:
+The develop function takes 2 positional arguments:
 
- setup
+setup
    The path to a setup script, typically named "setup.py", or a
    directory containing a setup.py script.
 
- dest
+dest
    The directory to install the egg link to
 
- It supports some optional keyword argument:
+It supports some optional keyword argument:
 
- build_ext
+build_ext
    A dictionary of options to be passed to the distutils build_ext
    command when building extensions.
 
- We have a local directory containing the extdemo source:
+We have a local directory containing the extdemo source:
 
     >>> ls(extdemo)
     -  MANIFEST
@@ -1139,62 +1139,62 @@ We have a link server that has a number of eggs:
     -  extdemo.c
     -  setup.py
 
- Now, we can use the develop function to create a develop egg from the source
- distribution:
+Now, we can use the develop function to create a develop egg from the source
+distribution:
 
     >>> zc.buildout.easy_install.develop(
     ...   extdemo, dest,
     ...   {'include-dirs': os.path.join(sample_buildout, 'include')})
     '/sample-install/extdemo.egg-link'
 
- The name of the egg link created is returned.
+The name of the egg link created is returned.
 
- Now if we look in our destination directory, we see we have an extdemo
- egg link:
+Now if we look in our destination directory, we see we have an extdemo
+egg link:
 
     >>> ls(dest)
     d  extdemo-1.4-py2.4-unix-i686.egg
     -  extdemo.egg-link
 
- And that the source directory contains the compiled extension:
+And that the source directory contains the compiled extension:
 
     >>> contents = os.listdir(extdemo)
     >>> bool([f for f in contents if f.endswith('.so') or f.endswith('.pyd')])
     True
 
- Download cache
- --------------
+Download cache
+--------------
 
- Normally, when distributions are installed, if any processing is
- needed, they are downloaded from the internet to a temporary directory
- and then installed from there.  A download cache can be used to avoid
- the download step.  This can be useful to reduce network access and to
- create source distributions of an entire buildout.
+Normally, when distributions are installed, if any processing is
+needed, they are downloaded from the internet to a temporary directory
+and then installed from there.  A download cache can be used to avoid
+the download step.  This can be useful to reduce network access and to
+create source distributions of an entire buildout.
 
- A download cache is specified by calling the download_cache
- function.  The function always returns the previous setting. If no
- argument is passed, then the setting is unchanged.  If an argument is
- passed, the download cache is set to the given path, which must point
- to an existing directory.  Passing None clears the cache setting.
+A download cache is specified by calling the download_cache
+function.  The function always returns the previous setting. If no
+argument is passed, then the setting is unchanged.  If an argument is
+passed, the download cache is set to the given path, which must point
+to an existing directory.  Passing None clears the cache setting.
 
- To see this work, we'll create a directory and set it as the cache
- directory:
+To see this work, we'll create a directory and set it as the cache
+directory:
 
     >>> cache = tmpdir('cache')
     >>> zc.buildout.easy_install.download_cache(cache)
 
- We'll recreate our destination directory:
+We'll recreate our destination directory:
 
     >>> remove(dest)
     >>> dest = tmpdir('sample-install')
 
- We'd like to see what is being fetched from the server, so we'll
- enable server logging:
+We'd like to see what is being fetched from the server, so we'll
+enable server logging:
 
     >>> _ = get(link_server+'enable_server_logging')
     GET 200 /enable_server_logging
 
- Now, if we install demo, and extdemo:
+Now, if we install demo, and extdemo:
 
     >>> ws = zc.buildout.easy_install.install(
     ...     ['demo==0.2'], dest,
@@ -1214,30 +1214,30 @@ We have a link server that has a number of eggs:
     GET 200 /extdemo-1.5.zip
     ['/sample-install/extdemo-1.5-py2.4-linux-i686.egg']
 
- Not only will we get eggs in our destination directory:
+Not only will we get eggs in our destination directory:
 
     >>> ls(dest)
     d  demo-0.2-py2.4.egg
     d  demoneeded-1.1-py2.4.egg
     d  extdemo-1.5-py2.4-linux-i686.egg
 
- But we'll get distributions in the cache directory:
+But we'll get distributions in the cache directory:
 
     >>> ls(cache)
     -  demo-0.2-py2.4.egg
     -  demoneeded-1.1.zip
     -  extdemo-1.5.zip
 
- The cache directory contains uninstalled distributions, such as zipped
- eggs or source distributions.
+The cache directory contains uninstalled distributions, such as zipped
+eggs or source distributions.
 
- Let's recreate our destination directory and clear the index cache:
+Let's recreate our destination directory and clear the index cache:
 
     >>> remove(dest)
     >>> dest = tmpdir('sample-install')
     >>> zc.buildout.easy_install.clear_index_cache()
 
- Now when we install the distributions:
+Now when we install the distributions:
 
     >>> ws = zc.buildout.easy_install.install(
     ...     ['demo==0.2'], dest,
@@ -1259,43 +1259,43 @@ We have a link server that has a number of eggs:
     d  demoneeded-1.1-py2.4.egg
     d  extdemo-1.5-py2.4-linux-i686.egg
 
- Note that we didn't download the distributions from the link server.
+Note that we didn't download the distributions from the link server.
 
- If we remove the restriction on demo, we'll download a newer version
- from the link server:
+If we remove the restriction on demo, we'll download a newer version
+from the link server:
 
     >>> ws = zc.buildout.easy_install.install(
     ...     ['demo'], dest,
     ...     links=[link_server], index=link_server+'index/')
     GET 200 /demo-0.3-py2.4.egg
 
- Normally, the download cache is the preferred source of downloads, but
- not the only one.
+Normally, the download cache is the preferred source of downloads, but
+not the only one.
 
- Installing solely from a download cache
- ---------------------------------------
+Installing solely from a download cache
+---------------------------------------
 
- A download cache can be used as the basis of application source
- releases.  In an application source release, we want to distribute an
- application that can be built without making any network accesses.  In
- this case, we distribute a download cache and tell the easy_install
- module to install from the download cache only, without making network
- accesses.  The install_from_cache function can be used to signal that
- packages should be installed only from the download cache.  The
- function always returns the previous setting.  Calling it with no
- arguments returns the current setting without changing it:
+A download cache can be used as the basis of application source
+releases.  In an application source release, we want to distribute an
+application that can be built without making any network accesses.  In
+this case, we distribute a download cache and tell the easy_install
+module to install from the download cache only, without making network
+accesses.  The install_from_cache function can be used to signal that
+packages should be installed only from the download cache.  The
+function always returns the previous setting.  Calling it with no
+arguments returns the current setting without changing it:
 
     >>> zc.buildout.easy_install.install_from_cache()
     False
 
- Calling it with a boolean value changes the setting and returns the
- previous setting:
+Calling it with a boolean value changes the setting and returns the
+previous setting:
 
     >>> zc.buildout.easy_install.install_from_cache(True)
     False
 
- Let's remove demo-0.3-py2.4.egg from the cache, clear the index cache,
- recreate the destination directory, and reinstall demo:
+Let's remove demo-0.3-py2.4.egg from the cache, clear the index cache,
+recreate the destination directory, and reinstall demo:
 
     >>> for  f in os.listdir(cache):
     ...     if f.startswith('demo-0.3-'):
@@ -1313,9 +1313,9 @@ We have a link server that has a number of eggs:
     d  demo-0.2-py2.4.egg
     d  demoneeded-1.1-py2.4.egg
 
- This time, we didn't download from or even query the link server.
+This time, we didn't download from or even query the link server.
 
- .. Disable the download cache:
+.. Disable the download cache:
 
     >>> zc.buildout.easy_install.download_cache(None)
     '/cache'