Documentation updates

Sphinx documenation updates, including:
- Extensively re-wrote the "alternatives to cmd2" section as it was many years out of date
- Reworded a few humorous sections in an attempt to be more professional
- Removed reference to command synonyms/aliases which no longer exist
- Added more detail in a couple places
- Minor rewording and bugfixes throughout

Also added a note to cmd2.py about the expected values for doctest only working for Python 2.7.

cmd2.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python
 # coding=utf-8
 """Variant on standard library's cmd with extra features.
 
@@ -1956,6 +1957,8 @@ def tearDown(self):
 if __name__ == '__main__':
     doctest.testmod(optionflags=doctest.NORMALIZE_WHITESPACE)
 
+    # NOTE: The doctest expected values work with Python 2.7, but are a bit off for Python 3.x.
+
 '''
 To make your application transcript-testable, replace
 

docs/alternatives.rst

@@ -5,46 +5,49 @@ Alternatives to cmd and cmd2
 For programs that do not interact with the user in a continuous loop -
 programs that simply accept a set of arguments from the command line, return
 results, and do not keep the user within the program's environment - all
-you need are sys_\ .argv (the command-line arguments) and optparse_
-(for parsing UNIX-style options and flags).
+you need are sys_\ .argv (the command-line arguments) and argparse_
+(for parsing UNIX-style options and flags).  Though some people may prefer docopt_
+or click_ to argparse_.
 
-.. _optparse: http://docs.python.org/library/optparse.html#module-optparse
+.. _sys: https://docs.python.org/3/library/sys.html
+.. _argparse: https://docs.python.org/3/library/argparse.html
+.. _docopt: https://pypi.python.org/pypi/docopt
+.. _click: http://click.pocoo.org
 
-.. _sys: http://docs.python.org/library/sys.html#module-sys
-
-.. _curses: http://docs.python.org/library/curses.html#module-curses
-
-.. _cmd: https://docs.python.org/3/library/cmd.html
 
 The curses_ module produces applications that interact via a plaintext
 terminal window, but are not limited to simple text input and output;
 they can paint the screen with options that are selected from using the
 cursor keys.  However, programming a curses_-based application is not as
 straightforward as using cmd_.
 
-Several packages in PyPI enable interactive command-line applications
-approximately similar in concept to cmd_ applications.  None of them
-share cmd2's close ties to cmd, but they may be worth investigating
-nonetheless.
-
-  * CmdLoop_
-  * cly_
-  * CmDO_ (As of Feb. 2010, webpage is missing.)
-  * pycopia-CLI_
-
-cmdln_, another package in PyPI, is an extension to cmd_ and, though it
-doesn't retain full cmd_ compatibility, shares its basic structure with
-cmd_.
+.. _curses: https://docs.python.org/3/library/curses.html
+.. _cmd: https://docs.python.org/3/library/cmd.html
 
-.. _cmdln: http://pypi.python.org/pypi/cmdln
+Several Python packages exist for building interactive command-line applications
+approximately similar in concept to cmd_ applications.  None of them
+share ``cmd2``'s close ties to cmd_, but they may be worth investigating
+nonetheless.  Two of the most mature and full featured are:
 
-.. _CmdLoop: http://pypi.python.org/pypi/CmdLoop
+  * `Python Prompt Toolkit`_
+  * Click_
 
-.. _cly: http://pypi.python.org/pypi/cly
+.. _`Python Prompt Toolkit`: https://github.com/jonathanslenders/python-prompt-toolkit
 
-.. _CmDO: http://pypi.python.org/pypi/CmDO/0.7
+`Python Prompt Toolkit`_ is a library for building powerful interactive command lines and terminal applications in
+Python.  It provides a lot of advanced visual features like syntax highlighting, bottom bars, and the ability to
+create fullscreen apps.
 
-.. _pycopia-CLI: https://github.com/kdart/pycopia/tree/master/CLI
+Click_ is a Python package for creating beautiful command line interfaces in a composable way with as little code as
+necessary.  It is more geared towards command line utilities instead of command line interpreters, but it can be used
+for either.
 
-I've found several alternatives to cmd in PyPI - CmdLoop, cly, CMdO, and pycopia. cly looks wonderful, but I haven't been able to get it working under Windows, and that's a show-stopper for many potential sqlpython users. In any case, none of the alternatives are based on cmd - they're written from scratch, which means that a cmd-based app would need complete rewriting to use them. I like sticking close to the Standard Library whenever possible. cmd2 lets you do that.
+Getting a working command-interpreter application based on either `Python Prompt Toolkit`_ or Click_ requires a good
+deal more effort and boilerplate code than ``cmd2``.  ``cmd2`` focuses on providing an excellent out-of-the-box experience
+with as many useful features as possible built in for free with as little work required on the developer's part as
+possible.  We believe that ``cmd2`` provides developers the easiest way to write a command-line interpreter, while
+allowing a good experience for end users.  If you are seeking a visually richer end-user experience and don't
+mind investing more development time, we would recommend checking out `Python Prompt Toolkit`_.
 
+In the future, we may investigate options for incorporating the usage of `Python Prompt Toolkit`_ and/or Click_ into
+``cmd2`` applicaitons.

docs/freefeatures.rst

@@ -32,9 +32,8 @@ are recognized; you may change this by overriding
 ``app.commentGrammars`` with a different pyparsing_
 grammar.
 
-Comments can be useful in :ref:`scripts`.  Used
-in an interactive session, they may indicate
-mental imbalance.
+Comments can be useful in :ref:`scripts`, but would
+be pointless within an interactive session.
 
 ::
 
@@ -105,9 +104,10 @@ command.  Entered without arguments, it enters an
 interactive Python session.  That session can call
 "back" to your application with ``cmd("")``.  Through
 ``self``, it also has access to your application
-instance itself.  (If that thought terrifies you,
-you can set the ``locals_in_py`` parameter to ``False``.
-See see :ref:`parameters`)
+instance itself which can be extremely useful for debugging.
+(If giving end-users this level of introspection is inappropriate,
+the ``locals_in_py`` parameter can be set to ``False`` and removed
+from the settable dictionary. See see :ref:`parameters`)
 
 ::
 
@@ -157,8 +157,7 @@ also provide `bash-like history list editing`_.
 Quitting the application
 ========================
 
-``cmd2`` pre-defines a ``quit`` command for you (with
-synonyms ``exit`` and simply ``q``).
+``cmd2`` pre-defines a ``quit`` command for you.
 It's trivial, but it's one less thing for you to remember.
 
 

docs/index.rst

@@ -33,7 +33,7 @@ The basic use of ``cmd2`` is identical to that of cmd_.
 
 .. note::
 
-   The tab-completion capability provided by cmd_ relies on underlying capability provided by GNU readline or an
+   The tab-completion feature provided by cmd_ relies on underlying capability provided by GNU readline or an
    equivalent library.  Linux distros will almost always come with the required library installed.
    For Mac OS X, we recommend installing the `gnureadline <https://pypi.python.org/pypi/gnureadline>`_ Python module.
    For Windows, we recommend installing the `pyreadline <https://pypi.python.org/pypi/pyreadline>`_ Python module.

docs/overview.rst

@@ -17,7 +17,7 @@ differs from cmd_.
 .. note::
 
    ``cmd2`` is not quite a drop-in replacement for cmd_.
-   The `cmd.emptyline() function <https://docs.python.org/3/library/cmd.html#cmd.Cmd.emptyline>`_ is called
+   The `cmd.emptyline() <https://docs.python.org/3/library/cmd.html#cmd.Cmd.emptyline>`_ function is called
    when an empty line is entered in response to the prompt. By default, in cmd_ if this method is not overridden, it
    repeats and executes the last nonempty command entered.  However, no end user we have encountered views this as
    expected or desirable default behavior.  Thus, the default behvior in ``cmd2`` is to simply go to the next line

docs/settingchanges.rst

@@ -16,8 +16,8 @@ By default, all ``cmd2`` command names are case-insensitive;
 set ``App.case_insensitive`` to False.
 
 Whether or not you set ``case_insensitive``, *please do not* define
-command method names with any uppercase letters.  ``cmd2`` will probably
-do something evil if you do.
+command method names with any uppercase letters.  ``cmd2`` expects all command methods
+to be lowercase.
 
 Shortcuts
 =========
@@ -118,3 +118,7 @@ with::
     quiet: False                   # Don't print nonessential feedback
     timing: False                  # Report execution times
 
+Any of these user-settable parameters can be set while running your app with the ``set`` command like so::
+
+    set abbrev False
+

docs/unfreefeatures.rst

@@ -21,7 +21,7 @@ Parsed statements
 =================
 
 ``cmd2`` passes ``arg`` to a ``do_`` method (or
-``default`) as a ParsedString, a subclass of
+``default``) as a ParsedString, a subclass of
 string that includes an attribute ``parsed``.
 ``parsed`` is a ``pyparsing.ParseResults``
 object produced by applying a pyparsing_
@@ -62,10 +62,9 @@ If ``parsed`` does not contain an attribute,
 querying for it will return ``None``.  (This
 is a characteristic of ``pyparsing.ParseResults``.)
 
-ParsedString was developed to support sqlpython_
-and reflects its needs.  The parsing grammar and
-process are painfully complex and should not be
-considered stable; future ``cmd2`` releases may
+The parsing grammar and process currently employed
+by cmd2 is stable, but is likely significantly more
+complex than it needs to be.  Future ``cmd2`` releases may
 change it somewhat (hopefully reducing complexity).
 
 (Getting ``arg`` as a ``ParsedString`` is
@@ -74,8 +73,6 @@ changes from the cmd_ standard, but there will
 be no result unless you change your application
 to *use* ``arg.parsed``.)
 
-.. _sqlpython: http://pypi.python.org/pypi/sqlpython/
-
 .. _cmd: https://docs.python.org/3/library/cmd.html
 
 .. _pyparsing: http://pyparsing.wikispaces.com/
@@ -224,8 +221,8 @@ useful for non-essential feedback that the user may not always want
 to read.  ``quiet`` is only relevant if
 ``app.pfeedback`` is sometimes used.
 
-``select``
-==========
+select
+======
 
 Presents numbered options to user, as bash ``select``.