41 files changed, 196 insertions, 315 deletions
diff --git a/doc/algos.rst b/doc/algos.rst
deleted file mode 100644
index d7e3f2498..000000000
--- a/doc/algos.rst
+++ /dev/null
@@ -1,109 +0,0 @@
-
-.. _algo_list:
-
-Algorithms
-========================================
-
-Supported Algorithms
-----------------------------------------
-
-Botan provides a number of different cryptographic algorithms and
-primitives, including:
-
-TLS/Public Key Infrastructure
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-  * SSL/TLS (from SSL v3 to TLS v1.2), including using preshared
-    keys (TLS-PSK) or passwords (TLS-SRP)
-  * X.509 certificates (including generating new self-signed and CA
-    certs) and CRLs
-  * Certificate path validation
-  * PKCS #10 certificate requests (creation and certificate issue)
-
-Public Key Cryptography
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-  * Encryption algorithms RSA, ElGamal, DLIES (padding schemes OAEP,
-    PKCS #1 v1.5)
-  * Signature algorithms RSA, DSA, ECDSA, GOST 34.10-2001,
-    Nyberg-Rueppel, Rabin-Williams (padding schemes PSS, PKCS #1 v1.5,
-    X9.31)
-  * Key agreement techniques Diffie-Hellman and ECDH
-
-Hash functions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-  * NIST hashes: SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512
-  * SHA-3 (Keccak) and SHA-3 candidates Skein-512 and Blue Midnight Wish-512
-  * RIPE hashes: RIPEMD-160 and RIPEMD-128
-  * Hash function combiners (Parallel and Comb4P)
-  * Other common hash functions Whirlpool and Tiger
-  * National standard hashes HAS-160 and GOST 34.11
-  * Obsolete or insecure hashes MD5, MD4, MD2
-  * Non-cryptographic checksums Adler32, CRC24, CRC32
-
-Block ciphers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-  * Authenticated cipher modes EAX, OCB, GCM, and CCM
-  * Unauthenticated cipher modes CTR, CBC, XTS, CFB, OFB, and ECB
-  * AES (Rijndael) and AES candidates Serpent, Twofish, MARS, CAST-256, RC6
-  * DES, and variants 3DES and DESX
-  * National/telecom block ciphers SEED, KASUMI, MISTY1, GOST 28147
-  * Other block ciphers including Blowfish, CAST-128, IDEA, Noekeon,
-    Skipjack, TEA, XTEA, RC2, RC5, SAFER-SK, and Square
-  * Block cipher constructions Luby-Rackoff and Lion
-
-Stream Ciphers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
- * RC4
- * Salsa20/XSalsa20
- * CTR and OFB modes also present a stream cipher interface
-
-Authentication Codes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
- * HMAC, CMAC (aka OMAC1)
- * Obsolete designs CBC-MAC, ANSI X9.19 DES-MAC, and the
-   protocol-specific SSLv3 authentication code
-
-Other Useful Things
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-  * Key derivation functions for passwords, including PBKDF2
-  * Password hashing functions, including bcrypt
-  * General key derivation functions KDF1 and KDF2 from IEEE 1363
-  * PRFs from ANSI X9.42, SSL v3.0, TLS v1.0
-
-Recommended Algorithms
----------------------------------
-
-This section is by no means the last word on selecting which
-algorithms to use.  However, botan includes a sometimes bewildering
-array of possible algorithms, and unless you're familiar with the
-latest developments in the field, it can be hard to know what is
-secure and what is not. The following attributes of the algorithms
-were evaluated when making this list: security, standardization,
-patent status, support by other implementations, and efficiency (in
-roughly that order).
-
-If your data is in motion, strongly consider using :doc:`tls` as a
-pre built, already standard and well studied protocol.
-
-Otherwise, if you simply *must* do something custom, use:
-
-* Block ciphers: AES or Serpent in EAX mode, or in CBC, CTR, or XTS
-  mode with a message authentication code.
-
-* General hash functions: SHA-256, SHA-512, SHA-3
-
-* Message authentication: HMAC with SHA-256
-
-* Public Key Encryption: RSA, 2048+ bit keys, with OAEP and SHA-256
-  ("EME1(SHA-256)")
-
-* Public Key Signatures: RSA, 2048+ bit keys with PSS and SHA-512
-  ("EMSA4(SHA-512)")
-
-* Key Agreement: Diffie-Hellman or ECDH, with "KDF2(SHA-256)"
diff --git a/doc/contents.rst b/doc/contents.rst
deleted file mode 100644
index 27a96de35..000000000
--- a/doc/contents.rst
+++ /dev/null
@@ -1,51 +0,0 @@
-
-Contents
-=================================
-
-.. toctree::
-   :maxdepth: 2
-
-   index
-   reading
-   faq
-   download
-   building
-   firststep
-   filters
-   pubkey
-   x509
-   ocsp
-   tls
-   credentials_manager
-   aead
-   bigint
-   lowlevel
-   secmem
-   kdf
-   pbkdf
-   passhash
-   cryptobox
-   srp
-   rng
-   fpe
-   versions
-   python
-   relnotes/index
-
-.. toctree::
-   :hidden:
-
-   license
-   credits
-   users
-   pgpkey
-   algos
-   vcs
-   release_process
-   build_log
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`
diff --git a/doc/build_log.rst b/doc/dev/build_log.rst
index dd2fd7180..dd2fd7180 100644
--- a/doc/build_log.rst
+++ b/doc/dev/build_log.rst
diff --git a/doc/release_process.rst b/doc/dev/release_process.rst
index 953b7dda2..cf7ba44fc 100644
--- a/doc/release_process.rst
+++ b/doc/dev/release_process.rst
@@ -23,11 +23,11 @@ prefix).
 Build The Release
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The release script is ``src/build-data/scripts/dist.py`` and runs from
+The release script is ``src/scripts/dist.py`` and runs from
 a monotone repository by pulling the revision matching the tag set
 previously. For instance::
 
- $ src/build-data/scripts/dist.py --mtn-db ~/var/mtn/botan.mtn 1.11.8
+ $ src/scripts/dist.py --mtn-db ~/var/mtn/botan.mtn 1.11.8
 
 The ``--mtn-db`` 'option' is mandatory, unless the environmental
 variable ``BOTAN_MTN_DB`` is set, in which case that value is used if
@@ -49,12 +49,7 @@ Build The Windows Installer
 
 On Windows, run ``configure.py`` to setup a build::
 
- $ python ./configure.py --cc=msvc --cpu=$ARCH --enable-ssse3 --distribution-info=unmodified
-
-The ``--enable-ssse3`` looks unsafe, but in fact under Visual C++ we
-do not compile with any special CPU specific flags, so this merely has
-the effect of enabling support for SSE2/SSSE3 optimizations which will
-only be used if ``cpuid`` indicates they are supported.
+ $ python ./configure.py --cc=msvc --cpu=$ARCH --distribution-info=unmodified
 
 After completing the build (and running the tests), use `InnoSetup
 <http://www.jrsoftware.org/isinfo.php>`_ to create the installer.  A
@@ -86,7 +81,7 @@ Post Release Process
 
 Immediately after the new release is created, increment the version
 number in ``botan_version.py`` and add a new release notes file for
-the next release, including a new entry in ``relnotes/index.rst``.
+the next release, including a new entry in ``doc/relnotes/index.rst``.
 
 Use "Not Yet Released" as the placeholder for the release date. Use
 checkin message "Bump for X.Y.Z".
diff --git a/doc/index.rst b/doc/index.rst
deleted file mode 100644
index 318812077..000000000
--- a/doc/index.rst
+++ /dev/null
@@ -1,70 +0,0 @@
-
-Welcome
-========================================
-
-Botan is a crypto library for C++ released under the permissive
-:doc:`BSD-2 (or FreeBSD) license <license>`.
-
-It provides most any :doc:`cryptographic algorithm <algos>` you might
-be looking for, along with :doc:`tls`, :doc:`X.509 certs, CRLs, and
-path validation <x509>`, a :doc:`pipeline-style message processing
-system <filters>`, :doc:`bcrypt password hashing <passhash>`, and
-other useful things. A third party open source implementation of
-`SSHv2 <http://www.netsieben.com/products/ssh/>`_ that uses botan is
-also available. In addition to C++ you can use botan from :doc:`Python
-<python>` or Perl (both included in tree), or with `Node.js
-<https://github.com/justinfreitag/node-botan>`_.
-
-See the :doc:`faq` for a list of common questions and answers.
-
-.. only:: html and website
-
-   See :doc:`download` for information about getting the latest version.
-
-The core of botan is written in C++11 (or C++98 for versions up to and
-including 1.10) with no dependencies besides the STL and the rest of
-the ISO standard library, but the library also includes optional
-modules which make further assumptions about their environment,
-providing features such as compression (using zlib or bzip2), entropy
-gathering, and secure memory allocation. Assembly implementations of
-key algorithms like SHA-1 and multiple precision integer routines for
-x86 and x86-64 processors are also included.
-
-It runs on most common operating systems and can be used with a number
-of different commercial and open source compilers. The :doc:`build log
-<build_log>` contains information about recently tested targets. It
-has more than a few :doc:`known users <users>` and is already included
-in most major package distributions, including
-\
-`Fedora <https://admin.fedoraproject.org/pkgdb/acls/name/botan>`_,
-`EPEL <http://dl.fedoraproject.org/pub/epel/6/SRPMS/repoview/botan.html>`_ (for RHEL/CentOS),
-`Debian <http://packages.debian.org/search?keywords=libbotan>`_,
-`Ubuntu <http://packages.ubuntu.com/search?keywords=botan>`_,
-`Gentoo <http://packages.gentoo.org/package/botan>`_,
-`Arch Linux <http://www.archlinux.org/packages/extra/x86_64/botan/>`_,
-`Slackbuild <http://slackbuilds.org/result/?search=Botan>`_,
-`FreeBSD <http://www.freshports.org/security/botan>`_,
-`NetBSD <ftp://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/security/botan/README.html>`_,
-`Cygwin <http://cygwin.com/packages/botan/>`_,
-`MacPorts <http://www.macports.org/ports.php?by=name&substr=botan>`_,
-`OpenPKG <http://www.openpkg.org/product/packages/?package=botan>`_, and
-`T2 SDE <http://www.t2-project.org/packages/botan.html>`_
-
-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, a number of
-individuals and organizations have :doc:`contributed <credits>`.
-Check out the :doc:`release notes <relnotes/index>` 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/>`_.
-Patches, "philosophical" bug reports, announcements of programs using
-the library, and related topics are also welcome. 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>`_.
-
diff --git a/doc/aead.rst b/doc/manual/aead.rst
index dbd06bbe1..dbd06bbe1 100644
--- a/doc/aead.rst
+++ b/doc/manual/aead.rst
diff --git a/doc/bigint.rst b/doc/manual/bigint.rst
index 66a055eb7..66a055eb7 100644
--- a/doc/bigint.rst
+++ b/doc/manual/bigint.rst
diff --git a/doc/building.rst b/doc/manual/building.rst
index 0df1b5a7e..6c9cfba3c 100644
--- a/doc/building.rst
+++ b/doc/manual/building.rst
@@ -11,7 +11,7 @@ the build system, primarily due to lack of access. Please contact the
 maintainer if you would like to build Botan on such a system.
 
 Botan's build is controlled by configure.py, which is a `Python
-<http://www.python.org>`_ script. Python 2.5 or later is required.
+<http://www.python.org>`_ script. Python 2.6 or later is required.
 
 For the impatient, this works for most systems::
 
diff --git a/doc/manual/contents.rst b/doc/manual/contents.rst
new file mode 100644
index 000000000..598510578
--- /dev/null
+++ b/doc/manual/contents.rst
@@ -0,0 +1,28 @@
+
+Contents
+========================================
+
+.. toctree::
+
+   index
+   building
+   firststep
+   secmem
+   rng
+   filters
+   pubkey
+   x509
+   ocsp
+   tls
+   credentials_manager
+   aead
+   bigint
+   lowlevel
+   kdf
+   pbkdf
+   passhash
+   cryptobox
+   srp
+   fpe
+   versions
+   python
diff --git a/doc/credentials_manager.rst b/doc/manual/credentials_manager.rst
index 04e9e3f2e..04e9e3f2e 100644
--- a/doc/credentials_manager.rst
+++ b/doc/manual/credentials_manager.rst
diff --git a/doc/cryptobox.rst b/doc/manual/cryptobox.rst
index ea77eee5a..ea77eee5a 100644
--- a/doc/cryptobox.rst
+++ b/doc/manual/cryptobox.rst
diff --git a/doc/filters.rst b/doc/manual/filters.rst
index cb8f010b6..cb8f010b6 100644
--- a/doc/filters.rst
+++ b/doc/manual/filters.rst
diff --git a/doc/firststep.rst b/doc/manual/firststep.rst
index 8010789d6..8010789d6 100644
--- a/doc/firststep.rst
+++ b/doc/manual/firststep.rst
diff --git a/doc/fpe.rst b/doc/manual/fpe.rst
index a2005e158..9fbb27f7c 100644
--- a/doc/fpe.rst
+++ b/doc/manual/fpe.rst
@@ -54,4 +54,4 @@ This example encrypts a credit card number with a valid
 `Luhn checksum <http://en.wikipedia.org/wiki/Luhn_algorithm>`_ to
 another number with the same format, including a correct checksum.
 
-.. literalinclude:: ../src/apps/fpe.cpp
+.. literalinclude:: ../../src/cmd/fpe.cpp
diff --git a/doc/reading.rst b/doc/manual/index.rst
index 3b3545e28..988d7732f 100644
--- a/doc/reading.rst
+++ b/doc/manual/index.rst
@@ -1,7 +1,12 @@
 
-Recommended Reading
+Introduction
 ========================================
 
+If you need to build the library first, start with :doc:`building`.
+
+Books and other resources
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 It's a very good idea if you have some knowledge of cryptography
 *before* trying to use the library. This is an area where it is very
 easy to make mistakes, and where things are often subtle and/or
@@ -21,3 +26,15 @@ Especially recommended are:
 - *Handbook of Applied Cryptography*
   by Alfred J. Menezes, Paul C. Van Oorschot, and Scott A. Vanstone
   (`available online <http://www.cacr.math.uwaterloo.ca/hac/>`_)
+
+If you're doing something non-trivial or unique, you might want to at
+the very least ask for review/input on a mailing list such as the
+`metzdowd <http://www.metzdowd.com/mailman/listinfo/cryptography>`_ or
+`randombit <http://lists.randombit.net/mailman/listinfo/cryptography>`_
+crypto lists. And (if possible) pay a professional cryptographer or
+security company to review your design and code.
+
+References
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :ref:`genindex` and :ref:`search` may be useful.
diff --git a/doc/kdf.rst b/doc/manual/kdf.rst
index 4ab2fd5dc..4ab2fd5dc 100644
--- a/doc/kdf.rst
+++ b/doc/manual/kdf.rst
diff --git a/doc/lowlevel.rst b/doc/manual/lowlevel.rst
index 398d52d85..398d52d85 100644
--- a/doc/lowlevel.rst
+++ b/doc/manual/lowlevel.rst
diff --git a/doc/ocsp.rst b/doc/manual/ocsp.rst
index 6c52cbe50..6c52cbe50 100644
--- a/doc/ocsp.rst
+++ b/doc/manual/ocsp.rst
diff --git a/doc/passhash.rst b/doc/manual/passhash.rst
index a398369b5..0d6721ddf 100644
--- a/doc/passhash.rst
+++ b/doc/manual/passhash.rst
@@ -97,7 +97,7 @@ outputs that look like this::
 
 Here is an example of using bcrypt:
 
-.. literalinclude:: ../src/apps/bcrypt.cpp
+.. literalinclude:: ../../src/cmd/bcrypt.cpp
 
 .. _passhash9:
 
diff --git a/doc/pbkdf.rst b/doc/manual/pbkdf.rst
index 14434f63e..14434f63e 100644
--- a/doc/pbkdf.rst
+++ b/doc/manual/pbkdf.rst
diff --git a/doc/pubkey.rst b/doc/manual/pubkey.rst
index 5fdcafc8d..efeea692c 100644
--- a/doc/pubkey.rst
+++ b/doc/manual/pubkey.rst
@@ -93,7 +93,7 @@ into a pair of key files. One is the public key in X.509 format (PEM encoded),
 the private key is in PKCS #8 format (also PEM encoded), either encrypted or
 unencrypted depending on if a password was given.
 
-.. literalinclude:: ../src/apps/keygen.cpp
+.. literalinclude:: ../../src/cmd/keygen.cpp
 
 .. _serializing_private_keys:
 
@@ -481,11 +481,11 @@ Signatures are verified using
 
 Here is an example of DSA signature generation
 
-.. literalinclude:: ../src/apps/dsa_sign.cpp
+.. literalinclude:: ../../src/cmd/dsa_sign.cpp
 
 Here is an example that verifies DSA signatures
 
-.. literalinclude:: ../src/apps/dsa_ver.cpp
+.. literalinclude:: ../../src/cmd/dsa_ver.cpp
 
 Key Agreement
 ---------------------------------
diff --git a/doc/python.rst b/doc/manual/python.rst
index 734d2c6f4..b8fd59b9a 100644
--- a/doc/python.rst
+++ b/doc/manual/python.rst
@@ -14,8 +14,8 @@ Botan includes a binding for Python, implemented using Boost.Python.
 As you can see, it is not currently documented, though there are a few
 examples under `src/scripts/examples`, such as RSA:
 
-.. literalinclude:: ../src/scripts/examples/rsa.py
+.. literalinclude:: ../../src/scripts/examples/rsa.py
 
 and EAX encryption using a passphrase:
 
-.. literalinclude:: ../src/scripts/examples/cipher.py
+.. literalinclude:: ../../src/scripts/examples/cipher.py
diff --git a/doc/rng.rst b/doc/manual/rng.rst
index 66679271d..66679271d 100644
--- a/doc/rng.rst
+++ b/doc/manual/rng.rst
diff --git a/doc/secmem.rst b/doc/manual/secmem.rst
index 76751bb40..76751bb40 100644
--- a/doc/secmem.rst
+++ b/doc/manual/secmem.rst
diff --git a/doc/srp.rst b/doc/manual/srp.rst
index e3aace5ff..e3aace5ff 100644
--- a/doc/srp.rst
+++ b/doc/manual/srp.rst
diff --git a/doc/tls.rst b/doc/manual/tls.rst
index f0de4320b..805bca823 100644
--- a/doc/tls.rst
+++ b/doc/manual/tls.rst
@@ -259,7 +259,7 @@ TLS Clients
 
 A simple TLS client example:
 
-.. literalinclude:: ../src/apps/tls_client.cpp
+.. literalinclude:: ../../src/cmd/tls_client.cpp
 
 TLS Servers
 ----------------------------------------
@@ -294,7 +294,7 @@ protocols the server is willing to advertise it supports.
 
 A TLS server that can handle concurrent connections using asio:
 
-.. literalinclude:: ../src/apps/tls_server_asio.cpp
+.. literalinclude:: ../../src/cmd/tls_server_asio.cpp
 
 .. _tls_sessions:
 
diff --git a/doc/versions.rst b/doc/manual/versions.rst
index 9562fdce5..9562fdce5 100644
--- a/doc/versions.rst
+++ b/doc/manual/versions.rst
diff --git a/doc/x509.rst b/doc/manual/x509.rst
index 422912db3..8504126a5 100644
--- a/doc/x509.rst
+++ b/doc/manual/x509.rst
@@ -277,7 +277,7 @@ new certificate:
 
 Here's an example:
 
-.. literalinclude ../src/apps/ca.cpp
+.. literalinclude ../../src/cmd/ca.cpp
 
 Generating CRLs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -344,7 +344,7 @@ protocols. The library provides a utility function for this:
 
 An example:
 
-.. literalinclude:: ../src/apps/self_sig.cpp
+.. literalinclude:: ../../src/cmd/self_sig.cpp
 
 Creating PKCS #10 Requests
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -363,7 +363,7 @@ certificate.
 
 An example:
 
-.. literalinclude:: ../src/apps/pkcs10.cpp
+.. literalinclude:: ../../src/cmd/pkcs10.cpp
 
 Certificate Options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/doc/relnotes/1_11_0.rst b/doc/relnotes/1_11_0.rst
index bfcdc213a..9662afca9 100644
--- a/doc/relnotes/1_11_0.rst
+++ b/doc/relnotes/1_11_0.rst
@@ -11,19 +11,18 @@ Version 1.11.0, 2012-07-19
 TLS and PKI Changes
 """"""""""""""""""""""""""""""""""""""""
 
-There have been many changes and improvements to :doc:`TLS
-<../tls>`. The interface is now purely event driven and does not
-directly interact with sockets.  New TLS features include TLS v1.2
-support, client certificate authentication, renegotiation, session
-tickets, and session resumption. Session information can be saved in
-memory or to an encrypted SQLite3 database. Newly supported TLS
-ciphersuite algorithms include using SHA-2 for message authentication,
-pre shared keys and SRP for authentication and key exchange, ECC
-algorithms for key exchange and signatures, and anonymous DH/ECDH key
-exchange.
+There have been many changes and improvements to TLS.  The interface
+is now purely event driven and does not directly interact with
+sockets.  New TLS features include TLS v1.2 support, client
+certificate authentication, renegotiation, session tickets, and
+session resumption. Session information can be saved in memory or to
+an encrypted SQLite3 database. Newly supported TLS ciphersuite
+algorithms include using SHA-2 for message authentication, pre shared
+keys and SRP for authentication and key exchange, ECC algorithms for
+key exchange and signatures, and anonymous DH/ECDH key exchange.
 
-Support for :doc:`OCSP <../ocsp>` has been added. Currently only
-client-side support exists.
+Support for OCSP has been added. Currently only client-side support
+exists.
 
 The API for X.509 path validation has changed, with
 ``x509_path_validate`` in x509path.h now handles path validation and
diff --git a/doc/relnotes/1_11_7.rst b/doc/relnotes/1_11_7.rst
index 5c8415fd8..4c29d0480 100644
--- a/doc/relnotes/1_11_7.rst
+++ b/doc/relnotes/1_11_7.rst
@@ -3,19 +3,20 @@ Version 1.11.7, Not Yet Released
 
 * Botan's basic numeric types are now defined in terms of the
   C99/C++11 standard integer types. For instance `u32bit` is now a
-  typedef for `uint32_t`, and both names are included in the
-  namespace.
+  typedef for `uint32_t`, and both names are included in the library
+  namespace. This should not result in any application-visible
+  changes.
 
 * There are now two executable outputs of the build, `botan-test`,
-  which runs some or all of the tests, and `botan` which is used as a
-  driver to call into various subcommands which can also act as
-  examples of library use, much in the manner of the `openssl`
-  command. It understands the commands `base64`, `asn1`, `x509`,
-  `tls_client`, `tls_server`, `bcrypt`, `keygen`, `speed`, and various
-  others. As part of this change many obsolete, duplicated, or one-off
-  examples were removed, while others were extended with new
-  functionality. Contributions of new subcommands, new bling for
-  exising ones, or documentation in any form is welcome.
+  which runs the tests, and `botan` which is used as a driver to call
+  into various subcommands which can also act as examples of library
+  use, much in the manner of the `openssl` command. It understands the
+  commands `base64`, `asn1`, `x509`, `tls_client`, `tls_server`,
+  `bcrypt`, `keygen`, `speed`, and various others. As part of this
+  change many obsolete, duplicated, or one-off examples were removed,
+  while others were extended with new functionality. Contributions of
+  new subcommands, new bling for exising ones, or documentation in any
+  form is welcome.
 
 * Fix a bug in Lion, which was broken by a change in 1.11.0. The
   problem was not noticed before as Lion was also missing a test vector
diff --git a/doc/relnotes/1_9_14.rst b/doc/relnotes/1_9_14.rst
index c60de26d1..318d7b53d 100644
--- a/doc/relnotes/1_9_14.rst
+++ b/doc/relnotes/1_9_14.rst
@@ -1,8 +1,7 @@
 Version 1.9.14, 2011-03-01
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* Add support for bcrypt, OpenBSD's password hashing scheme. It is
-  described in :ref:`bcrypt`.
+* Add support for bcrypt, OpenBSD's password hashing scheme.
 
 * Add support for NIST's AES key wrapping algorithm, as described in
   :rfc:`3394`. It is available by including ``rfc3394.h``.
diff --git a/doc/relnotes/1_9_16.rst b/doc/relnotes/1_9_16.rst
index 549e243f3..fe7441be8 100644
--- a/doc/relnotes/1_9_16.rst
+++ b/doc/relnotes/1_9_16.rst
@@ -28,7 +28,7 @@ Version 1.9.16, 2011-04-11
 * The overload of ``generate_passhash9`` that takes an explicit
   algorithm identifier has been merged with the one that does not.
   The algorithm identifier code has been moved from the second
-  parameter to the fourth. See :ref:`passhash9` for details.
+  parameter to the fourth.
 
 * Change shared library versioning to match the normal Unix
   conventions. Instead of ``libbotan-X.Y.Z.so``, the shared lib is
diff --git a/doc/relnotes/1_9_17.rst b/doc/relnotes/1_9_17.rst
index fbf9b3dee..794120be3 100644
--- a/doc/relnotes/1_9_17.rst
+++ b/doc/relnotes/1_9_17.rst
@@ -8,7 +8,7 @@ Version 1.9.17, 2011-04-29
   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 :doc:`../fpe` for more information.
+  ``fe1_decrypt``.
 
 * New options to ``configure.py`` control what tools are used for
   documentation generation. The ``--with-sphinx`` option enables using
diff --git a/doc/relnotes/contents.rst b/doc/relnotes/contents.rst
new file mode 100644
index 000000000..15f3ff948
--- /dev/null
+++ b/doc/relnotes/contents.rst
@@ -0,0 +1,7 @@
+
+Contents
+========================================
+
+.. toctree::
+
+   index
diff --git a/doc/website/contents.rst b/doc/website/contents.rst
new file mode 100644
index 000000000..55c302d01
--- /dev/null
+++ b/doc/website/contents.rst
@@ -0,0 +1,15 @@
+
+Contents
+========================================
+
+.. toctree::
+
+   index
+   license
+   faq
+   download
+   pgpkey
+   credits
+   users
+   vcs
+   relnotes/index
diff --git a/doc/download.rst b/doc/website/download.rst
index dcb1b4174..c537dec82 100644
--- a/doc/download.rst
+++ b/doc/website/download.rst
@@ -6,26 +6,18 @@ All releases are signed with a :doc:`PGP key <pgpkey>`.
 
 Unsure which release you want? Check the :ref:`FAQ <devel_vs_stable>`.
 
-.. only:: not website
-
-   .. note::
+.. note::
 
-      If you are viewing this documentation offline, a more recent
-      release `may be available <https://botan.randombit.net/download.html>`_.
+   If you are planning on developing an application using TLS, using
+   the latest 1.11 release instead of 1.10 is highly recommended.
 
 Current Stable Series (1.10)
 ----------------------------------------
 
-The latest version of the current stable series, from branch
-``net.randombit.botan.1_10``, is :doc:`relnotes/1_10_7`:
+The latest stable branch release is :doc:`relnotes/1_10_7`:
 :tgz:`1.10.7` (:tgz_sig:`sig <1.10.7>`),
 :tbz:`1.10.7` (:tbz_sig:`sig <1.10.7>`)
 
-.. note::
-
-   If you are planning on developing an application using TLS, using
-   the latest 1.11 release instead of 1.10 is highly recommended.
-
 Windows Installer
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -38,8 +30,7 @@ are also available.
 Current Development Series (1.11)
 ----------------------------------------
 
-The latest version of the current development series, from branch
-``net.randombit.botan``, is :doc:`relnotes/1_11_6`:
+The latest development release is :doc:`relnotes/1_11_6`:
 :tgz:`1.11.6` (:tgz_sig:`sig <1.11.6>`),
 :tbz:`1.11.6` (:tbz_sig:`sig <1.11.6>`)
 
diff --git a/doc/faq.rst b/doc/website/faq.rst
index 0b7170e4c..5cd66cabe 100644
--- a/doc/faq.rst
+++ b/doc/website/faq.rst
@@ -12,6 +12,14 @@ standards and de-facto standards like X.509v3 certificates, and
 various useful constructs like format-preserving encryption, all or
 nothing transforms, and secret splitting.
 
+Who wrote it?
+----------------------------------------
+
+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, a number of
+individuals and organizations have :doc:`contributed <credits>`.
+
 .. _devel_vs_stable:
 
 Which release should I use?
@@ -200,29 +208,47 @@ You can do any combination of:
 Does botan support SSL/TLS, SSH, S/MIME, OpenPGP...
 ------------------------------------------------------------
 
-Support for SSL/TLS is included in version 1.9.4 and later. Currently
-SSLv3 and TLS 1.0 and 1.1 are supported. The latest development
-versions also support TLS 1.2.
+The latest development (1.11) releases support TLS up to TLS v1.2.
+The 1.10 releases support up to TLS v1.1 using a different design
+and API; new applications intending to use TLS should use 1.11.
 
 `NetSieben SSH <http://netsieben.com/products/ssh/>`_ is an open
-source SSHv2 implementation that uses botan.
+source SSHv2 client implementation that uses botan.
 
-A preliminary and very incomplete implementation of CMS (the crypto
-layer underlying S/MIME) is included in ``src/cms``, but it needs a
-lot of love and attention before being truly useful.
-
-There is currently no support for OpenPGP.
+There is currently no support for OpenPGP, CMS, OTR, or SSHv2 servers.
 
 Will it work on my platform XYZ??
 ----------------------------------------
 
+It runs on most common operating systems and can be used with a number
+of different commercial and open source compilers, and is already
+included in most major package distributions, including
+\
+`Fedora <https://admin.fedoraproject.org/pkgdb/acls/name/botan>`_,
+`EPEL <http://dl.fedoraproject.org/pub/epel/6/SRPMS/repoview/botan.html>`_ (for RHEL/CentOS),
+`Debian <http://packages.debian.org/search?keywords=libbotan>`_,
+`Ubuntu <http://packages.ubuntu.com/search?keywords=botan>`_,
+`Gentoo <http://packages.gentoo.org/package/botan>`_,
+`Arch Linux <http://www.archlinux.org/packages/extra/x86_64/botan/>`_,
+`Slackbuild <http://slackbuilds.org/result/?search=Botan>`_,
+`FreeBSD <http://www.freshports.org/security/botan>`_,
+`NetBSD <ftp://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/security/botan/README.html>`_,
+`Cygwin <http://cygwin.com/packages/botan/>`_,
+`MacPorts <http://www.macports.org/ports.php?by=name&substr=botan>`_,
+`OpenPKG <http://www.openpkg.org/product/packages/?package=botan>`_, and
+`T2 SDE <http://www.t2-project.org/packages/botan.html>`_
+
 The most common stumbling block is a compiler that is buggy or can't
-handle modern C++ (specifically, C++98). Check out the :doc:`build log
-<build_log>` for a sense of which platforms are actively being tested.
+handle modern C++ (specifically, C++98). Most any recent release of
+GCC, Clang, Intel C++, Visual C++, etc are all fine. It is tested most
+heavily on Linux but especially the stable versions are built and
+tested across a range of Unices as well as OS X and Windows.
 
-Versions 1.11.0 and higher require a C++11 compiler as well as various
-Boost libraries (especially filesystem but also asio and regex). GCC
-4.7.0 and Clang 3.1 are known to work well.
+Versions 1.11.0 and higher require a C++11 compiler as well as Boost
+filesystem (plus optional use of Boost asio). GCC 4.7.0 and Clang 3.1
+or higher should work. Visual C++ 2013 seems to support all the
+required features, but probably needs a bit of work, as Windows has
+not seen much attention.
 
 I'm not feeling this, what can I use instead?
 ------------------------------------------------------------
@@ -237,8 +263,8 @@ I'm not feeling this, what can I use instead?
 
 * `OpenSSL <http://www.openssl.org>`_ is written in C and mostly
   targeted to being an SSL/TLS implementation but there is a lot of
-  other stuff in there as well.
+  other stuff in there as well. BSD plus wonky advertising clause.
 
-* `Crypto++ <http://www.cryptopp.com/>`_ is a C++ crypto library. Its
-  API is quite different from botans, and it offers a number of
-  algorithms botan does not (such as MQV).
+* `Crypto++ <http://www.cryptopp.com/>`_ is a C++ crypto library which
+  is roughly feature comparable to botan but with a very different
+  approach to the API. Boost license.
diff --git a/doc/website/index.rst b/doc/website/index.rst
new file mode 100644
index 000000000..c6b6c1b0b
--- /dev/null
+++ b/doc/website/index.rst
@@ -0,0 +1,30 @@
+
+Welcome
+========================================
+
+Botan is a crypto library for C++ released under the permissive
+:doc:`BSD-2 license <license>`.
+
+It provides useful things like SSL/TLS, X.509 certificates, ECDSA,
+AES, GCM, and bcrypt, plus a kitchen sink of crypto algorithms of
+various utility. A third party open source implementation of `SSHv2
+<http://www.netsieben.com/products/ssh/>`_ that uses botan is also
+available. In addition to C++ you can use botan from Python or Perl
+(both included in tree), or with `Node.js
+<https://github.com/justinfreitag/node-botan>`_.
+
+See the :doc:`faq` for a list of common questions and answers and
+:doc:`download` for information about getting the latest release.
+
+If you need help or have questions, send a mail to the `development
+mailing list
+<http://lists.randombit.net/mailman/listinfo/botan-devel/>`_.
+Patches, "philosophical" bug reports, announcements of programs using
+the library, and related topics are also welcome. If you find what you
+believe to be a bug, please file a ticket in `Bugzilla
+<http://bugs.randombit.net/>`_.
+
+The `manual <http://botan.randombt.net>`_ and
+`Doxygen reference <http://botan.randombit.net/doxygen>`_ for
+the most recent revision is available online.
+
diff --git a/doc/pgpkey.rst b/doc/website/pgpkey.rst
index ef8827835..ef8827835 100644
--- a/doc/pgpkey.rst
+++ b/doc/website/pgpkey.rst
diff --git a/doc/users.rst b/doc/website/users.rst
index 1580dc1e5..7cb0d924a 100644
--- a/doc/users.rst
+++ b/doc/website/users.rst
@@ -1,9 +1,12 @@
 
-Known Users
+Users
 ========================================
 
-This is a list of some of the known users of botan. If you'd like to
-be added to the list, email the development list.
+This is a list of some of the known users of botan. The open source
+projects might be helpful as an additional reference for library
+usage.
+
+If you'd like to be added to the list, email the development list.
 
 Open Source Software
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/doc/vcs.rst b/doc/website/vcs.rst
index e2353ee53..e2353ee53 100644
--- a/doc/vcs.rst
+++ b/doc/website/vcs.rst