Merge branch '0.3.4-fix-docs'

7 files changed, 52 insertions, 51 deletions

diff --git a/docs/source/api/interface.rst b/docs/source/api/interface.rst
index 7d66cf1f..0ee0cb29 100644
--- a/docs/source/api/interface.rst
+++ b/docs/source/api/interface.rst
@@ -1,7 +1,7 @@
 User Interface
 ==================
 
-Alot sets up a widget tree and an :class:`mainloop <urwid.main_loop.TwistedEventLoop>`
+Alot sets up a widget tree and a :class:`mainloop <urwid.main_loop.TwistedEventLoop>`
 in the constructor of :class:`alot.ui.UI`. The visible area is
 a :class:`urwid.Frame`, where the footer is used as a status line and the body part
 displays the currently active :class:`alot.buffers.Buffer`.
@@ -14,7 +14,8 @@ customary in urwid. Instead, the root widget given to urwids mainloop is a custo
 key presses to the wrapped root widget and thereby accessing standard urwid
 behaviour.
 
-In order to keep the interface non-blocking, alot makes use of twisted's deferred_ - a
+In order to keep the interface non-blocking and react to events like
+terminal size changes, alot makes use of twisted's deferred_ - a
 framework that makes it easy to deal with callbacks. Many commands in alot make use of
 `inline callbacks`_, which allow you to treat deferred-returning functions almost like
 syncronous functions. Consider the following example of a function that prompts for some
diff --git a/docs/source/crypto/index.rst b/docs/source/crypto/index.rst
deleted file mode 100644
index 52fb356a..00000000
--- a/docs/source/crypto/index.rst
+++ /dev/null
@@ -1,47 +0,0 @@
-************
-Cryptography
-************
-
-At the moment alot only supports signing of outgoing mails via PGP/MIME (:rfc:`3156`).
-Encryption via PGP/MIME (:rfc:`3156`) is in an experimental stadium.
-
-.. note:: To use GPG with alot, you need to have `gpg-agent` running.
-
-  `gpg-agent` will handle passphrase entry in a secure and configurable way, and it will cache your passphrase for some
-  amount of time so you don’t have to enter it over and over again. For details on how to set this up we refer to
-  `gnupg's manual <http://www.gnupg.org/documentation/manuals/gnupg/>`_.
-
-.. rubric:: Signing outgoing emails
-
-You can use the commands `sign`, `unsign` and `togglesign` in envelope mode
-to determine if you want this mail signed and if so, which key to use.
-To specify the key to use you can pass a hint string as argument to
-the `sign` or `togglesign` command. This hint would typically
-be a fingerprint or an email address associated (by gnupg) with a key.
-
-Signing (and hence passwd entry) will be done at most once shortly before
-a mail is sent.
-
-In case no key is specified, alot will leave the selection of a suitable key to gnupg
-so you can influence that by setting the `default-key` option in :file:`~/.gnupg/gpg.conf`
-accordingly.
-
-You can set the default to-sign bit and the key to use for each :ref:`account <config.accounts>`
-individually using the options :ref:`sign_by_default <sign-by-default>` and :ref:`gpg_key <gpg-key>`.
-
-
-.. rubric:: Tips
-
-In case you are using alot via SSH, we recommend to use `pinentry-curses`
-instead of the default graphical pinentry. You can do that by setting up your
-:file:`~/.gnupg/gpg-agent.conf` like this::
-
-    pinentry-program /usr/bin/pinentry-curses
-
-.. rubric:: Encrypt outgoing emails
-
-You can use the commands `encrypt` and `unencrypt` in envelope mode to
-encrypt the mail. You have to give a hint string as argument to the `encrypt`
-command. This hint would normally be a fingerprint of the key.
-
-Encryption is done after signing (if signing is enabled) the email.
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
index 84d9620d..212603e6 100644
--- a/docs/source/faq.rst
+++ b/docs/source/faq.rst
@@ -17,7 +17,7 @@ FAQ
 2. What's with the snotty name?
 
     It's not meant to be presumptuous. I like the dichotomy; I like to picture the look on
-    someone's face who reads the :mailheader:`X-MAILER` flag "notmuch/alot"; I like cookies; I like
+    someone's face who reads the :mailheader:`User-Agent` header "notmuch/alot"; I like cookies; I like
     `this comic strip <http://hyperboleandahalf.blogspot.com/2010/04/alot-is-better-than-you-at-everything.html>`_.
 
 3. I want feature X!
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 323bec4c..d383dad5 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -14,7 +14,6 @@ User Manual
    installation
    usage/index
    configuration/index
-   crypto/index
    api/index
    faq
 
diff --git a/docs/source/usage/crypto.rst b/docs/source/usage/crypto.rst
new file mode 100644
index 00000000..6cee7753
--- /dev/null
+++ b/docs/source/usage/crypto.rst
@@ -0,0 +1,41 @@
+Cryptography
+============
+
+Alot has built in support for constructing signed and/or encrypted mails
+according to PGP/MIME (:rfc:`3156`, :rfc:`3156`) via gnupg.
+It does however rely on a running `gpg-agent` to handle password entries.
+
+.. note:: You need to have `gpg-agent` running to use GPG with alot!
+
+  `gpg-agent` will handle passphrase entry in a secure and configurable way, and it will cache your
+  passphrase for some time so you don’t have to enter it over and over again. For details on how to
+  set this up we refer to `gnupg's manual <http://www.gnupg.org/documentation/manuals/gnupg/>`_.
+
+.. rubric:: Signing outgoing emails
+
+You can use the commands :ref:`sign <cmd.envelope.sign>`,
+:ref:`unsign <cmd.envelope.unsign>` and
+:ref:`togglesign <cmd.envelope.togglesign>` in envelope mode
+to determine if you want this mail signed and if so, which key to use.
+To specify the key to use you may pass a hint string as argument to
+the `sign` or `togglesign` command. This hint would typically
+be a fingerprint or an email address associated (by gnupg) with a key.
+
+Signing (and hence passwd entry) will be done at most once shortly before
+a mail is sent.
+
+In case no key is specified, alot will leave the selection of a suitable key to gnupg
+so you can influence that by setting the `default-key` option in :file:`~/.gnupg/gpg.conf`
+accordingly.
+
+You can set the default to-sign bit and the key to use for each :ref:`account <config.accounts>`
+individually using the options :ref:`sign_by_default <sign-by-default>` and :ref:`gpg_key <gpg-key>`.
+
+.. rubric:: Encrypt outgoing emails
+
+You can use the commands :ref:`encrypt <cmd.envelope.encrypt>`,
+:ref:`unencrypt <cmd.envelope.unencrypt>` and
+and :ref:`toggleencrypt <cmd.envelope.toggleencrypt>` and
+in envelope mode to ask alot to encrypt the mail before sending.
+The :ref:`encrypt <cmd.envelope.encrypt>` command accepts an optional
+hint string as argument to determine the key of the recipient.
diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst
index 224f831a..9d469597 100644
--- a/docs/source/usage/index.rst
+++ b/docs/source/usage/index.rst
@@ -12,13 +12,19 @@ First Steps
 .. _usage.first_steps:
 .. include:: first_steps.rst
 
+
 .. _usage.commands:
 .. include:: commands.rst
 
+
+.. _usage.crypto:
+.. include:: crypto.rst
+
 .. toctree::
    :hidden:
 
    commands
    first_steps
    synopsis
+   crypto
 
diff --git a/docs/source/usage/modes/global.rst b/docs/source/usage/modes/global.rst
index 8099500e..58039e04 100644
--- a/docs/source/usage/modes/global.rst
+++ b/docs/source/usage/modes/global.rst
@@ -3,6 +3,7 @@
 
 Global Commands
 ---------------
+
 The following commands are available globally
 
 .. _cmd.global.bclose: