Merge branch 'master' into api_docs

# Conflicts:
#	cmd2/ansi.py
#	docs/features/completion.rst

8 files changed, 83 insertions, 32 deletions

diff --git a/docs/features/argument_processing.rst b/docs/features/argument_processing.rst
index 9d98ea93..82244d7e 100644
--- a/docs/features/argument_processing.rst
+++ b/docs/features/argument_processing.rst
@@ -325,14 +325,13 @@ Subcommands are supported for commands using either the ``@with_argparser`` or
 is based on argparse sub-parsers.
 
 You may add multiple layers of subcommands for your command. ``cmd2`` will
-automatically traverse and tab-complete subcommands for all commands using
+automatically traverse and tab complete subcommands for all commands using
 argparse.
 
-See the subcommands_ and tab_autocompletion_ example to learn more about how to
+See the subcommands_ example to learn more about how to
 use subcommands in your ``cmd2`` application.
 
 .. _subcommands: https://github.com/python-cmd2/cmd2/blob/master/examples/subcommands.py
-.. _tab_autocompletion: https://github.com/python-cmd2/cmd2/blob/master/examples/tab_autocompletion.py
 
 
 Argparse Extensions
diff --git a/docs/features/completion.rst b/docs/features/completion.rst
index c8b0a813..ffb5f80b 100644
--- a/docs/features/completion.rst
+++ b/docs/features/completion.rst
@@ -1,7 +1,7 @@
 Completion
 ==========
 
-``cmd2`` adds tab-completion of file system paths for all built-in commands
+``cmd2`` adds tab completion of file system paths for all built-in commands
 where it makes sense, including:
 
 - ``edit``
@@ -9,7 +9,7 @@ where it makes sense, including:
 - ``run_script``
 - ``shell``
 
-``cmd2`` also adds tab-completion of shell commands to the ``shell`` command.
+``cmd2`` also adds tab completion of shell commands to the ``shell`` command.
 
 Additionally, it is trivial to add identical file system path completion to
 your own custom commands.  Suppose you have defined a custom command ``foo`` by
@@ -17,7 +17,7 @@ implementing the ``do_foo`` method.  To enable path completion for the ``foo``
 command, then add a line of code similar to the following to your class which
 inherits from ``cmd2.Cmd``::
 
-    complete_foo = self.path_complete
+    complete_foo = cmd2.Cmd.path_complete
 
 This will effectively define the ``complete_foo`` readline completer method in
 your class and make it utilize the same path completion logic as the built-in
@@ -39,7 +39,7 @@ Tab Completion Using Argparse Decorators
 When using one the Argparse-based :ref:`api/decorators:cmd2.decorators`,
 ``cmd2`` provides automatic tab-completion of flag names.
 
-Tab-completion of argument values can be configured by using one of five
+Tab completion of argument values can be configured by using one of five
 parameters to ``argparse.ArgumentParser.add_argument()``
 
 - ``choices``
@@ -47,26 +47,26 @@ parameters to ``argparse.ArgumentParser.add_argument()``
 - ``completer_function`` / ``completer_method``
 
 See the arg_decorators_ or colors_ example for a demonstration of how to
-use the ``choices`` parameter. See the tab_autocompletion_ example for a
+use the ``choices`` parameter. See the argparse_completion_ example for a
 demonstration of how to use the ``choices_function`` and ``choices_method``
-parameters. See the arg_decorators_ or tab_autocompletion_ example for a
+parameters. See the arg_decorators_ or argparse_completion_ example for a
 demonstration of how to use the ``completer_method`` parameter.
 
-When tab-completing flags and/or argument values for a ``cmd2`` command using
+When tab completing flags and/or argument values for a ``cmd2`` command using
 one of these decorators, ``cmd2`` keeps track of state so that once a flag has
-already previously been provided, it won't attempt to tab-complete it again.
+already previously been provided, it won't attempt to tab complete it again.
 When no completion results exists, a hint for the current argument will be
 displayed to help the user.
 
 .. _arg_decorators: https://github.com/python-cmd2/cmd2/blob/master/examples/arg_decorators.py
 .. _colors: https://github.com/python-cmd2/cmd2/blob/master/examples/colors.py
-.. _tab_autocompletion: https://github.com/python-cmd2/cmd2/blob/master/examples/tab_autocompletion.py
+.. _argparse_completion: https://github.com/python-cmd2/cmd2/blob/master/examples/argparse_completion.py
 
 
 CompletionItem For Providing Extra Context
 ------------------------------------------
 
-When tab-completing things like a unique ID from a database, it can often be
+When tab completing things like a unique ID from a database, it can often be
 beneficial to provide the user with some extra context about the item being
 completed, such as a description.  To facilitate this, ``cmd2`` defines the
 ``CompletionItem`` class which can be returned from any of the 4 completion
@@ -76,5 +76,5 @@ or ``completion_method``.
 .. autoclass:: cmd2.argparse_custom.CompletionItem
     :members:
 
-See the tab_autocompletion_ example or the implementation of the built-in
+See the argparse_completion_ example or the implementation of the built-in
 **set** command for demonstration of how this is used.
diff --git a/docs/features/embedded_python_shells.rst b/docs/features/embedded_python_shells.rst
index 68377876..70765b21 100644
--- a/docs/features/embedded_python_shells.rst
+++ b/docs/features/embedded_python_shells.rst
@@ -67,7 +67,7 @@ code directory for an example of how to achieve this in your own applications.
 Using ``py`` to run scripts directly is considered deprecated.  The newer
 ``run_pyscript`` command is superior for doing this in two primary ways:
 
-- it supports tab-completion of file system paths
+- it supports tab completion of file system paths
 - it has the ability to pass command-line arguments to the scripts invoked
 
 There are no disadvantages to using ``run_pyscript`` as opposed to ``py
diff --git a/docs/features/help.rst b/docs/features/help.rst
index 920516f5..57aa2187 100644
--- a/docs/features/help.rst
+++ b/docs/features/help.rst
@@ -1,11 +1,60 @@
 Help
 ====
 
-use the categorize() function to create help categories
+From our experience, end users rarely read documentation no matter how high-
+quality or useful that documentation might be.  So it is important that you
+provide good built-in help within your application.  Fortunately, ``cmd2``
+makes this easy.
 
-Use ``help_method()`` to custom roll your own help messages.
+Getting Help
+------------
 
-See :ref:`features/argument_processing:Help Messages`
+``cmd2`` makes it easy for end users of ``cmd2`` applications to get help via
+the built-in ``help`` command.  The ``help`` command by itself displays a list
+of the commands available:
+
+.. code-block:: text
+
+    (Cmd) help
+
+    Documented commands (use 'help -v' for verbose/'help <topic>' for details):
+    ===========================================================================
+    alias  help     ipy    py    run_pyscript  set    shortcuts
+    edit   history  macro  quit  run_script    shell
+
+The ``help`` command can also be used to provide detailed help for a specific
+command:
+
+.. code-block:: text
+
+    (Cmd) help quit
+    Usage: quit [-h]
+
+    Exit this application
+
+    optional arguments:
+      -h, --help  show this help message and exit
+
+Providing Help
+--------------
+
+``cmd2`` makes it easy for developers of ``cmd2`` applications to provide this
+help.  By default, the help for a command is the docstring for the ``do_*``
+method defining the command - e.g. for a command **foo**, that command is
+implementd by defining the ``do_foo`` method and the docstring for that method
+is the help.
+
+For commands which use one of the ``argparse`` decorators to parse arguments,
+help is provided by ``argparse``. See
+:ref:`features/argument_processing:Help Messages` for more information.
+
+Occasionally there might be an unusual circumstance where providing static help
+text isn't good enough and you want to provide dynamic information in the help
+text for a command.  To meet this need, if a ``help_foo`` method is defined to
+match the ``do_foo`` method, then that method will be used to provide the help
+for command **foo**.  This dynamic help is only supported for commands which
+do not use an ``argparse`` decorator because didn't want different output for
+``help cmd`` than for ``cmd -h``.
 
 Categorizing Commands
 ---------------------
@@ -124,18 +173,21 @@ The ``help`` command also has a verbose option (``help -v`` or ``help
 
     Other
     ================================================================================
-    alias               Define or display aliases
+    alias               Manage aliases
     config              Config command
-    edit                Edit a file in a text editor
-    help                List available commands with "help" or detailed help with "help cmd"
-    history             usage: history [-h] [-r | -e | -s | -o FILE | -t TRANSCRIPT] [arg]
-    py                  Invoke python command, shell, or script
+    edit                Run a text editor and optionally open a file with it
+    help                List available commands or provide detailed help for a specific command
+    history             View, run, edit, save, or clear previously entered commands
+    macro               Manage macros
+    py                  Invoke Python command or shell
     quit                Exits this application
     run_pyscript        Runs a python script file inside the console
     run_script          Runs commands in script file that is encoded as either ASCII or UTF-8 text
-    set                 usage: set [-h] [-a] [-l] [settable [settable ...]]
+    set                 Set a settable parameter or show current settings of parameters
     shell               Execute a command as if at the OS prompt
-    shortcuts           Lists shortcuts available
-    unalias             Unsets aliases
+    shortcuts           List available shortcuts
     version             Version command
 
+When called with the ``-v`` flag for verbose help, the one-line description for
+each command is provided by the first line of the docstring for that command's
+associated ``do_*`` method.
diff --git a/docs/features/initialization.rst b/docs/features/initialization.rst
index 6824c7bf..b1ca4f05 100644
--- a/docs/features/initialization.rst
+++ b/docs/features/initialization.rst
@@ -133,7 +133,7 @@ override:
   command via ``self`` (Default: ``False``)
 - **macros**: dictionary of macro names and their values
 - **max_completion_items**: max number of CompletionItems to display during
-  tab-completion (Default: 50)
+  tab completion (Default: 50)
 - **pager**: sets the pager command used by the ``Cmd.ppaged()`` method for
   displaying wrapped output using a pager
 - **pager_chop**: sets the pager command used by the ``Cmd.ppaged()`` method
diff --git a/docs/features/os.rst b/docs/features/os.rst
index 89905d17..77bc6a66 100644
--- a/docs/features/os.rst
+++ b/docs/features/os.rst
@@ -20,7 +20,7 @@ to type::
 
     (Cmd) !ls -al
 
-NOTE: ``cmd2`` provides user-friendly tab-completion throughout the process of
+NOTE: ``cmd2`` provides user-friendly tab completion throughout the process of
 running a shell command - first for the shell command name itself, and then for
 file paths in the argument section.
 
diff --git a/docs/features/scripting.rst b/docs/features/scripting.rst
index 62af2e6d..1128f5e1 100644
--- a/docs/features/scripting.rst
+++ b/docs/features/scripting.rst
@@ -34,7 +34,7 @@ Running Command Scripts
 
 Command script files can be executed using the built-in ``run_script`` command
 or ``@`` shortcut. Both ASCII and UTF-8 encoded unicode text files are
-supported. The ``run_script`` command supports tab-completion of file system
+supported. The ``run_script`` command supports tab completion of file system
 paths.  There is a variant ``_relative_run_script`` command or ``@@``
 shortcut for use within a script which uses paths relative to the first script.
 
@@ -73,7 +73,7 @@ using ``run_pyscript`` is shown below  along with the arg_printer_ script::
     arg 2: 'bar'
     arg 3: 'baz 23'
 
-``run_pyscript`` supports tab-completion of file system paths, and as shown
+``run_pyscript`` supports tab completion of file system paths, and as shown
 above it has the ability to pass command-line arguments to the scripts invoked.
 
 Python scripts executed with ``run_pyscript`` can run ``cmd2`` application
diff --git a/docs/features/settings.rst b/docs/features/settings.rst
index 5a4a9c0f..aa3e5cec 100644
--- a/docs/features/settings.rst
+++ b/docs/features/settings.rst
@@ -89,11 +89,11 @@ max_completion_items
 ~~~~~~~~~~~~~~~~~~~~
 
 Maximum number of CompletionItems to display during tab completion. A
-CompletionItem is a special kind of tab-completion hint which displays both a
+CompletionItem is a special kind of tab completion hint which displays both a
 value and description and uses one line for each hint. Tab complete the ``set``
 command for an example.
 
-If the number of tab-completion hints exceeds ``max_completion_items``, then
+If the number of tab completion hints exceeds ``max_completion_items``, then
 they will be displayed in the typical columnized format and will not include
 the description text of the CompletionItem.