updated front matter and other documentation

13 files changed, 362 insertions, 242 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 093973a..d9ed120 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# PassLib documentation build configuration file, created by
+# Passlib documentation build configuration file, created by
 # sphinx-quickstart on Mon Mar  2 14:12:06 2009.
 #
 # This file is execfile()d with the current directory set to its containing dir.
@@ -57,6 +57,9 @@ extensions = [
 
     # replace sphinx :samp: role handler with one that allows escaped {} chars
     'cloud_sptheme.ext.escaped_samp_literals',
+
+    # add "issue" role
+    'cloud_sptheme.ext.issue_tracker',
     ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -73,7 +76,7 @@ master_doc = 'contents'
 index_doc = 'index'
 
 # General information about the project.
-project = u'PassLib'
+project = u'Passlib'
 copyright = u'2008-2011, Assurance Technologies, LLC'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -99,8 +102,11 @@ version = csp.get_version(release)
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = [
-    #disabling documentation of this until module is more mature.
+    # disabling documentation of this until module is more mature.
     "lib/passlib.utils.compat.rst",
+
+    # may remove this in future release
+    "lib/passlib.utils.md4.rst",
 ]
 
 # The reST default role (used for this markup: `text`) to use for all documents.
@@ -126,6 +132,7 @@ modindex_common_prefix = [ "passlib." ]
 # -- Options for all output ---------------------------------------------------
 todo_include_todos = "hide-todos" not in options
 keep_warnings = "hide-warnings" not in options
+issue_tracker_url = "gc:passlib"
 
 # -- Options for HTML output ---------------------------------------------------
 
@@ -136,7 +143,7 @@ html_theme = 'cloud'
 # 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.
-if html_theme == 'cloud':
+if html_theme in ['cloud', 'redcloud']:
     html_theme_options = { "roottarget": index_doc, "collapsiblesidebar": True }
     if 'for-pypi' in options:
         html_theme_options['googleanalytics_id'] = 'UA-22302196-2'
diff --git a/docs/contents.rst b/docs/contents.rst
index c15aed3..099c5f8 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -3,23 +3,22 @@ Table Of Contents
 =================
 
 .. toctree::
+    :maxdepth: 4
 
     Front Page <index>
     install
 
-    new_app_quickstart
-
     overview
+    new_app_quickstart
 
-    password_hash_api
     lib/passlib.hash
 
     lib/passlib.context-tutorial
     lib/passlib.context
     lib/passlib.apps
-    lib/passlib.apache
     lib/passlib.hosts
 
+    lib/passlib.apache
     lib/passlib.ext.django
 
     lib/passlib.exc
diff --git a/docs/index.rst b/docs/index.rst
index bdb2ca5..5118c31 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,64 +1,105 @@
 ==========================================
-PassLib |release| documentation
+Passlib |release| documentation
 ==========================================
 
 Welcome
 =======
-Passlib is a password hashing library for Python 2 & 3,
-which provides cross-platform implementations of over 20 password hashing algorithms,
-as well as a framework for managing existing password hashes.
-It's designed to be useful for a large range of tasks, including:
-
-* quick-start password hashing for new python applications ~
-  :doc:`quickstart guide <new_app_quickstart>`
-
-* constructing a configurable hashing policy
-  to match the needs of any python application ~
-  :data:`passlib.context`
-
-* reading & writing Apache htpasswd / htdigest files ~
-  :mod:`passlib.apache`
-
-* creating & verifying hashes used by MySQL, PostgreSQL, OpenLDAP,
-  and other applications ~
-  :mod:`passlib.apps`
-
-* creating & verifying hashes found in Unix "shadow" files ~
-  :data:`passlib.hosts`
-
-See the library overview for more details and usage examples.
-
-Quick Links
-===========
-
-.. raw:: html
-
-    <table class="contentstable" align="center">
-    <tr>
-        <td width="50%" valign="top">
-            <p class="biglink">
-                <a class="biglink" href="overview.html">Library Overview</a><br>
-                <span class="linkdescr">describes how Passlib is laid out</span>
-            </p>
-
-            <p class="biglink">
-                <a class="biglink" href="install.html">Installation</a><br>
-                <span class="linkdescr">requirements and installation instructions</span>
-            </p>
-        </td>
-        <td width="50%" valign="top">
-            <p class="biglink">
-                <a class="biglink" href="lib/passlib.hash.html">Supported Hashes</a><br>
-                <span class="linkdescr">complete list of supported password hash algorithms</span>
-            </p>
-
-            <p class="biglink">
-                <a class="biglink" href="history.html">Changelog</a><br>
-                <span class="linkdescr">history of current and past releases</span>
-            </p>
-        </td>
-    </tr>
-    </table>
+Passlib is a password hashing library for Python 2 & 3, which provides
+cross-platform implementations of over 30 password hashing algorithms, as well
+as a framework for managing existing password hashes. It's designed to be useful
+for a wide range of tasks, from verifying a hash found in /etc/shadow, to
+providing full-strength password hashing for multi-user application.
+
+As a quick sample, the following code hashes and then verifies a password
+using the :doc:`SHA256-Crypt </lib/passlib.hash.sha256_crypt>` algorithm::
+
+    >>> # import the hash algorithm
+    >>> from passlib.hash import sha256_crypt
+
+    >>> # generate new salt, and hash a password
+    >>> hash = sha256_crypt.encrypt("toomanysecrets")
+    >>> hash
+    '$5$rounds=80000$zvpXD3gCkrt7tw.1$QqeTSolNHEfgryc5oMgiq1o8qCEAcmye3FoMSuvgToC'
+
+    >>> # verifying the password
+    >>> sha256_crypt.verify("toomanysecrets", hash)
+    True
+    >>> sha256_crypt.verify("joshua", hash)
+    False
+
+Contents
+========
+
+Introductory Materials
+----------------------
+
+    :doc:`install`
+        requirements & installation instructions
+
+    :doc:`overview`
+        describes how Passlib is laid out
+
+    :doc:`New Application Quickstart <new_app_quickstart>`
+        choosing a password hash for new applications
+
+----
+
+Password Hashing Algorithms
+---------------------------
+    :mod:`passlib.hash`
+        all the password hashes supported by Passlib --
+            - :doc:`Overview <lib/passlib.hash>`
+            - :ref:`mcf-hashes`
+            - :ref:`ldap-hashes`
+            - :ref:`database-hashes`
+            - :ref:`windows-hashes`
+            - :ref:`other-hashes`
+
+    :doc:`PasswordHash interface <password_hash_api>`
+        examples & documentation of the common hash interface
+        used by all the hash algorithms in Passlib.
+
+CryptContext Objects
+--------------------
+    :mod:`passlib.context`
+        provides the :class:`!CryptContext` class, a flexible container
+        for managing and migrating between multiple hash algorithms.
+
+    :mod:`passlib.apps`
+        predefined CryptContext objects for managing the hashes used by
+        MySQL, PostgreSQL, OpenLDAP, and others applications.
+
+    :mod:`passlib.hosts`
+        predefined CryptContext objects for managing the hashes
+        found in Linux & BSD "shadow" files.
+
+Application Helpers
+-------------------
+    :mod:`passlib.apache`
+        classes for manipulating Apache's ``htpasswd`` and ``htdigest`` files.
+
+    :mod:`passlib.ext.django`
+        Django plugin which monkeypatches support for (almost) any hash in Passlib.
+
+Support Modules
+---------------
+    :mod:`passlib.exc`
+
+        custom warnings and exceptions used by Passlib
+
+..
+    :mod:`passlib.registry`
+    :mod:`passlib.utils`
+
+----
+
+Other Documents
+---------------
+    :doc:`modular_crypt_format`
+        reference listing "modular crypt format" support across Unix systems.
+
+    :doc:`Changelog <history>`
+        Passlib's release history
 
 Online Resources
 ================
@@ -66,12 +107,12 @@ Online Resources
     .. rst-class:: html-plain-table
 
     ================ ===================================================
-    **Homepage**:    `<http://passlib.googlecode.com>`_
-    **Online Docs**: `<http://packages.python.org/passlib>`_
-    **Discussion**:  `<http://groups.google.com/group/passlib-users>`_
+    Homepage:        `<http://passlib.googlecode.com>`_
+    Online Docs:     `<http://packages.python.org/passlib>`_
+    Discussion:      `<http://groups.google.com/group/passlib-users>`_
     ---------------- ---------------------------------------------------
     ---------------- ---------------------------------------------------
-    **PyPI**:        `<http://pypi.python.org/pypi/passlib>`_
-    **Downloads**:   `<http://code.google.com/p/passlib/downloads>`_
-    **Source**:      `<http://code.google.com/p/passlib/source>`_
+    PyPI:            `<http://pypi.python.org/pypi/passlib>`_
+    Downloads:       `<http://code.google.com/p/passlib/downloads>`_
+    Source:          `<http://code.google.com/p/passlib/source>`_
     ================ ===================================================
diff --git a/docs/install.rst b/docs/install.rst
index 3b4f7d3..4f7742c 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -52,12 +52,12 @@ To install from a source directory using :command:`setup.py`::
 
 Testing
 =======
-PassLib contains a comprehensive set of unittests providing nearly complete coverage.
+Passlib contains a comprehensive set of unittests providing nearly complete coverage.
 All unit tests are contained within the :mod:`passlib.tests` subpackage,
 and are designed to be run using the
 `Nose <http://somethingaboutorange.com/mrl/projects/nose>`_ unit testing library.
 
-Once PassLib and Nose have been installed, the tests may be run from the source directory::
+Once Passlib and Nose have been installed, the tests may be run from the source directory::
 
     # to run the platform-relevant tests...
     nosetests -v --tests passlib/tests
@@ -82,9 +82,9 @@ you will need to:
 
 1. Install `Sphinx <http://sphinx.pocoo.org/>`_ (1.0 or better)
 2. Install the `Cloud Sphinx Theme <http://packages.python.org/cloud_sptheme>`_.
-3. Download the PassLib source
-4. From the PassLib source directory, run :samp:`python setup.py build_sphinx`.
+3. Download the Passlib source
+4. From the Passlib source directory, run :samp:`python setup.py build_sphinx`.
 5. Once Sphinx completes it's run, point a web browser to the file at :samp:`{$SOURCE}/build/sphinx/html/index.html`
-   to access the PassLib documentation in html format.
+   to access the Passlib documentation in html format.
 6. Alternately, steps 4 & 5 can be replaced by running :samp:`python setup.py docdist`,
    which will build a zip file of the documentation in :samp:`{$SOURCE}/dist`.
diff --git a/docs/lib/passlib.apache.rst b/docs/lib/passlib.apache.rst
index 8649e62..19779b7 100644
--- a/docs/lib/passlib.apache.rst
+++ b/docs/lib/passlib.apache.rst
@@ -10,10 +10,11 @@ htpasswd and htdigest files; though the use of two helper classes.
 
 .. versionchanged:: 1.6
     The api for this module was updated to be more flexible,
-    and to have (hopefully) less confusing method names.
-    The old method and keyword names are supported but deprecated, and
+    and to have less ambiguous method names.
+    The old method and keyword names are deprecated, and
     will be removed in Passlib 1.8.
-    No more backwards-incompatible changes are currently planned.
+    No more backwards-incompatible changes are currently planned
+    for these classes.
 
 .. index:: apache; htpasswd
 
diff --git a/docs/lib/passlib.apps.rst b/docs/lib/passlib.apps.rst
index 619e21f..90a9624 100644
--- a/docs/lib/passlib.apps.rst
+++ b/docs/lib/passlib.apps.rst
@@ -5,46 +5,45 @@
 .. module:: passlib.apps
     :synopsis: encrypting & verifying passwords used in sql servers and other applications
 
-This lists a number of :class:`!CryptContext` instances that are predefined
-by PassLib for easily handling the multiple formats used by various applications.
-(For details about how to use a :class:`!CryptContext` instance,
-see :doc:`passlib.context-usage`).
+.. _predefined-context-example:
 
-.. _quickstart-custom-applications:
+This module contains a number of preconfigured :ref:`CryptContext <context-overview>` instances
+that are provided by Passlib for easily handling the hash formats used by various applications.
 
-Custom Applications
-===================
-.. data:: custom_app_context
+.. rst-class:: html-toggle
 
-    This :class:`!CryptContext` object is provided for new python applications
-    to quickly and easily add password hashing support.
-    It offers:
+Usage Example
+=============
+The :class:`!CryptContext` class itself has a large number of features,
+but to give an example of how to quickly use the instances in this module:
 
-    * Support for :class:`~passlib.hash.sha256_crypt` and :class:`~passlib.hash.sha512_crypt`
-    * Defaults to SHA256-Crypt under 32 bit systems; SHA512-Crypt under 64 bit systems.
-    * Comes pre-configured with strong rounds settings.
+Each of the objects in this module can be imported directly::
 
-    For applications which want to quickly add a password hash,
-    all they need to do is the following::
-
-        >>> #import the context under an app-specific name (so it can easily be replaced later)
-        >>> from passlib.apps import custom_app_context as pwd_context
+    >>> # as an example, this imports the custom_app_context object,
+    >>> # a helper to let new applications *quickly* add password hashing.
+    >>> from passlib.apps import custom_app_context
 
-        >>> #encrypting a password...
-        >>> hash = pwd_context.encrypt("somepass")
+Encrypting a password is simple (and salt generation is handled automatically)::
 
-        >>> #verifying a password...
-        >>> ok = pwd_context.verify("somepass", hash)
+    >>> hash = custom_app_context.encrypt("toomanysecrets")
+    >>> hash
+    '$5$rounds=84740$fYChCy.52EzebF51$9bnJrmTf2FESI93hgIBFF4qAfysQcKoB0veiI0ZeYU4'
 
-        >>> #[optional] encrypting a password for an admin account - uses stronger settings
-        >>> hash = pwd_context.encrypt("somepass", category="admin")
+Verifying a password against an existing hash is just as quick::
 
-.. seealso::
+    >>> custom_app_context.verify("toomanysocks", hash)
+    False
+    >>> custom_app_context.verify("toomanysecrets", hash)
+    True
 
-    The :doc:`/new_app_quickstart`.
+.. seealso:: the :ref:`CryptContext Tutorial <context-tutorial>`
+    and :ref:`CryptContext Reference <context-reference>`
+    for more information about the CryptContext class.
 
 .. index:: django; crypt context
 
+.. _django-contexts:
+
 Django
 ======
 The following objects provide pre-configured :class:`!CryptContext` instances
@@ -182,16 +181,22 @@ PostgreSQL
 
         >>> from passlib.apps import postgres_context
 
-        >>> #encrypting a password...
+        >>> # encrypting a password...
         >>> postgres_context.encrypt("somepass", user="dbadmin")
         'md578ed0f0ab2be0386645c1b74282917e7'
 
-        >>> #verifying a password...
+        >>> # verifying a password...
         >>> postgres_context.verify("somepass", 'md578ed0f0ab2be0386645c1b74282917e7', user="dbadmin")
         True
         >>> postgres_context.verify("wrongpass", 'md578ed0f0ab2be0386645c1b74282917e7', user="dbadmin")
         False
 
+        >>> # forgetting the user will result in an error:
+        >>> postgres_context.encrypt("somepass")
+        Traceback (most recent call last):
+            <traceback omitted>
+        TypeError: user must be unicode or bytes, not None
+
 .. index:: roundup; crypt context
 
 Roundup
@@ -218,3 +223,25 @@ The following contexts are available for reading Roundup password hash fields:
 
     this is an alias for the latest version-specific roundup context supported
     by passlib, currently the :data:`!roundup15_context`.
+
+.. _quickstart-custom-applications:
+
+Custom Applications
+===================
+.. data:: custom_app_context
+
+    This :class:`!CryptContext` object is provided for new python applications
+    to quickly and easily add password hashing support.
+    It comes preconfigured with:
+
+    * Support for :class:`~passlib.hash.sha256_crypt` and :class:`~passlib.hash.sha512_crypt`
+    * Defaults to SHA256-Crypt under 32 bit systems, SHA512-Crypt under 64 bit systems.
+    * Large number of ``rounds``, for increased time-cost to hedge against attacks.
+
+    For applications which want to quickly add a password hash,
+    all they need to do is import and use this object, per the
+    :ref:`usage example <predefined-context-example>` at the top of this page.
+
+    .. seealso::
+
+        The :doc:`/new_app_quickstart` for additional details.
diff --git a/docs/lib/passlib.exc.rst b/docs/lib/passlib.exc.rst
index b60ba63..6dbd4a5 100644
--- a/docs/lib/passlib.exc.rst
+++ b/docs/lib/passlib.exc.rst
@@ -16,7 +16,13 @@ Exceptions
 Warnings
 ========
 .. autoexception:: PasslibWarning
+
+Minor Warnings
+--------------
 .. autoexception:: PasslibConfigWarning
 .. autoexception:: PasslibHashWarning
+
+Critical Warnings
+-----------------
 .. autoexception:: PasslibRuntimeWarning
 .. autoexception:: PasslibSecurityWarning
diff --git a/docs/lib/passlib.hosts.rst b/docs/lib/passlib.hosts.rst
index 85514e8..954bf03 100644
--- a/docs/lib/passlib.hosts.rst
+++ b/docs/lib/passlib.hosts.rst
@@ -5,25 +5,68 @@
 .. module:: passlib.hosts
     :synopsis: encrypting & verifying operating system passwords
 
-This module provides :class:`!CryptContext` instances for encrypting &
-verifying password hashes tied to user accounts of various operating systems.
+This module provides some preconfigured :ref:`CryptContext <context-overview>`
+instances for encrypting & verifying password hashes tied to user accounts of various operating systems.
 While (most) of the objects are available cross-platform,
 their use is oriented primarily towards Linux and BSD variants.
 
 .. seealso::
+    for Microsoft Windows, see the list of :ref:`windows-hashes`
+    in :mod:`passlib.hash`.
 
-    :mod:`passlib.context` module for details about how to use a :class:`!CryptContext` instance.
+.. rst-class:: html-toggle
+
+Usage Example
+=============
+The :class:`!CryptContext` class itself has a large number of features,
+but to give an example of how to quickly use the instances in this module:
+
+Each of the objects in this module can be imported directly::
+
+    >>> # as an example, this imports the linux_context object,
+    >>> # which is configured to recognized most hashes found in Linux /etc/shadow files.
+    >>> from passlib.apps import linux_context
+
+Encrypting a password is simple (and salt generation is handled automatically)::
+
+    >>> hash = linux_context.encrypt("toomanysecrets")
+    >>> hash
+    '$5$rounds=84740$fYChCy.52EzebF51$9bnJrmTf2FESI93hgIBFF4qAfysQcKoB0veiI0ZeYU4'
+
+Verifying a password against an existing hash is just as quick::
+
+    >>> linux_context.verify("toomanysocks", hash)
+    False
+    >>> linux_context.verify("toomanysecrets", hash)
+    True
+
+You can also identify hashes::
+    >>> linux_context.identify(hash)
+    'sha512_crypt'
+
+Or encrypt using a specific algorithm::
+    >>> linux_context.schemes()
+    ('sha512_crypt', 'sha256_crypt', 'md5_crypt', 'des_crypt', 'unix_disabled')
+    >>> linux_context.encrypt("password", scheme="des_crypt")
+    '2fmLLcoHXuQdI'
+    >>> linux_context.identify('2fmLLcoHXuQdI')
+    'des_crypt'
+
+.. seealso::
+    the :ref:`CryptContext Tutorial <context-tutorial>`
+    and :ref:`CryptContext Reference <context-reference>`
+    for more information about the CryptContext class.
 
 Unix Password Hashes
 ====================
-PassLib provides a number of pre-configured :class:`!CryptContext` instances
+Passlib provides a number of pre-configured :class:`!CryptContext` instances
 which can identify and manipulate all the formats used by Linux and BSD.
 See the :ref:`modular crypt identifier list <mcf-identifiers>` for a complete
 list of which hashes are supported by which operating system.
 
 Predefined Contexts
 -------------------
-PassLib provides :class:`!CryptContext` instances
+Passlib provides :class:`!CryptContext` instances
 for the following Unix variants:
 
 .. data:: linux_context
@@ -54,21 +97,6 @@ for the following Unix variants:
     particularly the common strings ``!`` and ``*`` which are used to indicate
     that an account has been disabled [#shadow]_.
 
-A quick usage example, using the :data:`!linux_context` instance::
-
-    >>> from passlib.hosts import linux_context
-    >>> hash = linux_context.encrypt("password")
-    >>> hash
-    '$6$rounds=31779$X2o.7iqamZ.bAigR$ojbo/zh6sCmUuibhM7lnqR4Vy0aB3xGZXOYVLgtTFgNYiXaTNn/QLUz12lDSTdxJCLXHzsHiWCsaryAlcbAal0'
-    >>> linux_context.verify("password", hash)
-    True
-    >>> linux_context.identify(hash)
-    'sha512_crypt'
-    >>> linux_context.encrypt("password", scheme="des_crypt")
-    '2fmLLcoHXuQdI'
-    >>> linux_context.identify('2fmLLcoHXuQdI')
-    'des_crypt'
-
 Current Host OS
 ---------------
 
diff --git a/docs/lib/passlib.registry.rst b/docs/lib/passlib.registry.rst
index e2359d2..6302cb7 100644
--- a/docs/lib/passlib.registry.rst
+++ b/docs/lib/passlib.registry.rst
@@ -5,13 +5,23 @@
 .. module:: passlib.registry
     :synopsis: registry for tracking password hash handlers.
 
-This module contains the code PassLib uses to track all password hash handlers
+This module contains the code Passlib uses to track all password hash handlers
 that it knows about. While custom handlers can be used directly within an application,
 or even handed to a :class:`!CryptContext`; it is frequently useful to register
 them globally within a process and then refer to them by name.
 This module provides facilities for that, as well as programmatically
 querying passlib to detect what algorithms are available.
 
+.. warning::
+
+    This module is primarily used as an internal support module.
+    It's interface has not been finalized yet, and may be changed somewhat
+    between major releases of Passlib, as the internal code is cleaned up
+    and simplified.
+
+    Applications should access hashes through the :mod:`passlib.hash` module
+    where possible (new ones may also be registered by writing to that module).
+
 Interface
 =========
 .. autofunction:: get_crypt_handler
diff --git a/docs/lib/passlib.utils.handlers.rst b/docs/lib/passlib.utils.handlers.rst
index 8d0e202..06028c2 100644
--- a/docs/lib/passlib.utils.handlers.rst
+++ b/docs/lib/passlib.utils.handlers.rst
@@ -2,17 +2,18 @@
     pair: custom hash handler; implementing
 
 ==========================================================================
-:mod:`passlib.utils.handlers` - Helpers for writing password hash handlers
+:mod:`passlib.utils.handlers` - Framework for writing password hashes
 ==========================================================================
 
 .. module:: passlib.utils.handlers
-    :synopsis: helper classes for writing password hash handlers
+    :synopsis: framework for writing password hashes
 
 .. warning::
 
     This module is primarily used as an internal support module.
-    It's interface has not been finalized yet, and may change between major
-    releases of Passlib.
+    It's interface has not been finalized yet, and may be changed somewhat
+    between major releases of Passlib, as the internal code is cleaned up
+    and simplified.
 
 .. todo::
 
@@ -23,29 +24,29 @@
 Implementing Custom Handlers
 ============================
 All that is required in order to write a custom handler that will work with
-PassLib is to create an object (be it module, class, or object) that
+Passlib is to create an object (be it module, class, or object) that
 exposes the functions and attributes required by the :ref:`password-hash-api`.
-For classes, PassLib does not make any requirements about what a class instance
+For classes, Passlib does not make any requirements about what a class instance
 should look like (if the implementation even uses them).
 
-That said, most of the handlers built into PassLib are based around the :class:`GenericHandler`
+That said, most of the handlers built into Passlib are based around the :class:`GenericHandler`
 class, and it's associated mixin classes. While deriving from this class is not required,
 doing so will greatly reduce the amount of addition code that is needed for
 all but the most convoluted password hash schemes.
 
 Once a handler has been written, it may be used explicitly, passed into
 an application's custom :class:`CryptContext` directly, or registered
-globally with PassLib via the :mod:`passlib.registry` module.
+globally with Passlib via the :mod:`passlib.registry` module.
 
 See :ref:`testing-hash-handlers` for details about how to test
-custom handlers against PassLib's unittest suite.
+custom handlers against Passlib's unittest suite.
 
 The GenericHandler Class
 ========================
 
 Design
 ------
-Most of the handlers built into PassLib are based around the :class:`GenericHandler`
+Most of the handlers built into Passlib are based around the :class:`GenericHandler`
 class. This class is designed under the assumption that the common
 workflow for hashes is some combination of the following:
 
diff --git a/docs/lib/passlib.utils.rst b/docs/lib/passlib.utils.rst
index fd06c67..2e4f9f6 100644
--- a/docs/lib/passlib.utils.rst
+++ b/docs/lib/passlib.utils.rst
@@ -5,10 +5,17 @@
 .. module:: passlib.utils
     :synopsis: internal helpers for implementing password hashes
 
-This module contains a number of utility functions used by passlib
-to implement the builtin handlers, and other code within passlib.
+This module contains a number of utility functions used by Passlib
+to implement the builtin hashes and other internals.
 They may also be useful when implementing custom handlers for existing legacy formats.
 
+.. warning::
+
+    This module is primarily used as an internal support module.
+    It's interface has not been finalized yet, and may be changed somewhat
+    between major releases of Passlib, as the internal code is cleaned up
+    and simplified.
+
 Constants
 =========
 
@@ -116,7 +123,8 @@ Predefined Instances
 .. versionchanged:: 1.6
    Previous versions of Passlib contained
    a module named :mod:`!passlib.utils.h64`; As of Passlib 1.6 this
-   was replaced by the the ``h64`` and ``h64big`` instances;
+   was replaced by the the ``h64`` and ``h64big`` instances of
+   the :class:`Base64Engine` class;
    the interface remains mostly unchanged.
 
 Other
@@ -170,7 +178,6 @@ There are also a few sub modules which provide additional utility functions:
 
     passlib.utils.handlers
     passlib.utils.des
-    passlib.utils.md4
     passlib.utils.pbkdf2
 
 ..
diff --git a/docs/new_app_quickstart.rst b/docs/new_app_quickstart.rst
index 32df641..98097dc 100644
--- a/docs/new_app_quickstart.rst
+++ b/docs/new_app_quickstart.rst
@@ -40,7 +40,7 @@ instance; see below for more...
 Choosing a Hash
 ================
 *If you already know what hash algorithm(s) you want to use,
-skip to the next section,* `Creating a CryptContext`_.
+skip to the next section,* `Creating and Using a CryptContext`_.
 
 If you'd like to set up a configuration that's right for your
 application, the first thing to do is choose a password hashing scheme.
@@ -159,8 +159,26 @@ standard format for encoding password hashes using this algorithm
     the external M2Crypto package to speed up PBKDF2 calculations,
     though this is not required.
 
-Creating a CryptContext
-=======================
+.. index:: scrypt; status of
+
+What about SCrypt?
+..................
+`SCrypt <http://www.tarsnap.com/scrypt.html>`_ is the leading contender
+to be the next-generation password hash algorithm. It offers many advances
+over all of the above hashes; the primary feature being that it has
+a variable *memory* cost as well as time cost. It is incredibly well designed,
+and looks to likely replace all the others in this section.
+
+However, it is still young by comparison to the others; and has not been as throughly
+tested, or widely implemented. The only Python wrapper that exists
+does not even expose the underlying :func:`!scrypt` function,
+but is rather a file encryption tool.
+Due to these reasons, SCrypt has not yet been integrated into Passlib.
+
+.. seealso:: :issue:`8` of the Passlib bugtracker, for the current status of Passlib's SCrypt support.
+
+Creating and Using a CryptContext
+=================================
 One you've chosen what password hash(es) you want to use,
 the next step is to define a :class:`~passlib.context.CryptContext` object
 to manage your hashes, and relating configuration information.
@@ -175,36 +193,32 @@ Insert the following code into your application::
     #create a single global instance for your app...
     #
     pwd_context = CryptContext(
-        #replace this list with the hash(es) you wish to support.
-        #this example sets pbkdf2_sha256 as the default,
-        #with support for legacy des_crypt hashes.
+        # replace this list with the hash(es) you wish to support.
+        # this example sets pbkdf2_sha256 as the default,
+        # with support for legacy des_crypt hashes.
         schemes=["pbkdf2_sha256", "des_crypt" ],
         default="pbkdf2_sha256",
 
-        #vary rounds parameter randomly when creating new hashes...
-        all__vary_rounds = "10%",
+        # vary rounds parameter randomly when creating new hashes...
+        all__vary_rounds = 0.1,
 
-        #set the number of rounds that should be used...
-        #(appropriate values may vary for different schemes,
+        # set the number of rounds that should be used...
+        # (appropriate values may vary for different schemes,
         # and the amount of time you wish it to take)
         pbkdf2_sha256__default_rounds = 8000,
         )
 
+To start using your CryptContext, import the context you created wherever it's needed::
 
-Using a CryptContext
-====================
-To start using your CryptContext, import the context you created
-in the previous section wherever needed::
-
-    >>> #import context from where you defined it...
+    >>> # import context from where you defined it...
     >>> from myapp.model.security import pwd_context
 
-    >>> #encrypting a password...
+    >>> # encrypting a password...
     >>> hash = pwd_context.encrypt("somepass")
     >>> hash
     '$pbkdf2-sha256$7252$qKFNyMYTmgQDCFDS.jRJDQ$sms3/EWbs4/3k3aOoid5azwq3HPZKVpUUrAsCfjrN6M'
 
-    >>> #verifying a password...
+    >>> # verifying a password...
     >>> pwd_context.verify("somepass", hash)
     True
     >>> pwd_context.verify("wrongpass", hash)
@@ -212,8 +226,9 @@ in the previous section wherever needed::
 
 .. seealso::
 
-    * :mod:`passlib.hash` - list of all hashes supported by passlib.
-    * :mod:`passlib.context` - for more details about the CryptContext class.
+    * :mod:`passlib.hash` -- list of all hashes supported by passlib.
+    * :ref:`CryptContext Overview & Tutorial <context-overview>` -- walkthrough of how to use the CryptContext class.
+    * :ref:`CryptContext Reference <context-reference>` -- reference for the CryptContext api.
 
 .. rubric:: Footnotes
 
diff --git a/docs/overview.rst b/docs/overview.rst
index c9aad2c..899b7fe 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -8,96 +8,74 @@ as stored in mysql and postgres, and various other places.
 Passlib's contents can be roughly grouped into three categories:
 password hashes, password contexts, and utility functions.
 
-.. note::
-
-    New applications which just need drop-in password hashing support
-    should see the :doc:`new_app_quickstart`.
-
 Password Hashes
 ===============
 All of the hash schemes supported by Passlib are implemented
-as classes importable from the :mod:`passlib.hash` module.
-All of these classes support a single uniform interface of standard class methods.
-These methods are documented in detail by the :ref:`password hash api <password-hash-api>`.
-
-As a quick example of how a password hash can be used directly::
-
-    >>> #import the SHA512-Crypt class:
-    >>> from passlib.hash import sha512_crypt as sc
-
-    >>> #generate new salt, encrypt password:
-    >>> h = sc.encrypt("password")
-    >>> h
-    '$6$rounds=40000$xCsOXRqPPk5AGDFu$o5eyqxEoOSq0dLRFbPxEHp5Jc1vFVj47BNT.h9gmjSHXDS15mjIM.GSUaT5r6Z.Xa1Akrv4FAgKJE3EfbkJxs1'
-
-    >>> #same, but with explict number of rounds:
-    >>> sc.encrypt("password", rounds=10000)
-    '$6$rounds=10000$QWT8AlDMYRms7vSx$.1267Pg6Opn9CblFndtBJ2Q0AI0fcI2IX93zX3gi1Qse./j.VlKYX59NIUlbs0A66wCbfu/vra9wMv2uwTZAI.'
-
-    >>> #check if string is recognized as belonging to this hash scheme:
-    >>> sc.identify(h)
-    True
-    >>> #check if some other hash is recognized:
-    >>> sc.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31')
-    False
-
-    >>> #verify correct password:
-    >>> sc.verify("password", h)
-    True
-    >>> #verify incorrect password:
-    >>> sc.verify("secret", h)
-    False
+as classes which can be imported from the :mod:`passlib.hash` module.
+In turn, all of the hash classes implement a single uniform interface,
+which is documented in detail and with usage examples in the
+:ref:`password-hash-api` document.
+However, many of these hashes are severely insecure, provided only for legacy
+purposes, or are specialized in ways that are not generally useful.
+If you are creating a new application and need to choose a password hash,
+see the :doc:`new_app_quickstart`.
+
+.. seealso::
+
+    - :mod:`passlib.hash` -- all the hashes supported by Passlib.
+    - :ref:`password-hash-api` -- documentation of the common PasswordHash interface.
+    - :doc:`new_app_quickstart` -- choosing a hash for new applications.
 
 Password Contexts
 =================
-Mature applications frequently have to deal with tables of existing password
-hashes. Over time, they have to migrate to newer and stronger schemes; as well as raise
-the requirements for existing algorithms as more processing power becomes available.
-In this case, directly importing and handling the various schemes
-generally becomes complicated and tedious.
-
-The :mod:`passlib.context` module provides the :class:`!CryptContext` class and other
-utilties to help with these use-cases. This class handles
-managing multiple password hash schemes, deprecation & migration of old hashes, and
-many other policy requirements.
-
-A quick example of how a password context can be used::
-
-    >>> #importing the 'linux_context', which understands
-    >>> #all hashes found on standard linux systems:
-    >>> from passlib.hosts import linux_context as lc
-
-    >>> #try encrypting a password
-    >>> lc.encrypt("password")
-    '$6$rounds=30000$suoPoYtkbccdZa3v$DW2KUcV98H4IrvlBB0YZf4DM8zqz5vduygB3OROhPzwHE5PDNVkpSUjJfjswn/dXqidha5t5CSCCIhtm6mIDR1'
-
-    >>> #try encrypting a password using a specified scheme
-    >>> lc.encrypt("password", scheme="des_crypt")
-    'q1Oyx5r9mdGZ2'
-
-    >>> #try verifying a password (scheme is autodetected)
-    >>> lc.verify('password', 'q1Oyx5r9mdGZ2')
-    True
-
-Predefined Password Contexts
-============================
-In addition to the :mod:`!passlib.context` module,
-PassLib provides a number of pre-configured :class:`!CryptContext` instances
+Mature applications frequently have to deal with tables of existing password hashes.
+Over time, they have to support a number of tasks:
+
+* add support for new algorithms, and deprecate old ones,
+* raise the time-cost settings for existing algorithms, as computing power increases,
+* and do rolling upgrades of existing hashes to comply with these changes.
+* hardcode these policies in the source, or spend time implementing
+  a configuration language for them.
+
+In these situations, loading and handling multiple hash algorithms becomes
+complicated and tedious. The :mod:`passlib.context` module provides a single class,
+:class:`!CryptContext`, which attempts to solve all of these problems,
+or at least relieve applications developers of (most of) the burden.
+This class handles managing multiple password hash schemes,
+deprecation & migration of old hashes, and supports a simple configuration
+language that can be serialized to an INI file.
+
+.. seealso::
+
+    * :ref:`CryptContext Tutorial <context-tutorial>` -- complete walkthrough of the CryptContext class.
+    * :ref:`CryptContext API Reference <context-reference>` -- full method and attribute documentation.
+
+Application Helpers
+===================
+Passlib also provides a number of pre-configured :class:`!CryptContext` instances
 in order to get users started quickly:
 
-* The :mod:`passlib.apache` module contains classes
-  for managing htpasswd and htdigest files.
+    * :mod:`passlib.apps` -- contains pre-configured
+      instances for managing hashes used by Postgres, Mysql, and LDAP, and others.
+
+    * :mod:`passlib.hosts` -- contains pre-configured
+      instances for managing hashes as found in the /etc/shadow files
+      on Linux and BSD systems.
+
+Passlib also contains a couple of additional modules which provide
+support for certain application-specific tasks:
 
-* The :mod:`passlib.apps` module contains pre-configured
-  instances for managing hashes used by Postgres, Mysql, and LDAP, and others.
+    * :mod:`passlib.apache` -- classes for managing htpasswd and htdigest files.
 
-* The :mod:`passlib.hosts` module contains pre-configured
-  instances for managing hashes as found in the /etc/shadow files
-  on Linux and BSD systems.
+    * :mod:`passlib.ext.django` -- Django plugin which monkeypatches support for (almost) any hash in Passlib.
 
 Utility Functions
 =================
-The :mod:`passlib.registry` and :mod:`passlib.utils` modules contain a large number
-of support functions, most of which are only needed when
-are implementing custom password hash schemes. Most users of passlib
-will not need to use these.
+Additionally, Passlib contains a number of modules which are used internally
+to implement the all of the other features. These may change between major
+releases, and won't be needed by most users of Passlib. They are documented
+mainly to aid in examining the source.
+
+    * :mod:`passlib.exc` -- all the custom errors & warnings used by Passlib.
+    * :mod:`passlib.registry` -- functions for registering password hash algorithms.
+    * :mod:`passlib.utils` -- support functions for implementing password hashes.