6 files changed, 78 insertions, 23 deletions

diff --git a/docs/migrating/free_features.rst b/docs/migrating/free_features.rst
deleted file mode 100644
index afb29fc3..00000000
--- a/docs/migrating/free_features.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-What you get for free
-=====================
-
-A brief list (with links to details) of major features you get for free once
-you migrate.
diff --git a/docs/migrating/incompatibilities.rst b/docs/migrating/incompatibilities.rst
index 2804aeac..014df7ff 100644
--- a/docs/migrating/incompatibilities.rst
+++ b/docs/migrating/incompatibilities.rst
@@ -4,7 +4,7 @@ Incompatibilities
 .. _cmd: https://docs.python.org/3/library/cmd.html
 
 ``cmd2`` strives to be drop-in compatible with cmd_, however there are a few
-things that are not.
+incompatibilities.
 
 
 Cmd.emptyline()
@@ -14,9 +14,9 @@ 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 behavior in
-``cmd2`` is to simply go to the next line and issue the prompt again.  At this
+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.
@@ -27,11 +27,20 @@ Cmd.identchars
 
 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.  Since version
-0.9.0, ``cmd2`` has ignored ``identchars``. cmd_ uses those characters to split
-the first "word" of the input, but the parsing logic in ``cmd2`` parses on
-whitespace.  This has the added benefit of full unicode support, unlike cmd_ or
-versions of ``cmd2`` prior to 0.9.0.
+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``.
+
+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.
+
+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>`.
 
 
 Cmd.cmdqueue
@@ -52,4 +61,3 @@ 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 9c01b1bd..58253a4d 100644
--- a/docs/migrating/index.rst
+++ b/docs/migrating/index.rst
@@ -1,11 +1,14 @@
-Migrating from cmd
+Migrating From cmd
 ==================
 
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
    why
    incompatibilities
    minimum
-   free_features
-   nextsteps
+   next_steps
+
+
+.. include:: summary.rst
\ No newline at end of file
diff --git a/docs/migrating/nextsteps.rst b/docs/migrating/next_steps.rst
index 3f560501..3f560501 100644
--- a/docs/migrating/nextsteps.rst
+++ b/docs/migrating/next_steps.rst
diff --git a/docs/migrating/summary.rst b/docs/migrating/summary.rst
new file mode 100644
index 00000000..5bde2d0c
--- /dev/null
+++ b/docs/migrating/summary.rst
@@ -0,0 +1,15 @@
+
+.. _cmd: https://docs.python.org/3/library/cmd.html
+
+If you're thinking of migrating your cmd_ app to ``cmd2``, this section
+will help you decide if it's right for your app, and show you how to
+do it.
+
+* :ref:`migrating/why:Why cmd2` - we try and convince you
+  to use ``cmd2`` instead of cmd_
+* :ref:`migrating/incompatibilities:Incompatibilities` - ``cmd2`` is not
+  quite 100% compatible with cmd_.
+* :ref:`migrating/minimum:Minimum Required Changes` - the minimum changes
+  required to move from cmd_ to ``cmd2``. Start your migration here.
+* :ref:`migrating/next_steps:Next Steps` - Once you've migrated, here a list
+  of things you can do next to add even more functionality to your app.
diff --git a/docs/migrating/why.rst b/docs/migrating/why.rst
index 1561bb91..5445b03f 100644
--- a/docs/migrating/why.rst
+++ b/docs/migrating/why.rst
@@ -1,5 +1,5 @@
-Why Migrate to cmd2
-===================
+Why cmd2
+========
 
 .. _cmd: https://docs.python.org/3/library/cmd.html
 
@@ -7,17 +7,19 @@ cmd
 ---
 
 cmd_ is the Python Standard Library's module for creating simple interactive
-command-line applications.
-cmd_ is an extremely bare-bones framework which leaves a lot to be desired.  It
-doesn't even include a built-in way to exit from an application!
+command-line applications. cmd_ is an extremely bare-bones framework which
+leaves a lot to be desired.  It doesn't even include a built-in way to exit
+from an application!
 
 Since the API provided by cmd_ provides the foundation on which ``cmd2`` is
 based, understanding the use of cmd_ is the first step in learning the use of
 ``cmd2``. Once you have read the cmd_ docs, return here to learn the ways that
 ``cmd2`` differs from cmd_.
 
+
 cmd2
 ----
+
 ``cmd2`` is a batteries-included extension of cmd_, which provides a wealth of
 functionality to make it quicker and easier for developers to create
 feature-rich interactive command-line applications which delight customers.
@@ -42,3 +44,35 @@ include:
 * Both Python and ASCII text application scripting is built-in
 * Ability to run non-interactively for automation purposes
 
+
+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.
+
+- Users can load script files, which contain a series of commands
+  to be executed.
+
+- Users can create :ref:`features/shortcuts_aliases_macros:Shortcuts, Aliases,
+  and Macros` to reduce the typing required for repetitive commands.
+
+- Embedded python shell allows a user to execute python code from within your
+  ``cmd2`` app. How meta.
+
+- :ref:`features/clipboard:Clipboard Integration` allows you to save command
+  output to the operating system clipboard.
+
+- A built-in :ref:`features/misc:Timer` can show how long it takes a command to
+  execute
+
+- A :ref:`Transcript <features/transcripts:Transcripts>` is a file which
+  contains both the input and output of a successful session of a
+  ``cmd2``-based app. The transcript can be played back into the app as a unit
+  test.
+