Merge pull request #726 from python-cmd2/integrate_legacy_documentation

Integrate legacy documentation

1 files changed, 60 insertions, 0 deletions

diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst
index 5813322b..c03f8778 100644
--- a/docs/features/generating_output.rst
+++ b/docs/features/generating_output.rst
@@ -9,6 +9,39 @@ how to generate output
 - exceptions
 - color support
 
+Standard ``cmd`` applications produce their output with
+``self.stdout.write('output')`` (or with ``print``, but ``print`` decreases
+output flexibility).  ``cmd2`` applications can use ``self.poutput('output')``,
+``self.pfeedback('message')``, ``self.perror('errmsg')``, and
+``self.ppaged('text')`` instead.  These methods have these advantages:
+
+- Handle output redirection to file and/or pipe appropriately
+- More concise
+    - ``.pfeedback()`` destination is controlled by ``quiet`` parameter.
+- Option to display long output using a pager via ``ppaged()``
+
+.. automethod:: cmd2.cmd2.Cmd.poutput
+    :noindex:
+.. automethod:: cmd2.cmd2.Cmd.perror
+    :noindex:
+.. automethod:: cmd2.cmd2.Cmd.pfeedback
+    :noindex:
+.. automethod:: cmd2.cmd2.Cmd.ppaged
+    :noindex:
+
+
+Suppressing non-essential output
+--------------------------------
+
+The ``quiet`` setting controls whether ``self.pfeedback()`` actually produces
+any output. If ``quiet`` is ``False``, then the output will be produced. If
+``quiet`` is ``True``, no output will be produced.
+
+This makes ``self.pfeedback()`` useful for non-essential output like status
+messages. Users can control whether they would like to see these messages by
+changing the value of the ``quiet`` setting.
+
+
 Output Redirection
 ------------------
 
@@ -43,3 +76,30 @@ If you need to include any of these redirection characters in your command, you
 can enclose them in quotation marks, ``mycommand 'with > in the argument'``.
 
 
+Colored Output
+--------------
+
+The output methods in the previous section all honor the ``allow_ansi``
+setting, which has three possible values:
+
+Never
+    poutput(), pfeedback(), and ppaged() strip all ANSI escape sequences
+    which instruct the terminal to colorize output
+
+Terminal
+    (the default value) poutput(), pfeedback(), and ppaged() do not strip any
+    ANSI escape sequences when the output is a terminal, but if the output is a
+    pipe or a file the escape sequences are stripped. If you want colorized
+    output you must add ANSI escape sequences using either cmd2's internal ansi
+    module or another color library such as `plumbum.colors`, `colorama`, or
+    `colored`.
+
+Always
+    poutput(), pfeedback(), and ppaged() never strip ANSI escape sequences,
+    regardless of the output destination
+
+Colored and otherwise styled output can be generated using the `ansi.style()`
+function:
+
+.. automethod:: cmd2.ansi.style
+