diff options
Diffstat (limited to 'USAGE.md')
| -rw-r--r-- | USAGE.md | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/USAGE.md b/USAGE.md new file mode 100644 index 00000000..375d5ec9 --- /dev/null +++ b/USAGE.md @@ -0,0 +1,214 @@ +Usage +===== +In all views, arrows, page-up/down, j,k and space can be used to move the focus. +Escape cancels prompts. You can hit ":" at any time and type in commands +to the prompt. Any commandline can be mapped by using the "MODE-maps" sections +in the config file. These are the default keymaps: + + [global-maps] + @ = refresh + 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 = closefocussed + enter = openfocussed + + [search-maps] + a = toggletag inbox + & = toggletag killed + l = retagprompt + O = refineprompt + enter = openthread + | = refineprompt + + [envelope-maps] + a = prompt attach ~/ + y = send + s = 'prompt subject ' + t = 'prompt to ' + enter = reedit + + [taglist-maps] + enter = select + + [thread-maps] + C = fold --all + E = unfold --all + H = toggleheaders + P = print --thread + S = save --all + a = toggletag inbox + g = groupreply + f = forward + p = print + s = save + r = reply + enter = select + | = 'prompt pipeto ' + +Config +------ +Just like offlineimap or notmuch itself, alot reads a config file in the "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 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 the account X: realname, email address, sendmail + + [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}. + +All configs are optional, but if you want to send mails you need to +specify at least one account section. +A sample gmail section looks like this: + + [account gmail] + realname = Patrick Totzke + address = patricktotzke@gmail.com + aliases = patricktotzke@googlemail.com + gpg_key = D7D6C5AA + sender_type = sendmail + sendmail_command = msmtp --account=gmail -t + +I use this for my uni-account: + + [account uoe] + realname = Patrick Totzke + address = ... + aliases = foobar@myuni.uk;f.bar@myuni.uk;f.b100@students.myuni.uk + sender_type = sendmail + sendmail_command = msmtp --account=uoe -t + sent_box = maildir:///home/pazz/mail/uoe/Sent + draft_box = maildir:///home/pazz/mail/uoe/Drafts + signature = ~/my_uni_vcard.vcs + signature_filename = p.totzke.vcs + abook_command = abook --mutt-query + + +Caution: 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_mailbox` 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 file specified by `signature` is attached to all outgoing mails from this account, optionally renamed to +`signature_filename`. + +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!). + + +Hooks +----- +Hooks are python callables that live in a module specified by +`hooksfile` in the `[global]` section of your config. Per default this points +to `~/.config/alot/hooks.py`. +For every command X, the callable 'pre_X' will be called before X and 'post_X' afterwards. + +When a hook gets called, it receives instances of + + * ui: `alot.ui.UI`, the main user interface object that can prompt etc. + * dbm: `alot.db.DBManager`, the applications database manager + * aman: `alot.account.AccountManager`, can be used to look up account info + * log: `logging.Logger`, to write to logfile + * config: `alot.settings.config`, a configparser to access the users config + +An autogenerated API doc for these can be found at http://pazz.github.com/alot/ , +the sphinx sources live in the `docs` folder. +As an example, consider this pre-hook for the exit command, +that logs a personalized goodby message: + +```python +def pre_exit(aman=None, log=None, **rest): + accounts = aman.get_accounts() + if accounts: + log.info('goodbye, %s!' % accounts[0].realname) + else: + log.info('goodbye!') +``` + +Apart from command pre and posthooks, the following hooks will be interpreted: + * `reply_prefix(realname, address, timestamp, **kwargs)` + Is used to reformat the first indented line in a reply message. + Should return a string and defaults to 'Quoting %s (%s)\n' % (realname, timestamp) + + * `forward_prefix(realname, address, timestamp, **kwargs)` + Is used to reformat the first indented line in a inline forwarded message. + Returns a string and defaults to 'Forwarded message from %s (%s)\n' % (realname, timestamp) + * `pre_edit_translate(bodytext, **kwargs)` + can be used to manipulate a messages bodytext before the editor is called. + Receives and returns a string. + * `post_edit_translate(bodytext, **kwargs)` + can be used to manipulate a messages bodytext after the editor is called + Receives and returns a string. + + + +Theming +------- +You can change the colour settings in the section `[Xc-theme]`, where X is the +colour mode you use. This defaults to 256, but 16 and 1 are also possible. +The colourmode can be changed in the globals section or given as a commandline +parameter (-C). +The keys in this section should be self explanatory. In 16c and 256c modes you can define Y_fg and +Y_bg for the foreground and background of each keyword Y. These can define colorcodes and flags +like `underline` or `bold`, comma separated if you want more than one. See urwids doc on Attributes: +http://excess.org/urwid/reference.html#AttrSpec +Urwid privides a neat script that makes choosing colours easy, which can be found here: +http://excess.org/urwid/browser/palette_test.py + +See `data/example.full.rc` for a complete list of widgets that can be themed. +Moreover, keywords that start with "tag_" will be used to display specific tags. For instance, you +can use the following to always display the "todo" tag in white on red, when in 256c-mode. + + [256c-theme] + tag_todo_bg = #d66 + tag_todo_fg = white + +You can translate tag strings before displaying them using the [tag-translate] section. +A key=value statement in this section is interpreted as: +Always display the tag `key` as string `value`. Utf-8 symbols are welcome here. +See e.g. http://panmental.de/symbols/info.htm +I personally display my maildir flags like this: + + [tag-translate] + flagged = ⚑ + unread = ✉ + replied = ⇄ |