joined and cleaned up user/api docs

10 files changed, 662 insertions, 0 deletions

diff --git a/docs/source/usage/commands.rst b/docs/source/usage/commands.rst
new file mode 100644
index 00000000..8608bc50
--- /dev/null
+++ b/docs/source/usage/commands.rst
@@ -0,0 +1,17 @@
+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.rst b/docs/source/usage/first_steps.rst
new file mode 100644
index 00000000..3ffa09ac
--- /dev/null
+++ b/docs/source/usage/first_steps.rst
@@ -0,0 +1,6 @@
+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.
+
+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
new file mode 100644
index 00000000..7e97e78e
--- /dev/null
+++ b/docs/source/usage/index.rst
@@ -0,0 +1,14 @@
+*****
+Usage
+*****
+
+Commandline invocation
+======================
+.. include:: synopsis.rst
+
+First Steps
+===========
+
+.. include:: first_steps.rst
+
+.. include:: commands.rst
diff --git a/docs/source/usage/modes/bufferlist.rst b/docs/source/usage/modes/bufferlist.rst
new file mode 100644
index 00000000..b619edf5
--- /dev/null
+++ b/docs/source/usage/modes/bufferlist.rst
@@ -0,0 +1,20 @@
+bufferlist
+----------
+The following commands are available in bufferlist mode
+
+.. index:: close
+
+close
+_____
+
+close focussed buffer
+
+
+.. index:: select
+
+select
+______
+
+focus selected buffer
+
+
diff --git a/docs/source/usage/modes/envelope.rst b/docs/source/usage/modes/envelope.rst
new file mode 100644
index 00000000..5e7cc1f3
--- /dev/null
+++ b/docs/source/usage/modes/envelope.rst
@@ -0,0 +1,87 @@
+envelope
+--------
+The following commands are available in envelope mode
+
+.. index:: set
+
+set
+___
+
+set header value
+
+positional arguments
+	:0: header to refine
+	:1: value
+
+
+optional arguments
+	:---append: keep previous values.
+
+.. index:: toggleheaders
+
+toggleheaders
+_____________
+
+toggle display of all headers
+
+
+.. index:: edit
+
+edit
+____
+
+edit mail
+
+optional arguments
+	:---spawn: force spawning of editor in a new terminal.
+	:---no-refocus: don't refocus envelope after editing (Defaults to: 'True').
+
+.. index:: send
+
+send
+____
+
+send mail
+
+
+.. index:: attach
+
+attach
+______
+
+attach files to the mail
+
+argument
+	file(s) to attach (accepts wildcads)
+
+
+.. index:: refine
+
+refine
+______
+
+prompt to change the value of a header
+
+argument
+	header to refine
+
+
+.. index:: save
+
+save
+____
+
+save draft
+
+
+.. index:: unset
+
+unset
+_____
+
+remove header field
+
+argument
+	header to refine
+
+
diff --git a/docs/source/usage/modes/global.rst b/docs/source/usage/modes/global.rst
new file mode 100644
index 00000000..845db65f
--- /dev/null
+++ b/docs/source/usage/modes/global.rst
@@ -0,0 +1,174 @@
+global
+------
+The following commands are available globally
+
+.. index:: bclose
+
+bclose
+______
+
+close a buffer
+
+
+.. index:: bprevious
+
+bprevious
+_________
+
+focus previous buffer
+
+
+.. index:: search
+
+search
+______
+
+open a new search buffer
+
+argument
+	search string
+
+optional arguments
+	:---sort: sort order. Valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
+
+.. index:: compose
+
+compose
+_______
+
+compose a new email
+
+optional arguments
+	:---sender: sender.
+	:---template: path to a template message file.
+	:---subject: subject line.
+	:---to: recipients.
+	:---cc: copy to.
+	:---bcc: blind copy to.
+	:---attach: attach files.
+	:---omit_signature: do not add signature.
+	:---spawn: spawn editor in new terminal.
+
+.. index:: prompt
+
+prompt
+______
+
+prompts for commandline and interprets it upon select
+
+argument
+	initial content
+
+
+.. index:: help
+
+help
+____
+
+
+    display help for a command. Use 'bindings' to
+    display all keybings interpreted in current mode.'
+    
+
+argument
+	command or 'bindings'
+
+
+.. index:: move
+
+move
+____
+
+move focus
+
+argument
+	direction
+
+
+.. index:: shellescape
+
+shellescape
+___________
+
+run external command
+
+argument
+	command line to execute
+
+optional arguments
+	:---spawn: run in terminal window.
+	:---thread: run in separate thread.
+	:---refocus: refocus current buffer                      after command has finished.
+
+.. index:: refresh
+
+refresh
+_______
+
+refresh the current buffer
+
+
+.. index:: cancel
+
+cancel
+______
+
+send cancel event
+
+
+.. index:: pyshell
+
+pyshell
+_______
+
+open an interactive python shell for introspection
+
+
+.. index:: exit
+
+exit
+____
+
+shut down cleanly
+
+
+.. index:: flush
+
+flush
+_____
+
+flush write operations or retry until committed
+
+
+.. index:: bufferlist
+
+bufferlist
+__________
+
+open a list of active buffers
+
+
+.. index:: bnext
+
+bnext
+_____
+
+focus next buffer
+
+
+.. index:: select
+
+select
+______
+
+send select event
+
+
+.. index:: taglist
+
+taglist
+_______
+
+opens taglist buffer
+
+
diff --git a/docs/source/usage/modes/search.rst b/docs/source/usage/modes/search.rst
new file mode 100644
index 00000000..6a8632d5
--- /dev/null
+++ b/docs/source/usage/modes/search.rst
@@ -0,0 +1,108 @@
+search
+------
+The following commands are available in search mode
+
+.. index:: sort
+
+sort
+____
+
+set sort order
+
+argument
+	sort order. valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
+
+
+.. index:: untag
+
+untag
+_____
+
+remove tags from all messages in the thread
+
+argument
+	comma separated list of tags
+
+optional arguments
+	:---no-flush: postpone a writeout to the index (Defaults to: 'True').
+
+.. index:: retag
+
+retag
+_____
+
+set tags of all messages in the thread
+
+argument
+	comma separated list of tags
+
+optional arguments
+	:---no-flush: postpone a writeout to the index (Defaults to: 'True').
+
+.. index:: refineprompt
+
+refineprompt
+____________
+
+prompt to change this buffers querystring
+
+
+.. index:: tag
+
+tag
+___
+
+add tags to all messages in the thread
+
+argument
+	comma separated list of tags
+
+optional arguments
+	:---no-flush: postpone a writeout to the index (Defaults to: 'True').
+
+.. index:: refine
+
+refine
+______
+
+refine query
+
+argument
+	search string
+
+optional arguments
+	:---sort: sort order. Valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
+
+.. index:: retagprompt
+
+retagprompt
+___________
+
+prompt to retag selected threads' tags
+
+
+.. index:: toggletags
+
+toggletags
+__________
+
+flip presence of tags on this thread.
+    A tag is considered present if at least one message contained in this
+    thread is tagged with it. In that case this command will remove the tag
+    from every message in the thread.
+    
+
+argument
+	comma separated list of tags
+
+optional arguments
+	:---no-flush: postpone a writeout to the index (Defaults to: 'True').
+
+.. index:: select
+
+select
+______
+
+open thread in a new buffer
+
+
diff --git a/docs/source/usage/modes/taglist.rst b/docs/source/usage/modes/taglist.rst
new file mode 100644
index 00000000..4272ccfa
--- /dev/null
+++ b/docs/source/usage/modes/taglist.rst
@@ -0,0 +1,12 @@
+taglist
+-------
+The following commands are available in taglist mode
+
+.. index:: select
+
+select
+______
+
+search for messages with selected tag
+
+
diff --git a/docs/source/usage/modes/thread.rst b/docs/source/usage/modes/thread.rst
new file mode 100644
index 00000000..41d58b52
--- /dev/null
+++ b/docs/source/usage/modes/thread.rst
@@ -0,0 +1,193 @@
+thread
+------
+The following commands are available in thread mode
+
+.. index:: pipeto
+
+pipeto
+______
+
+pipe message(s) to stdin of a shellcommand
+
+argument
+	shellcommand to pipe to
+
+optional arguments
+	:---all: pass all messages.
+	:---format: output format. Valid choices are: \`raw\`,\`decoded\`,\`id\`,\`filepath\` (Defaults to: 'raw').
+	:---separately: call command once for each message.
+	:---background: don't stop the interface.
+	:---add_tags: add 'Tags' header to the message.
+	:---shell: let the shell interpret the command.
+	:---notify_stdout: display command's stdout as notification message.
+
+.. index:: editnew
+
+editnew
+_______
+
+edit message in as new
+
+
+.. index:: toggleheaders
+
+toggleheaders
+_____________
+
+display all headers
+
+optional arguments
+	:---all: affect all messages.
+
+.. index:: print
+
+print
+_____
+
+print message(s)
+
+optional arguments
+	:---all: print all messages.
+	:---raw: pass raw mail string.
+	:---separately: call print command once for each message.
+	:---add_tags: add 'Tags' header to the message.
+
+.. index:: remove
+
+remove
+______
+
+remove message(s) from the index
+
+optional arguments
+	:---all: remove whole thread.
+
+.. index:: togglesource
+
+togglesource
+____________
+
+display message source
+
+optional arguments
+	:---all: affect all messages.
+
+.. index:: retag
+
+retag
+_____
+
+set message(s) tags.
+
+argument
+	comma separated list of tags
+
+optional arguments
+	:---all: tag all messages in thread.
+	:---no-flush: postpone a writeout to the index (Defaults to: 'True').
+
+.. index:: fold
+
+fold
+____
+
+fold message(s)
+
+optional arguments
+	:---all: fold all messages.
+
+.. index:: tag
+
+tag
+___
+
+add tags to message(s)
+
+argument
+	comma separated list of tags
+
+optional arguments
+	:---all: tag all messages in thread.
+	:---no-flush: postpone a writeout to the index (Defaults to: 'True').
+
+.. index:: untag
+
+untag
+_____
+
+remove tags from message(s)
+
+argument
+	comma separated list of tags
+
+optional arguments
+	:---all: tag all messages in thread.
+	:---no-flush: postpone a writeout to the index (Defaults to: 'True').
+
+.. index:: unfold
+
+unfold
+______
+
+unfold message(s)
+
+optional arguments
+	:---all: unfold all messages.
+
+.. index:: forward
+
+forward
+_______
+
+forward message
+
+optional arguments
+	:---attach: attach original mail.
+
+.. index:: reply
+
+reply
+_____
+
+reply to message
+
+optional arguments
+	:---all: reply to all.
+
+.. index:: save
+
+save
+____
+
+save attachment(s)
+
+argument
+	path to save to
+
+optional arguments
+	:---all: save all attachments.
+
+.. index:: toggletags
+
+toggletags
+__________
+
+flip presence of tags on message(s)
+
+argument
+	comma separated list of tags
+
+optional arguments
+	:---all: tag all messages in thread.
+	:---no-flush: postpone a writeout to the index (Defaults to: 'True').
+
+.. index:: select
+
+select
+______
+
+select focussed element. The fired action depends on the focus:
+        - if message summary, this toggles visibility of the message,
+        - if attachment line, this opens the attachment
+
+
diff --git a/docs/source/usage/synopsis.rst b/docs/source/usage/synopsis.rst
new file mode 100644
index 00000000..c18bfa03
--- /dev/null
+++ b/docs/source/usage/synopsis.rst
@@ -0,0 +1,31 @@
+.. 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)
+    -C, --colour-mode=COLOR        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
+
+%    .. option:: -m <module>, --module <module>
+%
+%       Run a module as a script.
+%
+
+
+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