Finish migration documentation for #719

8 files changed, 198 insertions, 38 deletions

diff --git a/docs/features/argument_processing.rst b/docs/features/argument_processing.rst
index 5efc83ef..d0f2c137 100644
--- a/docs/features/argument_processing.rst
+++ b/docs/features/argument_processing.rst
@@ -4,8 +4,9 @@ Argument Processing
 ===================
 
 ``cmd2`` makes it easy to add sophisticated argument processing to your
-commands using the ``argparse`` python module. ``cmd2`` handles the following
-for you:
+commands using the `argparse
+<https://docs.python.org/3/library/argparse.html>`_ python module. ``cmd2``
+handles the following for you:
 
 1. Parsing input and quoted strings like the Unix shell
 
@@ -16,7 +17,9 @@ for you:
    The ``Namespace`` includes the ``Statement`` object that was created when
    parsing the command line. It is stored in the ``__statement__`` attribute of
    the ``Namespace``.
+
 4. Adds the usage message from the argument parser to your command.
+
 5. Checks if the ``-h/--help`` option is present, and if so, display the help
    message for the command
 
diff --git a/docs/features/misc.rst b/docs/features/misc.rst
index 7165cb85..4db9f682 100644
--- a/docs/features/misc.rst
+++ b/docs/features/misc.rst
@@ -8,3 +8,8 @@ Timer
 Turn the timer setting on, and ``cmd2`` will show the wall time it takes for
 each command to execute.
 
+
+Exiting
+-------
+
+Mention quit, exit, and EOF handling built into ``cmd2``.
diff --git a/docs/migrating/incompatibilities.rst b/docs/migrating/incompatibilities.rst
index 014df7ff..db70798b 100644
--- a/docs/migrating/incompatibilities.rst
+++ b/docs/migrating/incompatibilities.rst
@@ -15,11 +15,9 @@ The `Cmd.emptyline()
 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 behavior in
-``cmd2`` is to simply go to the next line and issue the prompt again. At this
-time, ``cmd2`` completely ignores empty lines and the base class
-cmd.emptyline() method never gets called and thus the emptyline() behavior
-cannot be overridden.
+as expected or desirable default behavior. ``cmd2`` completely ignores empty
+lines and the base class ``cmd.emptyline()`` method never gets called and thus
+the empty line behavior cannot be overridden.
 
 
 Cmd.identchars
@@ -29,15 +27,17 @@ In cmd_, the `Cmd.identchars
 <https://docs.python.org/3/library/cmd.html#cmd.Cmd.identchars>`_ attribute
 contains the string of characters accepted for command names. cmd_ uses those
 characters to split the first "word" of the input, without requiring the user
-to type a space. For example, if ``identchars`` contained a string of all alphabetic
-characters, the user could enter a command like ``L20`` and it would be interpreted
-as the command ``L`` with the first argument of ``20``.
+to type a space. For example, if ``identchars`` contained a string of all
+alphabetic characters, the user could enter a command like ``L20`` and it would
+be interpreted as the command ``L`` with the first argument of ``20``.
 
 Since version 0.9.0, ``cmd2`` has ignored ``identchars``; the parsing logic in
 ``cmd2`` splits the command and arguments on whitespace. While cmd_ technically
-supports unicode, as a practical matter, it would be nearly impossible to
-enumerate all the "alphabetic" unicode characters in the ``identchars``
-attribute.
+supports unicode, but using non-ascii unicode characters in command names while
+simultaneously using ``identchars`` functionality is non-trivial. Requiring
+white space to delimit arguments also ensures reliable operation of many other
+useful ``cmd2`` features, including :ref:`features/completion:Completion` and
+:ref:`features/shortcuts_aliases_macros:Shortcuts, Aliases, and Macros`.
 
 If you really need this functionality in your app, you can add it back in by
 writing a :ref:`Postparsing Hook <features/hooks:Postparsing Hooks>`.
@@ -57,7 +57,3 @@ scripts, Python scripts, transcripts, and history replays, the only way to
 preserve consistent behavior across these methods was to eliminate the command
 queue. Additionally, reasoning about application behavior is much easier
 without this queue present.
-
-If developers need this sort of thing, they can add it in their application.
-However, if they are not extremely careful there would likely be unintended
-consequences.
diff --git a/docs/migrating/index.rst b/docs/migrating/index.rst
index 58253a4d..73d6b1c7 100644
--- a/docs/migrating/index.rst
+++ b/docs/migrating/index.rst
@@ -11,4 +11,4 @@ Migrating From cmd
    next_steps
 
 
-.. include:: summary.rst
\ No newline at end of file
+.. include:: summary.rst
diff --git a/docs/migrating/minimum.rst b/docs/migrating/minimum.rst
index d604cf7a..c23bbbd7 100644
--- a/docs/migrating/minimum.rst
+++ b/docs/migrating/minimum.rst
@@ -1,4 +1,51 @@
-Minimum required changes
+Minimum Required Changes
 ========================
 
-The minimum required changes to move to cmd2
+``cmd2.Cmd`` subclasses ``Cmd.cmd`` from the standard library, and overrides
+most of the methods. Most apps based on the standard library can be migrated to
+``cmd2`` in just a couple of minutes.
+
+
+Import and Inheritance
+----------------------
+
+You need to change your import from this::
+
+    import cmd
+
+to this::
+
+    import cmd2
+
+Then you need to change your class definition from::
+
+    class CmdLineApp(cmd.Cmd):
+
+to::
+
+    class CmdLineApp(cmd2.Cmd):
+
+
+Exiting
+-------
+
+Have a look at the commands you created to exit your application. You probably
+have one called ``exit`` and maybe a similar one called ``quit``. You also
+might have implemented a ``do_EOF()`` method so your program exits like many
+operating system shells. If all these commands do is quit the application,
+you may be able to remove them. See :ref:`features/misc:Exiting`.
+
+
+Distribution
+------------
+
+If you are distributing your application, you'll also need to ensure
+that ``cmd2`` is properly installed. You will need to add this to
+your ``setup()`` method in ``setup.py``::
+
+    install_requires=[
+        'cmd2>=1,<2`
+    ]
+
+See :ref:`overview/integrating:Integrate cmd2 Into Your Project` for more
+details.
diff --git a/docs/migrating/next_steps.rst b/docs/migrating/next_steps.rst
index 3f560501..f43c69c9 100644
--- a/docs/migrating/next_steps.rst
+++ b/docs/migrating/next_steps.rst
@@ -1,6 +1,62 @@
 Next Steps
 ==========
 
-What features (with links to details) are easy to implement next
+Once your current application is using ``cmd2``, you can start to expand the
+functionality by levering other ``cmd2`` features. The three ideas here will
+get you started. Browse the rest of the :ref:`features/index:Features` to see
+what else ``cmd2`` can help you do.
 
-:doc:`Help <../features/help>`
+
+Argument Parsing
+----------------
+
+For all but the simplest of commands, it's probably easier to use `argparse
+<https://docs.python.org/3/library/argparse.html>`_ to parse user input.
+``cmd2`` provides a ``@with_argparser()`` decorator which associates an
+``ArgumentParser`` object with one of your commands. Using this method will:
+
+1. Pass your command a `Namespace
+<https://docs.python.org/3/library/argparse.html#argparse.Namespace>`_
+containing the arguments instead of a string of text.
+
+2. Properly handle quoted string input from your users.
+
+3. Create a help message for you based on the ``ArgumentParser``.
+
+4. Give you a big headstart adding :ref:`features/completion:Completion` to
+   your application.
+
+5. Make it much easier to implement subcommands (i.e. ``git`` has
+   a bunch of subcommands such as ``git pull``, ``git diff``, etc).
+
+There's a lot more about :ref:`features/argument_processing:Argument
+Processing` if you want to dig in further.
+
+
+Help
+----
+
+If you have lot of commands in your application, ``cmd2`` can categorize those
+commands using a one line decorator ``@with_category()``. When a user types
+``help`` the available commands will be organized by the category you
+specified.
+
+If you were already using ``argparse`` or decided to switch to it, you can
+easily :ref:`standardize all of your help messages
+<features/argument_processing:Help Messages>` to be generated by your argument
+parsers and displayed by ``cmd2``. No more help messages that don't match what
+the code actually does.
+
+
+Generating Output
+-----------------
+
+If your program generates output by printing directly to ``sys.stdout``, you
+should consider switching to :meth:`cmd2.cmd2.Cmd.poutput`,
+:meth:`cmd2.cmd2.Cmd.perror`, and :meth:`cmd2.cmd2.Cmd.pfeedback`. These
+methods work with several of the built in :ref:`features/settings:Settings` to
+allow the user to view or suppress feedback (i.e. progress or status output).
+They also properly handle ansi colored output according to user preference.
+Speaking of colored output, you can use any color library you want, or use the
+included :meth:`cmd2.ansi.style` function. These and other related topics are
+covered in :ref:`features/generating_output:Generating Output`.
diff --git a/docs/migrating/why.rst b/docs/migrating/why.rst
index 5445b03f..a166d648 100644
--- a/docs/migrating/why.rst
+++ b/docs/migrating/why.rst
@@ -32,18 +32,6 @@ further modifications.  Migrating to ``cmd2`` will also open many additional
 doors for making it possible for developers to provide a top-notch interactive
 command-line experience for their users.
 
-``cmd2`` provides a full-featured framework for creating professional-quality
-interactive command-line applications. A few of the highlights of ``cmd2``
-include:
-
-* Applications created are full-featured shells in their own right with ability
-  to call shell commands, redirect command output, pipe command output to shell
-  commands, etc.
-* Superior tab-completion capabilities, especially when using included argparse
-  decorators
-* Both Python and ASCII text application scripting is built-in
-* Ability to run non-interactively for automation purposes
-
 
 Free Features
 -------------
@@ -51,10 +39,18 @@ Free Features
 After switching from cmd_ to ``cmd2``, your application will have the following
 new features and capabilities, without you having to do anything:
 
-- More robust :ref:`features/history:History`. Both cmd_ and ``cmd2`` have readline
-  history, but ``cmd2`` also has a robust ``history`` command which allows you
-  to edit prior commands in a text editor of your choosing, re-run multiple
-  commands at a time, and save prior commands as a script to be executed later.
+- More robust :ref:`features/history:History`. Both cmd_ and ``cmd2`` have
+  readline history, but ``cmd2`` also has a robust ``history`` command which
+  allows you to edit prior commands in a text editor of your choosing, re-run
+  multiple commands at a time, and save prior commands as a script to be
+  executed later.
+
+- Users can redirect output to a file or pipe it to some other operating system
+  command. You did remember to use ``self.stdout`` instead of ``sys.stdout`` in
+  all of your print functions, right? If you did, then this will work out of
+  the box. If you didn't, you'll have to go back and fix them. Before you do,
+  you might consider the various ways ``cmd2`` has of
+  :ref:`features/generating_output:Generating Output`.
 
 - Users can load script files, which contain a series of commands
   to be executed.
@@ -76,3 +72,11 @@ new features and capabilities, without you having to do anything:
   ``cmd2``-based app. The transcript can be played back into the app as a unit
   test.
 
+
+Next Steps
+----------
+
+In addition to the features you get with no additional work, ``cmd2`` offers a
+broad range of additional capabilties which can be easily added to your
+application. :ref:`migrating/next_steps:Next Steps` has some ideas of where
+you can start, or you can dig in to all the :ref:`features/index:Features`.
diff --git a/examples/migrating.py b/examples/migrating.py
new file mode 100644
index 00000000..3a25b8c8
--- /dev/null
+++ b/examples/migrating.py
@@ -0,0 +1,49 @@
+#!/usr/bin/env python
+# coding=utf-8
+"""
+A sample application for cmd which can be used to show how to migrate to cmd2.
+"""
+import random
+
+import cmd
+
+
+class CmdLineApp(cmd.Cmd):
+    """ Example cmd application. """
+
+    MUMBLES = ['like', '...', 'um', 'er', 'hmmm', 'ahh']
+    MUMBLE_FIRST = ['so', 'like', 'well']
+    MUMBLE_LAST = ['right?']
+
+    def do_exit(self, line):
+        """Exit the application"""
+        return True
+
+    do_EOF = do_exit
+    do_quit = do_exit
+
+    def do_speak(self, line):
+        """Repeats what you tell me to."""
+        print(line, file=self.stdout)
+
+    do_say = do_speak
+
+    def do_mumble(self, line):
+        """Mumbles what you tell me to."""
+        words = line.split(' ')
+        output = []
+        if random.random() < .33:
+            output.append(random.choice(self.MUMBLE_FIRST))
+        for word in words:
+            if random.random() < .40:
+                output.append(random.choice(self.MUMBLES))
+            output.append(word)
+        if random.random() < .25:
+            output.append(random.choice(self.MUMBLE_LAST))
+        print(' '.join(output), file=self.stdout)
+
+
+if __name__ == '__main__':
+    import sys
+    c = CmdLineApp()
+    sys.exit(c.cmdloop())