Started filling in some missing stuff in the new documentation structure

docs/index.rst

@@ -40,8 +40,6 @@ Getting Started
 Migrating from cmd
 ==================
 
-[create links with short descriptions to the various migrating pages here]
-
 .. toctree::
    :maxdepth: 2
 
@@ -51,8 +49,6 @@ Migrating from cmd
 Features
 ========
 
-[create links with short descriptions to the various feature pages here]
-
 .. toctree::
    :maxdepth: 2
 
@@ -71,8 +67,6 @@ API Reference
 Examples
 ========
 
-[create links with short descriptions to the various examples pages here]
-
 .. toctree::
    :maxdepth: 2
 

docs/migrating/incompatibilities.rst

@@ -7,16 +7,49 @@ Incompatibilities
 things that are not.
 
 
-cmd.emptyline()
+Cmd.emptyline()
 ---------------
 
-The `cmd.emptyline()
+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
-time, cmd2 completely ignores empty lines and the base class cmd.emptyline()
-method never gets called and thus the emptyline() behavior cannot be
-overridden.
+time, ``cmd2`` completely ignores empty lines and the base class
+cmd.emptyline() method never gets called and thus the emptyline() behavior
+cannot be overridden.
+
+
+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.
+
+
+Cmd.cmdqueue
+------------
+In cmd_, the `Cmd.cmdqueue
+<https://docs.python.org/3/library/cmd.html#cmd.Cmd.cmdqueue>`_ attribute
+contains A list of queued input lines. The cmdqueue list is checked in
+``cmdloop()`` when new input is needed; if it is nonempty, its elements will be
+processed in order, as if entered at the prompt.
+
+Since version 0.9.13 ``cmd2`` has removed support for ``Cmd.cmdqueue``.
+Because ``cmd2`` supports running commands via the main ``cmdloop()``, text
+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.
+

docs/migrating/why.rst

@@ -3,23 +3,42 @@ Why Migrate to cmd2
 
 .. _cmd: https://docs.python.org/3/library/cmd.html
 
-``cmd2`` is an extension of cmd_, the Python Standard Library's module for
-creating simple interactive command-line applications.
+cmd
+---
 
-``cmd2`` can be used as a drop-in replacement for cmd_.  Simply importing
-``cmd2`` in place of cmd_ will add many features to an application without any
-further modifications.
+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!
 
-Understanding the use of cmd_ is the first step in learning the use of
+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.
 
-Describe why you would want to migrate, and the benefits of doing so
-
-Unicode
-
-features
-
-active community
+``cmd2`` can be used as a drop-in replacement for cmd_ with a few minor
+discrepancies as discussed in the
+:ref:`migrating/incompatibilities:Incompatibilities` section.  Simply importing
+``cmd2`` in place of cmd_ will add many features to an application without any
+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