split index and lower headings of old versions so TOC looks nicer

3 files changed, 92 insertions, 91 deletions

diff --git a/doc/source/goals.rst b/doc/source/goals.rst
new file mode 100644
index 0000000..96e3a33
--- /dev/null
+++ b/doc/source/goals.rst
@@ -0,0 +1,62 @@
+Goals
+-----
+
+The interface is based on `LuaJIT's FFI`_, and follows a few principles:
+
+* The goal is to call C code from Python without learning a 3rd language:
+  existing alternatives require users to learn domain specific language
+  (Cython_, SWIG_) or API (ctypes_). The CFFI design requires users to know
+  only C and Python, minimizing the extra bits of API that need to be learned.
+
+* Keep all the Python-related logic in Python so that you don't need to
+  write much C code (unlike `CPython native C extensions`_).
+
+* The preferred way is to work at the level of the API (Application
+  Programming Interface): the C compiler is called from the declarations
+  you write to validate and link to the C language constructs.
+  Alternatively, it is also possible to work at the ABI level
+  (Application Binary Interface), the way ctypes_ work.
+  However, on non-Windows platforms, C libraries typically
+  have a specified C API but not an ABI (e.g. they may
+  document a "struct" as having at least these fields, but maybe more).
+
+* Try to be complete.  For now some C99 constructs are not supported,
+  but all C89 should be, including macros (and including macro "abuses",
+  which you can `manually wrap`_ in saner-looking C functions).
+
+* Attempt to support both PyPy and CPython, with a reasonable path
+  for other Python implementations like IronPython and Jython.
+
+* Note that this project is **not** about embedding executable C code in
+  Python, unlike `Weave`_.  This is about calling existing C libraries
+  from Python.
+
+.. _`LuaJIT's FFI`: http://luajit.org/ext_ffi.html
+.. _`Cython`: http://www.cython.org
+.. _`SWIG`: http://www.swig.org/
+.. _`CPython native C extensions`: http://docs.python.org/extending/extending.html
+.. _`native C extensions`: http://docs.python.org/extending/extending.html
+.. _`ctypes`: http://docs.python.org/library/ctypes.html
+.. _`Weave`: http://wiki.scipy.org/Weave
+.. _`manually wrap`: overview.html#abi-versus-api
+
+Get started by reading `the overview`__.
+
+.. __: overview.html
+
+
+Comments and bugs
+-----------------
+
+The best way to contact us is on the IRC ``#pypy`` channel of
+``irc.freenode.net``.  Feel free to discuss matters either there or in
+the `mailing list`_.  Please report to the `issue tracker`_ any bugs.
+
+As a general rule, when there is a design issue to resolve, we pick the
+solution that is the "most C-like".  We hope that this module has got
+everything you need to access C code and nothing more.
+
+--- the authors, Armin Rigo and Maciej Fijalkowski
+
+.. _`issue tracker`: https://bitbucket.org/cffi/cffi/issues
+.. _`mailing list`: https://groups.google.com/forum/#!forum/python-cffi
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 4a4d29b..1126318 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -6,13 +6,10 @@ C Foreign Function Interface for Python.  Interact with almost any C
 code from Python, based on C-like declarations that you can often
 copy-paste from header files or documentation.
 
-* Goals_
-
-  * `Comments and bugs`_
-
 .. toctree::
    :maxdepth: 2
 
+   goals
    whatsnew
    installation
    overview
@@ -22,65 +19,4 @@ copy-paste from header files or documentation.
    embedding
 
 
-Goals
------
-
-The interface is based on `LuaJIT's FFI`_, and follows a few principles:
-
-* The goal is to call C code from Python without learning a 3rd language:
-  existing alternatives require users to learn domain specific language
-  (Cython_, SWIG_) or API (ctypes_). The CFFI design requires users to know
-  only C and Python, minimizing the extra bits of API that need to be learned.
-
-* Keep all the Python-related logic in Python so that you don't need to
-  write much C code (unlike `CPython native C extensions`_).
-
-* The preferred way is to work at the level of the API (Application
-  Programming Interface): the C compiler is called from the declarations
-  you write to validate and link to the C language constructs.
-  Alternatively, it is also possible to work at the ABI level
-  (Application Binary Interface), the way ctypes_ work.
-  However, on non-Windows platforms, C libraries typically
-  have a specified C API but not an ABI (e.g. they may
-  document a "struct" as having at least these fields, but maybe more).
-
-* Try to be complete.  For now some C99 constructs are not supported,
-  but all C89 should be, including macros (and including macro "abuses",
-  which you can `manually wrap`_ in saner-looking C functions).
-
-* Attempt to support both PyPy and CPython, with a reasonable path
-  for other Python implementations like IronPython and Jython.
-
-* Note that this project is **not** about embedding executable C code in
-  Python, unlike `Weave`_.  This is about calling existing C libraries
-  from Python.
-
-.. _`LuaJIT's FFI`: http://luajit.org/ext_ffi.html
-.. _`Cython`: http://www.cython.org
-.. _`SWIG`: http://www.swig.org/
-.. _`CPython native C extensions`: http://docs.python.org/extending/extending.html
-.. _`native C extensions`: http://docs.python.org/extending/extending.html
-.. _`ctypes`: http://docs.python.org/library/ctypes.html
-.. _`Weave`: http://wiki.scipy.org/Weave
-.. _`manually wrap`: overview.html#abi-versus-api
-
-Get started by reading `the overview`__.
-
-.. __: overview.html
-
-
-Comments and bugs
------------------
-
-The best way to contact us is on the IRC ``#pypy`` channel of
-``irc.freenode.net``.  Feel free to discuss matters either there or in
-the `mailing list`_.  Please report to the `issue tracker`_ any bugs.
-
-As a general rule, when there is a design issue to resolve, we pick the
-solution that is the "most C-like".  We hope that this module has got
-everything you need to access C code and nothing more.
-
---- the authors, Armin Rigo and Maciej Fijalkowski
 
-.. _`issue tracker`: https://bitbucket.org/cffi/cffi/issues
-.. _`mailing list`: https://groups.google.com/forum/#!forum/python-cffi
diff --git a/doc/source/whatsnew.rst b/doc/source/whatsnew.rst
index fba3b65..8692c64 100644
--- a/doc/source/whatsnew.rst
+++ b/doc/source/whatsnew.rst
@@ -95,8 +95,11 @@ v1.11
 .. __: http://bugs.python.org/issue31105
 
 
+Older Versions
+==============
+
 v1.10.1
-=======
+-------
 
 (only released inside PyPy 5.8.0)
 
@@ -107,7 +110,7 @@ v1.10.1
 
 
 v1.10
-=====
+-----
 
 * Issue #295: use calloc() directly instead of
   PyObject_Malloc()+memset() to handle ffi.new() with a default
@@ -169,7 +172,7 @@ v1.10
 
 
 v1.9
-====
+----
 
 * Structs with variable-sized arrays as their last field: now we track
   the length of the array after ``ffi.new()`` is called, just like we
@@ -204,7 +207,7 @@ v1.9
 
 
 v1.8.3
-======
+------
 
 * When passing a ``void *`` argument to a function with a different
   pointer type, or vice-versa, the cast occurs automatically, like in C.
@@ -217,7 +220,7 @@ v1.8.3
 
 
 v1.8.2
-======
+------
 
 * Issue #283: fixed ``ffi.new()`` on structures/unions with nested
   anonymous structures/unions, when there is at least one union in
@@ -226,7 +229,7 @@ v1.8.2
 
 
 v1.8.1
-======
+------
 
 * CPython 3.x: experimental: the generated C extension modules now use
   the "limited API", which means that, as a compiled .so/.dll, it should
@@ -241,7 +244,7 @@ v1.8.1
 
 
 v1.8
-====
+----
 
 * Removed the restriction that ``ffi.from_buffer()`` cannot be used on
   byte strings.  Now you can get a ``char *`` out of a byte string,
@@ -255,7 +258,7 @@ v1.8
 
 
 v1.7
-====
+----
 
 * ``ffi.gc(p, None)`` removes the destructor on an object previously
   created by another call to ``ffi.gc()``
@@ -284,7 +287,7 @@ v1.7
 
 
 v1.6
-====
+----
 
 * `ffi.list_types()`_
 
@@ -307,13 +310,13 @@ v1.6
 
 
 v1.5.2
-======
+------
 
 * Fix 1.5.1 for Python 2.6.
 
 
 v1.5.1
-======
+------
 
 * A few installation-time tweaks (thanks Stefano!)
 
@@ -325,7 +328,7 @@ v1.5.1
 
 
 v1.5.0
-======
+------
 
 * Support for `using CFFI for embedding`__.
 
@@ -333,13 +336,13 @@ v1.5.0
 
 
 v1.4.2
-======
+------
 
 Nothing changed from v1.4.1.
 
 
 v1.4.1
-======
+------
 
 * Fix the compilation failure of cffi on CPython 3.5.0.  (3.5.1 works;
   some detail changed that makes some underscore-starting macros
@@ -349,7 +352,7 @@ v1.4.1
 
 
 v1.4.0
-======
+------
 
 * A `better way to do callbacks`__ has been added (faster and more
   portable, and usually cleaner).  It is a mechanism for the
@@ -390,7 +393,7 @@ v1.4.0
 
 
 v1.3.1
-======
+------
 
 * The optional typedefs (``bool``, ``FILE`` and all Windows types) were
   not always available from out-of-line FFI objects.
@@ -406,7 +409,7 @@ v1.3.1
 
 
 v1.3.0
-======
+------
 
 * Added `ffi.memmove()`_.
 
@@ -441,13 +444,13 @@ v1.3.0
 
 
 v1.2.1
-======
+------
 
 Nothing changed from v1.2.0.
 
 
 v1.2.0
-======
+------
 
 * Out-of-line mode: ``int a[][...];`` can be used to declare a structure
   field or global variable which is, simultaneously, of total length
@@ -500,14 +503,14 @@ v1.2.0
 
 
 v1.1.2
-======
+------
 
 * ``ffi.gc()``: fixed a race condition in multithreaded programs
   introduced in 1.1.1
 
 
 v1.1.1
-======
+------
 
 * Out-of-line mode: ``ffi.string()``, ``ffi.buffer()`` and
   ``ffi.getwinerror()`` didn't accept their arguments as keyword
@@ -525,7 +528,7 @@ v1.1.1
 
 
 v1.1.0
-======
+------
 
 * Out-of-line API mode: we can now declare integer types with
   ``typedef int... foo_t;``.  The exact size and signedness of ``foo_t``
@@ -558,13 +561,13 @@ v1.1.0
 
 
 v1.0.3
-======
+------
 
 * Same as 1.0.2, apart from doc and test fixes on some platforms.
 
 
 v1.0.2
-======
+------
 
 * Variadic C functions (ending in a "..." argument) were not supported
   in the out-of-line ABI mode.  This was a bug---there was even a
@@ -574,7 +577,7 @@ v1.0.2
 
 
 v1.0.1
-======
+------
 
 * ``ffi.set_source()`` crashed if passed a ``sources=[..]`` argument.
   Fixed by chrippa on pull request #60.
@@ -587,7 +590,7 @@ v1.0.1
 
 
 v1.0.0
-======
+------
 
 * The main news item is out-of-line module generation: