spelling, capitalization, and formatting cleanup

doc/conf.py

@@ -55,8 +55,8 @@
 
 # General information about the project.
 project = u'Autocrypt'
-copyright = u'2016, hpk, dkg and the autocrypt team'
-author = u'hpk, dkg and the autocrypt team'
+copyright = u'2016, hpk, dkg and the Autocrypt team'
+author = u'hpk, dkg and the Autocrypt team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

doc/ecosystem-dangers.rst

@@ -93,7 +93,7 @@ Mitigations:
 - make out-of-band verification of keys between users 
   fun and thus increase the risk for attackers to get detected.
 
-- research how "level 2" autocrypt could evolve to offer
+- research how "level 2" Autocrypt could evolve to offer
   automated support against active attackers.
 
 

doc/features.rst

@@ -5,7 +5,7 @@ Features of the Autocrypt effort
 End-to-end encrypted e-mail has been around for decades, but has failed
 to see wide adoption outside of specialist communities, in large part
 because of difficulties user experience and certification models.
-To better understand how the fresh autocrypt effort is different 
+To better understand how the fresh Autocrypt effort is different 
 from previous ones here are some of its features:
 
 - **Protect first against passive data-collecting adversaries**,
@@ -15,7 +15,7 @@ from previous ones here are some of its features:
   motivation of this and the next points.
 
 - **Focus on incremental deployment**, always consider that there
-  will be both autocrypt-enabled MUAs and traditional plain ones,
+  will be both Autocrypt-enabled MUAs and traditional plain ones,
   interacting with each other. 
 
 - **Don't ask users anything about keys, ever.** And minimize and 

doc/index.rst

@@ -10,10 +10,10 @@ in-app-only communication.  E-mail remains the largest open federated
 identity and messaging eco-system, anchors the web, mobiles and continues 
 to relay sensitive information between citizens and organisations. 
 
-The autocrypt project is driven by mail app developers, hackers 
+The Autocrypt project is driven by mail app developers, hackers 
 and researchers who are willing to take fresh approaches, learn from
 past mistakes, and collectively aim to increase the overall encryption
-of E-Mail in the net.  The group effort was born and named "autocrypt"
+of E-Mail in the net.  The group effort was born and named "Autocrypt"
 on December 17th 2016 by ~20 people during a 5-day meeting at the 
 OnionSpace in Berlin. It's a dynamic, fun process which is open to 
 new people, influences and contributions. No need to tweet but
@@ -72,14 +72,15 @@ Channels
 If you want to help, including offering constructive criticism, 
 you may:
 
-- join the `autocrypt mailing list`_
+- join the `Autocrypt mailing list`_
 
 - join chats at **#autocrypt on freenode or matrix.org**.
 
 - collaborate through PRs, issues and edits on our
-  `github autocrypt repo <https://github.com/autocrypt/autocrypt>`_
+  `github Autocrypt repo`
 
-.. _`autocrypt mailing list`: https://lists.mayfirst.org/mailman/listinfo/autocrypt
+.. _`Autocrypt mailing list`: https://lists.mayfirst.org/mailman/listinfo/autocrypt
+.. _`github Autocrypt repo`: https://github.com/autocrypt/autocrypt
 
 .. _`upcoming events`:
 

doc/key-discovery.rst

@@ -1,9 +1,21 @@
 Autocrypt in-band key discovery
 ===============================
 
-Autocrypt key discovery happens through headers of mail messages sent between mail apps. Similar to TLS's machine to machine handshake, users first need to have a cleartext mail exchange.  Subsequent mails from the receiving peer will may then be encrypted.  Mail apps show encryptability to their users at "compose-mail" time and give them a choice of encryption or cleartext, defaulting to what the other side has specified in their header.
-
-Autocrypt key discovery is safe only against passive eavesdroppers. It is trivial for providers to perform active downgrade or man-in-the-middle attacks on Autocrypt's key discovery.  Users may, however, detect such tampering if they out-of-band verify their keys at some later point in time.  This possiblity in turn is likely to keep most providers honest or at least prevent them from performing active attacks on a massive scale.
+Autocrypt key discovery happens through headers of mail messages sent
+between mail apps. Similar to TLS's machine to machine handshake,
+users first need to have a cleartext mail exchange.  Subsequent mails
+from the receiving peer will may then be encrypted.  Mail apps show
+encryptability to their users at "compose-mail" time and give them a
+choice of encryption or cleartext, defaulting to what the other side
+has specified in their header.
+
+Autocrypt key discovery is safe only against passive eavesdroppers. It
+is trivial for providers to perform active downgrade or
+man-in-the-middle attacks on Autocrypt's key discovery.  Users may,
+however, detect such tampering if they out-of-band verify their keys
+at some later point in time.  This possiblity in turn is likely to
+keep most providers honest or at least prevent them from performing
+active attacks on a massive scale.
 
 .. contents::
 
@@ -26,13 +38,20 @@ Header Format
 -------------
 
 The ``Autocrypt:`` header MUST have the following format:
+
 ```
-Autocrypt-ENCRYPTION: to=aaa@bbb.cc; [type=(p|...);] [prefer-encrypted=(yes|no);] key=BASE64
+Autocrypt-ENCRYPTION: to=a@b.example; [type=(p|...);] [prefer-encrypted=(yes|no);] key=BASE64
 ```
 
-Where key includes a Base64 representation of a minimal key. For now we only support 'p' as the type, which represents a specific subset of OpenPGP (see key-formats.rst).
-'prefer-encrypted' indicates that agents should default to encrypting when composing emails.
-Autocrypt compatible Agents MUST include one header with a key in a Autocrypt compatible format.
+Where key includes a Base64 representation of a minimal key. For now
+we only support ``p`` as the type, which represents a specific subset
+of OpenPGP (see key-formats.rst).
+
+``prefer-encrypted`` indicates that agents should default to
+encrypting when composing emails to this recipient.
+
+Autocrypt compatible Agents MUST include one header with a key in a
+Autocrypt-compatible format.
 
 "Happy path" example: 1:1 communication
 ---------------------------------------
@@ -71,7 +90,7 @@ We encourage MUA developers to propose heuristics for handling the undirected
 case. We will document the best approaches to develop a shared understanding.
 
 group mail communication (1:N)
-------------------------------------------
+------------------------------
 
 Consider a blank state and a first outgoing message from Alice to Bob
 and Carol.  Alice's MUA add a header just like in the 1:1 case so
@@ -94,8 +113,8 @@ is about **opportunistic** encryption, i.e. encrypt if possible and
 otherwise don't get in the way of users.
 
 
-Loosing access to decryption key
--------------------------------------------
+Losing access to decryption key
+-------------------------------
 
 If Alice loses access to her decryption secret:
 
@@ -119,13 +138,13 @@ your mail") Bob's MUA will see the new key and subsequently use it.
 .. note::
 
     Unless we can get perfect recoverability (also for device loss etc.) we will
-    always have to consider this "fatal" case of loosing a secret key and how
+    always have to consider this "fatal" case of losing a secret key and how
     users can deal with it.  Especially in the federated email context We do
     not think perfect recoverability is feasible.
 
 
-Dowgrading / switch to a MUA without Autocrypt support
-------------------------------------------------------
+Downgrading / switch to a MUA without Autocrypt support
+-------------------------------------------------------
 
 Alice might decide to switch to a different MUA which does not support Autocrypt.
 
@@ -138,7 +157,7 @@ will disable encryption to Alice for subsequent mails.
 -----------------------------
 
 Autocrypt pins down key formats and algorithms to reduce the requirements
-for autocrypt-supporting implementations.  If OpenPGP key format is used, 
+for Autocrypt-supporting implementations.  If OpenPGP key format is used, 
 the message also uses OpenPGP Message encoding (PGP/MIME, RFC 3156)
 
 **For New Users**
@@ -197,8 +216,8 @@ but the key should not be uploaded in the first place.
 
 Accidental or malicious uploading of keys with associated email
 addresses should be prevented by introducing a flag at the keys that
-says that keyservers shouldn't accept it.  See `issue #7
-<https://github.com/autocrypt/inbome/issues/7>`_.
+says that keyservers shouldn't accept it.  See `issue #1
+<https://github.com/autocrypt/autocrypt/issues/1>`_.
 
 
 **For current OpenPGP users**

doc/user-experience.rst

@@ -12,7 +12,7 @@ encrypted.
 During the initial rollout, we do not expect most e-mails to be
 encrypted.  Rather, only mails that are deliberately encrypted by the
 sender will be unreadable on webmail or non-Autocrypt clients.  In a
-near future `level of implementation <levels.html>`_, users will be
+near future `level of implementation <levels>`, users will be
 able to read mail from *any* e-mail app that is Autocrypt-enabled, not
 just one.
 
@@ -22,4 +22,4 @@ when composing outbound e-mail that allows the user to encrypt the
 existing message.  Some apps might not even have that.
 
 If you are an implementer, please see `the Level 0 UI
-guidance <level0/user-interface.html>`_ for more details.
+guidance <level0/user-interface.html>` for more details.