minor documentation changes

3 files changed, 22 insertions, 19 deletions

diff --git a/docs/lib/passlib.hash.crypt16.rst b/docs/lib/passlib.hash.crypt16.rst
index 28c5424..9fd2a21 100644
--- a/docs/lib/passlib.hash.crypt16.rst
+++ b/docs/lib/passlib.hash.crypt16.rst
@@ -51,7 +51,8 @@ The crypt16 algorithm uses a weakened version of the des-crypt algorithm:
    The salt string uses little-endian
    :func:`hash64 <passlib.utils.h64.decode_int12>` encoding.
 
-3. The password is NULL padded at the end or truncated to 16 bytes, as appropriate.
+3. If the password is larger than 16 bytes, the end is truncated to 16 bytes.
+   If the password is smaller than 16 bytes, the end is NULL padded to 16 bytes.
 
 4. The lower 7 bits of the first 8 characters of the password are used
    to form a 56-bit integer; with the first character providing
@@ -62,9 +63,10 @@ The crypt16 algorithm uses a weakened version of the des-crypt algorithm:
    starting with a null input block,
    and using the 56-bit integer from step 4 as the DES key.
 
-   The salt is used to to mutate the normal DES encrypt operation
-   by swapping bits :samp:`{i}` and :samp:`{i}+24` in the DES E-Box output
-   if and only if bit :samp:`{i}` is set in the salt value.
+   The salt value from step 2 is used to to mutate the normal 
+   DES encrypt operation by swapping bits :samp:`{i}` and :samp:`{i}+24` 
+   in the DES E-Box output if and only if bit :samp:`{i}` is set in 
+   the salt value.
 
 6. The 64-bit result of the last round of step 5 is then
    lsb-padded with 2 zero bits.
diff --git a/docs/lib/passlib.hash.oracle10.rst b/docs/lib/passlib.hash.oracle10.rst
index 27e7b6b..15deac3 100644
--- a/docs/lib/passlib.hash.oracle10.rst
+++ b/docs/lib/passlib.hash.oracle10.rst
@@ -82,11 +82,12 @@ Oracle10 account passwords, due to the following flaws [#flaws]_:
   (eg ``system``) will occur more frequently as salts,
   weakening the effectiveness of the salt in foiling pre-computed tables.
 
-* The fact that is it case insensitive, and simply concatenates the username
-  and password, greatly reduces the keyspace for brute-force
-  or pre-computed attacks.
+* The fact that it is case insensitive, and simply concatenates the username
+  and password, greatly reduces the keyspace that must be searched by 
+  brute-force or pre-computed attacks.
 
-* It's simplicity makes high-speed brute force attacks much more feasible.
+* It's simplicity, and decades of research on high-speed DES 
+  implementations, makes efficient brute force attacks much more feasible.
 
 Deviations
 ==========
@@ -109,7 +110,7 @@ There is only one known issue:
 .. rubric:: Footnotes
 
 .. [#enc] The exact encoding used in step 3 of the algorithm is not clear from known references.
-          PassLib uses ``utf-16-be``, as this is both compatible with existing test vectors
+          PassLib uses ``utf-16-be``, as this is both compatible with existing test vectors,
           and supports unicode input.
 
 .. [#flaws] Whitepaper analyzing flaws in this algorithm -
diff --git a/docs/new_app_quickstart.rst b/docs/new_app_quickstart.rst
index a3a84ff..d18afb3 100644
--- a/docs/new_app_quickstart.rst
+++ b/docs/new_app_quickstart.rst
@@ -86,7 +86,7 @@ There is also an alternative LDAP-formatted version
 Issues: Neither the original Blowfish,
 nor the modified version which BCrypt uses, have been NIST approved;
 this matter of concern is what motivated the development of SHA512-Crypt.
-As well, it's rounds parameter is logarithmically scaled,
+As well, its rounds parameter is logarithmically scaled,
 making it hard to fine-tune the amount of time taken to verify passwords;
 which can be an issue for applications that handle a large number
 of simultaneous logon attempts (eg web apps).
@@ -102,7 +102,7 @@ of simultaneous logon attempts (eg web apps).
 SHA512-Crypt
 ............
 :class:`~passlib.hash.sha512_crypt` is
-based on well-tested :class:`~passlib.hash.md5_crypt`
+based on the well-tested :class:`~passlib.hash.md5_crypt`
 algorithm. In use since 2008, it's the default hash on most Linux systems;
 its direct ancestor :class:`!md5_crypt` has been in use since 1994 on most Unix systems.
 If you want your application's hashes to be readable by the
@@ -112,10 +112,10 @@ on 32 bit processors; as well as LDAP-formatted versions of these (
 :class:`~passlib.hash.ldap_sha512_crypt` and
 :class:`~passlib.hash.ldap_sha256_crypt`).
 
-Issues: Like :class:`~passlib.hash.md5_crypt`, it's algorithm
+Issues: Like :class:`~passlib.hash.md5_crypt`, its algorithm
 composes the underlying message digest hash in a baroque
 and somewhat arbitrary set combinations.
-So far this "kitchen sink" design has been successful in it's
+So far this "kitchen sink" design has been successful in its
 primary purpose: to prevent any attempts to create an optimized
 version for use in a pre-computed or brute-force search.
 However, this design also hampers analysis of the algorithm
@@ -123,13 +123,13 @@ for future flaws.
 
 This algorithm is probably the best choice for Google App Engine,
 as Google's production servers appear to provide native support
-via :mod:`crypt`, which will be used by Passlib. 
+via :mod:`crypt`, which will be used by Passlib.
 
 .. note::
 
-    References to this algorithm are frequently confused with a raw SHA-512 hash;
-    while it uses SHA-512 as a cryptographic primitive,
-    this algorithm's resulting password hash is far more secure.
+    References to this algorithm are frequently confused with a raw SHA-512 hash.
+    While :class:`!sha512_crypt` uses the SHA-512 hash as a cryptographic primitive,
+    the algorithm's resulting password hash is far more secure.
 
 PBKDF2
 ......
@@ -148,10 +148,10 @@ on 32 bit processors; as well as LDAP-formatted versions of these (
 :class:`~passlib.hash.ldap_pbkdf2_sha256`).
 
 Issues: PBKDF2 has no security or portability issues.
-However, it's only come into wide use as a password hash
+However, it has only come into wide use as a password hash
 in recent years; mainly hampered by the fact that there is no
 standard format for encoding password hashes using this algorithm
-(which is why Passlib has it's own :ref:`custom format <mcf-pbkdf2-format>`).
+(which is why Passlib has its own :ref:`custom format <mcf-pbkdf2-format>`).
 
 .. note::