From 1daf5d2cb63145408520f39c799425a82b2ec948 Mon Sep 17 00:00:00 2001
From: kotfu <kotfu@kotfu.net>
Date: Sat, 11 Aug 2018 19:54:10 -0600
Subject: First pass at improved colorizing

- colors setting now allows Always, Terminal, Never values
- poutput() and perror() honor these new settings
---
 docs/settingchanges.rst |  4 ++--
 docs/unfreefeatures.rst | 25 +++++++++++++++++++++----
 2 files changed, 23 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/settingchanges.rst b/docs/settingchanges.rst
index 02955273..e08b6026 100644
--- a/docs/settingchanges.rst
+++ b/docs/settingchanges.rst
@@ -137,7 +137,7 @@ comments, is viewable from within a running application
 with::
 
     (Cmd) set --long
-    colors: True                   # Colorized output (*nix only)
+    colors: Terminal               # Allow colorized output
     continuation_prompt: >         # On 2nd+ line of input
     debug: False                   # Show full error stack on error
     echo: False                    # Echo command issued into output
@@ -150,5 +150,5 @@ with::
 
 Any of these user-settable parameters can be set while running your app with the ``set`` command like so::
 
-    set colors False
+    set colors Never
 
diff --git a/docs/unfreefeatures.rst b/docs/unfreefeatures.rst
index a2eff50a..93249425 100644
--- a/docs/unfreefeatures.rst
+++ b/docs/unfreefeatures.rst
@@ -139,12 +139,29 @@ instead.  These methods have these advantages:
 .. automethod:: cmd2.cmd2.Cmd.ppaged
 
 
-color
-=====
+Colored Output
+==============
 
-Text output can be colored by wrapping it in the ``colorize`` method.
+The output methods in the previous section all honor the ``colors`` setting,
+which has three possible values:
 
-.. automethod:: cmd2.cmd2.Cmd.colorize
+Never
+    poutput() and pfeedback() strip all ANSI escape sequences
+    which instruct the terminal to colorize output
+
+Terminal
+    (the default value) poutput() and pfeedback() 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, preferably using some python color library
+    like `plumbum.colors`, `colorama`, `blessings`, or `termcolor`.
+
+Always
+    poutput() and pfeedback() never strip ANSI escape sequences, regardless of
+    the output destination
+
+
+The previously recommended ``colorize`` method is now deprecated.
 
 
 .. _quiet:
-- 
cgit v1.2.1