Doc and theming updates

10 files changed, 86 insertions, 49 deletions

diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
new file mode 100644
index 000000000..c907c7597
--- /dev/null
+++ b/doc/_templates/layout.html
@@ -0,0 +1,9 @@
+{% extends "!layout.html" %}
+
+{% block header %}
+    <div class="header-wrapper">
+      <div class="header">
+        <h1>{{ shorttitle|e }}</h1>
+      </div>
+    </div>
+{% endblock %}
diff --git a/doc/algos.txt b/doc/algos.txt
index bc1477ee7..119b81a7f 100644
--- a/doc/algos.txt
+++ b/doc/algos.txt
@@ -12,39 +12,33 @@ primitives, including:
 
 * 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
+  * 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
-
- * RIPE hashes: RIPEMD-160 and RIPEMD-128
-
- * SHA-3 candidates Skein-512, Keccak, and Blue Midnight Wish-512
-
- * 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
+  * NIST hashes: SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512
+  * RIPE hashes: RIPEMD-160 and RIPEMD-128
+  * SHA-3 candidates Skein-512, Keccak, and Blue Midnight Wish-512
+  * 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
 
- * 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, Skipjack
- * Other block ciphers including Blowfish, CAST-128, IDEA, Noekeon,
-   TEA, XTEA, RC2, RC5, SAFER-SK, and Square
- * Block cipher constructions Luby-Rackoff and Lion
- * Block cipher modes ECB, CBC, CBC/CTS, CFB, OFB, CTR, XTS and
-   authenticated cipher mode EAX
+  * 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, Skipjack
+  * Other block ciphers including Blowfish, CAST-128, IDEA, Noekeon,
+    TEA, XTEA, RC2, RC5, SAFER-SK, and Square
+  * Block cipher constructions Luby-Rackoff and Lion
+  * Block cipher modes ECB, CBC, CBC/CTS, CFB, OFB, CTR, XTS and
+    authenticated cipher mode EAX
 
 * Stream ciphers ARC4, Salsa20/XSalsa20, Turing, and WiderWake4+1
 
@@ -53,17 +47,17 @@ primitives, including:
 
 * Public Key Infrastructure
 
- * X.509 certificates (including generating new self-signed and CA
-   certs) and CRLs
- * Certificate path validation
- * PKCS #10 certificate requests (creation and certificate issue)
+  * X.509 certificates (including generating new self-signed and CA
+    certs) and CRLs
+  * Certificate path validation
+  * PKCS #10 certificate requests (creation and certificate issue)
 
 * Other cryptographic utility functions including
 
- * Key derivation functions for passwords: PBKDF1 (PKCS #5 v1.5),
-   PBKDF2 (PKCS #5 v2.0), OpenPGP S2K (RFC 2440)
- * General key derivation functions KDF1 and KDF2 from IEEE 1363
- * PRFs from ANSI X9.42, SSL v3.0, TLS v1.0
+  * Key derivation functions for passwords: PBKDF1 (PKCS #5 v1.5),
+    PBKDF2 (PKCS #5 v2.0), OpenPGP S2K (RFC 2440)
+  * General key derivation functions KDF1 and KDF2 from IEEE 1363
+  * PRFs from ANSI X9.42, SSL v3.0, TLS v1.0
 
 Recommended Algorithms
 ---------------------------------
diff --git a/doc/build_log.txt b/doc/build_log.txt
index 6873d6249..49eba86c5 100644
--- a/doc/build_log.txt
+++ b/doc/build_log.txt
@@ -14,6 +14,7 @@ Debian reports the build results for 1.8 on `a number of platforms
 ===========   =======   ===================   ========================   ============================   ========
 Date          Version   OS                    CPU                        Compiler                       Results
 ===========   =======   ===================   ========================   ============================   ========
+2011-05-02    1.9.17    FreeBSD 8.2           x86-64                     GCC 4.2.1                      OK
 2011-04-25    1.9.16    Gentoo 10.0           Intel Core i7-860          Clang 2.9                      Miscompiles SSE2 IDEA
 2011-04-23    1.9.16    Gentoo 10.0           Intel Core i7-860          Sun C++ 5.10                   OK
 2011-04-22    1.9.16    Gentoo 10.0           Intel Core i7-860          Intel C++ 11.1                 OK
diff --git a/doc/conf.py b/doc/conf.py
index 1a5dfe198..f6fb09d1f 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -31,6 +31,24 @@ import botan_version
 # If your documentation needs a minimal Sphinx version, state it here.
 needs_sphinx = '1.0'
 
+"""
+Assert that we are running under Sphinx 1.0.7 or later. Earlier
+versions have bugs in the C++ domain that cause crashes. And
+needs_sphinx only allows us to assert needing a particular major/minor
+version.
+"""
+def check_sphinx_version():
+    import sphinx
+
+    version = map(int, sphinx.__version__.split('.'))
+    if version[0] == 1 and version[1] == 0 and version[2] < 7:
+        # Exit rather than throwing to avoid a confusing backtrace
+        print "This Sphinx is too old - upgrade to at least 1.0.7"
+        import sys
+        sys.exit(1)
+
+check_sphinx_version()
+
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = []
@@ -103,12 +121,17 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'agogo'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {
+    'linkcolor': 'blue',
+    'headerlinkcolor': 'blue',
+    'headercolor1': 'darkblue',
+    'headercolor2': 'darkblue',
+    }
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
diff --git a/doc/contents.txt b/doc/contents.txt
index 023fa2b1c..633625e14 100644
--- a/doc/contents.txt
+++ b/doc/contents.txt
@@ -5,7 +5,7 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   welcome
+   index
    building
    firststep
    filters
diff --git a/doc/faq.txt b/doc/faq.txt
index 38be253a7..2e5ff1e91 100644
--- a/doc/faq.txt
+++ b/doc/faq.txt
@@ -28,16 +28,20 @@ stability between releases on the development branch, and API changes
 may be made without notice. Feel free to send comments on API changes,
 or API problems, to the list.
 
-If you want to ship a binary that is usable out of the box on a Linux
-distro that ships botan (most do), or you want to ensure you're not
-having to track a moving target, you'll probably prefer using the
+If you don't want to have to worry about tracking a moving target, and
+just want something that works, you'll probably prefer using the
 stable releases. If you want to get the latest features, the
-development releases are the obvious choice. If you're building an
-application that will embed botan into it (without relying on a shared
-library), you want to use an amalgamation build, which basically turns
-botan into a single header and a single source file which you can
-easily include in your existing application build; this feature is
-currently only available in the development trees.
+development releases are the obvious choice.
+
+If you want to ship a binary that is usable out of the box on a Linux
+distro that ships botan, you'll probably want to match versions with
+that distro; as of this writing most ship with 1.8.
+
+If you're building an application that will embed botan into it
+(without relying on a shared library), you want to use an amalgamation
+build, which basically turns botan into a single header and a single
+source file which you can easily include in your existing application
+build. In this case you can pick which ever tree you prefer.
 
 The self-test program can't locate the library
 -----------------------------------------------
@@ -165,8 +169,8 @@ You can do any combination of:
 Does botan support SSL/TLS, SSH, S/MIME, OpenPGP...
 ------------------------------------------------------------
 
-Support for SSL/TLS is included in the most recent development
-releases (1.9.x). Currently SSLv3 and TLS 1.0 and 1.1 are supported.
+Support for SSL/TLS is included in version 1.9.4 and later. Currently
+SSLv3 and TLS 1.0 and 1.1 are supported.
 
 `NetSieben SSH <http://netsieben.com/products/ssh/>`_ is an open
 source SSHv2 implementation that uses botan.
diff --git a/doc/fpe.txt b/doc/fpe.txt
index 243be87d9..5c035f0b7 100644
--- a/doc/fpe.txt
+++ b/doc/fpe.txt
@@ -2,6 +2,8 @@
 Format Preserving Encryption
 ========================================
 
+.. versionadded:: 1.9.17
+
 Format preserving encryption (FPE) refers to a set of techniques for
 encrypting data such that the ciphertext has the same format as the
 plaintext. For instance, you can use FPE to encrypt credit card
diff --git a/doc/welcome.txt b/doc/index.txt
index 430a71f20..430a71f20 100644
--- a/doc/welcome.txt
+++ b/doc/index.txt
diff --git a/doc/pgpkey.txt b/doc/pgpkey.txt
index 1d2f3debc..ef8827835 100644
--- a/doc/pgpkey.txt
+++ b/doc/pgpkey.txt
@@ -2,6 +2,8 @@
 PGP Code Signing Key
 ========================================
 
+.. highlight:: none
+
 The following PGP key is used to sign all releases::
 
   pub   2048R/EFBADFBC 2004-10-30
diff --git a/doc/ssl.txt b/doc/ssl.txt
index 7b61fa88c..26954d6a4 100644
--- a/doc/ssl.txt
+++ b/doc/ssl.txt
@@ -4,6 +4,8 @@
 SSL and TLS
 ========================================
 
+.. versionadded:: 1.9.4
+
 Botan supports both client and server implementations of the SSL/TLS
 protocols, including SSL v3, TLS v1.0, and TLS v1.1. The insecure and
 obsolete SSL v2 is not supported.