fixed some awkward sentences in docs

3 files changed, 44 insertions, 47 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 34f6e90..00c3dd2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,21 +7,23 @@ Welcome
 Passlib is a password hashing library for Python, which provides cross-platform
 implementations of over 20 password hashing algorithms;
 as well as a framework for managing and migrating existing password hashes.
-It's designed to be useful for a large range of tasks...
+It's designed to be useful for a large range of tasks:
 
-* as a cross-platform replacement for stdlib's :func:`!crypt` --> :data:`~passlib.hosts.host_context`.
+* as a cross-platform replacement for stdlib's crypt ~
+  :data:`passlib.hosts.host_context`
 
 * encrypting & verifying most hash formats used by:
-    - Linux & BSD shadow files --> :mod:`passlib.hosts`
-    - Apache htpasswd & htdigest files --> :mod:`passlib.apache`
-    - MySQL, PostgreSQL, and Oracle user account tables
-    - OpenLDAP password hashes
-    - Many other applications --> :mod:`passlib.apps`.
 
-* drop-in password hash support for new python applications --> :data:`~passlib.apps.custom_app_context`.
+    - Linux & BSD shadow files ~ :mod:`passlib.hosts`
+    - Apache htpasswd & htdigest files ~ :mod:`passlib.apache`
+    - MySQL, PostgreSQL, and Oracle, OpenLDAP, and other applications ~
+      :mod:`passlib.apps`
 
-* building a configurable hashing policy
-  for python applications to migrate existing hashing schemes --> :mod:`passlib.context`.
+* quick-start password hashing for new python applications ~
+  :data:`passlib.apps.custom_app_context`
+
+* construct a configurable hashing policy
+  to match the needs of any python application ~ :data:`passlib.context`
 
 See the :doc:`library overview <overview>` for more details and usage examples.
 
diff --git a/docs/lib/passlib.hosts.rst b/docs/lib/passlib.hosts.rst
index 163e1e6..08538fd 100644
--- a/docs/lib/passlib.hosts.rst
+++ b/docs/lib/passlib.hosts.rst
@@ -78,13 +78,19 @@ Current Host OS
 
     :platform: Unix
 
-    It should support all the algorithms the native OS :func:`!crypt` will support.
-    The main difference is that it provides introspection about *which* schemes
-    are available on a given system, as well as defaulting to the strongest
-    algorithm and decent number of rounds when encrypting new passwords
-    (whereas :func:`!crypt` invariably defaults to using :mod:`~passlib.hash.des_crypt`).
-
-    This can be used in conjunction with stdlib's :mod:`!spwd` module
+    This :class:`~passlib.context.CryptContext` instance should detect and support
+    all the algorithms the native OS :func:`!crypt` offers.
+    The main differences between this object and :func:`!crypt`:
+
+    * this object provides introspection about *which* schemes
+      are available on a given system (via ``host_context.policy.schemes()``).
+    * it defaults to the strongest algorithm available,
+      automatically configured to an appropriate strength
+      for encrypting new passwords.
+    * whereas :func:`!crypt` typically defaults to using
+      :mod:`~passlib.hash.des_crypt`; and provides little introspection.
+
+    As an example, this can be used in conjunction with stdlib's :mod:`!spwd` module
     to verify user passwords on the local system::
 
         >>> #NOTE/WARNING: this example requires running as root on most systems.
@@ -98,7 +104,6 @@ Current Host OS
         This object is only available on systems where the stdlib :mod:`!crypt` module is present.
         In version 1.3 and earlier, it was available on non-Unix systems, though it did nothing useful.
 
-
 References
 ==========
 
diff --git a/docs/modular_crypt_format.rst b/docs/modular_crypt_format.rst
index 9c31c8e..aa80900 100644
--- a/docs/modular_crypt_format.rst
+++ b/docs/modular_crypt_format.rst
@@ -122,43 +122,33 @@ by the modular crypt format hashes found in passlib:
 Identifiers & Platform Support
 ==============================
 
-The following chart lists the various operating systems, which
-hash algorithms are known to be supported, as well as the hash's
-identifying prefix.
-
-==================================== ================== =========== =========== =========== ===========
-Scheme                               Prefix             Linux       FreeBSD     NetBSD      OpenBSD
-==================================== ================== =========== =========== =========== ===========
-:class:`~passlib.hash.des_crypt`     n/a                y           y           y           y
+The following table lists of all the major MCF hashes supported by passlib,
+and indicates which operating systems offer native support. 
+
+==================================== ================== =========== =========== =========== =========== =======
+Scheme                               Prefix             Linux       FreeBSD     NetBSD      OpenBSD     Solaris
+==================================== ================== =========== =========== =========== =========== =======
+:class:`~passlib.hash.des_crypt`     n/a                y           y           y           y           y
 :class:`~passlib.hash.bsdi_crypt`    ``_``                          y           y
-:class:`~passlib.hash.md5_crypt`     ``$1$``            y           y           y           y
-:class:`~passlib.hash.sun_md5_crypt` ``$md5$``
-:class:`~passlib.hash.bcrypt`        ``$2$``, ``$2a$``              y           y           y
+:class:`~passlib.hash.md5_crypt`     ``$1$``            y           y           y           y           y
+:class:`~passlib.hash.sun_md5_crypt` ``$md5$``                                                          y
+:class:`~passlib.hash.bcrypt`        ``$2$``, ``$2a$``              y           y           y           y
 :class:`~passlib.hash.nthash`        ``$3$``                        y
-:class:`~passlib.hash.sha256_crypt`  ``$5$``            y
-:class:`~passlib.hash.sha512_crypt`  ``$6$``            y
-:class:`~passlib.hash.sha1_crypt`    ``$sha1$``                                 y
-==================================== ================== =========== =========== =========== ===========
-
-.. note::
-
-    :class:`!des_crypt` and :class:`!bsdi_crypt` do not conform to the MCF,
-    but are listed here for completeness.
-
-.. todo::
-
-    include Solaris and other Unix flavors in this chart.
+:class:`~passlib.hash.sha256_crypt`  ``$5$``            y                                               y
+:class:`~passlib.hash.sha512_crypt`  ``$6$``            y                                               y
+:class:`~passlib.hash.sha1_crypt`    ``$sha1$``                                 y 
+==================================== ================== =========== =========== =========== =========== =======
 
-The following chart lists other MCF schemes supported by passlib,
+The following table lists the other MCF hashes supported by passlib,
 most of which are only used by applications:
 
-=========================================== =================== =======================
+=========================================== =================== ===========================
 Scheme                                      Prefix              Known Uses
-=========================================== =================== =======================
+=========================================== =================== ===========================
 :class:`~passlib.hash.apr_md5_crypt`        ``$apr1$``          Apache htdigest files
-:class:`~passlib.hash.phpass`               ``$P$``, ``$H$``    PHPass applications
+:class:`~passlib.hash.phpass`               ``$P$``, ``$H$``    PHPass-based applications
 :class:`~passlib.hash.pbkdf2_sha1`          ``$pbkdf2-sha1$``
 :class:`~passlib.hash.pbkdf2_sha256`        ``$pbkdf2-sha256$``
 :class:`~passlib.hash.pbkdf2_sha512`        ``$pbkdf2-sha512$``
 :class:`~passlib.hash.dlitz_pbkdf2_sha1`    ``$p5k2$``
-=========================================== =================== =======================
+=========================================== =================== ===========================