diff options
author | Patrick Totzke <patricktotzke@gmail.com> | 2013-06-02 21:17:42 +0100 |
---|---|---|
committer | Patrick Totzke <patricktotzke@gmail.com> | 2013-06-02 21:17:42 +0100 |
commit | 62783b3b098bac3c5da958c8df14a6cd408b5343 (patch) | |
tree | 8deb38802dbc23412223579570634f1418af9331 /docs/source | |
parent | 5820ef46cfff2799abbc63e47443ee82692b25d4 (diff) | |
parent | 05a09c8ec9ff5b40ad395ac69a95abbc572401cd (diff) |
Merge branch '0.3.4-fix-docs'
Diffstat (limited to 'docs/source')
-rw-r--r-- | docs/source/api/interface.rst | 5 | ||||
-rw-r--r-- | docs/source/crypto/index.rst | 47 | ||||
-rw-r--r-- | docs/source/faq.rst | 2 | ||||
-rw-r--r-- | docs/source/index.rst | 1 | ||||
-rw-r--r-- | docs/source/usage/crypto.rst | 41 | ||||
-rw-r--r-- | docs/source/usage/index.rst | 6 | ||||
-rw-r--r-- | docs/source/usage/modes/global.rst | 1 |
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: |