Document KDF properly.

Split log by release series instead of year.

Make dedicated landing page.

If SPHINX_OPTS is set, it will be passed to sphinx-build

10 files changed, 216 insertions, 234 deletions

diff --git a/doc/algos.txt b/doc/algos.txt
index b82d8d5c0..bc1477ee7 100644
--- a/doc/algos.txt
+++ b/doc/algos.txt
@@ -94,48 +94,3 @@ algorithms listed here are (currently) thought to be safe.
   DSA or ECDSA with "EMSA1(SHA-256)"
 
 * Key Agreement: Diffie-Hellman or ECDH, with "KDF2(SHA-256)"
-
-Algorithms Listing
-----------------------------------------
-
-Botan includes a very sizable number of cryptographic algorithms. In
-nearly all cases, you never need to know the header file or type name
-to use them. However, you do need to know what string (or strings) are
-used to identify that algorithm. These names conform to those set out
-by SCAN (Standard Cryptographic Algorithm Naming), which is a document
-that specifies how strings are mapped onto algorithm objects, which is
-useful for a wide variety of crypto APIs (SCAN is oriented towards
-Java, but Botan and several other non-Java libraries also make at
-least some use of it). For full details, read the `SCAN document
-<http://www.users.zetnet.co.uk/hopwood/crypto/scan/>`_.
-
-Many of these algorithms can take options (such as the number of
-rounds in a block cipher, the output size of a hash function,
-etc). These are shown in the following list; all of them default to
-reasonable values. There are algorithm-specific limits on most of
-them. When you see something like "HASH" or "BLOCK", that means
-you should insert the name of some algorithm of that type. There are
-no defaults for those options.
-
-A few very obscure algorithms are skipped; if you need one of them,
-you'll know it, and you can look in the appropriate header to see what
-that classes' ``name`` function returns (the names tend to
-match that in SCAN, if it's defined there).
-
- - ROUNDS: The number of rounds in a block cipher.
- - OUTSZ: The output size of a hash function or MAC
-
-**Block Ciphers:** "AES-128", "AES-192", "AES-256", "Blowfish",
-"CAST-128", "CAST-256", "DES", "DESX", "TripleDES", "GOST-28147-89",
-"IDEA", "KASUMI", "MARS", "MISTY1(ROUNDS)", "Noekeon", "RC2",
-"RC5(ROUNDS)", "RC6", "SAFER-SK(ROUNDS)", "SEED", "Serpent",
-"Skipjack", "Square", "TEA", "Twofish", "XTEA"
-
-**Stream Ciphers:** "ARC4", "MARK4", "Salsa20", "Turing",
-"WiderWake4+1-BE"
-
-**Hash Functions:** "HAS-160", "GOST-34.11", "Keccak-1600(OUTSZ)",
-"MD2", "MD4", "MD5", "RIPEMD-128", "RIPEMD-160", "SHA-160", "SHA-256",
-"SHA-384", "SHA-512", "Skein-512", "Tiger(OUTSZ)", "Whirlpool"
-
-**MACs:** "HMAC(HASH)", "CMAC(BLOCK)", "X9.19-MAC"
diff --git a/doc/building.txt b/doc/building.txt
index 6784a0141..56beef43e 100644
--- a/doc/building.txt
+++ b/doc/building.txt
@@ -1,5 +1,5 @@
 
-Building Botan
+Building The Library
 =================================
 
 This document describes how to build Botan on Unix/POSIX and MS
diff --git a/doc/conf.py b/doc/conf.py
index d802afa28..1a5dfe198 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -45,7 +45,7 @@ source_suffix = '.txt'
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = 'contents'
 
 # General information about the project.
 project = u'botan'
@@ -190,7 +190,7 @@ htmlhelp_basename = 'botandoc'
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'botan.tex', u'botan Reference Manual',
+  ('contents', 'botan.tex', u'botan Reference Manual',
    u'Jack Lloyd', 'manual'),
 ]
 
@@ -203,10 +203,10 @@ latex_documents = [
 #latex_use_parts = False
 
 # If true, show page references after internal links.
-latex_show_pagerefs = True
+latex_show_pagerefs = False
 
 # If true, show URL addresses after external links.
-latex_show_urls = True
+latex_show_urls = False
 
 # Additional stuff for the LaTeX preamble.
 #latex_preamble = ''
diff --git a/doc/contents.txt b/doc/contents.txt
new file mode 100644
index 000000000..023fa2b1c
--- /dev/null
+++ b/doc/contents.txt
@@ -0,0 +1,42 @@
+
+Contents
+=================================
+
+.. toctree::
+   :maxdepth: 2
+
+   welcome
+   building
+   firststep
+   filters
+   pubkey
+   x509
+   ssl
+   bigint
+   lowlevel
+   secmem
+   kdf
+   pbkdf
+   passhash
+   rng
+   fpe
+
+.. toctree::
+   :hidden:
+
+   license
+   credits
+   faq
+   users
+   support
+   download
+   pgpkey
+   algos
+   log
+   build_log
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
diff --git a/doc/download.txt b/doc/download.txt
index 8d4e2436c..b6229cfd6 100644
--- a/doc/download.txt
+++ b/doc/download.txt
@@ -2,9 +2,6 @@
 Getting The Latest Sources
 ========================================
 
-Latest Releases
-----------------------------------------
-
 All releases are signed with a :doc:`PGP key <pgpkey>`.
 
 Unsure which release you want? Check the :ref:`FAQ <devel_vs_stable>`.
@@ -14,10 +11,10 @@ Unsure which release you want? Check the :ref:`FAQ <devel_vs_stable>`.
    .. note::
 
       If you are viewing this documentation offline, a more recent
-      version may be available at http://botan.randombit.net/download.html
+      release `may be available <http://botan.randombit.net/download.html>`_
 
 Current Stable Release
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------------
 
 The current stable release is `1.8.11
 <http://botan.randombit.net/news/releases/1_8_11.html>`_ which was
@@ -40,7 +37,7 @@ Windows binary installer for use with Visual C++ 2008:
 <http://botan.randombit.net/files/win32/botan-1.8.11_win64.exe>`_
 
 Current Development Release
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------------
 
 The current development release is `1.9.16
 <http://botan.randombit.net/news/releases/1_9_16.html>`_ which was
diff --git a/doc/filters.txt b/doc/filters.txt
index 1af8c10f3..2355005aa 100644
--- a/doc/filters.txt
+++ b/doc/filters.txt
@@ -71,7 +71,7 @@ generators and entropy sources you want to, however for 99% of cases
 ``AutoSeeded_RNG`` is preferable.
 
 ``Pipe`` also has convenience methods for dealing with
-``std::iostream``s. Here is an example of those, using the
+``std::iostream``. Here is an example of those, using the
 ``Bzip_Compression`` filter (included as a module; if you have bzlib
 available, check the build instructions for how to enable it) to
 compress a file::
@@ -272,7 +272,7 @@ Data Sources
 
 A ``DataSource`` is a simple abstraction for a thing that stores
 bytes. This type is used heavily in the areas of the API related to
-ASN.1 encoding/decoding. The following types are ``DataSource``s:
+ASN.1 encoding/decoding. The following types are ``DataSource``:
 ``Pipe``, ``SecureQueue``, and a couple of special purpose ones:
 ``DataSource_Memory`` and ``DataSource_Stream``.
 
diff --git a/doc/fpe.txt b/doc/fpe.txt
index 80a24a70e..243be87d9 100644
--- a/doc/fpe.txt
+++ b/doc/fpe.txt
@@ -1,6 +1,4 @@
 
-.. _fpe:
-
 Format Preserving Encryption
 ========================================
 
diff --git a/doc/kdf.txt b/doc/kdf.txt
index feb458108..da916dcb3 100644
--- a/doc/kdf.txt
+++ b/doc/kdf.txt
@@ -4,4 +4,34 @@
 Key Derivation Functions
 ========================================
 
-Todo
+Key derivation functions are used to turn some amount of shared secret
+material into uniform random keys suitable for use with symmetric
+algorithms. An example of an input which is useful for a KDF is a
+shared secret created using Diffie-Hellman key agreement.
+
+.. cpp:class:: KDF
+
+  .. cpp:function:: SecureVector<byte> derive_key( \
+     size_t key_len, const MemoryRegion<byte>& secret, \
+     const std::string& salt = "") const
+
+  .. cpp:function:: SecureVector<byte> derive_key( \
+     size_t key_len, const MemoryRegion<byte>& secret, \
+     const MemoryRegion<byte>& salt) const
+
+  .. cpp:function:: SecureVector<byte> derive_key( \
+     size_t key_len, const MemoryRegion<byte>& secret, \
+     const byte* salt, size_t salt_len) const
+
+  .. cpp:function:: SecureVector<byte> derive_key( \
+     size_t key_len, const byte* secret, size_t secret_len, \
+     const std::string& salt) const
+
+   All variations on the same theme. Deterministically creates a
+   uniform random value from *secret* and *salt*. Typically *salt* is
+   a lable or identifier, such as a session id.
+
+You can create a :cpp:class:`KDF` using
+
+.. cpp:function:: KDF* get_kdf(const std::string& algo_spec)
+
diff --git a/doc/log.txt b/doc/log.txt
index d90d5c0eb..7e00e87c2 100644
--- a/doc/log.txt
+++ b/doc/log.txt
@@ -4,7 +4,7 @@
 Release Notes
 ========================================
 
-2011
+Series 1.9
 ----------------------------------------
 
 Version 1.9.17, Not Yet Released
@@ -15,7 +15,7 @@ Version 1.9.17, Not Yet Released
   and ``fpe_decrypt``. These were renamed as it is likely that other
   FPE schemes will be included in the future. The header is now
   ``fpe_fe1.h``, and the functions are named ``fe1_encrypt`` and
-  ``fe1_decrypt``. See :ref:`fpe` for more information.
+  ``fe1_decrypt``. See :doc:`fpe` for more information.
 
 * New options to ``configure.py`` control what tools are used for
   documentation generation. The ``--with-sphinx`` option enables using
@@ -75,8 +75,9 @@ Version 1.9.16, 2011-04-11
 
 * Change shared library versioning to match the normal Unix
   conventions. Instead of ``libbotan-X.Y.Z.so``, the shared lib is
-  named ``libbotan.so.X.Y.Z``; this allows the runtime linker to do
-  its runtime linky magic.
+  named ``libbotan-X.Y.so.Z``; this allows the runtime linker to do
+  its runtime linky magic. It can be safely presumed that any change
+  in the major or minor version indicates ABI incompatability.
 
 * Remove the socket wrapper code; it was not actually used by anything
   in the library, only in the examples, and you can use whatever kind
@@ -135,9 +136,6 @@ Version 1.9.13, 2011-02-19
 * Fix problems in the amalgamation build
 * Fix building under Clang 2.9 and Sun Studio 12
 
-2010
-----------------------------------------
-
 Version 1.9.12, 2010-12-13
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -177,27 +175,6 @@ Version 1.9.11, 2010-11-29
 * Improve support for Intel Atom processors
 * Fix compilation problems under Sun Studio and Clang
 
-Version 1.8.11, 2010-11-02
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* Fix a number of CRL encoding and decoding bugs
-* When building a debug library under VC++, use the debug runtime
-* Fix compilation under Sun Studio on Linux and Solaris
-* Add several functions for compatability with 1.9
-* In the examples, read most input files as binary
-* The Perl build script has been removed in this release
-
-Version 1.8.10, 2010-08-31
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* Switch default PKCS #8 encryption algorithm from 3DES to AES-256
-* Increase default hash iterations from 2048 to 10000 in PBES1 and PBES2
-* Use small tables in the first round of AES
-* Add PBKDF typedef and get_pbkdf for better compatability with 1.9
-* Add version of S2K::derive_key taking salt and iteration count
-* Enable the /proc-walking entropy source on NetBSD
-* Fix the doxygen makefile target
-
 Version 1.9.10, 2010-08-12
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -220,21 +197,6 @@ Version 1.9.9, 2010-06-28
 * Fix compilation under Apple's GCC 4.2
 * Expand and update the Doxygen documentation
 
-Version 1.8.9, 2010-06-16
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* Use constant time multiplication in IDEA
-* Avoid possible timing attack against OAEP decoding
-* Add new X509::BER_encode and PKCS8::BER_encode
-* Enable DLL builds under Windows
-* Add Win32 installer support
-* Add support for the Clang compiler
-* Fix problem in semcem.h preventing build under Clang or GCC 3.4
-* Fix bug that prevented creation of DSA groups under 1024 bits
-* Fix crash in GMP_Engine if library is shutdown and reinitialized
-* Work around problem with recent binutils in x86-64 SHA-1
-* The Perl build script is no longer supported and refuses to run by default
-
 Version 1.9.8, 2010-06-14
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -308,9 +270,6 @@ Version 1.9.4, 2010-03-09
 * Greatly improve the Win32 installer
 * Several fixes for Visual C++ debug builds
 
-2009
-----------------------------------------
-
 Version 1.9.3, 2009-11-19
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -331,14 +290,6 @@ Version 1.9.2, 2009-11-03
 * Add AltiVec runtime detection
 * Fix x86 CPU identification with Intel C++ and Visual C++
 
-Version 1.8.8, 2009-11-03
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* Alter Skein-512 to match the tweaked 1.2 specification
-* Fix use of inline asm for access to x86 bswap function
-* Allow building the library without AES enabled
-* Add 'powerpc64' alias to ppc64 arch for Gentoo ebuild
-
 Version 1.9.1, 2009-10-23
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -366,6 +317,53 @@ Version 1.9.0, 2009-09-09
 * Add --no-autoload option to configure.py, for minimized builds
 * The previously used configure.pl script is no longer supported
 
+Series 1.8
+----------------------------------------
+
+Version 1.8.11, 2010-11-02
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Fix a number of CRL encoding and decoding bugs
+* When building a debug library under VC++, use the debug runtime
+* Fix compilation under Sun Studio on Linux and Solaris
+* Add several functions for compatability with 1.9
+* In the examples, read most input files as binary
+* The Perl build script has been removed in this release
+
+Version 1.8.10, 2010-08-31
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Switch default PKCS #8 encryption algorithm from 3DES to AES-256
+* Increase default hash iterations from 2048 to 10000 in PBES1 and PBES2
+* Use small tables in the first round of AES
+* Add PBKDF typedef and get_pbkdf for better compatability with 1.9
+* Add version of S2K::derive_key taking salt and iteration count
+* Enable the /proc-walking entropy source on NetBSD
+* Fix the doxygen makefile target
+
+Version 1.8.9, 2010-06-16
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Use constant time multiplication in IDEA
+* Avoid possible timing attack against OAEP decoding
+* Add new X509::BER_encode and PKCS8::BER_encode
+* Enable DLL builds under Windows
+* Add Win32 installer support
+* Add support for the Clang compiler
+* Fix problem in semcem.h preventing build under Clang or GCC 3.4
+* Fix bug that prevented creation of DSA groups under 1024 bits
+* Fix crash in GMP_Engine if library is shutdown and reinitialized
+* Work around problem with recent binutils in x86-64 SHA-1
+* The Perl build script is no longer supported and refuses to run by default
+
+Version 1.8.8, 2009-11-03
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Alter Skein-512 to match the tweaked 1.2 specification
+* Fix use of inline asm for access to x86 bswap function
+* Allow building the library without AES enabled
+* Add 'powerpc64' alias to ppc64 arch for Gentoo ebuild
+
 Version 1.8.7, 2009-09-09
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -428,14 +426,14 @@ Version 1.8.1, 2009-01-20
 * Relicense api.tex from CC-By-SA 2.5 to BSD
 * Fix botan-config on MacOS X, Solaris
 
-2008
-----------------------------------------
-
 Version 1.8.0, 2008-12-08
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * Fix compilation on Solaris with GCC
 
+Series 1.7
+----------------------------------------
+
 Version 1.7.24, 2008-12-01
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -620,12 +618,6 @@ Version 1.7.9, 2008-08-27
 * Compilation fixes for MinGW and Visual Studio C++ 2008
 * Some autoconfiguration fixes for Windows
 
-Version 1.6.5, 2008-08-27
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* Add noexec stack marker for GNU linker in assembly code
-* Fix autoconfiguration problem on x86 with GCC 4.2 and 4.3
-
 Version 1.7.8, 2008-07-15
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -689,11 +681,6 @@ Version 1.7.4, 2008-03-10
 * Build fix for NetBSD systems
 * Prevent es_dev from being built except on Unix systems
 
-Version 1.6.4, 2008-03-08
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* Fix a compilation problem with Visual Studio C++ 2003
-
 Version 1.7.3, 2008-01-23
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -706,9 +693,6 @@ Version 1.7.3, 2008-01-23
 * Truncate X9.42 PRF output rather than allow counter overflow
 * PowerPC is now assumed to be big-endian
 
-2007
-----------------------------------------
-
 Version 1.7.2, 2007-10-13
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -730,12 +714,6 @@ Version 1.7.1, 2007-07-23
 * Modify most of the library to avoid use the C-style casts
 * Use higher resolution timers in symmetric benchmarks
 
-Version 1.6.3, 2007-07-23
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* Fix a race condition in the algorithm lookup cache
-* Fix problems building the memory pool on some versions of Visual C++
-
 Version 1.7.0, 2007-05-19
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -746,6 +724,26 @@ Version 1.7.0, 2007-05-19
 * Documentation updates
 * Update the todo list
 
+Series 1.6
+----------------------------------------
+
+Version 1.6.5, 2008-08-27
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Add noexec stack marker for GNU linker in assembly code
+* Fix autoconfiguration problem on x86 with GCC 4.2 and 4.3
+
+Version 1.6.4, 2008-03-08
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Fix a compilation problem with Visual Studio C++ 2003
+
+Version 1.6.3, 2007-07-23
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Fix a race condition in the algorithm lookup cache
+* Fix problems building the memory pool on some versions of Visual C++
+
 Version 1.6.2, 2007-03-24
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -761,14 +759,14 @@ Version 1.6.1, 2007-01-20
 * Fix some build problems under Visual Studio with debug enabled
 * Fix a bug in BER_Decoder that was triggered under some compilers
 
-2006
-----------------------------------------
-
 Version 1.6.0, 2006-12-17
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * Minor cleanups versus 1.5.13
 
+Series 1.5
+----------------------------------------
+
 Version 1.5.13, 2006-12-10
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -918,14 +916,6 @@ Version 1.5.2, 2006-01-15
 * Enabled the symmetric algorithm tests, which were accidentally off in 1.5.1
 * Removed the Default_Mutex's unused clone() member function
 
-Version 1.4.12, 2006-01-15
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* Fixed an off-by-one memory read in MISTY1::key()
-* Fixed a nasty memory leak in Output_Buffers::retire()
-* Changed maximum HMAC keylength to 1024 bits
-* Fixed a build problem in the hardware timer module on 64-bit PowerPC
-
 Version 1.5.1, 2006-01-08
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -953,9 +943,17 @@ Version 1.5.0, 2006-01-01
 * Removed the deprecated algorithms SEAL, ISAAC, and HAVAL
 * Change es_ftw to use unbuffered I/O
 
-2005
+Series 1.4
 ----------------------------------------
 
+Version 1.4.12, 2006-01-15
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Fixed an off-by-one memory read in MISTY1::key()
+* Fixed a nasty memory leak in Output_Buffers::retire()
+* Changed maximum HMAC keylength to 1024 bits
+* Fixed a build problem in the hardware timer module on 64-bit PowerPC
+
 Version 1.4.11, 2005-12-31
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1056,9 +1054,6 @@ Version 1.4.5, 2005-02-26
 * Removed some left-over debugging code
 * Removed SSL3_MAC, SSL3_PRF, and TLS_PRF
 
-2004
-----------------------------------------
-
 Version 1.4.4, 2004-12-02
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1114,6 +1109,9 @@ Version 1.4.0, 2004-06-26
 * Fixed some build problems on Tru64, HP-UX
 * Fixed compile problems with Intel C++, Compaq C++
 
+Series 1.3
+----------------------------------------
+
 Version 1.3.14, 2004-06-12
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1196,9 +1194,6 @@ Version 1.3.9, 2004-03-07
 * Fixed some BeOS build problems
 * Fixed the WiderWake benchmark
 
-2003
-----------------------------------------
-
 Version 1.3.8, 2003-12-30
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1264,11 +1259,6 @@ Version 1.3.5, 2003-11-30
 * RPM changed to install into /usr instead of /usr/local
 * Added support for QNX
 
-Version 1.2.8, 2003-11-21
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* Merged several important bug fixes from 1.3.x
-
 Version 1.3.4, 2003-11-21
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1336,6 +1326,14 @@ Version 1.3.0, 2003-11-02
 * Removed certain deprecated constructors of RSA, DSA, DH, RW, NR
 * Made PEM decoding more forgiving of extra text before the header
 
+Series 1.2
+----------------------------------------
+
+Version 1.2.8, 2003-11-21
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Merged several important bug fixes from 1.3.x
+
 Version 1.2.7, 2003-10-31
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1437,6 +1435,9 @@ Version 1.2.0, 2003-04-28
 * Removed the 'mpi_ia32' module, pending rewrite
 * Workaround a GCC 2.95.x bug in eme1.cpp
 
+Series 1.1
+----------------------------------------
+
 Version 1.1.13, 2003-04-22
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1520,15 +1521,6 @@ Version 1.1.7, 2003-01-12
 * Added SSL3-MAC and SSL3-PRF
 * Documentation updates, including a new tutorial
 
-Version 1.0.2, 2003-01-12
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* Fixed an obscure SEGFAULT causing bug in Pipe
-* Fixed an obscure but dangerous bug in SecureVector::swap
-
-2002
-----------------------------------------
-
 Version 1.1.6, 2002-12-10
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1627,6 +1619,15 @@ Version 1.1.0, 2002-09-14
 * Added support for variable-pass Tiger
 * Major speedup for Rabin-Williams key generation
 
+Series 1.0
+----------------------------------------
+
+Version 1.0.2, 2003-01-12
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Fixed an obscure SEGFAULT causing bug in Pipe
+* Fixed an obscure but dangerous bug in SecureVector::swap
+
 Version 1.0.1, 2002-09-14
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1644,6 +1645,9 @@ Version 1.0.0, 2002-08-26
 * Added Karatsuba multiplication and k-ary exponentiation
 * Fixed a problem in the multiplication routines
 
+Series 0.9
+----------------------------------------
+
 Version 0.9.2, 2002-08-18
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1678,6 +1682,9 @@ Version 0.9.0, 2002-08-03
 * PK_* can take a string naming the encoding method to use
 * Started writing some internals documentation
 
+Series 0.8
+----------------------------------------
+
 Version 0.8.7, 2002-07-30
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1814,6 +1821,9 @@ Version 0.8.0, 2002-04-24
 * Documentation updates for the new stuff (still incomplete)
 * Many new deprecated things: check doc/deprecated.txt
 
+Series 0.7
+----------------------------------------
+
 Version 0.7.10, 2002-04-07
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1863,9 +1873,6 @@ Version 0.7.8, 2002-02-28
 * Fixed various minor bugs
 * Added a couple of new example programs (stack and hasher2)
 
-2001
-----------------------------------------
-
 Version 0.7.7, 2001-11-24
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/doc/index.txt b/doc/welcome.txt
index 442d0b6b9..430a71f20 100644
--- a/doc/index.txt
+++ b/doc/welcome.txt
@@ -1,7 +1,5 @@
 
-.. _contents:
-
-A friendly C++ crypto library
+Welcome
 ========================================
 
 Botan is a :doc:`BSD-licensed <license>` crypto library for C++. It
@@ -11,7 +9,10 @@ provides applications with most any :doc:`cryptographic algorithm
 message processing system <filters>`, and a wide variety of other
 features. A third party open source implementation of `SSHv2
 <http://www.netsieben.com/products/ssh/>`_ that uses botan is also
-available.
+available. In addition to C++ you can use botan from Python or Perl,
+though the current bindings only wrap portions of the library.
+
+See the :doc:`faq` for a list of common questions and answers.
 
 .. only:: html and website
 
@@ -46,28 +47,21 @@ already included in most major package distributions, including
 more than a few :doc:`known users <users>`.
 
 It was started as a personal project by `Jack Lloyd
-<http:://www.randombit.net>`_, who continues to be the maintainer and
-release manager. Since the first release in 2001, many individuals and
-organizations have contributed bug fixes and new features.  There have
-been over 150 releases in the decade since the first publicly released
-version; the :doc:`release notes <log>` and `news archive
-<http://botan.randombit.net/news>`_ have more information about the
-release history.
-
-In addition to C++ you can use botan from Python or Perl, though the
-current bindings only wrap portions of the library.
-
-See the :doc:`faq` for a list of common questions and answers.
+<http:://www.randombit.net>`_,who continues to be the maintainer and
+release manager. Since the first release in 2001, a number of
+:doc:`individuals and organizations <credits>` have contributed bug
+fixes and new features. Check out the :doc:`release notes <log>` and
+`news archive <http://botan.randombit.net/news>`_ for more project
+history.
 
 If you need help or have questions, send a mail to the `development
 mailing list
 <http://lists.randombit.net/mailman/listinfo/botan-devel/>`_.
 "Philosophical" bug reports, announcements of programs using the
 library, and related topics are also welcome. :doc:`Commercial support
-options <support>` are also available.
-
-If you find what you believe to be a bug, please file a ticket in
-`Bugzilla <http://bugs.randombit.net/>`_.
+options <support>` are also available. If you find what you believe to
+be a bug, please file a ticket in `Bugzilla
+<http://bugs.randombit.net/>`_.
 
 A useful reference while reading this manual is the `Doxygen
 documentation <http://botan.randombit.net/doxygen>`_.
@@ -94,44 +88,3 @@ Especially recommended are:
 - *Handbook of Applied Cryptography*
   Alfred J. Menezes, Paul C. Van Oorschot, and Scott A. Vanstone
   (`available online <http://www.cacr.math.uwaterloo.ca/hac/>`_)
-
-Documentation Contents
-=================================
-
-.. toctree::
-   :hidden:
-
-   algos
-   build_log
-   download
-   faq
-   license
-   log
-   pgpkey
-   support
-   users
-
-.. toctree::
-   :maxdepth: 2
-
-   building
-   firststep
-   filters
-   pubkey
-   x509
-   ssl
-   bigint
-   lowlevel
-   secmem
-   kdf
-   pbkdf
-   passhash
-   rng
-   fpe
-   credits
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`