Merge last bits from the tutorial.

Many other cleanups and changes in the docs. Make the index page a
functional standin for the current site so the entire website can be
built using Sphinx.

1 files changed, 109 insertions, 13 deletions

diff --git a/doc/index.txt b/doc/index.txt
index 2f55ea362..442d0b6b9 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -1,13 +1,119 @@
 
-Botan Reference Manual
+.. _contents:
+
+A friendly C++ crypto library
+========================================
+
+Botan is a :doc:`BSD-licensed <license>` crypto library for C++. It
+provides applications with most any :doc:`cryptographic algorithm
+<algos>` you might be looking for, along with :doc:`SSL/TLS <ssl>`,
+:doc:`X.509 certificates and CRLs <x509>`, a :doc:`pipeline-style
+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.
+
+.. only:: html and website
+
+   See :doc:`download` for information about getting the latest version.
+
+The core of botan is written in C++98 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 is
+already included in most major package distributions, including
+\
+`Fedora <https://admin.fedoraproject.org/pkgdb/acls/name/botan>`_,
+`EPEL <http://download.fedora.redhat.com/pub/epel/beta/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&amp;substr=botan>`_,
+`OpenPKG <http://www.openpkg.org/product/packages/?package=botan>`_, and
+`T2 SDE <http://www.t2-project.org/packages/botan.html>`_ and has
+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.
+
+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/>`_.
+
+A useful reference while reading this manual is the `Doxygen
+documentation <http://botan.randombit.net/doxygen>`_.
+
+Recommended Reading
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+counterintuitive. Obviously the library tries to provide things at a
+high level precisely to minimize the number of ways things can go
+wrong, but naive use will almost certainly not result in a secure
+system.
+
+Especially recommended are:
+
+- *Cryptography Engineering*
+  Niels Ferguson, Bruce Schneier, and Tadayoshi Kohno
+
+- *Security Engineering -- A Guide to Building Dependable Distributed Systems*
+  Ross Anderson
+
+- *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
 =================================
 
-Contents:
+.. toctree::
+   :hidden:
+
+   algos
+   build_log
+   download
+   faq
+   license
+   log
+   pgpkey
+   support
+   users
 
 .. toctree::
    :maxdepth: 2
 
-   intro
    building
    firststep
    filters
@@ -22,17 +128,7 @@ Contents:
    passhash
    rng
    fpe
-   examples
-   algos
-   faq
-   pgpkeys
-   license
    credits
-   contrib
-   support
-   users
-   build_log
-   log
 
 Indices and tables
 ==================