summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorPatrick Totzke <patricktotzke@gmail.com>2012-07-25 07:42:17 +0100
committerPatrick Totzke <patricktotzke@gmail.com>2012-07-25 07:43:11 +0100
commit3125495f01e635465143497b1967998318f32af9 (patch)
tree96c005d02798dcbf3919955cda4bdc48450ee0e5 /docs
parentb1ff38a0a0153fde32b2d4fa666313e89436fb46 (diff)
doc: describe commands instead of using subsections
Diffstat (limited to 'docs')
-rwxr-xr-xdocs/source/generate_commands.py22
-rw-r--r--docs/source/usage/modes/bufferlist.rst16
-rw-r--r--docs/source/usage/modes/envelope.rst124
-rw-r--r--docs/source/usage/modes/global.rst200
-rw-r--r--docs/source/usage/modes/search.rst116
-rw-r--r--docs/source/usage/modes/taglist.rst8
-rw-r--r--docs/source/usage/modes/thread.rst242
7 files changed, 306 insertions, 422 deletions
diff --git a/docs/source/generate_commands.py b/docs/source/generate_commands.py
index eb241d10..b7a175de 100755
--- a/docs/source/generate_commands.py
+++ b/docs/source/generate_commands.py
@@ -49,19 +49,16 @@ def rstify_parser(parser):
usage = usage.replace('--','---')
# section header
- out += '.. index:: %s\n' % parser.prog
- out +='\n%s\n' % parser.prog
- out += '_'*len(parser.prog)
- out += '\n\n'
+ out += '.. describe:: %s\n\n' % parser.prog
# description
- out += parser.description
+ out += ' '*4 + parser.description
out += '\n\n'
if len(parser._positionals._group_actions) == 1:
- out += "argument\n"
+ out += " argument\n"
a = parser._positionals._group_actions[0]
- out += "\t%s" % parser._positionals._group_actions[0].help
+ out += ' '*8 + parser._positionals._group_actions[0].help
if a.choices:
out += ". valid choices are: %s." % ','.join(['\`%s\`' % s for s
in a.choices])
@@ -69,9 +66,9 @@ def rstify_parser(parser):
out += ". defaults to: '%s'." % a.default
out += '\n\n'
elif len(parser._positionals._group_actions) > 1:
- out += "positional arguments\n"
+ out += " positional arguments\n"
for index, a in enumerate(parser._positionals._group_actions):
- out += "\t:%s: %s" % (index, a.help)
+ out += " %s: %s" % (index, a.help)
if a.choices:
out += ". valid choices are: %s." % ','.join(['\`%s\`' % s for s
in a.choices])
@@ -81,10 +78,10 @@ def rstify_parser(parser):
out += '\n\n'
if parser._optionals._group_actions:
- out += "optional arguments\n"
+ out += " optional arguments\n"
for a in parser._optionals._group_actions:
switches = [s.replace('--','---') for s in a.option_strings]
- out += "\t:%s: %s" % (', '.join(switches), a.help)
+ out += " :%s: %s" % (', '.join(switches), a.help)
if a.choices and not isinstance(a, BooleanAction):
out += ". Valid choices are: %s" % ','.join(['\`%s\`' % s for s
in a.choices])
@@ -123,7 +120,8 @@ if __name__ == "__main__":
modefile.write('The following commands are available globally\n\n')
for cmdstring,struct in modecommands.items():
cls, parser, forced_args = struct
- labelline = '.. _cmd_%s_%s:\n' % (mode, cmdstring)
+ labelline = '.. _cmd.%s.%s:\n\n' % (mode, cmdstring.replace('_',
+ '-'))
modefile.write(labelline)
modefile.write(rstify_parser(parser))
modefile.close()
diff --git a/docs/source/usage/modes/bufferlist.rst b/docs/source/usage/modes/bufferlist.rst
index 3028916e..dc2d4dfc 100644
--- a/docs/source/usage/modes/bufferlist.rst
+++ b/docs/source/usage/modes/bufferlist.rst
@@ -5,21 +5,17 @@ bufferlist
----------
The following commands are available in bufferlist mode
-.. _cmd_bufferlist_close:
-.. index:: close
+.. _cmd.bufferlist.close:
-close
-_____
+.. describe:: close
-close focussed buffer
+ close focussed buffer
-.. _cmd_bufferlist_select:
-.. index:: select
+.. _cmd.bufferlist.select:
-select
-______
+.. describe:: select
-focus selected buffer
+ focus selected buffer
diff --git a/docs/source/usage/modes/envelope.rst b/docs/source/usage/modes/envelope.rst
index 3422e6e5..65b39c6a 100644
--- a/docs/source/usage/modes/envelope.rst
+++ b/docs/source/usage/modes/envelope.rst
@@ -5,127 +5,105 @@ envelope
--------
The following commands are available in envelope mode
-.. _cmd_envelope_set:
-.. index:: set
+.. _cmd.envelope.set:
-set
-___
+.. describe:: set
-set header value
+ set header value
-positional arguments
- :0: header to refine
- :1: value
+ positional arguments
+ 0: header to refine
+ 1: value
-optional arguments
- :---append: keep previous values.
+ optional arguments
+ :---append: keep previous values.
-.. _cmd_envelope_togglesign:
-.. index:: togglesign
+.. _cmd.envelope.togglesign:
-togglesign
-__________
+.. describe:: togglesign
-toggle sign status
+ toggle sign status
-argument
- which key id to use
+ argument
+ which key id to use
-.. _cmd_envelope_toggleheaders:
-.. index:: toggleheaders
+.. _cmd.envelope.toggleheaders:
-toggleheaders
-_____________
+.. describe:: toggleheaders
-toggle display of all headers
+ toggle display of all headers
-.. _cmd_envelope_edit:
-.. index:: edit
+.. _cmd.envelope.edit:
-edit
-____
+.. describe:: edit
-edit mail
+ edit mail
-optional arguments
- :---spawn: spawn editor in new terminal.
- :---refocus: refocus envelope after editing (Defaults to: 'True').
+ optional arguments
+ :---spawn: spawn editor in new terminal.
+ :---refocus: refocus envelope after editing (Defaults to: 'True').
-.. _cmd_envelope_send:
-.. index:: send
+.. _cmd.envelope.send:
-send
-____
+.. describe:: send
-send mail
+ send mail
-.. _cmd_envelope_sign:
-.. index:: sign
+.. _cmd.envelope.sign:
-sign
-____
+.. describe:: sign
-mark mail to be signed before sending
+ mark mail to be signed before sending
-argument
- which key id to use
+ argument
+ which key id to use
-.. _cmd_envelope_attach:
-.. index:: attach
+.. _cmd.envelope.attach:
-attach
-______
+.. describe:: attach
-attach files to the mail
+ attach files to the mail
-argument
- file(s) to attach (accepts wildcads)
+ argument
+ file(s) to attach (accepts wildcads)
-.. _cmd_envelope_refine:
-.. index:: refine
+.. _cmd.envelope.refine:
-refine
-______
+.. describe:: refine
-prompt to change the value of a header
+ prompt to change the value of a header
-argument
- header to refine
+ argument
+ header to refine
-.. _cmd_envelope_save:
-.. index:: save
+.. _cmd.envelope.save:
-save
-____
+.. describe:: save
-save draft
+ save draft
-.. _cmd_envelope_unsign:
-.. index:: unsign
+.. _cmd.envelope.unsign:
-unsign
-______
+.. describe:: unsign
-mark mail not to be signed before sending
+ mark mail not to be signed before sending
-.. _cmd_envelope_unset:
-.. index:: unset
+.. _cmd.envelope.unset:
-unset
-_____
+.. describe:: unset
-remove header field
+ remove header field
-argument
- header to refine
+ argument
+ header to refine
diff --git a/docs/source/usage/modes/global.rst b/docs/source/usage/modes/global.rst
index bc6f4a44..9b8f5307 100644
--- a/docs/source/usage/modes/global.rst
+++ b/docs/source/usage/modes/global.rst
@@ -5,202 +5,166 @@ global
------
The following commands are available globally
-.. _cmd_global_bclose:
-.. index:: bclose
+.. _cmd.global.bclose:
-bclose
-______
+.. describe:: bclose
-close a buffer
+ close a buffer
-.. _cmd_global_bprevious:
-.. index:: bprevious
+.. _cmd.global.bprevious:
-bprevious
-_________
+.. describe:: bprevious
-focus previous buffer
+ focus previous buffer
-.. _cmd_global_search:
-.. index:: search
+.. _cmd.global.search:
-search
-______
+.. describe:: search
-open a new search buffer
+ open a new search buffer
-argument
- search string
+ argument
+ search string
-optional arguments
- :---sort: sort order. Valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
+ optional arguments
+ :---sort: sort order. Valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
-.. _cmd_global_compose:
-.. index:: compose
+.. _cmd.global.compose:
-compose
-_______
+.. describe:: compose
-compose a new email
+ 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.
+ 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.
-.. _cmd_global_prompt:
-.. index:: prompt
+.. _cmd.global.prompt:
-prompt
-______
+.. describe:: prompt
-prompts for commandline and interprets it upon select
+ prompts for commandline and interprets it upon select
-argument
- initial content
+ argument
+ initial content
-.. _cmd_global_help:
-.. index:: help
-
-help
-____
+.. _cmd.global.help:
+.. describe:: help
+
display help for a command. Use 'bindings' to
display all keybings interpreted in current mode.'
-argument
- command or 'bindings'
+ argument
+ command or 'bindings'
-.. _cmd_global_move:
-.. index:: move
+.. _cmd.global.move:
-move
-____
+.. describe:: move
-move focus
+ move focus
-argument
- direction
+ argument
+ direction
-.. _cmd_global_shellescape:
-.. index:: shellescape
+.. _cmd.global.shellescape:
-shellescape
-___________
+.. describe:: shellescape
-run external command
+ run external command
-argument
- command line to execute
+ 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.
+ optional arguments
+ :---spawn: run in terminal window.
+ :---thread: run in separate thread.
+ :---refocus: refocus current buffer after command has finished.
-.. _cmd_global_refresh:
-.. index:: refresh
+.. _cmd.global.refresh:
-refresh
-_______
+.. describe:: refresh
-refresh the current buffer
+ refresh the current buffer
-.. _cmd_global_cancel:
-.. index:: cancel
+.. _cmd.global.cancel:
-cancel
-______
+.. describe:: cancel
-send cancel event
+ send cancel event
-.. _cmd_global_pyshell:
-.. index:: pyshell
+.. _cmd.global.pyshell:
-pyshell
-_______
+.. describe:: pyshell
-open an interactive python shell for introspection
+ open an interactive python shell for introspection
-.. _cmd_global_exit:
-.. index:: exit
+.. _cmd.global.exit:
-exit
-____
+.. describe:: exit
-shut down cleanly
+ shut down cleanly
-.. _cmd_global_flush:
-.. index:: flush
+.. _cmd.global.flush:
-flush
-_____
+.. describe:: flush
-flush write operations or retry until committed
+ flush write operations or retry until committed
-.. _cmd_global_bufferlist:
-.. index:: bufferlist
+.. _cmd.global.bufferlist:
-bufferlist
-__________
+.. describe:: bufferlist
-open a list of active buffers
+ open a list of active buffers
-.. _cmd_global_call:
-.. index:: call
+.. _cmd.global.call:
-call
-____
+.. describe:: call
- Executes python code
+ Executes python code
-argument
- python command string to call
+ argument
+ python command string to call
-.. _cmd_global_bnext:
-.. index:: bnext
+.. _cmd.global.bnext:
-bnext
-_____
+.. describe:: bnext
-focus next buffer
+ focus next buffer
-.. _cmd_global_select:
-.. index:: select
+.. _cmd.global.select:
-select
-______
+.. describe:: select
-send select event
+ send select event
-.. _cmd_global_taglist:
-.. index:: taglist
+.. _cmd.global.taglist:
-taglist
-_______
+.. describe:: taglist
-opens taglist buffer
+ opens taglist buffer
diff --git a/docs/source/usage/modes/search.rst b/docs/source/usage/modes/search.rst
index 16404cf4..73b158c2 100644
--- a/docs/source/usage/modes/search.rst
+++ b/docs/source/usage/modes/search.rst
@@ -5,116 +5,98 @@ search
------
The following commands are available in search mode
-.. _cmd_search_sort:
-.. index:: sort
+.. _cmd.search.sort:
-sort
-____
+.. describe:: sort
-set sort order
+ set sort order
-argument
- sort order. valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
+ argument
+ sort order. valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
-.. _cmd_search_untag:
-.. index:: untag
+.. _cmd.search.untag:
-untag
-_____
+.. describe:: untag
-remove tags from all messages in the thread
+ remove tags from all messages in the thread
-argument
- comma separated list of tags
+ argument
+ comma separated list of tags
-optional arguments
- :---no-flush: postpone a writeout to the index (Defaults to: 'True').
+ optional arguments
+ :---no-flush: postpone a writeout to the index (Defaults to: 'True').
-.. _cmd_search_retag:
-.. index:: retag
+.. _cmd.search.retag:
-retag
-_____
+.. describe:: retag
-set tags of all messages in the thread
+ set tags of all messages in the thread
-argument
- comma separated list of tags
+ argument
+ comma separated list of tags
-optional arguments
- :---no-flush: postpone a writeout to the index (Defaults to: 'True').
+ optional arguments
+ :---no-flush: postpone a writeout to the index (Defaults to: 'True').
-.. _cmd_search_refineprompt:
-.. index:: refineprompt
+.. _cmd.search.refineprompt:
-refineprompt
-____________
+.. describe:: refineprompt
-prompt to change this buffers querystring
+ prompt to change this buffers querystring
-.. _cmd_search_tag:
-.. index:: tag
+.. _cmd.search.tag:
-tag
-___
+.. describe:: tag
-add tags to all messages in the thread
+ add tags to all messages in the thread
-argument
- comma separated list of tags
+ argument
+ comma separated list of tags
-optional arguments
- :---no-flush: postpone a writeout to the index (Defaults to: 'True').
+ optional arguments
+ :---no-flush: postpone a writeout to the index (Defaults to: 'True').
-.. _cmd_search_refine:
-.. index:: refine
+.. _cmd.search.refine:
-refine
-______
+.. describe:: refine
-refine query
+ refine query
-argument
- search string
+ argument
+ search string
-optional arguments
- :---sort: sort order. Valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
+ optional arguments
+ :---sort: sort order. Valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
-.. _cmd_search_retagprompt:
-.. index:: retagprompt
+.. _cmd.search.retagprompt:
-retagprompt
-___________
+.. describe:: retagprompt
-prompt to retag selected threads' tags
+ prompt to retag selected threads' tags
-.. _cmd_search_toggletags:
-.. index:: toggletags
+.. _cmd.search.toggletags:
-toggletags
-__________
+.. describe:: toggletags
-flip presence of tags on this thread.
+ 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
+ argument
+ comma separated list of tags
-optional arguments
- :---no-flush: postpone a writeout to the index (Defaults to: 'True').
+ optional arguments
+ :---no-flush: postpone a writeout to the index (Defaults to: 'True').
-.. _cmd_search_select:
-.. index:: select
+.. _cmd.search.select:
-select
-______
+.. describe:: select
-open thread in a new buffer
+ open thread in a new buffer
diff --git a/docs/source/usage/modes/taglist.rst b/docs/source/usage/modes/taglist.rst
index c6f7198b..995e75e5 100644
--- a/docs/source/usage/modes/taglist.rst
+++ b/docs/source/usage/modes/taglist.rst
@@ -5,12 +5,10 @@ taglist
-------
The following commands are available in taglist mode
-.. _cmd_taglist_select:
-.. index:: select
+.. _cmd.taglist.select:
-select
-______
+.. describe:: select
-search for messages with selected tag
+ search for messages with selected tag
diff --git a/docs/source/usage/modes/thread.rst b/docs/source/usage/modes/thread.rst
index 096d7c20..b60215d7 100644
--- a/docs/source/usage/modes/thread.rst
+++ b/docs/source/usage/modes/thread.rst
@@ -5,211 +5,179 @@ thread
------
The following commands are available in thread mode
-.. _cmd_thread_pipeto:
-.. index:: pipeto
+.. _cmd.thread.pipeto:
-pipeto
-______
+.. describe:: pipeto
-pipe message(s) to stdin of a shellcommand
+ pipe message(s) to stdin of a shellcommand
-argument
- shellcommand to pipe to
+ 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.
+ 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.
-.. _cmd_thread_editnew:
-.. index:: editnew
+.. _cmd.thread.editnew:
-editnew
-_______
+.. describe:: editnew
-edit message in as new
+ edit message in as new
-optional arguments
- :---spawn: open editor in new window.
+ optional arguments
+ :---spawn: open editor in new window.
-.. _cmd_thread_toggleheaders:
-.. index:: toggleheaders
+.. _cmd.thread.toggleheaders:
-toggleheaders
-_____________
+.. describe:: toggleheaders
-display all headers
+ display all headers
-optional arguments
- :---all: affect all messages.
+ optional arguments
+ :---all: affect all messages.
-.. _cmd_thread_print:
-.. index:: print
+.. _cmd.thread.print:
-print
-_____
+.. describe:: print
-print message(s)
+ 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.
+ 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.
-.. _cmd_thread_remove:
-.. index:: remove
+.. _cmd.thread.remove:
-remove
-______
+.. describe:: remove
-remove message(s) from the index
+ remove message(s) from the index
-optional arguments
- :---all: remove whole thread.
+ optional arguments
+ :---all: remove whole thread.
-.. _cmd_thread_togglesource:
-.. index:: togglesource
+.. _cmd.thread.togglesource:
-togglesource
-____________
+.. describe:: togglesource
-display message source
+ display message source
-optional arguments
- :---all: affect all messages.
+ optional arguments
+ :---all: affect all messages.
-.. _cmd_thread_retag:
-.. index:: retag
+.. _cmd.thread.retag:
-retag
-_____
+.. describe:: retag
-set message(s) tags.
+ set message(s) tags.
-argument
- comma separated list of 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').
+ optional arguments
+ :---all: tag all messages in thread.
+ :---no-flush: postpone a writeout to the index (Defaults to: 'True').
-.. _cmd_thread_fold:
-.. index:: fold
+.. _cmd.thread.fold:
-fold
-____
+.. describe:: fold
-fold message(s)
+ fold message(s)
-optional arguments
- :---all: fold all messages.
+ optional arguments
+ :---all: fold all messages.
-.. _cmd_thread_tag:
-.. index:: tag
+.. _cmd.thread.tag:
-tag
-___
+.. describe:: tag
-add tags to message(s)
+ add tags to message(s)
-argument
- comma separated list of 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').
+ optional arguments
+ :---all: tag all messages in thread.
+ :---no-flush: postpone a writeout to the index (Defaults to: 'True').
-.. _cmd_thread_untag:
-.. index:: untag
+.. _cmd.thread.untag:
-untag
-_____
+.. describe:: untag
-remove tags from message(s)
+ remove tags from message(s)
-argument
- comma separated list of 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').
+ optional arguments
+ :---all: tag all messages in thread.
+ :---no-flush: postpone a writeout to the index (Defaults to: 'True').
-.. _cmd_thread_unfold:
-.. index:: unfold
+.. _cmd.thread.unfold:
-unfold
-______
+.. describe:: unfold
-unfold message(s)
+ unfold message(s)
-optional arguments
- :---all: unfold all messages.
+ optional arguments
+ :---all: unfold all messages.
-.. _cmd_thread_forward:
-.. index:: forward
+.. _cmd.thread.forward:
-forward
-_______
+.. describe:: forward
-forward message
+ forward message
-optional arguments
- :---attach: attach original mail.
- :---spawn: open editor in new window.
+ optional arguments
+ :---attach: attach original mail.
+ :---spawn: open editor in new window.
-.. _cmd_thread_reply:
-.. index:: reply
+.. _cmd.thread.reply:
-reply
-_____
+.. describe:: reply
-reply to message
+ reply to message
-optional arguments
- :---all: reply to all.
- :---spawn: open editor in new window.
+ optional arguments
+ :---all: reply to all.
+ :---spawn: open editor in new window.
-.. _cmd_thread_save:
-.. index:: save
+.. _cmd.thread.save:
-save
-____
+.. describe:: save
-save attachment(s)
+ save attachment(s)
-argument
- path to save to
+ argument
+ path to save to
-optional arguments
- :---all: save all attachments.
+ optional arguments
+ :---all: save all attachments.
-.. _cmd_thread_toggletags:
-.. index:: toggletags
+.. _cmd.thread.toggletags:
-toggletags
-__________
+.. describe:: toggletags
-flip presence of tags on message(s)
+ flip presence of tags on message(s)
-argument
- comma separated list of 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').
+ optional arguments
+ :---all: tag all messages in thread.
+ :---no-flush: postpone a writeout to the index (Defaults to: 'True').
-.. _cmd_thread_select:
-.. index:: select
+.. _cmd.thread.select:
-select
-______
+.. describe:: select
-select focussed element. The fired action depends on the focus:
+ 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