From 1dbf2617306f3d6beeb40f8bb506db58217fe683 Mon Sep 17 00:00:00 2001 From: Patrick Totzke Date: Tue, 10 Jul 2012 20:44:26 +0100 Subject: doc: fix toctree warnings this is done now by either including a hidden toctree or renaming *.rst files --- docs/source/conf.py | 4 +- docs/source/configuration/accounts_table | 135 ++++++++ docs/source/configuration/accounts_table.rst | 135 -------- docs/source/configuration/alotrc_table | 471 +++++++++++++++++++++++++++ docs/source/configuration/alotrc_table.rst | 471 --------------------------- docs/source/configuration/index.rst | 6 +- docs/source/description | 4 + docs/source/description.rst | 4 - docs/source/generate_configs.py | 4 +- docs/source/index.rst | 2 +- docs/source/manpage.rst | 6 +- docs/source/usage/commands | 29 ++ docs/source/usage/commands.rst | 15 - docs/source/usage/first_steps | 10 + docs/source/usage/first_steps.rst | 10 - docs/source/usage/index.rst | 6 +- docs/source/usage/synopsis | 26 ++ docs/source/usage/synopsis.rst | 26 -- 18 files changed, 690 insertions(+), 674 deletions(-) create mode 100644 docs/source/configuration/accounts_table delete mode 100644 docs/source/configuration/accounts_table.rst create mode 100644 docs/source/configuration/alotrc_table delete mode 100644 docs/source/configuration/alotrc_table.rst create mode 100644 docs/source/description delete mode 100644 docs/source/description.rst create mode 100644 docs/source/usage/commands delete mode 100644 docs/source/usage/commands.rst create mode 100644 docs/source/usage/first_steps delete mode 100644 docs/source/usage/first_steps.rst create mode 100644 docs/source/usage/synopsis delete mode 100644 docs/source/usage/synopsis.rst (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index 24eb6a9c..dd2cccc1 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -93,7 +93,9 @@ release = version # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = [] +exclude_patterns = [ +'manpage.rst' +] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None 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 `. + + :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 ` 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/accounts_table.rst b/docs/source/configuration/accounts_table.rst deleted file mode 100644 index aea1956c..00000000 --- a/docs/source/configuration/accounts_table.rst +++ /dev/null @@ -1,135 +0,0 @@ - -.. 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 `. - - :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 ` 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 ` + + :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 ` + 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 ` + 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 ` + 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 ` + + :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 ` + 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 `_ + + :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/configuration/alotrc_table.rst b/docs/source/configuration/alotrc_table.rst deleted file mode 100644 index 6b4e2092..00000000 --- a/docs/source/configuration/alotrc_table.rst +++ /dev/null @@ -1,471 +0,0 @@ - -.. 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 ` - - :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 ` - 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 ` - 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 ` - 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 ` - - :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 ` - 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 `_ - - :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/configuration/index.rst b/docs/source/configuration/index.rst index 90744ef7..b14af2e1 100644 --- a/docs/source/configuration/index.rst +++ b/docs/source/configuration/index.rst @@ -24,7 +24,7 @@ The type of an option is used to validate a given value. For instance, if the type says "boolean" you may only provide "True" or "False" as values in your config file, otherwise alot will complain on startup. Strings *may* be quoted but do not need to be. -.. include:: alotrc_table.rst +.. include:: alotrc_table .. _account: @@ -59,7 +59,7 @@ Here is an example configuration:: The following entries are interpreted at the moment: -.. include:: accounts_table.rst +.. include:: accounts_table Contacts Completion @@ -151,7 +151,7 @@ Hooks are python callables that live in a module specified by `hooksfile` in the config. Per default this points to :file:`~/.config/alot/hooks.py`. When a hook gets called it receives a reference to the :class:`main user interface ` and the :class:`database manager `. -For every :doc:`COMMAND <../usage/commands>` in mode :ref:`MODE `, the callables :func:`pre_MODE_COMMAND` and :func:`post_MODE_COMMAND` +For every :ref:`COMMAND ` in mode :ref:`MODE `, the callables :func:`pre_MODE_COMMAND` and :func:`post_MODE_COMMAND` -- if defined -- will be called before and after the command is applied respectively. The signature for the pre-`send` hook in envelope mode for example looks like this: 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/description.rst b/docs/source/description.rst deleted file mode 100644 index 9dea9693..00000000 --- a/docs/source/description.rst +++ /dev/null @@ -1,4 +0,0 @@ -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/generate_configs.py b/docs/source/generate_configs.py index 123b017b..8b0009e8 100755 --- a/docs/source/generate_configs.py +++ b/docs/source/generate_configs.py @@ -60,9 +60,9 @@ if __name__ == "__main__": config = ConfigObj(None, configspec=specpath, stringify=False, list_values=False) config.validate(Validator()) - alotrc_table_file = os.path.join(HERE, 'configuration', 'alotrc_table.rst') + alotrc_table_file = os.path.join(HERE, 'configuration', 'alotrc_table') rewrite_entries(config.configspec, alotrc_table_file, 'defaults/alot.rc.spec', sort=True) - rewrite_entries(config, os.path.join(HERE, 'configuration', 'accounts_table.rst'), + rewrite_entries(config, os.path.join(HERE, 'configuration', 'accounts_table'), 'defaults/alot.rc.spec', sec=config.configspec['accounts']['__many__']) diff --git a/docs/source/index.rst b/docs/source/index.rst index cc227b77..4742e36d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -5,7 +5,7 @@ User Manual =========== -.. include:: description.rst +.. include:: description .. toctree:: :maxdepth: 2 diff --git a/docs/source/manpage.rst b/docs/source/manpage.rst index 0e53d82b..bfdf43da 100644 --- a/docs/source/manpage.rst +++ b/docs/source/manpage.rst @@ -4,16 +4,16 @@ Manpage Synopsis -------- -.. include:: usage/synopsis.rst +.. include:: usage/synopsis Description ----------- -.. include:: description.rst +.. include:: description Usage ----- -.. include:: usage/first_steps.rst +.. include:: usage/first_steps See Also 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/commands.rst b/docs/source/usage/commands.rst deleted file mode 100644 index bc93ac1a..00000000 --- a/docs/source/usage/commands.rst +++ /dev/null @@ -1,15 +0,0 @@ -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 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/first_steps.rst b/docs/source/usage/first_steps.rst deleted file mode 100644 index e99c44ce..00000000 --- a/docs/source/usage/first_steps.rst +++ /dev/null @@ -1,10 +0,0 @@ -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/index.rst b/docs/source/usage/index.rst index 7e97e78e..4992ba1c 100644 --- a/docs/source/usage/index.rst +++ b/docs/source/usage/index.rst @@ -4,11 +4,11 @@ Usage Commandline invocation ====================== -.. include:: synopsis.rst +.. include:: synopsis First Steps =========== -.. include:: first_steps.rst +.. include:: first_steps -.. include:: commands.rst +.. include:: commands 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 diff --git a/docs/source/usage/synopsis.rst b/docs/source/usage/synopsis.rst deleted file mode 100644 index 5bfb8e88..00000000 --- a/docs/source/usage/synopsis.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. 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 -- cgit v1.2.3