From b66ccfd799f60c14d94eba8a1b9ca4c20e52674a Mon Sep 17 00:00:00 2001 From: Patrick Totzke Date: Mon, 24 Oct 2011 10:42:37 +0100 Subject: updated docs --- COSTOMIZE.md | 152 ++++++++++++++++++++++++++++++++++++++++++ INSTALL | 58 ---------------- INSTALL.md | 57 ++++++++++++++++ README.md | 35 ++++++---- USAGE.md | 214 ----------------------------------------------------------- 5 files changed, 232 insertions(+), 284 deletions(-) create mode 100644 COSTOMIZE.md delete mode 100644 INSTALL create mode 100644 INSTALL.md delete mode 100644 USAGE.md diff --git a/COSTOMIZE.md b/COSTOMIZE.md new file mode 100644 index 00000000..8285998b --- /dev/null +++ b/COSTOMIZE.md @@ -0,0 +1,152 @@ +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 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 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.+?@.+?)\s+(?P.+)`, 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 = ⇄ diff --git a/INSTALL b/INSTALL deleted file mode 100644 index a995a3f6..00000000 --- a/INSTALL +++ /dev/null @@ -1,58 +0,0 @@ -INSTALL -======= - -Alot depends on development versions of notmuch and urwid. -Note that due to restrictions on argparse and subprocess, -you need to run *python v>=2.7*. - -urwid ------ -make sure you have - - git clone http://github.com/wardi/urwid - cd urwid - sudo python setup.py install - -It seems you need the python headers for this. -On debian/ubuntu: - - aptitude install python2.7-dev - - -notmuch -------- -install notmuch *and* python bindings from git: - - git clone git://notmuchmail.org/git/notmuch - - cd notmuch - ./configure - make - sudo make install - cd bindings/python - sudo python setup.py install - - -alot ----- -get alot and install it from git: - - git clone git://github.com/pazz/alot alot - cd alot - sudo python setup.py install - -That's it, now `alot` should be in your path. - -Alot tries to be as unobtrusive as possible, with one exception: -It forces you to use UTF-8 encoding whereever it can: -All text parts and headers of outgoing emails are converted to utf-8, -notmuch tagstrings, edited emails and config files are interpreted as utf-8. - -All configs are optional, but if you want to send mails you need to -specify at least one account section in you config: - - [account uoe] - realname = Your Name - address = your@address - -See USAGE for default keymaps and how to do fancy customization. diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..534a7ed7 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,57 @@ +INSTALL +======= + +Alot depends on development versions of notmuch and urwid. Note that due to restrictions +on argparse and subprocess, you need to run *python v>=2.7*, which only recently made it +into debian testing. + +urwid +----- +make sure you have urwid v >=1.0. To install from git use: + + git clone http://github.com/wardi/urwid + cd urwid + sudo python setup.py install + +It seems you need the python headers for this. On debian/ubuntu: + + aptitude install python2.7-dev + + +notmuch +------- +install notmuch *and* python bindings from git: + + git clone git://notmuchmail.org/git/notmuch + + cd notmuch + ./configure + make + sudo make install + cd bindings/python + sudo python setup.py install + + +alot +---- +get alot and install it from git: + + git clone git://github.com/pazz/alot alot + cd alot + sudo python setup.py install + +That's it, now `alot` should be in your path. + +Alot tries to be as unobtrusive as possible, with one exception: It forces you to use +UTF-8 encoding whereever it can: All text parts and headers of outgoing emails are +converted to utf-8, notmuch tagstrings, edited emails and config files are interpreted as +Utf-8. + +All configs are optional, but if you want to send mails you need to specify at least one +account section in your config: + + [account uoe] + realname = Your Name + address = your@address + +See `CUSTOMIZE.md` on how to do fancy customization. diff --git a/README.md b/README.md index b3720cfb..955a49b2 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,31 @@ -This is a proposal for a terminal gui for [notmuch mail][notmuch] -written in python using the [urwid][urwid] toolkit. +This is a proposal for a terminal gui for [notmuch mail][notmuch] written in +python using the [urwid][urwid] toolkit. -You can find some old screenshots in `data/alot*png`, -the files `INSTALL` and `USAGE` contain instructions on how to set it up, -use and customize. These files are nicely rendered in the [github wiki][wiki]. -The API docs for the current master branch are [here][api]. -the `docs` directory contains their sources. +The files `INSTALL.md` and `CUSTOMIZE.md` contain instructions on how to set it +up and customize respectively. + +(slightly outdated) autogenerated API docs for the current master branch can be +found [here][api]. Their sources live in the `docs` directory. Do comment on the code or file issues! I'm curious what you think of it. You can talk to me in #notmuch@Freenode. Current features include: ------------------------- + * modular and command prompt driven interface + * tab completion and usage help for all commands + * completion using addressbook lookups + * user configurable keyboard maps * spawn terminals for asynchronous editing of mails - * theming, optionally in monochromatic, 16 or 256 colours + * theming, optionally in 2, 16 or 256 colours * tag specific theming and tagstring translation * a hook system to inject one's own python code * python shell for introspection * forward/reply/group-reply of emails + * printing/piping of mails and threads * multiple accounts for sending mails via sendmail - * tab completion for commands and querystrings * priorizable notification popups * database manager that manages a write queue to the notmuch index - * user configurable keyboard maps - * printing/piping of mails and threads - * addressbook integration (dev branch) Soonish to be addressed non-features: ------------------------------------- @@ -33,6 +34,16 @@ Soonish to be addressed non-features: * folding for message parts * undo for commands + +Usage +===== +In all views, arrows, page-up/down, j,k and space can be used to move the focus. +Escape cancels prompts and Enter selects. Hit ":" at any time and type in commands +to the prompt. +Usage information on any command can be listed using `help YOURCOMMAND`. +The keybindings for the current mode are listet upon pressing '?'. + + [notmuch]: http://notmuchmail.org/ [urwid]: http://excess.org/urwid/ [api]: http://pazz.github.com/alot/ diff --git a/USAGE.md b/USAGE.md deleted file mode 100644 index 375d5ec9..00000000 --- a/USAGE.md +++ /dev/null @@ -1,214 +0,0 @@ -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.+?@.+?)\s+(?P.+)`, 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 = ⇄ -- cgit v1.2.3