Merge branch 'master' into generating_output_docs

# Conflicts:
#	docs/features/generating_output.rst
#	docs/features/settings.rst

1 files changed, 29 insertions, 5 deletions

diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst
index 34416092..78ff7657 100644
--- a/docs/features/generating_output.rst
+++ b/docs/features/generating_output.rst
@@ -36,7 +36,7 @@ conveniences.
   If you want to show an error message, put it in
   ``self.broken_pipe_warning`` when you initialize ``Cmd2.cmd``.
 
-  2. It examines and honors the :ref:`features/settings:allow_ansi` setting.
+  2. It examines and honors the :ref:`features/settings:allow_style` setting.
   See :ref:`features/generating_output:Colored Output` below for more details.
 
 Here's a simple command that shows this method in action::
@@ -48,6 +48,30 @@ Here's a simple command that shows this method in action::
 
 Colored Output
 --------------
+The output methods in the previous section all honor the ``allow_style``
+setting, which has three possible values:
+
+Never
+    poutput(), pfeedback(), and ppaged() strip all ANSI style sequences
+    which instruct the terminal to colorize output
+
+Terminal
+    (the default value) poutput(), pfeedback(), and ppaged() do not strip any
+    ANSI style sequences when the output is a terminal, but if the output is a
+    pipe or a file the style sequences are stripped. If you want colorized
+    output you must add ANSI style 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 style sequences,
+    regardless of the output destination
+
+Colored and otherwise styled output can be generated using the `ansi.style()`
+function:
+
+.. automethod:: cmd2.ansi.style
+   :noindex:
 
 You may want to generate output in different colors, which is typically done by
 adding `ANSI escape sequences
@@ -68,7 +92,7 @@ output, setting the window title in the terminal, and removing ANSI escape
 codes from a string. These functions are all documentated in
 :mod:`cmd2.ansi`.
 
-:mod:`cmd2.cmd2.Cmd` includes an :ref:`features/settings:allow_ansi` setting,
+:mod:`cmd2.cmd2.Cmd` includes an :ref:`features/settings:allow_style` setting,
 which controls whether ANSI escape sequences that instruct the terminal to
 colorize output are stripped from the output. The recommended approach is to
 construct your application so that it generates colorized output, and then
@@ -76,7 +100,7 @@ allow your users to use this setting to remove the colorization if they do not
 want it.
 
 Output generated by any of these
-methods will honor the :ref:`features/settings:allow_ansi` setting:
+methods will honor the :ref:`features/settings:allow_style` setting:
 
 - :meth:`~.cmd2.Cmd.poutput`
 - :meth:`~.cmd2.Cmd.perror`
@@ -144,7 +168,7 @@ Centering Text
 --------------
 
 If you would like to generate output which is centered in the user's terminal,
-the :meth:`cmd2.utils.center_text` method can help. Pass it a string and it
+the :meth:`cmd2.utils.align_center` method can help. Pass it a string and it
 will figure out the width of the terminal and return you a new string,
 appropriately padded so it will be centered.
 
@@ -158,7 +182,7 @@ are categories of Unicode characters that occupy 2 cells, and other that occupy
 0. To further complicate matters, you might have included ANSI escape sequences
 in the output to generate colors on the terminal.
 
-The :meth:`cmd2.ansi.ansi_safe_wcswidth` function solves both of these
+The :meth:`cmd2.ansi.style_aware_wcswidth` function solves both of these
 problems. Pass it a string, and regardless of which Unicode characters and ANSI
 escape sequences it contains, it will tell you how many characters on the
 screen that string will consume when printed.