Touchups to the docs

docs/source/choosing_and_using_curves.rst

@@ -6,8 +6,10 @@ Choosing and Using Curves
 The matter of which curve to use is the subject of some debate.  If you aren't sure, you might start here:
 https://safecurves.cr.yp.to/
 
-A number of curves are available in the python cryptography library, on which pyumbral depends.
-You can find them in cryptography.hazmat.primitives.asymmetric.ec.
+A number of curves are available in the Cryptography.io_ library, on which pyUmbral depends.
+You can find them in the ``cryptography.hazmat.primitives.asymmetric.ec`` module.
+
+.. _Cryptography.io: https://cryptography.io/en/latest/
 
 Be careful when choosing a curve - the security of your application depends on it.
 
@@ -39,7 +41,7 @@ operation.  This causes a small one-time performance penalty.
     Set a default curve with umbral.config.set_default_curve().
 
 
-To use SECP256K1 and avoid this penalty, you can simply call `set_default_curve()` with no argument:
+To use SECP256K1 and avoid this penalty, you can simply call ``set_default_curve()`` with no argument:
 
 
 .. code-block:: python
@@ -47,7 +49,7 @@ To use SECP256K1 and avoid this penalty, you can simply call `set_default_curve(
     >>> config.set_default_curve()
 
 Attempting to set the default curve twice in the same runtime will raise
-a `UmbralConfigurationError`.
+a ``UmbralConfigurationError``.
 
 
 .. code-block:: python

docs/source/installation.rst

@@ -6,7 +6,7 @@ v0.1.3-alpha.0
 Using pip
 -------------------------
 
-The easiest way to install pyUmbral is using pip:
+The easiest way to install pyUmbral is using ``pip``:
 
 .. code-block:: bash
 
@@ -48,15 +48,15 @@ Once you have acquired the source code, you can...
 Install dependencies
 ---------------------
 
-| The NuCypher team uses pipenv for managing pyUmbral's dependencies.
-| The recommended installation procedure is as follows:
+The NuCypher team uses pipenv for managing pyUmbral's dependencies.
+The recommended installation procedure is as follows:
 
 .. code-block:: bash
 
    $ sudo pip3 install pipenv
    $ pipenv install
 
-Post-installation, you can activate the pyUmbral's virtual enviorment
+Post-installation, you can activate the pyUmbral's virtual environment
 in your current terminal session by running :code:`pipenv shell`.
 
 If your installation is successful, the following command will succeed without error.

docs/source/using_pyumbral.rst

@@ -46,8 +46,8 @@ Encryption
 
 Generate an Umbral key pair
 -----------------------------
-First, Let's generate two asymmetric key pairs for Alice:
-A delegating key pair and a Signing key pair.
+First, let's generate two asymmetric key pairs for Alice:
+A delegating key pair and a signing key pair.
 
 .. doctest:: capsule_story
 
@@ -64,9 +64,8 @@ A delegating key pair and a Signing key pair.
 Encrypt with a public key
 --------------------------
 Now let's encrypt data with Alice's public key.
-Invocation of `pre.encrypt` returns both the `ciphertext`,
-and a `capsule`, Anyone with Alice's public key can perform
-this operation.
+Invocation of ``pre.encrypt`` returns both the ``ciphertext`` and a ``capsule``.
+Note that anyone with Alice's public key can perform this operation.
 
 
 .. doctest:: capsule_story
@@ -86,7 +85,7 @@ Alice can open the capsule and decrypt the ciphertext with her private key.
     >>> cleartext = pre.decrypt(ciphertext=ciphertext, capsule=capsule, decrypting_key=alices_private_key)
 
 
-Threshold split-key re-encryption
+Threshold Re-encryption
 ==================================
 
 Bob Exists
@@ -102,12 +101,13 @@ Bob Exists
 Alice grants access to Bob by generating kfrags 
 -----------------------------------------------
 When Alice wants to grant Bob access to open her encrypted messages, 
-she creates *threshold split re-encryption keys*, or *"kfrags"*, 
-which are next sent to N proxies or *Ursulas*. 
+she creates *re-encryption key fragments*, or *"kfrags"*,
+which are next sent to N proxies or *Ursulas*.
 
-| Generate re-encryption key fragments with "`M`(threshold) of `N`":
-| `threshold` - Minimum threshold of key fragments needed to activate a capsule.
-| `N` - Total number of key fragments to generate.
+Alice must specify ``N`` (the total number of kfrags),
+and a ``threshold`` (the minimum number of kfrags needed to activate a capsule).
+In the following example, Alice creates 20 kfrags,
+but Bob needs to get only 10 re-encryptions to activate the capsule.
 
 .. doctest:: capsule_story
 
@@ -148,14 +148,14 @@ or re-encrypted for him by Ursula, he will not be able to open it.
 Ursulas perform re-encryption
 ------------------------------
 Bob asks several Ursulas to re-encrypt the capsule so he can open it. 
-Each Ursula performs re-encryption on the capsule using the `kfrag` 
-provided by Alice, obtaining this way a "capsule fragment", or `cfrag`,
-Let's mock a network or transport layer by sampling `threshold` random `kfrags`,
+Each Ursula performs re-encryption on the capsule using the ``kfrag``
+provided by Alice, obtaining this way a "capsule fragment", or ``cfrag``.
+Let's mock a network or transport layer by sampling ``threshold`` random kfrags,
 one for each required Ursula. Note that each Ursula must prepare the received 
 capsule before re-encryption by setting the proper correctness keys.
 
-Bob collects the resulting `cfrags` from several Ursulas. 
-Bob must gather at least `threshold` `cfrags` in order to activate the capsule.
+Bob collects the resulting cfrags from several Ursulas.
+Bob must gather at least ``threshold`` cfrags in order to activate the capsule.
 
 
 .. doctest:: capsule_story
@@ -182,7 +182,7 @@ Bob must gather at least `threshold` `cfrags` in order to activate the capsule.
 
 Bob attaches cfrags to the capsule
 ----------------------------------
-Bob attaches at least `threshold` `cfrags` to the capsule, 
+Bob attaches at least ``threshold`` cfrags to the capsule,
 which has to be prepared in advance with the necessary correctness keys. 
 Only then it can become *activated*.
 
@@ -199,8 +199,7 @@ Only then it can become *activated*.
 
 Bob activates and opens the capsule
 ------------------------------------
-Finally, Bob activates and opens the capsule,
-then decrypts the re-encrypted ciphertext.
+Finally, Bob decrypts the re-encrypted ciphertext using the activated capsule.
 
 .. doctest:: capsule_story