Merge pull request #1276 from alexshpilkin/copyedit

Copyedit documentation

alot/__main__.py

@@ -23,35 +23,40 @@
 
 def parser():
     """Parse command line arguments, validate them, and return them."""
-    parser = argparse.ArgumentParser()
-    parser.add_argument('-v', '--version', action='version',
-                        version=alot.__version__)
+    parser = argparse.ArgumentParser(add_help=False)
     parser.add_argument('-r', '--read-only', action='store_true',
-                        help='open db in read only mode')
-    parser.add_argument('-c', '--config',
+                        help='open notmuch database in read-only mode')
+    parser.add_argument('-c', '--config', metavar='FILENAME',
                         action=cargparse.ValidatedStoreAction,
                         validator=cargparse.require_file,
-                        help='config file')
-    parser.add_argument('-n', '--notmuch-config', default=os.environ.get(
+                        help='configuration file')
+    parser.add_argument('-n', '--notmuch-config', metavar='FILENAME',
+                        default=os.environ.get(
                             'NOTMUCH_CONFIG',
                             os.path.expanduser('~/.notmuch-config')),
                         action=cargparse.ValidatedStoreAction,
                         validator=cargparse.require_file,
-                        help='notmuch config')
-    parser.add_argument('-C', '--colour-mode',
+                        help='notmuch configuration file')
+    parser.add_argument('-C', '--colour-mode', metavar='COLOURS',
                         choices=(1, 16, 256), type=int,
-                        help='terminal colour mode')
-    parser.add_argument('-p', '--mailindex-path',
+                        help='number of colours to use')
+    parser.add_argument('-p', '--mailindex-path', metavar='PATH',
                         action=cargparse.ValidatedStoreAction,
                         validator=cargparse.require_dir,
                         help='path to notmuch index')
-    parser.add_argument('-d', '--debug-level', default='info',
+    parser.add_argument('-d', '--debug-level', metavar='LEVEL', default='info',
                         choices=('debug', 'info', 'warning', 'error'),
-                        help='debug log [default: %(default)s]')
-    parser.add_argument('-l', '--logfile', default='/dev/null',
+                        help='debug level [default: %(default)s]')
+    parser.add_argument('-l', '--logfile', metavar='FILENAME',
+                        default='/dev/null',
                         action=cargparse.ValidatedStoreAction,
                         validator=cargparse.optional_file_like,
-                        help='logfile [default: %(default)s]')
+                        help='log file [default: %(default)s]')
+    parser.add_argument('-h', '--help', action='help',
+                        help='display this help and exit')
+    parser.add_argument('-v', '--version', action='version',
+                        version=alot.__version__,
+                        help='output version information and exit')
     # We will handle the subcommands in a separate run of argparse as argparse
     # does not support optional subcommands until now.
     parser.add_argument('command', nargs=argparse.REMAINDER,

alot/commands/envelope.py

@@ -621,7 +621,7 @@ def apply(self, ui):
 @registerCommand(
     MODE, 'retag', forced={'action': 'set'},
     arguments=[(['tags'], {'help': 'comma separated list of tags'})],
-    help='set message tags.',
+    help='set message tags',
 )
 @registerCommand(
     MODE, 'untag', forced={'action': 'remove'},

alot/commands/globals.py

@@ -38,16 +38,18 @@
 MODE = 'global'
 
 
-@registerCommand(MODE, 'exit')
+@registerCommand(MODE, 'exit', help="shut down cleanly")
 class ExitCommand(Command):
-    """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."""
 
     def __init__(self, _prompt=True, **kwargs):
+        """
+        :param _prompt: For internal use only, used to control prompting to
+                        close without sending, and is used by the
+                        BufferCloseCommand if settings change after yielding to
+                        the UI.
+        :type _prompt: bool
+        """
         super(ExitCommand, self).__init__(**kwargs)
         self.prompt_to_send = _prompt
 
@@ -352,7 +354,7 @@ def apply(self, ui):
 @registerCommand(MODE, 'repeat')
 class RepeatCommand(Command):
 
-    """Repeats the command executed last time"""
+    """repeat the command executed last time"""
     def __init__(self, **kwargs):
         Command.__init__(self, **kwargs)
 
@@ -367,7 +369,7 @@ def apply(self, ui):
     (['command'], {'help': 'python command string to call'})])
 class CallCommand(Command):
 
-    """Executes python code"""
+    """execute python code"""
     repeatable = True
 
     def __init__(self, command, **kwargs):
@@ -616,8 +618,8 @@ def f(*_):
     (['commandname'], {'help': 'command or \'bindings\''})])
 class HelpCommand(Command):
 
-    """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)"""
     def __init__(self, commandname='', **kwargs):
         """
         :param commandname: command to document
@@ -984,7 +986,7 @@ def apply(self, ui):
                       priority='error')
 
 
-@registerCommand(MODE, 'reload', help='Reload all configuration files')
+@registerCommand(MODE, 'reload', help='reload all configuration files')
 class ReloadCommand(Command):
 
     """Reload configuration."""

alot/commands/search.py

@@ -136,10 +136,9 @@ def apply(self, ui):
                           'default': 'True',
                           'help': 'postpone a writeout to the index'}),
         (['tags'], {'help': 'comma separated list of tags'})],
-    help='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.')
+    help='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')
 class TagCommand(Command):
 
     """manipulate message tags"""

alot/commands/thread.py

@@ -1069,9 +1069,9 @@ def apply(self, ui):
 @registerCommand(MODE, 'select')
 class ThreadSelectCommand(Command):
 
-    """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"""
     def apply(self, ui):
         focus = ui.get_deep_focus()
         if isinstance(focus, AttachmentWidget):

alot/defaults/alot.rc.spec

@@ -23,7 +23,7 @@ bug_on_exit = boolean(default=False)
 # offset of next focused buffer if the current one gets closed
 bufferclose_focus_offset = integer(default=-1)
 
-# number of colours to use
+# number of colours to use on the terminal
 colourmode = option(1, 16, 256, default=256)
 
 # number of spaces used to replace tab characters

docs/source/configuration/alotrc_table

@@ -105,7 +105,7 @@
 
 .. describe:: colourmode
 
-     number of colours to use
+     number of colours to use on the terminal
 
     :type: option, one of ['1', '16', '256']
     :default: 256

docs/source/configuration/config_options.rst

@@ -1,7 +1,7 @@
 .. _config.options:
 
-Config options
-==============
+Configuration Options
+=====================
 
 The following lists all available config options with their type and default values.
 The type of an option is used to validate a given value. For instance,

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 @@ def get_mode_docs():
             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('_',

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)`.
+    start in a search buffer using the query string provided as
+    parameter (see :manpage:`notmuch-search-terms(7)`)
 
 compose
     compose a new message

docs/source/usage/cli_options.rst

@@ -1,9 +1,18 @@
--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. 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)
--v, --version                  Display version string and exit
--h, --help                     Display  help and exit
+-r, --read-only  open notmuch database in read-only mode
+-c FILENAME, --config=FILENAME
+                 configuration file (default: ~/.config/alot/config)
+-n FILENAME, --notmuch-config=FILENAME
+                 notmuch configuration file (default: $NOTMUCH_CONFIG
+                 or ~/.notmuch-config)
+-C COLOURS, --colour-mode=COLOURS
+                 number of colours to use on the terminal; must be 1, 16 or 256
+                 (default: configuration option `colourmode` or 256)
+-p PATH, --mailindex-path=PATH
+                 path to notmuch index
+-d LEVEL, --debug-level=LEVEL
+                 debug level; must be one of debug, info, warning or error
+                 (default: info)
+-l FILENAME, --logfile=FILENAME
+                 log file (default: /dev/null)
+-h, --help       display help and exit
+-v, --version    output version information and exit

docs/source/usage/first_steps.rst

@@ -7,4 +7,4 @@ 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 `?`.
+to the prompt. The keybindings for the current mode are listed upon pressing `?`.

docs/source/usage/index.rst

@@ -2,8 +2,8 @@
 Usage
 *****
 
-Commandline invocation
-======================
+Command-Line Invocation
+=======================
 .. rubric:: Synopsis
 .. include:: synopsis.rst
 

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:
 

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: