fix #7 -- final reorg wrt sidebar and pages for now from my side.

I think the introduction is now clearer, the links on the left side
point to the main currently interesting docs.

doc/_templates/globaltoc.html

@@ -1,7 +1,11 @@
 
+<h3><a href="{{ pathto('contents') }}">{{ _('Table Of Contents') }}</a></h3>
+
 <ul>
-  <li><a href="{{ pathto('index') }}">Autocrypt Index & Contact</a></li>
-  <li><a href="{{ pathto('features') }}">Autocrypt Features</a></li>
+  <li><a href="{{ pathto('index') }}">Introduction</a></li>
+  <li><a href="{{ pathto('features') }}">Features</a></li>
+  <li><a href="{{ pathto('contact') }}">Contact and Events</a></li>
   <li><a href="{{ pathto('examples') }}">Example mail flows</a></li>
   <li><a href="{{ pathto('level0') }}">Level 0 support</a></li>
+  <li><a href="{{ pathto('contents') }}">All Docs</a></li>
 </ul>

doc/_templates/sidebarintro.html

@@ -1,5 +1,5 @@
 <h3>About Autocrypt</h3>
 <p>
-  Autocrypt aims to automatically replace the use of 
-  cleartext with end-to-end encrypted e-mail.
+  Autocrypt is to replace cleartext with 
+  end-to-end encrypted e-mail.
 </p>

doc/conf.py

@@ -51,7 +51,7 @@
 # source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = 'contents'
 
 # General information about the project.
 project = u'Autocrypt'
@@ -63,9 +63,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'0.4'
+version = u'0.5'
 # The full version, including alpha/beta/rc tags.
-release = u'0.4'
+release = u'0.5'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/contact.rst

@@ -0,0 +1,63 @@
+
+.. _`contact channels`:
+
+Channels
+--------
+
+If you want to help, including offering constructive criticism, 
+you may:
+
+- 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`_
+
+.. _`Autocrypt mailing list`: https://lists.mayfirst.org/mailman/listinfo/autocrypt
+
+.. _`github Autocrypt repo`: https://github.com/autocrypt/autocrypt
+
+
+Currently involved are developers from `K9/Android`_,
+`OpenKeyChain/Android`_, `Enigmail`_, `Mailpile`_, `Bitmask/LEAP`_ as
+well as people from the `nextleap`_, `enzevalos`_ research projects
+and the ACLU_.
+
+.. _`ACLU`: https://www.aclu.org/
+.. _`K9/Android`: https://k9mail.github.io/
+.. _`Enigmail`: https://enigmail.net/
+.. _`Mailpile`: https://mailpile.is/
+.. _`Bitmask/LEAP`: https://leap.se/en/docs/client
+.. _`nextleap`: https://nextleap.eu
+.. _`enzevalos`: https://www.inf.fu-berlin.de/groups/ag-si/enzevalos.html
+.. _`OpenKeyChain/Android`: https://www.openkeychain.org/
+
+.. _`Python`: https://www.python.org/
+.. _`Go`: https://golang.org/
+
+
+.. _`upcoming events`:
+
+Upcoming events
+---------------
+
+- Dec 2016: at `33c3`_, Hamburg, scheduled talk at the 
+  `We Fix the Net`_ session and probably another separate one.
+
+- Jan 2017: a prospective lightning talk from dkg at 
+  `RealWorldCrypto 2017`_ in New york
+
+- Mar 2017: Autocrypt sessions at the `Internet Freedom Festival`_
+  with hackers and users, several Autocrypt-people there.
+
+- April/May 2017: next Autocrypt unconf-hackathon planned roughly
+  around DE/NL/CH
+
+.. _`33c3`: https://events.ccc.de/congress/2016/wiki/Main_Page
+
+.. _`We Fix the Net`: https://events.ccc.de/congress/2016/wiki/Session:We_Fix_the_Net
+
+.. _`RealWorldCrypto 2017`: http://www.realworldcrypto.com/rwc2017
+
+.. _`Internet Freedom Festival`: https://internetfreedomfestival.org/

doc/contents.rst

@@ -0,0 +1,60 @@
+
+Current docs (work-in-progress)
+-------------------------------
+
+The following in-progress documents are written for early adopters
+and contributors, MUA developers and privacy enthusiasts.
+
+:doc:`index`
+     introduction to why Autocrypt exists and why it is trying 
+     to achieve more email encryption.
+
+:doc:`features`
+     discusses how the Autocrypt efforts is different from past 
+     e2e encryption efforts.
+
+:doc:`examples`
+     Example data flows and MUA state transitions.  This may be the
+     easiest place to get started with the concrete ideas behind
+     Autocrypt.
+
+:doc:`level0`
+     Minimum requirements and implementer guidance for Level 0
+     Autocrypt-capable MUAs.
+
+:doc:`other-crypto-interop`
+     Guidance for integrating Autocrypt with other e-mail encryption
+     mechanisms and UI for existing MUAs.
+
+:doc:`next-steps`
+     Future improvements for Autocrypt, beyond Level 0.
+
+:doc:`ecosystem-dangers`
+     Some documented risks and dangers to the mail ecosystem,
+     related to Autocrypt.
+
+:doc:`faq`
+
+:doc:`glossary`
+
+
+.. toctree::
+   :hidden:
+
+   index
+   features
+   contact
+   examples
+   level0
+   address-canonicalization
+   ecosystem-dangers
+   other-crypto-interop
+   faq
+   ui-examples
+   glossary
+   next-steps
+   backup
+   cleanup
+   peering
+
+

doc/features.rst

@@ -2,9 +2,6 @@
 Autocrypt features
 --------------------------------
 
-**If users ask how they can secure their e-mail the answer
-should be as simple as: use an autocrypt-enabled mail app!**
-
 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 with user experience and certification models.
@@ -37,15 +34,4 @@ from previous ones here are some of its features:
 - **Implement and specify "Level 0" support in several mail apps in spring
   2017.** Keep Level 0 minimal enough that it's easy for developers to
   adopt it and we can start to drive efforts from real-life experiences.
-  Please see :doc:`level0`.
-  Currently involved are developers from `K9/Android`_, `Enigmail`_,
-  `Mailpile`_, `Bitmask/LEAP`_ and others who are interested to add
-  support for OSX or write reference "bots" in `Python`_ or `Go`_.
-
-.. _`K9/Android`: https://k9mail.github.io/
-.. _`Enigmail`: https://enigmail.net/
-.. _`Mailpile`: https://mailpile.is/
-.. _`Bitmask/LEAP`: https://leap.se/en/docs/client
-
-.. _`Python`: https://www.python.org/
-.. _`Go`: https://golang.org/
+  Please see :doc:`level0`.  

doc/index.rst

@@ -1,127 +1,50 @@
-Autocrypt - E-mail Encryption for Everyone
-==========================================
-
-**The Autocrypt project aims to ease end-to-end email encryption 
-such that it eventually happens automatically.**
-
-E-mail has been declared dead many times but refuses to die.  And that 
-despite the constant drag of apps who want to lure us to
-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 
-and researchers who are willing to take fresh approaches, learn from
+Introducing Autocrypt: Email Encryption for Everyone
+====================================================
+
+**If users ask how they can secure their email the answer
+should be as simple as: use an Autocrypt-enabled mail app!**
+
+**Why improve email?** Email has been declared dead many times but 
+refuses to die. It remains the largest open federated identity and
+messaging eco-system, anchors the web, mobiles and continues to relay
+sensitive information between citizens and organisations. It has
+problems but do you prefer the proprietary, easy-to-track mobile phone 
+number system to become the single source of digital identification?
+
+**Why a new approach to email encryption?**  Encrypted email has been
+around for decades, but has failed to see wide adoption outside of
+specialist communities, in large part because of difficulties with user
+experience and certification models.  Autocrypt first aims to provide 
+convenient encryption that is neither perfect nor as secure as 
+traditional email encryption, but is convenient enough for
+much wider adoption.  
+
+The social Autocrypt approach
+------------------------------
+
+The Autocrypt project is driven by a diverse group mail of 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 email 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
-we have :ref:`contact channels` and :ref:`upcoming events`
-where you may talk with us.
-
-
-The Autocrypt approach
-----------------------
-
-Autocrypt uses existing e-mail messages to transfer the necessary
-information (such as public keys) between people to make it possible
-to encrypt future messages.  Under the hood, Autocrypt uses e-mail
-headers for this information transfer.  By default, no key management
-should be visible to the users.
-
-For simplicity, we are establishing this approach step-by-step using
-different "Levels" of implementation compliance.  We are currently
-documenting :doc:`Level 0 <level0>`, which should be supported in
-Spring of 2017 by various mailers.
-
-Note that this is an approach to bring opportunistic e-mail encryption
-to the masses.  Getting convenience-oriented users to take direct
-responsibility for key management has proved unlikely, leaving an
-overwhelming majority of mail in the clear.  Autocrypt aims to provide
-convenient encryption that is neither perfect nor as secure as
-traditional e-mail encryption, but should be convenient enough for
-much wider adoption.  Autocrypt does not defend against metadata
-tracking (who is sending email to whom) or active attacks (such as
-man-in-the-middle).
-
-Autocrypt will not get in the way of people who want to continue to do
-traditional encrypted e-mail, but they are not its target audience.
-
-
-Current docs (work-in-progress)
--------------------------------
-
-The following in-progress documents are written for software developers
-and privacy enthusiasts.
-
-:doc:`features`
-     discusses how the Autocrypt efforts is different from past 
-     e2e encryption efforts.
-
-:doc:`examples`
-     Example data flows and MUA state transitions.  This may be the
-     easiest place to get started with the concrete ideas behind Autocrypt.
-
-:doc:`level0`
-     Minimum requirements and implementer guidance for Level 0
-     Autocrypt-capable MUAs.
-
-:doc:`other-crypto-interop`
-     Guidance for integrating Autocrypt with other e-mail encryption mechanisms
-     and UI for existing MUAs.
-
-:doc:`next-steps`
-     Future improvements for Autocrypt, beyond Level 0.
-
-:doc:`ecosystem-dangers`
-     Some documented risks and dangers to the mail ecosystem,
-     related to Autocrypt.
-
-:doc:`faq`
-
-:doc:`glossary`
-
-.. _`contact channels`:
-
-Channels
---------
-
-If you want to help, including offering constructive criticism, 
-you may:
-
-- 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`_
-
-.. _`Autocrypt mailing list`: https://lists.mayfirst.org/mailman/listinfo/autocrypt
-
-.. _`github Autocrypt repo`: https://github.com/autocrypt/autocrypt
-
-.. _`upcoming events`:
-
-Upcoming events
----------------
-
-- Dec 2016: at `33c3`_, Hamburg, scheduled talk at the 
-  `We Fix the Net`_ session and probably a separate one.
-
-- Jan 2017: a prospective lightning talk from dkg at 
-  `RealWorldCrypto 2017`_ in New york
+new people, influences and contributions.  See :doc:`contact channels
+and upcoming events <contact>` on how you may talk with us and who
+"we" are currently.
 
-- Mar 2017: Autocrypt sessions at the `Internet Freedom Festival`_
-  with hackers and users, several Autocrypt-people there.
 
-- April/May 2017: next Autocrypt unconf-hackathon planned roughly
-  around DE/NL/CH
+The technical Autocrypt approach
+--------------------------------------
 
-.. _`33c3`: https://events.ccc.de/congress/2016/wiki/Main_Page
+Autocrypt uses existing email messages between people to transfer 
+the necessary information to allow encrypting subsequent messages.  
+Under the hood, Autocrypt uses email headers for this information
+transfer. By default, no key management should be visible to the users.
+See :doc:`features` for more highlights.
 
-.. _`We Fix the Net`: https://events.ccc.de/congress/2016/wiki/Session:We_Fix_the_Net
-
-.. _`RealWorldCrypto 2017`: http://www.realworldcrypto.com/rwc2017
+We are establishing this approach step-by-step using different "Levels"
+of implementation compliance.  We are currently documenting :doc:`Level
+0 <level0>`, which we aim to see supported in Spring of 2017 by various
+mailers.
 
-.. _`Internet Freedom Festival`: https://internetfreedomfestival.org/
+See :doc:`contents` for an index of all docs and discussion results so far.