Capitalize option and command descriptions consistently

10 files changed, 99 insertions, 103 deletions

diff --git a/docs/source/generate_commands.py b/docs/source/generate_commands.py
index c707615a..d2f61003 100755
--- a/docs/source/generate_commands.py
+++ b/docs/source/generate_commands.py
@@ -53,20 +53,20 @@ def rstify_parser(parser):
         a = parser._positionals._group_actions[0]
         out += ' '*8 + str(parser._positionals._group_actions[0].help)
         if a.choices:
-            out += ". valid choices are: %s." % ','.join(['\`%s\`' % s for s
-                                                          in a.choices])
+            out += "; valid choices are: %s" % ','.join(['\`%s\`' % s for s
+                                                         in a.choices])
         if a.default:
-            out += ". defaults to: '%s'." % a.default
+            out += " (defaults to: '%s')" % a.default
         out += '\n\n'
     elif len(parser._positionals._group_actions) > 1:
         out += "    positional arguments\n"
         for index, a in enumerate(parser._positionals._group_actions):
             out += "        %s: %s" % (index, a.help)
             if a.choices:
-                out += ". valid choices are: %s." % ','.join(
+                out += "; valid choices are: %s" % ','.join(
                     ['\`%s\`' % s for s in a.choices])
             if a.default:
-                out += ". defaults to: '%s'." % a.default
+                out += " (defaults to: '%s')" % a.default
             out += '\n'
         out += '\n\n'
 
@@ -76,11 +76,11 @@ def rstify_parser(parser):
         switches = [s.replace('--', '---') for s in a.option_strings]
         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
+            out += "; valid choices are: %s" % ','.join(['\`%s\`' % s for s
                                                          in a.choices])
         if a.default:
-            out += " (Defaults to: '%s')" % a.default
-        out += '.\n'
+            out += " (defaults to: '%s')" % a.default
+        out += '\n'
     out += '\n'
 
     return out
@@ -107,12 +107,13 @@ if __name__ == "__main__":
             modes.append(mode)
             header = 'Commands in `%s` mode' % mode
             modefile.write('%s\n%s\n' % (header, '-' * len(header)))
-            modefile.write('The following commands are available in %s mode'
+            modefile.write('The following commands are available in %s mode:'
                            '\n\n' % mode)
         else:
-            header = 'Global Commands'
+            header = 'Global commands'
             modefile.write('%s\n%s\n' % (header, '-' * len(header)))
-            modefile.write('The following commands are available globally\n\n')
+            modefile.write('The following commands are available globally:'
+                           '\n\n')
         for cmdstring, struct in sorted(modecommands.items()):
             cls, parser, forced_args = struct
             labelline = '.. _cmd.%s.%s:\n\n' % (mode, cmdstring.replace('_',
diff --git a/docs/source/usage/cli_commands.rst b/docs/source/usage/cli_commands.rst
index fdd9efc5..c8cedef5 100644
--- a/docs/source/usage/cli_commands.rst
+++ b/docs/source/usage/cli_commands.rst
@@ -1,6 +1,6 @@
 search
     start in a search buffer using the querystring provided as
-    parameter. See also :manpage:`notmuch-search-terms(7)`.
+    parameter (see :manpage:`notmuch-search-terms(7)`)
 
 compose
     compose a new message
diff --git a/docs/source/usage/cli_options.rst b/docs/source/usage/cli_options.rst
index d41d7a17..342c8f46 100644
--- a/docs/source/usage/cli_options.rst
+++ b/docs/source/usage/cli_options.rst
@@ -4,13 +4,13 @@
 -n FILENAME, --notmuch-config=FILENAME
                  notmuch config (default: $NOTMUCH_CONFIG or ~/.notmuch-config)
 -C COLOUR, --colour-mode=COLOUR
-                 terminal colour. Must be 1, 16 or 256
+                 terminal colour; must be 1, 16 or 256
 -p PATH, --mailindex-path=PATH
                  path to notmuch index
 -d LEVEL, --debug-level=LEVEL
-                 debug level (default: info). Must be one of debug, info,
-                 warning or error
+                 debug level; must be one of debug, info, warning or error
+                 (default: info)
 -l FILENAME, --logfile=FILENAME
                  logfile (default: /dev/null)
--v, --version    Display version string and exit
--h, --help       Display help and exit
+-v, --version    display version string and exit
+-h, --help       display help and exit
diff --git a/docs/source/usage/modes/bufferlist.rst b/docs/source/usage/modes/bufferlist.rst
index 7de661e9..673856a3 100644
--- a/docs/source/usage/modes/bufferlist.rst
+++ b/docs/source/usage/modes/bufferlist.rst
@@ -3,7 +3,7 @@
 
 Commands in `bufferlist` mode
 -----------------------------
-The following commands are available in bufferlist mode
+The following commands are available in bufferlist mode:
 
 .. _cmd.bufferlist.close:
 
diff --git a/docs/source/usage/modes/envelope.rst b/docs/source/usage/modes/envelope.rst
index ee857cc4..f003503a 100644
--- a/docs/source/usage/modes/envelope.rst
+++ b/docs/source/usage/modes/envelope.rst
@@ -3,7 +3,7 @@
 
 Commands in `envelope` mode
 ---------------------------
-The following commands are available in envelope mode
+The following commands are available in envelope mode:
 
 .. _cmd.envelope.attach:
 
@@ -22,8 +22,8 @@ The following commands are available in envelope mode
     edit mail
 
     optional arguments
-        :---spawn: spawn editor in new terminal.
-        :---refocus: refocus envelope after editing (Defaults to: 'True').
+        :---spawn: spawn editor in new terminal
+        :---refocus: refocus envelope after editing (defaults to: 'True')
 
 .. _cmd.envelope.encrypt:
 
@@ -35,7 +35,7 @@ The following commands are available in envelope mode
         keyid of the key to encrypt with
 
     optional arguments
-        :---trusted: only add trusted keys.
+        :---trusted: only add trusted keys
 
 .. _cmd.envelope.refine:
 
@@ -51,7 +51,7 @@ The following commands are available in envelope mode
 
 .. describe:: retag
 
-    set message tags.
+    set message tags
 
     argument
         comma separated list of tags
@@ -93,7 +93,7 @@ The following commands are available in envelope mode
 
 
     optional arguments
-        :---append: keep previous values.
+        :---append: keep previous values
 
 .. _cmd.envelope.sign:
 
@@ -125,7 +125,7 @@ The following commands are available in envelope mode
         keyid of the key to encrypt with
 
     optional arguments
-        :---trusted: only add trusted keys.
+        :---trusted: only add trusted keys
 
 .. _cmd.envelope.toggleheaders:
 
diff --git a/docs/source/usage/modes/global.rst b/docs/source/usage/modes/global.rst
index 1831a6cb..3a93090e 100644
--- a/docs/source/usage/modes/global.rst
+++ b/docs/source/usage/modes/global.rst
@@ -1,9 +1,9 @@
 .. CAUTION: THIS FILE IS AUTO-GENERATED!
 
 
-Global Commands
+Global commands
 ---------------
-The following commands are available globally
+The following commands are available globally:
 
 .. _cmd.global.bclose:
 
@@ -12,8 +12,8 @@ The following commands are available globally
     close a buffer
 
     optional arguments
-        :---redraw: redraw current buffer after command has finished.
-        :---force: never ask for confirmation.
+        :---redraw: redraw current buffer after command has finished
+        :---force: never ask for confirmation
 
 .. _cmd.global.bnext:
 
@@ -50,7 +50,7 @@ The following commands are available globally
 
 .. describe:: call
 
-    Executes python code
+    execute python code
 
     argument
         python command string to call
@@ -66,27 +66,22 @@ The following commands are available globally
         None
 
     optional arguments
-        :---sender: sender.
-        :---template: path to a template message file.
-        :---tags: comma-separated list of tags to apply to message.
-        :---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.
+        :---sender: sender
+        :---template: path to a template message file
+        :---tags: comma-separated list of tags to apply to message
+        :---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.exit:
 
 .. describe:: exit
 
-    Shut down cleanly.
-
-    The _prompt variable is for internal use only, it's used to control
-    prompting to close without sending, and is used by the BufferCloseCommand
-    if settings change after yielding to the UI.
-    
+    shut down cleanly
 
 
 .. _cmd.global.flush:
@@ -100,8 +95,8 @@ The following commands are available globally
 
 .. describe:: help
 
-    display help for a command. Use 'bindings' to display all keybings
-    interpreted in current mode.'
+    display help for a command (use 'bindings' to display all keybindings
+    interpreted in current mode)
 
     argument
         command or 'bindings'
@@ -152,7 +147,7 @@ The following commands are available globally
 
 .. describe:: reload
 
-    Reload all configuration files
+    reload all configuration files
 
 
 .. _cmd.global.removequery:
@@ -165,13 +160,13 @@ The following commands are available globally
         alias to remove
 
     optional arguments
-        :---no-flush: postpone a writeout to the index (Defaults to: 'True').
+        :---no-flush: postpone a writeout to the index (defaults to: 'True')
 
 .. _cmd.global.repeat:
 
 .. describe:: repeat
 
-    Repeats the command executed last time
+    repeat the command executed last time
 
 
 .. _cmd.global.savequery:
@@ -186,7 +181,7 @@ The following commands are available globally
 
 
     optional arguments
-        :---no-flush: postpone a writeout to the index (Defaults to: 'True').
+        :---no-flush: postpone a writeout to the index (defaults to: 'True')
 
 .. _cmd.global.search:
 
@@ -199,7 +194,7 @@ The following commands are available globally
         search string
 
     optional arguments
-        :---sort: sort order. Valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
+        :---sort: sort order; valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`
 
 .. _cmd.global.shellescape:
 
@@ -211,9 +206,9 @@ The following commands are available globally
         command line to execute
 
     optional arguments
-        :---spawn: run in terminal window.
-        :---thread: run in separate thread.
-        :---refocus: refocus current buffer after command has finished.
+        :---spawn: run in terminal window
+        :---thread: run in separate thread
+        :---refocus: refocus current buffer after command has finished
 
 .. _cmd.global.taglist:
 
@@ -222,5 +217,5 @@ The following commands are available globally
     opens taglist buffer
 
     optional arguments
-        :---tags: tags to display.
+        :---tags: tags to display
 
diff --git a/docs/source/usage/modes/namedqueries.rst b/docs/source/usage/modes/namedqueries.rst
index ee0217a4..b3aec3fe 100644
--- a/docs/source/usage/modes/namedqueries.rst
+++ b/docs/source/usage/modes/namedqueries.rst
@@ -3,7 +3,7 @@
 
 Commands in `namedqueries` mode
 -------------------------------
-The following commands are available in namedqueries mode
+The following commands are available in namedqueries mode:
 
 .. _cmd.namedqueries.select:
 
diff --git a/docs/source/usage/modes/search.rst b/docs/source/usage/modes/search.rst
index 43872eec..df6a15ef 100644
--- a/docs/source/usage/modes/search.rst
+++ b/docs/source/usage/modes/search.rst
@@ -3,7 +3,7 @@
 
 Commands in `search` mode
 -------------------------
-The following commands are available in search mode
+The following commands are available in search mode:
 
 .. _cmd.search.move:
 
@@ -25,7 +25,7 @@ The following commands are available in search mode
         search string
 
     optional arguments
-        :---sort: sort order. Valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
+        :---sort: sort order; valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`
 
 .. _cmd.search.refineprompt:
 
@@ -44,8 +44,8 @@ The following commands are available in search mode
         comma separated list of tags
 
     optional arguments
-        :---no-flush: postpone a writeout to the index (Defaults to: 'True').
-        :---all: retag all messages in search result.
+        :---no-flush: postpone a writeout to the index (defaults to: 'True')
+        :---all: retag all messages in search result
 
 .. _cmd.search.retagprompt:
 
@@ -66,7 +66,7 @@ The following commands are available in search mode
 
 
     optional arguments
-        :---no-flush: postpone a writeout to the index (Defaults to: 'True').
+        :---no-flush: postpone a writeout to the index (defaults to: 'True')
 
 .. _cmd.search.select:
 
@@ -82,7 +82,7 @@ The following commands are available in search mode
     set sort order
 
     argument
-        sort order. valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
+        sort order; valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`
 
 
 .. _cmd.search.tag:
@@ -95,20 +95,20 @@ The following commands are available in search mode
         comma separated list of tags
 
     optional arguments
-        :---no-flush: postpone a writeout to the index (Defaults to: 'True').
-        :---all: retag all messages in search result.
+        :---no-flush: postpone a writeout to the index (defaults to: 'True')
+        :---all: retag all messages in search result
 
 .. _cmd.search.toggletags:
 
 .. describe:: 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.
+    flip presence of tags on this thread: a tag is considered present and will be removed if at least one message in this thread is tagged with it
 
     argument
         comma separated list of tags
 
     optional arguments
-        :---no-flush: postpone a writeout to the index (Defaults to: 'True').
+        :---no-flush: postpone a writeout to the index (defaults to: 'True')
 
 .. _cmd.search.untag:
 
@@ -120,6 +120,6 @@ The following commands are available in search mode
         comma separated list of tags
 
     optional arguments
-        :---no-flush: postpone a writeout to the index (Defaults to: 'True').
-        :---all: retag all messages in search result.
+        :---no-flush: postpone a writeout to the index (defaults to: 'True')
+        :---all: retag all messages in search result
 
diff --git a/docs/source/usage/modes/taglist.rst b/docs/source/usage/modes/taglist.rst
index a22f7c2e..83400bbb 100644
--- a/docs/source/usage/modes/taglist.rst
+++ b/docs/source/usage/modes/taglist.rst
@@ -3,7 +3,7 @@
 
 Commands in `taglist` mode
 --------------------------
-The following commands are available in taglist mode
+The following commands are available in taglist mode:
 
 .. _cmd.taglist.select:
 
diff --git a/docs/source/usage/modes/thread.rst b/docs/source/usage/modes/thread.rst
index 1520e3cc..5fe5686f 100644
--- a/docs/source/usage/modes/thread.rst
+++ b/docs/source/usage/modes/thread.rst
@@ -3,7 +3,7 @@
 
 Commands in `thread` mode
 -------------------------
-The following commands are available in thread mode
+The following commands are available in thread mode:
 
 .. _cmd.thread.bounce:
 
@@ -19,7 +19,7 @@ The following commands are available in thread mode
     edit message in as new
 
     optional arguments
-        :---spawn: open editor in new window.
+        :---spawn: open editor in new window
 
 .. _cmd.thread.fold:
 
@@ -38,8 +38,8 @@ The following commands are available in thread mode
     forward message
 
     optional arguments
-        :---attach: attach original mail.
-        :---spawn: open editor in new window.
+        :---attach: attach original mail
+        :---spawn: open editor in new window
 
 .. _cmd.thread.indent:
 
@@ -71,14 +71,14 @@ The following commands are available in thread mode
         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 cmd's stdout as notification.
-        :---field_key: mailcap field key for decoding (Defaults to: 'copiousoutput').
+        :---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 cmd's stdout as notification
+        :---field_key: mailcap field key for decoding (defaults to: 'copiousoutput')
 
 .. _cmd.thread.print:
 
@@ -87,10 +87,10 @@ The following commands are available in thread mode
     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.
+        :---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:
 
@@ -99,7 +99,7 @@ The following commands are available in thread mode
     remove message(s) from the index
 
     optional arguments
-        :---all: remove whole thread.
+        :---all: remove whole thread
 
 .. _cmd.thread.reply:
 
@@ -108,9 +108,9 @@ The following commands are available in thread mode
     reply to message
 
     optional arguments
-        :---all: reply to all.
-        :---list: reply to list.
-        :---spawn: open editor in new window.
+        :---all: reply to all
+        :---list: reply to list
+        :---spawn: open editor in new window
 
 .. _cmd.thread.retag:
 
@@ -122,8 +122,8 @@ The following commands are available in thread mode
         comma separated list of tags
 
     optional arguments
-        :---all: tag all messages in thread.
-        :---no-flush: postpone a writeout to the index (Defaults to: 'True').
+        :---all: tag all messages in thread
+        :---no-flush: postpone a writeout to the index (defaults to: 'True')
 
 .. _cmd.thread.retagprompt:
 
@@ -142,15 +142,15 @@ The following commands are available in thread mode
         path to save to
 
     optional arguments
-        :---all: save all attachments.
+        :---all: save all attachments
 
 .. _cmd.thread.select:
 
 .. describe:: 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
+    select focussed element:
+        - if it is a message summary, toggle visibility of the message;
+        - if it is an attachment line, open the attachment
 
 
 .. _cmd.thread.tag:
@@ -163,8 +163,8 @@ The following commands are available in thread mode
         comma separated list of tags
 
     optional arguments
-        :---all: tag all messages in thread.
-        :---no-flush: postpone a writeout to the index (Defaults to: 'True').
+        :---all: tag all messages in thread
+        :---no-flush: postpone a writeout to the index (defaults to: 'True')
 
 .. _cmd.thread.toggleheaders:
 
@@ -196,8 +196,8 @@ The following commands are available in thread mode
         comma separated list of tags
 
     optional arguments
-        :---all: tag all messages in thread.
-        :---no-flush: postpone a writeout to the index (Defaults to: 'True').
+        :---all: tag all messages in thread
+        :---no-flush: postpone a writeout to the index (defaults to: 'True')
 
 .. _cmd.thread.unfold:
 
@@ -219,6 +219,6 @@ The following commands are available in thread mode
         comma separated list of tags
 
     optional arguments
-        :---all: tag all messages in thread.
-        :---no-flush: postpone a writeout to the index (Defaults to: 'True').
+        :---all: tag all messages in thread
+        :---no-flush: postpone a writeout to the index (defaults to: 'True')