Optimizing topic

(I hope at some point this can go away because
https://github.com/buildout/buildout/issues/355)

* Added reference documentation for command-line options

- Intentionally didn't document -o, -O and -n

  Offline mode is an attractive nuisance.

  -n is unlikely to be needed and can be spelled newest=true

- Removed -o, -O and -n from command help.

- Sorted options alphabetically in the reference doc and command help.

- Removed documentation of the log-level option.  It just confuses things.
  I seriously doubt that anyone uses it.

* Added configuration-file syntax reference

Added missing section on conditional sections

Fortunately, I was able to move and update the not-bad doctest here,
because it was more doc than test.

easy_install: moar loggin' for fetchin'

Make it clear from where we're fetching a dist that we don't have
installed, reporting the specific URL or the path from inside the
download cache.

* Added topic on reusing option values and buildout config options reference

* unbroke capitalization

* added another todo

But maybe I should stop doing this because sphinx tells me about
missing references.

* note that paths are whitespace separated.

* fixed some minor wording bugs.

* Added a hidden test to check my understanding of interaction with install-from-cache

* Clarify modes and semantics of extends-cache

* emphasize that in newst mode, we always download configuration

* expanded on logging control

* clarified socket-timeout

* spelling and it's

* simplify user-default example

* warn about unpinning when using develop eggs

* discuss unpinning

* explain why unpinning with empty pin is useful.

* reverted examples to use longer more explict forms

* typos

* Added tests for variables-extending-and-substitutions.rst

Also added more test helpers.

* Use bobo rather than ZEO in tests of docs

To make the tests more lightweight, because bobo is much smaller.

To allow people without the ability to build extensions to follow along.

* Fixed: test index (used for testing docs) was set to wrong path

* I want to see which tests are being run

History

Bootstrapping topic

windows: scripts are implemented with 2 files, avoid burping on that

Motivation, history and Python packaging topic

draft getting started

Start on new docs

Update tox versions according to Makefile

For some reason, installation is taking insanely long for Python 2
(10x Py3). NFC, but this bears further investication, given that it's just copying eggs, except pyc re-compilation to get correct path.

- Now wait up to 99 seconds for builds to complete.

- handle build timeout by printing output (rather than a failing
  assertion, now that we know it can happen).

- Got rid of the broken out() function.

there is an error.  I'd been trying to avoid writing a file, but that
made things too complicated.  I've seen some hard to reproduce test
failures that make turning on debugging in response to a failure
impractical.  Hopefully, if we get a test failure now, we'll be able
to see WTF.

In an attempt prevent extra logging in text output.  I'm not sure if
this results in less garbage output than we had before. It definately
reduces spurious output from the new getting-started test.

In any case, these should be cleaned up.

But getting failures when running with some other tests. Weird.