docs for configuration and accounts

2 files changed, 22 insertions, 450 deletions

diff --git a/alot/defaults/alot.rc b/alot/defaults/alot.rc
deleted file mode 100644
index d6dfa0c3..00000000
--- a/alot/defaults/alot.rc
+++ /dev/null
@@ -1,437 +0,0 @@
-[general]
-
-# ask for subject when compose
-ask_subject = True
-
-# confirm exit
-bug_on_exit = False
-
-# offset of next focussed buffer if the current one gets closed
-bufferclose_focus_offset=-1
-
-# number of colours your terminal supports
-colourmode = 256
-
-# number of spaces used to replace tab characters
-tabwidth = 8
-
-# templates directory that contains your message templates.
-# It will be used if you give `compose --template` a filename without a path prefix.
-# This defaults to `$XDG_CONFIG_HOME/alot/templates` if unset.
-template_dir =
-
-# fill threadline with message content
-display_content_in_threadline = False
-
-# headers that get displayed by default
-displayed_headers = From,To,Cc,Bcc,Subject
-
-# headers that are hidden in envelope buffers by default
-envelope_headers_blacklist = In-Reply-To,References
-
-# set terminal command used for spawning shell commands
-terminal_cmd = /usr/bin/x-terminal-emulator -e
-
-####################
-# EDITOR settings  #
-####################
-# editor command
-# if unset, alot will first try the EDITOR env variable, then /usr/bin/editor
-#editor_cmd = /usr/bin/vim -f -c 'set filetype=mail' +
-
-# file encoding used by your editor
-editor_writes_encoding = UTF-8
-
-# use terminal_command to spawn a new terminal for the editor?
-editor_spawn = False
-
-# 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
-editor_in_thread = False
-
-
-# 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.
-edit_headers_whitelist = *
-edit_headers_blacklist = Content-Type,MIME-Version,References,In-Reply-To
-
-
-# timeout in secs after a failed attempt to flush is repeated
-flush_retry_timeout = 5
-
-# where to look up hooks
-hooksfile = ~/.config/alot/hooks.py
-
-# time in secs to display status messages
-notify_timeout = 2
-
-# display statusline?
-show_statusbar = True
-
-# strftime format for timestamps. Note: you must escape % twice here:
-# use '%%%%' instead of '%' (and use '%%%%%%%%' to get a literal '%').
-# for the strftime format, see
-# http://docs.python.org/library/datetime.html#strftime-strptime-behavior
-# timestamp_format = ''
-
-# max length of authors line in thread widgets
-authors_maxlength = 30
-
-# how to print messages:
-# this specifies a shellcommand used pro printing.
-# threads/messages are piped to this as plaintext.
-# muttprint/a2ps works nicely
-print_cmd = ''
-
-# initial command when none is given as argument:
-initial_command = search tag:inbox AND NOT tag:killed
-
-# default sort order of results in a search
-# must be one of one of 'oldest_first', 'newest_first', 'message_id' or 'unsorted'
-search_threads_sort_order = newest_first
-
-# 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
-complete_matching_abook_only = False
-
-# shut down when the last buffer gets closed
-quit_on_last_bclose = False
-
-# 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)s' will be replaced by the version string of the running instance.
-# Beware ne necessary 3-fold escaping for the symbol '%' though.
-user_agent = 'alot/%%%%%%%%(version)s'
-
-
-[global-maps]
-j = move down
-k = move up
-' ' = move page down
-esc = cancel
-enter = select
-
-@ = refresh
-? = help bindings
-I = search tag:inbox AND NOT tag:killed
-L = taglist
-shift tab = bprevious
-U = search tag:unread
-tab = bnext
-\ = prompt 'search '
-d = bclose
-$ = flush
-m = compose
-o = prompt 'search '
-q = exit
-';' = bufferlist
-colon = prompt
-
-[bufferlist-maps]
-x = close
-select = openfocussed
-
-[search-maps]
-a = toggletags inbox
-& = toggletags killed
-! = toggletags flagged
-s = toggletags unread
-l = retagprompt
-O = refineprompt
-| = refineprompt
-
-[envelope-maps]
-a = prompt 'attach ~/'
-y = send
-P = save
-s = 'refine Subject'
-t = 'refine To'
-b = 'refine Bcc'
-c = 'refine Cc'
-select = edit
-H = toggleheaders
-
-[taglist-maps]
-
-[thread-maps]
-C = fold --all
-E = unfold --all
-c = fold
-e = unfold
-< = fold
-> = unfold
-H = toggleheaders
-h = togglesource
-P = print --all --separately --add_tags
-S = save --all
-g = reply --all
-f = forward
-p = print --add_tags
-n = editnew
-s = save
-r = reply
-| = prompt 'pipeto '
-
-[command-aliases]
-quit = exit
-bn = bnext
-clo = close
-bp = bprevious
-ls = bufferlist
-
-[highlighting]
-# Thread lines in the search buffer can be highlighted if they match a query
-# by theming their components.
-
-# dictionary of highlighting rules. The keys are queries you want highlighting
-# for; values are chosen designators that identify themeing options in the
-# colour scheme:
-#    search_thread_<component>_<id>_[focus_][fg|bg]
-# Note that the sequence of the list defines the search order. The first
-# specified query that matches selects the themeing.
-rules = { "tag:unread AND tag:flagged":"isunread+flagged",
-          "tag:unread":"isunread",
-          "tag:flagged":"isflagged" }
-
-# comma separated list of the components of a thread line you want highlighted
-# if a query matches.
-# Possible components are [date|mailcount|tags|authors|subject|content].
-components = subject
-
-[256c-theme]
-
-# default formating for tagstrings
-# add 'tag_X_[focus_]fg' and 'tag_X_[focus_]bg' to your config to specify
-# formating for tagstring 'X'
-tag_bg = default
-tag_fg = brown
-tag_focus_bg = #68a
-tag_focus_fg = #ffa
-
-#draft tag in red
-tag_draft_bg = #d66
-tag_draft_fg = white
-
-# formating of the `help bindings` overlay
-help_text_bg = g35
-help_text_fg = default
-help_section_bg = g35
-help_section_fg = bold,underline
-help_title_bg = g35
-help_title_fg = white,bold,underline
-
-# attributes used in all modi
-global_footer_bg = #006
-global_footer_fg = white
-global_notify_error_bg = dark red
-global_notify_error_fg = white
-global_notify_normal_bg = #68a
-global_notify_normal_fg = light gray
-global_prompt_bg = g10
-global_prompt_fg = light gray
-
-# mode specific attributes
-bufferlist_focus_bg = #68a
-bufferlist_focus_fg = #ffa
-bufferlist_results_even_bg = g3
-bufferlist_results_even_fg = default
-bufferlist_results_odd_bg = default
-bufferlist_results_odd_fg = default
-search_thread_authors_bg = default
-search_thread_authors_fg = #6d6
-search_thread_authors_isunread_fg = #6d6,bold
-search_thread_authors_isunread+flagged_fg = #6d6,bold
-search_thread_authors_focus_bg = #68a
-search_thread_authors_focus_fg = #8f6
-search_thread_authors_isunread_focus_fg = #8f6,bold
-search_thread_authors_isunread+flagged_focus_fg = #8f6,bold
-search_thread_bg = default
-search_thread_content_bg = default
-search_thread_content_fg = #866
-search_thread_content_isunread_fg = #866,bold
-search_thread_content_isunread+flagged_fg = #866,bold
-search_thread_content_focus_bg = #68a
-search_thread_content_focus_fg = #866
-search_thread_content_isunread_focus_fg = #866,bold
-search_thread_content_isunread+flagged_focus_fg = #866,bold
-search_thread_date_bg = default
-search_thread_date_fg = g58
-search_thread_date_isunread_fg = g58,bold
-search_thread_date_isflagged_fg = light red
-search_thread_date_isunread+flagged_fg = light red,bold
-search_thread_date_focus_bg = #68a
-search_thread_date_focus_fg = g89
-search_thread_date_isunread_focus_fg = g89,bold
-search_thread_date_isflagged_focus_fg = light red
-search_thread_date_isunread+flagged_focus_fg = light red,bold
-search_thread_fg = default
-search_thread_focus_bg = #68a
-search_thread_focus_fg = white
-search_thread_mailcount_bg = default
-search_thread_mailcount_fg = light gray
-search_thread_mailcount_isunread_fg = light gray,bold
-search_thread_mailcount_isflagged_fg = light red
-search_thread_mailcount_isunread+flagged_fg = light red,bold
-search_thread_mailcount_focus_bg = #68a
-search_thread_mailcount_focus_fg = g89
-search_thread_mailcount_isunread_focus_fg = g89,bold
-search_thread_mailcount_isflagged_focus_fg = light red
-search_thread_mailcount_isunread+flagged_focus_fg = light red,bold
-search_thread_subject_bg = default
-search_thread_subject_fg = g58
-search_thread_subject_isunread_fg = g58,bold
-search_thread_subject_isflagged_fg = light red
-search_thread_subject_isunread+flagged_fg = light red,bold
-search_thread_subject_focus_bg = #68a
-search_thread_subject_focus_fg = g89
-search_thread_subject_isunread_focus_fg = g89,bold
-search_thread_subject_isflagged_focus_fg = light red
-search_thread_subject_isunread+flagged_focus_fg = light red,bold
-search_thread_tags_bg = default
-search_thread_tags_fg = #a86
-search_thread_tags_focus_bg = #68a
-search_thread_tags_focus_fg = #ff8
-thread_attachment_bg = dark gray
-thread_attachment_fg = light gray
-thread_attachment_focus_bg = light green
-thread_attachment_focus_fg = light gray
-thread_body_bg = default
-thread_body_fg = light gray
-thread_header_bg = dark gray
-thread_header_fg = white
-thread_header_key_bg = dark gray
-thread_header_key_fg = white
-thread_header_value_bg = dark gray
-thread_header_value_fg = light gray
-thread_summary_even_bg = #068
-thread_summary_even_fg = white
-thread_summary_focus_bg = g58
-thread_summary_focus_fg = #ff8
-thread_summary_odd_bg = #006
-thread_summary_odd_fg = white
-
-
-[16c-theme]
-global_footer_bg = dark blue
-global_footer_fg = light green
-global_notify_error_bg = dark red
-global_notify_error_fg = white
-global_notify_normal_bg = dark gray
-global_notify_normal_fg = light gray
-global_prompt_bg = black
-global_prompt_fg = light gray
-help_text_bg = dark gray
-help_text_fg = default
-help_section_bg = dark gray
-help_section_fg = bold,underline
-help_title_bg = dark blue
-help_title_fg = white
-tag_bg = black
-tag_fg = brown
-tag_focus_bg = dark gray
-tag_focus_fg = white
-tag_draft_bg = light red
-tag_draft_fg = white
-bufferlist_focus_bg = dark gray
-bufferlist_focus_fg = white
-bufferlist_results_even_bg = black
-bufferlist_results_even_fg = light gray
-bufferlist_results_odd_bg = black
-bufferlist_results_odd_fg = light gray
-thread_attachment_bg = dark gray
-thread_attachment_fg = light gray
-thread_attachment_focus_bg = light green
-thread_attachment_focus_fg = light gray
-thread_body_bg = default
-thread_body_fg = light gray
-thread_header_bg = dark gray
-thread_header_fg = white
-thread_header_key_bg = dark gray
-thread_header_key_fg = white
-thread_header_value_bg = dark gray
-thread_header_value_fg = light gray
-thread_summary_even_bg = light blue
-thread_summary_even_fg = white
-thread_summary_focus_bg = dark cyan
-thread_summary_focus_fg = white
-thread_summary_odd_bg = dark blue
-thread_summary_odd_fg = white
-search_thread_authors_bg = default
-search_thread_authors_fg = dark green
-search_thread_authors_isunread_fg = dark green,bold
-search_thread_authors_focus_bg = dark gray
-search_thread_authors_focus_fg = dark green,bold
-search_thread_bg = default
-search_thread_content_bg = default
-search_thread_content_fg = dark gray
-search_thread_content_focus_bg = dark gray
-search_thread_content_focus_fg = black
-search_thread_date_bg = default
-search_thread_date_fg = light gray
-search_thread_date_focus_bg = dark gray
-search_thread_date_focus_fg = light gray
-search_thread_fg = default
-search_thread_focus_bg = dark gray
-search_thread_focus_fg = light gray
-search_thread_mailcount_bg = default
-search_thread_mailcount_fg = light gray
-search_thread_mailcount_focus_bg = dark gray
-search_thread_mailcount_focus_fg = light gray
-search_thread_subject_bg = default
-search_thread_subject_fg = light gray
-search_thread_subject_isunread_fg = light gray,bold
-search_thread_subject_isflagged_fg = light red
-search_thread_subject_focus_bg = dark gray
-search_thread_subject_focus_fg = light gray
-search_thread_subject_isunread_focus_fg = light gray,bold
-search_thread_subject_isflagged_focus_fg = light red,bold
-search_thread_tags_bg = default
-search_thread_tags_fg = brown
-search_thread_tags_focus_bg = dark gray
-search_thread_tags_focus_fg = yellow,bold
-
-
-[1c-theme]
-global_footer = standout
-global_notify_error = standout
-global_notify_normal = default
-global_prompt =
-help_text = default
-help_section = underline
-help_title = standout
-tag = default
-tag_focus = standout, bold
-tag_draft = standout
-bufferlist_focus = standout
-bufferlist_results_even = default
-bufferlist_results_odd = default
-search_thread = default
-search_thread_authors = default,underline
-search_thread_authors_focus = standout
-search_thread_content = default
-search_thread_content_focus = standout
-search_thread_date = default
-search_thread_date_focus = standout
-search_thread_focus = standout
-search_thread_mailcount = default
-search_thread_mailcount_focus = standout
-search_thread_subject = default
-search_thread_subject_isunread = bold
-search_thread_subject_isflagged = underline
-search_thread_subject_focus = standout
-search_thread_subject_isunread_focus = standout,bold
-search_thread_subject_isflagged_focus = standout,underline
-search_thread_tags = bold
-search_thread_tags_focus = standout
-thread_attachment = default
-thread_attachment_focus = underline
-thread_body = default
-thread_header = default
-thread_header_key = default
-thread_header_value = default
-thread_summary_even =
-thread_summary_focus = standout
-thread_summary_odd =
diff --git a/alot/defaults/alot.rc.spec b/alot/defaults/alot.rc.spec
index 40929404..4083c3d3 100644
--- a/alot/defaults/alot.rc.spec
+++ b/alot/defaults/alot.rc.spec
@@ -1,5 +1,4 @@
-# ask for subject when compose
-ask_subject = boolean(default=True)
+ask_subject = boolean(default=True)  # ask for subject when compose
 
 # confirm exit
 bug_on_exit = boolean(default=False)
@@ -29,12 +28,9 @@ envelope_headers_blacklist = string_list(default=list(In-Reply-To,References))
 # set terminal command used for spawning shell commands
 terminal_cmd = string(default='x-terminal-emulator -e')
 
-####################
-# EDITOR settings  #
-####################
 # editor command
 # if unset, alot will first try the EDITOR env variable, then /usr/bin/editor
-#editor_cmd = string(default="/usr/bin/vim -f -c 'set filetype=mail' +")
+editor_cmd = string(default=None)
 
 # file encoding used by your editor
 editor_writes_encoding = string(default='UTF-8')
@@ -43,18 +39,16 @@ editor_writes_encoding = string(default='UTF-8')
 editor_spawn = boolean(default=False)
 
 # call editor in separate thread.
-# in case your editor doesn't run in the same window as alot, setting true here
+# In case your editor doesn't run in the same window as alot, setting true here
 # will make alot non-blocking during edits
 editor_in_thread = boolean(default=False)
 
-
 # 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.
 edit_headers_whitelist = string_list(default=list(*,))
 edit_headers_blacklist = string_list(default=list(Content-Type,MIME-Version,References,In-Reply-To))
 
-
 # timeout in secs after a failed attempt to flush is repeated
 flush_retry_timeout = integer(default=5)
 
@@ -105,18 +99,26 @@ user_agent = string(default='alot/$VERSION')
         __many__ = string(default=None)
 
 [tags]
+    # for each tag
     [[__many__]]
+        # foreground
         fg = string(default=None)
+        # background
         bg = string(default=None)
+        # foreground if focussed
         focus_fg = string(default=None)
+        # background if focussed
         focus_bg = string(default=None)
+        # alternative string representation
         translated = string(default=None)
 
 [accounts]
 [[__many__]]
+        # your email address
+        address = string
+
         # used to format the (proposed) From-header in outgoing mails
         realname = string
-        address = string
 
         # used to clear your addresses/ match account when formating replies
         aliases = string_list(default=list())
@@ -124,13 +126,16 @@ user_agent = string(default='alot/$VERSION')
         # how to send mails
         sendmail_command = string(default='sendmail')
 
-        # where to store outgoing mail, e.g. maildir:///home/you/mail//Sent
+        # 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.
         sent_box = string(default=None)
 
         # how to tag sent mails.
         sent_tags = string_list(default=list('sent'))
 
-        # path to signature file
+        # path to signature file that gets attached to all outgoing mails from this account, optionally
+        # renamed to `signature_filename`.
         signature = string(default=None)
 
         # attach signature file if set to True, append its content (mimetype text)
@@ -141,6 +146,10 @@ user_agent = string(default='alot/$VERSION')
         # signature_as_attachment is set to True
         signature_filename = string(default=None)
 
-        # command to lookup contacts
+        # 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.
         abook_command = string(default=None)
+
+        # The regular expression used to match name/address pairs in the output of `abook_command`
         abook_regexp = string(default=None)