diff options
author | Patrick Totzke <patricktotzke@gmail.com> | 2012-07-12 22:15:47 +0100 |
---|---|---|
committer | Patrick Totzke <patricktotzke@gmail.com> | 2012-07-12 22:15:47 +0100 |
commit | 08ba54db2f825de3e6eb9f5693f57dd1332c1f23 (patch) | |
tree | b203d8fe69a5964cdafc6c7570ccdb467ec6bc16 /docs | |
parent | 382d5fcb9bed5aec164538a15e320314289b90f6 (diff) |
docstrings for new settings methods
Diffstat (limited to 'docs')
-rw-r--r-- | docs/source/configuration/accounts_table | 135 | ||||
-rw-r--r-- | docs/source/configuration/alotrc_table | 471 | ||||
-rw-r--r-- | docs/source/description | 4 | ||||
-rw-r--r-- | docs/source/usage/commands | 29 | ||||
-rw-r--r-- | docs/source/usage/first_steps | 10 | ||||
-rw-r--r-- | docs/source/usage/synopsis | 26 |
6 files changed, 675 insertions, 0 deletions
diff --git a/docs/source/configuration/accounts_table b/docs/source/configuration/accounts_table new file mode 100644 index 00000000..aea1956c --- /dev/null +++ b/docs/source/configuration/accounts_table @@ -0,0 +1,135 @@ + +.. CAUTION: THIS FILE IS AUTO-GENERATED + from the inline comments of specfile defaults/alot.rc.spec. + + If you want to change its content make your changes + to that spec to ensure they woun't be overwritten later. + +.. _address: + +.. describe:: address + + your main email address + + :type: string + +.. _realname: + +.. describe:: realname + + used to format the (proposed) From-header in outgoing mails + + :type: string + +.. _aliases: + +.. describe:: aliases + + used to clear your addresses/ match account when formatting replies + + :type: string list + :default: , + + +.. _sendmail-command: + +.. describe:: sendmail_command + + sendmail command. This is the shell command used to send out mails via the sendmail protocol + + :type: string + :default: "sendmail -t" + + +.. _sent-box: + +.. describe:: sent_box + + where to store outgoing mails, e.g. `maildir:///home/you/mail/Sent`. + You can use mbox, maildir, mh, babyl and mmdf in the protocol part of the URL. + + .. note:: If you want to add outgoing mails automatically to the notmuch index + you must use maildir in a path within your notmuch database path. + + :type: mail_container + :default: None + + +.. _draft-box: + +.. describe:: draft_box + + where to store draft mails, e.g. `maildir:///home/you/mail/Drafts`. + You can use mbox, maildir, mh, babyl and mmdf in the protocol part of the URL. + + .. note:: You will most likely want drafts indexed by notmuch to be able to + later access them within alot. This currently only works for + maildir containers in a path below your notmuch database path. + + :type: mail_container + :default: None + + +.. _sent-tags: + +.. describe:: sent_tags + + list of tags to automatically add to outgoing messages + + :type: string list + :default: sent, + + +.. _signature: + +.. describe:: signature + + path to signature file that gets attached to all outgoing mails from this account, optionally + renamed to ref:`signature_filename <signature-filename>`. + + :type: string + :default: None + + +.. _signature-as-attachment: + +.. describe:: signature_as_attachment + + attach signature file if set to True, append its content (mimetype text) + to the body text if set to False. + + :type: boolean + :default: False + + +.. _signature-filename: + +.. describe:: signature_filename + + signature file's name as it appears in outgoing mails if + :ref:`signature_as_attachment <signature-as-attachment>` is set to True + + :type: string + :default: None + + +.. _sign-by-default: + +.. describe:: sign_by_default + + Outgoing messages will be GPG signed by default if this is set to True. + + :type: boolean + :default: False + + +.. _gpg-key: + +.. describe:: gpg_key + + The GPG key ID you want to use with this account. If unset, alot will + use your default key. + + :type: string + :default: None + diff --git a/docs/source/configuration/alotrc_table b/docs/source/configuration/alotrc_table new file mode 100644 index 00000000..6b4e2092 --- /dev/null +++ b/docs/source/configuration/alotrc_table @@ -0,0 +1,471 @@ + +.. CAUTION: THIS FILE IS AUTO-GENERATED + from the inline comments of specfile defaults/alot.rc.spec. + + If you want to change its content make your changes + to that spec to ensure they woun't be overwritten later. + +.. _ask-subject: + +.. describe:: ask_subject + + + :type: boolean + :default: True + + +.. _attachment-prefix: + +.. describe:: attachment_prefix + + directory prefix for downloading attachments + + :type: string + :default: "~" + + +.. _authors-maxlength: + +.. describe:: authors_maxlength + + maximal length of authors string in search mode before it gets truncated + + :type: integer + :default: 30 + + +.. _bufferclose-focus-offset: + +.. describe:: bufferclose_focus_offset + + offset of next focused buffer if the current one gets closed + + :type: integer + :default: -1 + + +.. _bufferlist-statusbar: + +.. describe:: bufferlist_statusbar + + Format of the status-bar in bufferlist mode. + This is a pair of strings to be left and right aligned in the status-bar that may contain variables: + + * `{buffer_no}`: index of this buffer in the global buffer list + * `{total_messages}`: total numer of messages indexed by notmuch + * `{pending_writes}`: number of pending write operations to the index + + :type: mixed_list + :default: [{buffer_no}: bufferlist], total messages: {total_messages} + + +.. _bug-on-exit: + +.. describe:: bug_on_exit + + confirm exit + + :type: boolean + :default: False + + +.. _colourmode: + +.. describe:: colourmode + + number of colours to use + + :type: option, one of ['1', '16', '256'] + :default: 256 + + +.. _complete-matching-abook-only: + +.. describe:: complete_matching_abook_only + + in case more than one account has an address book: + Set this to True to make tab completion for recipients during compose only + look in the abook of the account matching the sender address + + :type: boolean + :default: False + + +.. _display-content-in-threadline: + +.. describe:: display_content_in_threadline + + fill threadline with message content + + :type: boolean + :default: False + + +.. _displayed-headers: + +.. describe:: displayed_headers + + headers that get displayed by default + + :type: string list + :default: From, To, Cc, Bcc, Subject + + +.. _edit-headers-blacklist: + +.. describe:: edit_headers_blacklist + + see :ref:`edit_headers_whitelist <edit-headers-whitelist>` + + :type: string list + :default: Content-Type, MIME-Version, References, In-Reply-To + + +.. _edit-headers-whitelist: + +.. describe:: edit_headers_whitelist + + Which header fields should be editable in your editor + used are those that match the whitelist and don't match the blacklist. + in both cases '*' may be used to indicate all fields. + + :type: string list + :default: \*, + + +.. _editor-cmd: + +.. describe:: editor_cmd + + editor command + if unset, alot will first try the :envvar:`EDITOR` env variable, then :file:`/usr/bin/editor` + + :type: string + :default: None + + +.. _editor-in-thread: + +.. 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 + + :type: boolean + :default: False + + +.. _editor-spawn: + +.. describe:: editor_spawn + + use terminal_command to spawn a new terminal for the editor? + equivalent to always providing the `--spawn=yes` parameter to compose/edit commands + + :type: boolean + :default: False + + +.. _editor-writes-encoding: + +.. describe:: editor_writes_encoding + + file encoding used by your editor + + :type: string + :default: "UTF-8" + + +.. _envelope-headers-blacklist: + +.. describe:: envelope_headers_blacklist + + headers that are hidden in envelope buffers by default + + :type: string list + :default: In-Reply-To, References + + +.. _envelope-statusbar: + +.. describe:: envelope_statusbar + + Format of the status-bar in envelope mode. + This is a pair of strings to be left and right aligned in the status-bar. + Apart from the global variables listed at :ref:`bufferlist_statusbar <bufferlist-statusbar>` + these strings may contain variables: + + * `{to}`: To-header of the envelope + + :type: mixed_list + :default: [{buffer_no}: envelope], total messages: {total_messages} + + +.. _flush-retry-timeout: + +.. describe:: flush_retry_timeout + + timeout in seconds after a failed attempt to writeout the database is repeated + + :type: integer + :default: 5 + + +.. _forward-subject-prefix: + +.. describe:: forward_subject_prefix + + String prepended to subject header on forward + only if original subject doesn't start with 'Fwd:' or this prefix + + :type: string + :default: "Fwd: " + + +.. _hooksfile: + +.. describe:: hooksfile + + where to look up hooks + + :type: string + :default: "~/.config/alot/hooks.py" + + +.. _initial-command: + +.. describe:: initial_command + + initial command when none is given as argument: + + :type: string + :default: "search tag:inbox AND NOT tag:killed" + + +.. _notify-timeout: + +.. describe:: notify_timeout + + time in secs to display status messages + + :type: integer + :default: 2 + + +.. _print-cmd: + +.. describe:: print_cmd + + how to print messages: + this specifies a shell command used for printing. + threads/messages are piped to this command as plain text. + muttprint/a2ps works nicely + + :type: string + :default: None + + +.. _prompt-suffix: + +.. describe:: prompt_suffix + + Suffix of the prompt used when waiting for user input + + :type: string + :default: ":" + + +.. _quit-on-last-bclose: + +.. describe:: quit_on_last_bclose + + shut down when the last buffer gets closed + + :type: boolean + :default: False + + +.. _quote-prefix: + +.. describe:: quote_prefix + + String prepended to line when quoting + + :type: string + :default: "> " + + +.. _reply-subject-prefix: + +.. describe:: reply_subject_prefix + + String prepended to subject header on reply + only if original subject doesn't start with 'Re:' or this prefix + + :type: string + :default: "Re: " + + +.. _search-statusbar: + +.. describe:: search_statusbar + + Format of the status-bar in search mode. + This is a pair of strings to be left and right aligned in the status-bar. + Apart from the global variables listed at :ref:`bufferlist_statusbar <bufferlist-statusbar>` + these strings may contain variables: + + * `{querystring}`: search string + * `{result_count}`: number of matching messages + * `{result_count_positive}`: 's' if result count is greater than 0. + + :type: mixed_list + :default: [{buffer_no}: search] for "{querystring}", {result_count} of {total_messages} messages + + +.. _search-threads-sort-order: + +.. describe:: search_threads_sort_order + + default sort order of results in a search + + :type: option, one of ['oldest_first', 'newest_first', 'message_id', 'unsorted'] + :default: newest_first + + +.. _show-statusbar: + +.. describe:: show_statusbar + + display status-bar at the bottom of the screen? + + :type: boolean + :default: True + + +.. _tabwidth: + +.. describe:: tabwidth + + number of spaces used to replace tab characters + + :type: integer + :default: 8 + + +.. _taglist-statusbar: + +.. describe:: taglist_statusbar + + Format of the status-bar in taglist mode. + This is a pair of strings to be left and right aligned in the status-bar. + These strings may contain variables listed at :ref:`bufferlist_statusbar <bufferlist-statusbar>` + that will be substituted accordingly. + + :type: mixed_list + :default: [{buffer_no}: taglist], total messages: {total_messages} + + +.. _template-dir: + +.. 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. + + :type: string + :default: "$XDG_CONFIG_HOME/alot/templates" + + +.. _terminal-cmd: + +.. describe:: terminal_cmd + + set terminal command used for spawning shell commands + + :type: string + :default: "x-terminal-emulator -e" + + +.. _theme: + +.. describe:: theme + + name of the theme to use + + :type: string + :default: None + + +.. _themes-dir: + +.. describe:: themes_dir + + directory containing theme files + + :type: string + :default: None + + +.. _thread-authors-me: + +.. describe:: thread_authors_me + + Word to replace own addresses with. Works in combination with + :ref:`thread_authors_replace_me <thread-authors-replace-me>` + + :type: string + :default: "Me" + + +.. _thread-authors-replace-me: + +.. describe:: thread_authors_replace_me + + Replace own email addresses with "me" in author lists + Uses own addresses and aliases in all configured accounts. + + :type: boolean + :default: True + + +.. _thread-statusbar: + +.. describe:: thread_statusbar + + Format of the status-bar in thread mode. + This is a pair of strings to be left and right aligned in the status-bar. + Apart from the global variables listed at :ref:`bufferlist_statusbar <bufferlist-statusbar>` + these strings may contain variables: + + * `{tid}`: thread id + * `{subject}`: subject line of the thread + * `{authors}`: abbreviated authors string for this thread + * `{message_count}`: number of contained messages + + :type: mixed_list + :default: [{buffer_no}: thread] {subject}, total messages: {total_messages} + + +.. _timestamp-format: + +.. describe:: timestamp_format + + timestamp format in `strftime format syntax <http://docs.python.org/library/datetime.html#strftime-strptime-behavior>`_ + + :type: string + :default: None + + +.. _user-agent: + +.. 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. + + :type: string + :default: "alot/{version}" + diff --git a/docs/source/description b/docs/source/description new file mode 100644 index 00000000..9dea9693 --- /dev/null +++ b/docs/source/description @@ -0,0 +1,4 @@ +Alot is a terminal-based mail user agent for the notmuch mail system. +It features a modular and command prompt driven interface +to provide a full MUA experience as an alternative to the Emacs mode shipped +with notmuch. diff --git a/docs/source/usage/commands b/docs/source/usage/commands new file mode 100644 index 00000000..ec0be2eb --- /dev/null +++ b/docs/source/usage/commands @@ -0,0 +1,29 @@ +.. _commands: + +Commands +======== + +:doc:`modes/global` + globally available commands +:doc:`modes/search` + shows a result list of threads for a query +:doc:`modes/thread` + displays a thread as a tree of messages +:doc:`modes/envelope` + message composition mode +:doc:`modes/bufferlist` + lists all active buffers +:doc:`modes/taglist` + lists all tagstrings present in the notmuch database + +.. toctree:: + :maxdepth: 2 + :hidden: + + modes/global + modes/search + modes/thread + modes/envelope + modes/bufferlist + modes/taglist + diff --git a/docs/source/usage/first_steps b/docs/source/usage/first_steps new file mode 100644 index 00000000..e99c44ce --- /dev/null +++ b/docs/source/usage/first_steps @@ -0,0 +1,10 @@ +The arrow keys, `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. + +The interface shows one buffer at a time, you can use `tab` and `Shift-Tab` to switch +between them, close the current buffer with `d` and list them all with `;`. + +The buffer type or *mode* (displayed at the bottom left) determines which prompt commands +are available. Usage information on any command can be listed by typing `help YOURCOMMAND` +to the prompt; The key bindings for the current mode are listed upon pressing `?`. diff --git a/docs/source/usage/synopsis b/docs/source/usage/synopsis new file mode 100644 index 00000000..5bfb8e88 --- /dev/null +++ b/docs/source/usage/synopsis @@ -0,0 +1,26 @@ +.. code-block:: none + + alot [-r] [-c CONFIGFILE] [-n NOTMUCHCONFIGFILE] [-C {1,16,256}] [-p DB_PATH] + [-d {debug,info,warning,error}] [-l LOGFILE] [--version] [--help] + [command] + +Options + + -r, --read-only open db in read only mode + -c, --config=FILENAME config file (default: ~/.config/alot/config) + -n, --notmuch-config=FILENAME notmuch config (default: $NOTMUCH_CONFIG or ~/.notmuch-config) + -C, --colour-mode=COLOUR terminal colour mode (default: 256). Must be 1, 16 or 256 + -p, --mailindex-path=PATH path to notmuch index + -d, --debug-level=LEVEL debug log (default: info). Must be one of debug,info,warning or error + -l, --logfile=FILENAME logfile (default: /dev/null) + --version Display version string and exit + --help Display help and exit + + +Commands + + search + start in a search buffer using the querystring provided as + parameter. See the SEARCH SYNTAX section of notmuch(1). + compose + compose a new message |