Documentation for colored output #765

4 files changed, 99 insertions, 64 deletions

diff --git a/docs/api/ansi.rst b/docs/api/ansi.rst
new file mode 100644
index 00000000..e361bd4f
--- /dev/null
+++ b/docs/api/ansi.rst
@@ -0,0 +1,5 @@
+cmd2.ansi
+=========
+
+.. automodule:: cmd2.ansi
+    :members:
diff --git a/docs/api/index.rst b/docs/api/index.rst
index 94d0fdd4..f0324eab 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -7,5 +7,6 @@ API Reference
    cmd
    decorators
    exceptions
+   ansi
    utility_classes
    utility_functions
diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst
index d63acea2..16ff044d 100644
--- a/docs/features/generating_output.rst
+++ b/docs/features/generating_output.rst
@@ -14,17 +14,17 @@ time you produce output, you can trivially change where all the output
 goes by changing how you initialize your class.
 
 ``cmd2`` extends this approach in a number of convenient ways. See
-:ref:`features/redirection:Output Redirection And Pipes` for information
-on how users can change where the output of a command is sent. In order
-for those features to work, the output you generate must be sent to
-``self.stdout``. You can use the methods described above, and everything
-will work fine. ``cmd2`` also includes a number of convenience methods
-which you may use to enhance the output your application produces.
+:ref:`features/redirection:Output Redirection And Pipes` for information on how
+users can change where the output of a command is sent. In order for those
+features to work, the output you generate must be sent to ``self.stdout``. You
+can use the methods described above, and everything will work fine. ``cmd2``
+also adds a number of output related methods to ``Cmd2.Cmd`` which you may use
+to enhance the output your application produces.
 
 
 TODO:
 
-- poutput
+
 - perror
 - pwarning
 - pexcept
@@ -33,14 +33,47 @@ TODO:
 - column formatting?
 - wcswidth?
 
-- allow_ansi setting
-- cmd2.ansi.style()
-
 - exceptions
 
 Ordinary Output
 ---------------
 
+The ``poutput()`` method is almost like using the Python built-in ``print()``
+function. ``poutput()`` adds two conveniences.
+
+Since users can pipe output to a shell command, it catches ``BrokenPipeError``
+and outputs the contents of ``self.broken_pipe_warning`` to ``stderr``.
+``self.broken_pipe_warning`` defaults to an empty string so this method will
+just swallow the exception. If you want to show some error message, put it in
+``self.broken_pipe_warning`` when you initialize ``Cmd2.cmd``.
+
+``poutput()`` also honors the :ref:`features/settings:allow_ansi` setting,
+which controls whether ANSI escape sequences that instruct the terminal to
+colorize output are stripped from the output.
+
+
+Colored Output
+--------------
+
+You may want to generate output in different colors, which is typically done by
+adding `ANSI escape sequences
+<https://en.wikipedia.org/wiki/ANSI_escape_code#Colors>`_ which tell the
+terminal to change the foreground and background colors. If you want to give
+yourself a headache, you can generate these by hand. You could also use another
+Python color library like `plumbum.colors
+<https://plumbum.readthedocs.io/en/latest/colors.html>`_, `colored
+<https://gitlab.com/dslackw/colored>`_, or `colorama
+<https://github.com/tartley/colorama>`_. Colorama is unique because when it's
+running on Windows, it wraps ``stdout``, looks for ANSI escape sequences, and
+converts them into the appropriate ``win32`` calls to modify the state of the
+terminal.
+
+``cmd2`` imports and uses Colorama and also provides a number of convenience
+methods for generating colorized output, measuring the screen width of
+colorized output, setting the window title in the terminal, and removing ANSI
+escape codes from a string. These functions are all documentated in
+:ref:`api/ansi:cmd2.ansi`.
+
 
 Error Messages
 --------------
@@ -55,19 +88,19 @@ Feedback
 
 You may have the need to display information to the user which is not intended
 to be part of the generated output. This could be debugging information or
-status information about the progress of long running commands. It's not output,
-it's not error messages, it's feedback. If you use the
+status information about the progress of long running commands. It's not
+output, it's not error messages, it's feedback. If you use the
 :ref:`features/settings:Timing` setting, the output of how long it took the
 command to run will be output as feedback. ``cmd2`` has a ``self.pfeedback()``
 method to produce this type of output, and several
 :ref:`features/settings:Settings` to control how this output is handled.
 
-If the ``quiet`` setting is ``True``, then calling ``self.pfeedback()`` produces
-no output. If ``quiet`` is ``False``, then the ``feedback_to_output`` setting is
-consulted to determine which file descriptor the feedback will be sent to. The
-default value of ``False`` means all feedback is sent to ``sys.stderr``. If set
-to ``True``, then the feedback output will be sent to ``self.stdout`` along with
-the rest of the generated output.
+If the ``quiet`` setting is ``True``, then calling ``self.pfeedback()``
+produces no output. If ``quiet`` is ``False``, then the ``feedback_to_output``
+setting is consulted to determine which file descriptor the feedback will be
+sent to. The default value of ``False`` means all feedback is sent to
+``sys.stderr``. If set to ``True``, then the feedback output will be sent to
+``self.stdout`` along with the rest of the generated output.
 
 
 Exceptions
@@ -90,30 +123,4 @@ Columnar Output
 Using wcswidth() and ansi.ansi_safe_wcswidth()
 
 
-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
 
diff --git a/docs/features/settings.rst b/docs/features/settings.rst
index b0575468..25162aed 100644
--- a/docs/features/settings.rst
+++ b/docs/features/settings.rst
@@ -11,6 +11,26 @@ Built In Settings
 ``cmd2`` has a number of built in settings, which a developer can set a default
 value, and which users can modify to change the behavior of the application.
 
+A list of all user-settable parameters, with brief comments, is viewable from
+within a running application::
+
+    (Cmd) set --long
+    allow_ansi: Terminal           # Allow ANSI escape sequences in output (valid values: Terminal, Always, Never)
+    continuation_prompt: >         # On 2nd+ line of input
+    debug: False                   # Show full error stack on error
+    echo: False                    # Echo command issued into output
+    editor: vim                    # Program used by ``edit``
+    feedback_to_output: False      # include nonessentials in `|`, `>` results
+    locals_in_py: False            # Allow access to your application in py via self
+    max_completion_items: 50       # Maximum number of CompletionItems to display during tab completion
+    prompt: (Cmd)                  # The prompt issued to solicit input
+    quiet: False                   # Don't print nonessential feedback
+    timing: False                  # Report execution times
+
+Any of these user-settable parameters can be set while running your app with
+the ``set`` command like so::
+
+    (Cmd) set allow_ansi Never
 
 Timing
 ~~~~~~
@@ -38,31 +58,29 @@ the application generates an error.  |settable|
 
 .. _parameters:
 
-Other user-settable parameters
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A list of all user-settable parameters, with brief
-comments, is viewable from within a running application
-with::
+allow_ansi
+~~~~~~~~~~
 
-    (Cmd) set --long
-    allow_ansi: Terminal           # Allow ANSI escape sequences in output (valid values: Terminal, Always, Never)
-    continuation_prompt: >         # On 2nd+ line of input
-    debug: False                   # Show full error stack on error
-    echo: False                    # Echo command issued into output
-    editor: vim                    # Program used by ``edit``
-    feedback_to_output: False      # include nonessentials in `|`, `>` results
-    locals_in_py: False            # Allow access to your application in py via self
-    max_completion_items: 50       # Maximum number of CompletionItems to display during tab completion
-    prompt: (Cmd)                  # The prompt issued to solicit input
-    quiet: False                   # Don't print nonessential feedback
-    timing: False                  # Report execution times
+The ``allow_ansi`` setting controls the behavior of ANSI escape sequences
+in output generated with any of the following methods:
 
-Any of these user-settable parameters can be set while running your app with
-the ``set`` command like so::
+- ``poutput()``
+- ``perror()``
+- ``pwarning()``
+- ``pfeedback()``
+- ``ppaged()``
 
-    set allow_ansi Never
+This setting can be one of three values:
 
+- ``Never`` - all ANSI escape sequences which instruct the terminal to colorize
+  output are stripped from the output.
+
+- ``Terminal`` - (the default value) pass through ANSI escape sequences when
+  the output is being sent to the terminal, but if the output is redirected to
+  a pipe or a file the escape sequences are stripped.
+
+- ``Always`` - ANSI escape sequences are always passed through, regardless
 
 
 Create New Settings
@@ -100,3 +118,7 @@ changes a setting, and will receive both the old value and the new value.
    now: 13
    (Cmd) sunbathe
    It's 13 C - are you a penguin?
+
+
+Hide Built-in Settings
+----------------------