docs for configuration and accounts

4 files changed, 209 insertions, 78 deletions

diff --git a/docs/source/configuration/accounts_table.rst b/docs/source/configuration/accounts_table.rst
new file mode 100644
index 00000000..efa7698b
--- /dev/null
+++ b/docs/source/configuration/accounts_table.rst
@@ -0,0 +1,51 @@
+
+.. describe:: address
+
+    your email address
+
+.. describe:: realname
+
+    used to format the (proposed) From-header in outgoing mails
+
+.. describe:: aliases
+
+    used to clear your addresses/ match account when formating replies
+
+.. describe:: sendmail_command
+
+    how to send mails
+
+.. describe:: sent_box
+
+    specifies the mailbox where you want outgoing mails to be stored after successfully sending them, e.g. 
+    where to store outgoing mail, e.g. `maildir:///home/you/mail//Sent`
+    You can use mbox, maildir, mh, babyl and mmdf in the protocol part of the url.
+
+.. describe:: sent_tags
+
+    how to tag sent mails.
+
+.. describe:: signature
+
+    path to signature file that gets attached to all outgoing mails from this account, optionally
+    renamed to `signature_filename`.
+
+.. describe:: signature_as_attachment
+
+    attach signature file if set to True, append its content (mimetype text)
+    to the body text if set to False. Defaults to False.
+
+.. describe:: signature_filename
+
+    signature file's name as it appears in outgoing mails if
+    signature_as_attachment is set to True
+
+.. describe:: abook_command
+
+    command to lookup contacts.
+    If you specified `abook_command`, it will be used for tab completion in queries (to/from) and in message
+    composition. The command will be called with your prefix as only argument and its output is searched for name-email pairs.
+
+.. describe:: abook_regexp
+
+    The regular expression used to match name/address pairs in the output of `abook_command`
diff --git a/docs/source/configuration/alotrc_table.rst b/docs/source/configuration/alotrc_table.rst
new file mode 100644
index 00000000..abb18e5e
--- /dev/null
+++ b/docs/source/configuration/alotrc_table.rst
@@ -0,0 +1,125 @@
+
+.. describe:: ask_subject
+
+    ask for subject when compose
+
+.. describe:: bug_on_exit
+
+    confirm exit
+
+.. describe:: bufferclose_focus_offset
+
+    offset of next focussed buffer if the current one gets closed
+
+.. describe:: colourmode
+
+    number of colours your terminal supports
+
+.. describe:: tabwidth
+
+    number of spaces used to replace tab characters
+
+.. describe:: template_dir
+
+    templates directory that contains your message templates.
+    It will be used if you give `compose --template` a filename without a path prefix.
+
+.. describe:: display_content_in_threadline
+
+    fill threadline with message content
+
+.. describe:: displayed_headers
+
+    headers that get displayed by default
+
+.. describe:: envelope_headers_blacklist
+
+    headers that are hidden in envelope buffers by default
+
+.. describe:: terminal_cmd
+
+    set terminal command used for spawning shell commands
+
+.. describe:: editor_cmd
+
+    editor command
+    if unset, alot will first try the EDITOR env variable, then /usr/bin/editor
+
+.. describe:: editor_writes_encoding
+
+    file encoding used by your editor
+
+.. describe:: editor_spawn
+
+    use terminal_command to spawn a new terminal for the editor?
+
+.. describe:: editor_in_thread
+
+    call editor in separate thread.
+    In case your editor doesn't run in the same window as alot, setting true here
+    will make alot non-blocking during edits
+
+.. describe:: edit_headers_whitelist
+
+    Which header fields should be editable in your editor
+    used are those that match the whitelist and don't macht the blacklist.
+    in both cases '*' may be used to indicate all fields.
+
+.. describe:: edit_headers_blacklist
+
+
+.. describe:: flush_retry_timeout
+
+    timeout in secs after a failed attempt to flush is repeated
+
+.. describe:: hooksfile
+
+    where to look up hooks
+
+.. describe:: notify_timeout
+
+    time in secs to display status messages
+
+.. describe:: show_statusbar
+
+    display statusline?
+
+.. describe:: timestamp_format
+
+    timestamp format in strftime format syntax:
+    http://docs.python.org/library/datetime.html#strftime-strptime-behavior
+
+.. describe:: authors_maxlength
+
+    max length of authors line in thread widgets
+
+.. describe:: print_cmd
+
+    how to print messages:
+    this specifies a shellcommand used pro printing.
+    threads/messages are piped to this as plaintext.
+    muttprint/a2ps works nicely
+
+.. describe:: initial_command
+
+    initial command when none is given as argument:
+
+.. describe:: search_threads_sort_order
+
+    default sort order of results in a search
+
+.. describe:: complete_matching_abook_only
+
+    in case more than one account has an address book:
+    Set this to True to make tabcompletion for recipients during compose only
+    look in the abook of the account matching the sender address
+
+.. describe:: quit_on_last_bclose
+
+    shut down when the last buffer gets closed
+
+.. describe:: user_agent
+
+    value of the User-Agent header used for outgoing mails.
+    setting this to the empty string will cause alot to omit the header all together.
+    The string '$VERSION' will be replaced by the version string of the running instance.
diff --git a/docs/source/configuration.rst b/docs/source/configuration/index.rst
index 4afc333b..ddf639a8 100644
--- a/docs/source/configuration.rst
+++ b/docs/source/configuration/index.rst
@@ -2,95 +2,50 @@
 Configuration
 *************
 
-Alot reads a config file in (extended) "INI" syntax:
-It consists of some sections whose names are given in square brackets, followed by
-key-value pairs that use "=" or ":" as separator, ';' and '#' are comment-prefixes.
-
-The default location for the config file is `~/.config/alot/config`.
-You can find a complete example config with the default values and their decriptions in
-`alot/defaults/alot.rc`.
-
-Note that since ":" is a separator for key-value pairs you need to use "colon" to bind
-commands to ":".
-
-Here is a key for the interpreted sections:
-
-[general]
-    global settings: set your editor etc
-[account X]
-    defines properties of account X: (see below)
-[X-maps]
-    defines keymaps for mode X. possible modes are:
-    envelope, search, thread, taglist, bufferlist and global.
-    global-maps are valid in all modes.
-[tag-translate]
-    defines a map from tagnames to strings that is used when
-    displaying tags. utf-8 symbols welcome.
-[Xc-theme]
-    define colour palette for colour mode. X is in {1, 16, 256}.
+Alot reads a config file in "INI" syntax:
+It consists of key-value pairs that use "=" as separator and '#' is comment-prefixes.
+Sections and subsections are defined using square brackets.
+The default location for the config file is :file:`~/.config/alot/config`.
 
+Config options
+==============
 
-Accounts
-========
-A sample gmail section looks like this (provided you have configured msmtp accordingly)::
-
-    [account gmail]
-    realname = Patrick Totzke
-    address = patricktotzke@gmail.com
-    aliases = patricktotzke@googlemail.com
-    sendmail_command = msmtp --account=gmail -t
-
-Here's a full list of the interpreted keywords in account sections::
-
-    # used to format the (proposed) From-header in outgoing mails
-    realname = your name
-    address = this accounts email address
-
-    # used to clear your addresses/ match account when formating replies
-    aliases = foobar@myuni.uk;f.bar@myuni.uk;f.b100@students.myuni.uk
-
-    # how to send mails
-    sendmail_command = command, defaults to 'sendmail'
-
-    # where to store outgoing mail
-    sent_box = maildir:///home/you/mail//Sent
-
-    # how to tag sent mails [default: sent]. seperate multiple tags with ','.
-    sent_tags = sent
-
-    # path to signature file
-    signature = ~/your_vcard_for_this_account.vcs
-
-    # attach signature file if set to True, append its content (mimetype text)
-    # to the body text if set to False. Defaults to False.
-    signature_as_attachment = False
+.. include:: alotrc_table.rst
 
-    # signature file's name as it appears in outgoing mails if
-    # signature_as_attachment is set to True
-    signature_filename = you.vcs
 
-    # command to lookup contacts
-    abook_command = abook --mutt-query
-    abook_regexp = regexp to match name & address in abook_commands output.
+Accounts
+========
+In order to be able to send mails, you have to define at least one account subsection in your config:
+There needs to be a section "accounts", and each subsection, indicated by double square brackets defines an account.
+
+Here is an example configuration::
+
+    [accounts]
+        [[work]]
+            realname = Bruce Wayne
+            address = b.wayne@wayneenterprises.com
+            gpg_key = D7D6C5AA
+            sendmail_command = msmtp --account=wayne -t
+            sent_box = maildir:///home/bruce/mail/work/Sent
+            draft_box = maildir:///home/bruce/mail/work/Drafts
+    
+        [[secret]]
+            realname = Batman
+            address = batman@batcave.org
+            aliases = batman@batmobile.org
+            sendmail_command = msmtp --account=batman -t
+            signature = ~/.batman.vcf
+            signature_as_attachment = True
 
 .. warning::
 
   Sending mails is only supported via sendmail for now. If you want
   to use a sendmail command different from `sendmail`, specify it as `sendmail_command`.
 
-`send_box` specifies the mailbox where you want outgoing mails to be stored
-after successfully sending them. You can use mbox, maildir, mh, babyl and mmdf
-in the protocol part of the url.
+The following entries are interpreted at the moment:
 
-The file specified by `signature` is attached to all outgoing mails from this account, optionally
-renamed to `signature_filename`.
+.. include:: accounts_table.rst
 
-If you specified `abook_command`, it will be used for tab completion in queries (to/from)
-and in message composition. The command will be called with your prefix as only argument
-and its output is searched for name-email pairs. The regular expression used here
-defaults to `(?P<email>.+?@.+?)\s+(?P<name>.+)`, which makes it work nicely with `abook --mutt-query`.
-You can tune this using the `abook_regexp` option (beware Commandparsers escaping semantic!).
-Have a look at the FAQ for other examples.
 
 
 Key Bindings
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 03dacb4b..adcb8425 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -12,5 +12,5 @@ User Manual
    :numbered:
 
    usage/index
-   configuration
+   configuration/index
    api/index