Integrate freefeatures into new doc structure

10 files changed, 161 insertions, 154 deletions

diff --git a/docs/examples/index.rst b/docs/examples/index.rst
index 2070b7a3..838c6402 100644
--- a/docs/examples/index.rst
+++ b/docs/examples/index.rst
@@ -5,3 +5,5 @@ Examples
    :maxdepth: 1
 
    first_app
+   removing_builtin_commands
+
diff --git a/docs/examples/removing_builtin_commands.rst b/docs/examples/removing_builtin_commands.rst
new file mode 100644
index 00000000..63f5160a
--- /dev/null
+++ b/docs/examples/removing_builtin_commands.rst
@@ -0,0 +1,7 @@
+Removing Builtin Commands
+=========================
+
+Show how to remove built in comamnds. Say for example you don't like the
+``quit`` command included in ``cmd2``. Your application has to subclass
+``cmd2.Cmd`` to work, which means you inherit the ``quit`` command. Here's how
+to remove it.
diff --git a/docs/features/completion.rst b/docs/features/completion.rst
index c89b24cc..5d2a722c 100644
--- a/docs/features/completion.rst
+++ b/docs/features/completion.rst
@@ -1,4 +1,33 @@
 Completion
 ==========
 
-How tab completion works and how to implement it in your own project
+``cmd2`` adds tab-completion of file system paths for all built-in commands
+where it makes sense, including:
+
+- ``edit``
+- ``run_pyscript``
+- ``run_script``
+- ``shell``
+
+``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
+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
+
+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
+commands.
+
+The built-in logic allows for a few more advanced path completion capabilities,
+such as cases where you only want to match directories.  Suppose you have a
+custom command ``bar`` implemented by the ``do_bar`` method.  You can enable
+path completion of directories only for this command by adding a line of code
+similar to the following to your class which inherits from ``cmd2.Cmd``::
+
+    # Make sure you have an "import functools" somewhere at the top
+    complete_bar = functools.partialmethod(cmd2.Cmd.path_complete, path_filter=os.path.isdir)
diff --git a/docs/features/embedded_python_shells.rst b/docs/features/embedded_python_shells.rst
index 7e8c027b..6d00536a 100644
--- a/docs/features/embedded_python_shells.rst
+++ b/docs/features/embedded_python_shells.rst
@@ -61,10 +61,10 @@ the application::
 The ``py`` command also allows you to run Python scripts via ``py
 run('myscript.py')``. This provides a more complicated and more powerful
 scripting capability than that provided by the simple text file scripts
-discussed in :ref:`scripts`.  Python scripts can include conditional control
-flow logic.  See the **python_scripting.py** ``cmd2`` application and the
-**script_conditional.py** script in the ``examples`` source code directory for
-an example of how to achieve this in your own applications.
+discussed in :ref:`features/scripting:Scripting`.  Python scripts can include
+conditional control flow logic.  See the **python_scripting.py** ``cmd2``
+application and the **script_conditional.py** script in the ``examples`` source
+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:
diff --git a/docs/features/history.rst b/docs/features/history.rst
index 7d6a03a4..8aa305c0 100644
--- a/docs/features/history.rst
+++ b/docs/features/history.rst
@@ -161,8 +161,9 @@ would::
 
 If you want to save the commands to a text file, but not edit and re-run them,
 use the ``-o`` or ``--output-file`` option. This is a great way to create
-:ref:`scripts`, which can be executed using the ``run_script`` command. To
-save the first 5 commands entered in this session to a text file::
+:ref:`Scripts <features/scripting:Scripting>`, which can be executed using the
+``run_script`` command. To save the first 5 commands entered in this session to
+a text file::
 
     (Cmd) history :5 -o history.txt
 
diff --git a/docs/features/misc.rst b/docs/features/misc.rst
index 4db9f682..b556d44e 100644
--- a/docs/features/misc.rst
+++ b/docs/features/misc.rst
@@ -12,4 +12,68 @@ each command to execute.
 Exiting
 -------
 
-Mention quit, exit, and EOF handling built into ``cmd2``.
+Mention quit, and EOF handling built into ``cmd2``.
+
+
+Shell Command
+-------------
+
+``cmd2`` includes a ``shell`` command which executes it's arguments in the
+operating system shell::
+
+    (Cmd) shell ls -al
+
+If you use the default :ref:`features/shortcuts_aliases_macros:Shortcuts`
+defined in ``cmd2`` you'll get a ``!`` shortcut for ``shell``, which allows you
+to type::
+
+    (Cmd) !ls -al
+
+
+Commands At Invocation
+----------------------
+
+.. _Argparse: https://docs.python.org/3/library/argparse.html
+
+You can send commands to your app as you invoke it by including them as extra
+arguments to the program. ``cmd2`` interprets each argument as a separate
+command, so you should enclose each command in quotation marks if it is more
+than a one-word command.
+
+.. code-block:: shell
+
+  $ python examples/example.py "say hello" "say Gracie" quit
+  hello
+  Gracie
+
+
+.. note::
+
+   If you wish to disable cmd2's consumption of command-line arguments, you can
+   do so by setting the  ``allow_cli_args`` argument of your ``cmd2.Cmd`` class
+   instance to ``False``.  This would be useful, for example, if you wish to
+   use something like Argparse_ to parse the overall command line arguments for
+   your application::
+
+       from cmd2 import Cmd
+       class App(Cmd):
+           def __init__(self):
+               super().__init__(allow_cli_args=False)
+
+
+Initialization Script
+---------------------
+
+.. _AliasStartup: https://github.com/python-cmd2/cmd2/blob/master/examples/alias_startup.py
+
+You can execute commands from an initialization script by passing a file
+path to the ``startup_script`` argument to the ``cmd2.Cmd.__init__()`` method
+like so::
+
+    class StartupApp(cmd2.Cmd):
+        def __init__(self):
+            cmd2.Cmd.__init__(self, startup_script='.cmd2rc')
+
+This text file should contain a :ref:`Command Script
+<features/scripting:Command Scripts>`. See the AliasStartup_ example for a
+demonstration.
diff --git a/docs/features/scripting.rst b/docs/features/scripting.rst
index 73566cde..52fab405 100644
--- a/docs/features/scripting.rst
+++ b/docs/features/scripting.rst
@@ -1,20 +1,62 @@
 Scripting
 =========
 
-Document use cases and commands for ``run_script`` and ``run_pyscript``
+Operating system shells have long had the ability to execute a sequence of
+commands saved in a text file. These script files make long sequences of
+commands easier to repeatedly execute. ``cmd2`` supports two similar
+mechanisms: command scripts and python scripts.
+
+
+Command Scripts
+---------------
+
+A command script contains a sequence of commands typed at the the prompt of a
+``cmd2`` based application. Unlike operating system shell scripts, command
+scripts can't contain logic or loops.
+
+
+Creating Command Scripts
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Command scripts can be created in several ways:
+
+- creating a text file using any method of your choice
+- using the built-in ``edit`` command to create or edit an existing text file
+- saving previously entered commands to a script file using ``history -s``. See
+  :ref:`features/history:History` for more details.
+
+If you create create a text file from scratch, just include one command per
+line, exactly as you would type it inside a ``cmd2`` application.
+
+
+Running Command Scripts
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Command script files can be executed using the built-in ``run_script`` command.
+Both ASCII and UTF-8 encoded unicode text files are supported.
+
 
 Comments
---------
+~~~~~~~~
 
 Any command line input where the first non-whitespace character is a `#` will
 be treated as a comment. This means any `#` character appearing later in the
 command will be treated as a literal. The same applies to a `#` in the middle
 of a multiline command, even if it is the first character on a line.
 
-Comments can be useful in :ref:`scripts`, but would be pointless within an
-interactive session.
+Comments are useful in scripts, but would be pointless within an interactive
+session.
 
 ::
 
   (Cmd) # this is a comment
-  (Cmd) this # is not a comment
+  (Cmd) command # this is not a comment
+
+
+Python Scripts
+--------------
+
+If you require logic flow, loops, branching, or other advanced features, you
+can write a python script which executes in the context of your ``cmd2`` app.
+This script is run using the ``run_pyscript`` command. See
+:ref:`features/embedded_python_shells:Embedded Python Shells`.
diff --git a/docs/features/transcripts.rst b/docs/features/transcripts.rst
index 18daeb78..fe074cfa 100644
--- a/docs/features/transcripts.rst
+++ b/docs/features/transcripts.rst
@@ -152,9 +152,9 @@ the path instead of specifying it verbatim, or we can escape the slashes::
    Some terminal emulators strip trailing space when you copy text from them.
    This could make the actual data generated by your app different than the
    text you pasted into the transcript, and it might not be readily obvious why
-   the transcript is not passing. Consider using :ref:`output_redirection` to
-   the clipboard or to a file to ensure you accurately capture the output of
-   your command.
+   the transcript is not passing. Consider using
+   :ref:`features/generating_output:Output Redirection` to the clipboard or to
+   a file to ensure you accurately capture the output of your command.
 
    If you aren't using regular expressions, make sure the newlines at the end
    of your transcript exactly match the output of your commands. A common cause
diff --git a/docs/freefeatures.rst b/docs/freefeatures.rst
deleted file mode 100644
index cb693be8..00000000
--- a/docs/freefeatures.rst
+++ /dev/null
@@ -1,136 +0,0 @@
-===================================
-Features requiring no modifications
-===================================
-
-These features are provided "for free" to a cmd_-based application
-simply by replacing ``import cmd`` with ``import cmd2 as cmd``.
-
-.. _cmd: https://docs.python.org/3/library/cmd.html
-
-.. _scripts:
-
-Script files
-============
-
-Text files can serve as scripts for your ``cmd2``-based application, with the
-``run_script``, ``_relative_run_script``, and ``edit`` commands.
-
-Both ASCII and UTF-8 encoded unicode text files are supported.
-
-Simply include one command per line, typed exactly as you would inside a
-``cmd2`` application.
-
-.. automethod:: cmd2.cmd2.Cmd.do_run_script
-    :noindex:
-
-.. automethod:: cmd2.cmd2.Cmd.do__relative_run_script
-    :noindex:
-
-.. automethod:: cmd2.cmd2.Cmd.do_edit
-    :noindex:
-
-
-Startup Initialization Script
-=============================
-
-You can execute commands from a startup initialization script by passing a file
-path to the ``startup_script`` argument to the ``cmd2.Cmd.__init__()`` method
-like so::
-
-    class StartupApp(cmd2.Cmd):
-        def __init__(self):
-            cmd2.Cmd.__init__(self, startup_script='.cmd2rc')
-
-See the AliasStartup_ example for a demonstration.
-
-.. _AliasStartup: https://github.com/python-cmd2/cmd2/blob/master/examples/alias_startup.py
-
-Commands at invocation
-======================
-
-You can send commands to your app as you invoke it by
-including them as extra arguments to the program.
-``cmd2`` interprets each argument as a separate
-command, so you should enclose each command in
-quotation marks if it is more than a one-word command.
-
-::
-
-  cat@eee:~/proj/cmd2/example$ python example.py "say hello" "say Gracie" quit
-  hello
-  Gracie
-  cat@eee:~/proj/cmd2/example$
-
-.. note::
-
-   If you wish to disable cmd2's consumption of command-line arguments, you can do so by setting the  ``allow_cli_args``
-   argument of your ``cmd2.Cmd`` class instance to ``False``.  This would be useful, for example, if you wish to use
-   something like Argparse_ to parse the overall command line arguments for your application::
-
-       from cmd2 import Cmd
-       class App(Cmd):
-           def __init__(self):
-               super().__init__(allow_cli_args=False)
-
-.. _Argparse: https://docs.python.org/3/library/argparse.html
-
-.. _output_redirection:
-
-
-
-Quitting the application
-========================
-
-``cmd2`` pre-defines a ``quit`` command for you.
-It's trivial, but it's one less thing for you to remember.
-
-
-Misc. pre-defined commands
-==========================
-
-Several generically useful commands are defined
-with automatically included ``do_`` methods.
-
-.. automethod:: cmd2.cmd2.Cmd.do_quit
-    :noindex:
-
-.. automethod:: cmd2.cmd2.Cmd.do_shell
-    :noindex:
-
-( ``!`` is a shortcut for ``shell``; thus ``!ls``
-is equivalent to ``shell ls``.)
-
-
-Tab-Completion
-==============
-
-``cmd2`` adds tab-completion of file system paths for all built-in commands
-where it makes sense, including:
-
-- ``edit``
-- ``run_pyscript``
-- ``run_script``
-- ``shell``
-
-``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
-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
-
-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
-commands.
-
-The built-in logic allows for a few more advanced path completion capabilities,
-such as cases where you only want to match directories.  Suppose you have a
-custom command ``bar`` implemented by the ``do_bar`` method.  You can enable
-path completion of directories only for this command by adding a line of code
-similar to the following to your class which inherits from ``cmd2.Cmd``::
-
-    # Make sure you have an "import functools" somewhere at the top
-    complete_bar = functools.partialmethod(cmd2.Cmd.path_complete, path_filter=os.path.isdir)
diff --git a/docs/index.rst b/docs/index.rst
index d9b5b14c..3ff4e379 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -95,7 +95,6 @@ To Be Integrated
 
 Files from old documentation to be integrated into new structure
 
-* :doc:`freefeatures`
 * :doc:`integrating`
 * :doc:`settingchanges`
 * :doc:`unfreefeatures`
@@ -105,7 +104,6 @@ Files from old documentation to be integrated into new structure
    :hidden:
    :caption: To Be Integrated
 
-   freefeatures
    integrating
    settingchanges
    unfreefeatures