Documentation updates

- Added a new section on application life cycle and hook methods
- Moved a warning to a more appropriate location
- Added a note about using allow_redirection to disable output redirection and pipes

4 files changed, 86 insertions, 8 deletions

diff --git a/docs/freefeatures.rst b/docs/freefeatures.rst
index a036973d..ddde62ca 100644
--- a/docs/freefeatures.rst
+++ b/docs/freefeatures.rst
@@ -65,7 +65,7 @@ quotation marks if it is more than a one-word command.
 
 .. note::
 
-   if you wish to disable cmd2's consumption of command-line arguments, you can do so by setting the  ``allow_cli_args``
+   If you wish to disable cmd2's consumption of command-line arguments, you can do so by setting the  ``allow_cli_args``
    attribute of your ``cmd2.Cmd`` class instance to ``False``.  This would be useful, for example, if you wish to use
    someting like Argparse_ to parse the overall command line arguments for your application::
 
@@ -105,6 +105,21 @@ app's value of ``self.redirector`` to use a different string for output redirect
     line1
     line2
 
+.. note::
+
+   If you wish to disable cmd2's output redirection and pipes features, you can do so by setting the ``allow_redirection``
+   attribute of your ``cmd2.Cmd`` class instance to ``False``.  This would be useful, for example, if you want to restrict
+   the ability for an end user to write to disk or interact with shell commands for security reasons::
+
+       from cmd2 import Cmd
+       class App(Cmd):
+           def __init__(self):
+               self.allow_redirection = False
+
+   cmd2's parser will still treat the ``>``, ``>>``, and `|` symbols as output redirection and pipe symbols and will strip
+   arguments after them from the command line arguments accordingly.  But output from a command will not be redirected
+   to a file or piped to a shell command.
+
 .. _pywin32: http://sourceforge.net/projects/pywin32/
 .. _xclip: http://www.cyberciti.biz/faq/xclip-linux-insert-files-command-output-intoclipboard/
 
diff --git a/docs/hooks.rst b/docs/hooks.rst
new file mode 100644
index 00000000..3849cce0
--- /dev/null
+++ b/docs/hooks.rst
@@ -0,0 +1,61 @@
+.. cmd2 documentation for application and command lifecycle and the hooks which are available
+
+cmd2 Application Lifecyle and Hooks
+===================================
+
+The typical way of starting a cmd2 application is as follows::
+
+    from cmd2 import Cmd
+    class App(Cmd):
+        # customized attributes and methods here
+    app = App()
+    app.cmdloop()
+
+There are several pre-existing methods and attributes which you can tweak to control the overall behavior of your
+application before, during, and after the main loop.
+
+Application Lifecycle Hook Methods
+----------------------------------
+The ``preloop`` and ``postloop`` methods run before and after the main loop, respectively.
+
+.. automethod:: cmd2.Cmd.preloop
+
+.. automethod:: cmd2.Cmd.postloop
+
+Application Lifecycle Attributes
+--------------------------------
+
+There are numerous attributes (member variables of the ``cmd2.Cmd``) which have a signficiant effect on the applicaiton
+behavior upon entering or during the main loop.  A partial list of some of the more important ones is presented here:
+
+- **intro**: *str* - if provided this serves as the intro banner printed once at start of application, after ``preloop`` runs
+- **allow_cli_args**: *bool* - if True (default), then searches for -t or --test at command line to invoke transcript testing mode instead of a normal main loop
+    and also processes any commands provided as arguments on the command line just prior to entering the main loop
+- **echo**: *bool* - if True, then the command line entered is echoed to the screen (most useful when running scripts)
+- **prompt**: *str* - sets the prompt which is displayed, can be dynamically changed based on applicatoin state and/or
+    command results
+
+
+Command Processing Hooks
+------------------------
+
+Inside the main loop, every time the user hits <Enter> the line is processed by the ``onecmd_plus_hooks`` method.
+
+.. automethod:: cmd2.Cmd.onecmd_plus_hooks
+
+As the ``onecmd_plus_hooks`` name implies, there are a number of *hook* methods that can be defined in order to inject
+applicaiton-specific behavior at various points during the processing of a line of text entered by the user.  ``cmd2``
+increases the 2 hooks provided by ``cmd`` (**precmd** and **postcmd**) to 6 for greater flexibility.  Here are
+the various hook methods, presented in chronological order starting with the ones called earliest in the process.
+
+.. automethod:: cmd2.Cmd.preparse
+
+.. automethod:: cmd2.Cmd.postparse
+
+.. automethod:: cmd2.Cmd.postparsing_precmd
+
+.. automethod:: cmd2.Cmd.precmd
+
+.. automethod:: cmd2.Cmd.postcmd
+
+.. automethod:: cmd2.Cmd.postparsing_postcmd
diff --git a/docs/index.rst b/docs/index.rst
index 2251b435..c532c1c6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -65,6 +65,7 @@ Contents:
    settingchanges
    unfreefeatures
    integrating
+   hooks
    alternatives
 
 Compatibility
diff --git a/docs/install.rst b/docs/install.rst
index 248d3c3c..dae100a9 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -24,13 +24,6 @@ install from PyPI_.
     sudo pip install <package_name>
 
 
-.. warning::
-
-  Versions of ``cmd2`` before 0.7.0 should be considered to be of unstable "beta" quality and should not be relied upon
-  for production use.  If you cannot get a version >= 0.7 from either pip or your OS repository, then we recommend
-  installing from GitHub - see :ref:`github`.
-
-
 Requirements for Installing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 * If you have Python 2 >=2.7.9 or Python 3 >=3.4 installed from `python.org
@@ -51,6 +44,8 @@ Requirements for Installing
     python -m pip install -U pip setuptools
 
 
+.. _`pip_install`:
+
 Use pip for Installing
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -88,6 +83,12 @@ For Python 3::
 
 This will also install the required 3rd-party dependencies.
 
+.. warning::
+
+  Versions of ``cmd2`` before 0.7.0 should be considered to be of unstable "beta" quality and should not be relied upon
+  for production use.  If you cannot get a version >= 0.7 from your OS repository, then we recommend
+  installing from either pip or GitHub - see :ref:`pip_install` or :ref:`github`.
+
 
 Deploy cmd2.py with your project
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~