From 56b0b8a0f310403d4664649ab9b69d3cd765dbe5 Mon Sep 17 00:00:00 2001
From: Patrick Totzke <patricktotzke@gmail.com>
Date: Wed, 16 May 2012 18:29:29 +0100
Subject: doc: cleanup crypto docs

---
 docs/source/crypto/index.rst         | 51 +++++++++++++++++++++---------------
 docs/source/generate_configs.py      |  5 ++--
 docs/source/usage/modes/envelope.rst | 30 +++++++++++++++++++++
 3 files changed, 63 insertions(+), 23 deletions(-)

(limited to 'docs')

diff --git a/docs/source/crypto/index.rst b/docs/source/crypto/index.rst
index 738676f9..c17d440d 100644
--- a/docs/source/crypto/index.rst
+++ b/docs/source/crypto/index.rst
@@ -1,16 +1,37 @@
 .. _cryptography
 
-**********************
-Cryptography (PGP/GPG)
-**********************
+************
+Cryptography
+************
 
-alot aims to support GPG cryptography. Currently, only sending signed emails is
-supported, but signature verification, encryption and decryption are planned.
+At the moment alot only supports signing of outgoing mails via PGP/MIME (:rfc:`3156`).
 
-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.
+.. 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 <account>`
+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
@@ -19,15 +40,3 @@ instead of the default graphical pinentry. You can do that by setting up your
     pinentry-program /usr/bin/pinentry-curses
 
 
-Signing outgoing emails
-=======================
-
-After composing a message and before sending it, use the `togglesign` command
-(bound to the S key in the default config) to make alot sign your email.
-
-By default, alot will leave the selection of a suitable GPG key to GPGME (the
-GPG library we use), so you can influence that by setting the `default-key`
-option in :file:`~/.gnupg/gpg.conf` accordingly.
-
-In case you want to use a specific key to sign an email, you can pass that key
-id to the `togglesign` command, for example `togglesign 4AC8EE1D`.
diff --git a/docs/source/generate_configs.py b/docs/source/generate_configs.py
index c10b7926..3a7a973b 100755
--- a/docs/source/generate_configs.py
+++ b/docs/source/generate_configs.py
@@ -24,7 +24,8 @@ def rewrite_entries(config, path, sec=None, sort=False):
         if default is not None:
             default = config._quote(default)
 
-        #print etype
+        if etype == 'gpg_key_hint':
+            etype = 'string'
         description = '\n.. _%s:\n' % entry.replace('_', '-')
         description += '\n.. describe:: %s\n\n' % entry
         comments = [sec.inline_comments[entry]] + sec.comments[entry]
@@ -37,7 +38,7 @@ def rewrite_entries(config, path, sec=None, sort=False):
             description += '\n    :type: %s\n' % etype
 
         if default != None:
-            if etype in ['string', 'string_list'] and default != 'None':
+            if etype in ['string', 'string_list', 'gpg_key_hint'] and default != 'None':
                 description += '    :default: `%s`\n\n' % (default)
             else:
                 description += '    :default: %s\n\n' % (default)
diff --git a/docs/source/usage/modes/envelope.rst b/docs/source/usage/modes/envelope.rst
index 5e7cc1f3..c3c7083c 100644
--- a/docs/source/usage/modes/envelope.rst
+++ b/docs/source/usage/modes/envelope.rst
@@ -17,6 +17,17 @@ positional arguments
 optional arguments
 	:---append: keep previous values.
 
+.. index:: togglesign
+
+togglesign
+__________
+
+toggle sign status
+
+argument
+	which key id to use
+
+
 .. index:: toggleheaders
 
 toggleheaders
@@ -44,6 +55,17 @@ ____
 send mail
 
 
+.. index:: sign
+
+sign
+____
+
+mark mail to be signed before sending
+
+argument
+	which key id to use
+
+
 .. index:: attach
 
 attach
@@ -74,6 +96,14 @@ ____
 save draft
 
 
+.. index:: unsign
+
+unsign
+______
+
+mark mail not to be signed before sending
+
+
 .. index:: unset
 
 unset
-- 
cgit v1.2.3