Finish generating_output and document output related settings

2 files changed, 90 insertions, 57 deletions

diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst
index 58e53962..34416092 100644
--- a/docs/features/generating_output.rst
+++ b/docs/features/generating_output.rst
@@ -22,19 +22,6 @@ also adds a number of output related methods to ``Cmd2.Cmd`` which you may use
 to enhance the output your application produces.
 
 
-TODO:
-
-
-- perror
-- pwarning
-- pexcept
-- ppaging
-
-- column formatting?
-- wcswidth?
-
-- exceptions
-
 Ordinary Output
 ---------------
 
@@ -91,22 +78,27 @@ want it.
 Output generated by any of these
 methods will honor the :ref:`features/settings:allow_ansi` setting:
 
-- :meth:`cmd2.cmd2.Cmd.poutput`
-- :meth:`cmd2.cmd2.Cmd.perror`
-- :meth:`cmd2.cmd2.Cmd.pwarning`
-- :meth:`cmd2.cmd2.Cmd.pexcept`
-- :meth:`cmd2.cmd2.Cmd.pfeedback`
-- :meth:`cmd2.cmd2.Cmd.ppaged`
+- :meth:`~.cmd2.Cmd.poutput`
+- :meth:`~.cmd2.Cmd.perror`
+- :meth:`~.cmd2.Cmd.pwarning`
+- :meth:`~.cmd2.Cmd.pexcept`
+- :meth:`~.cmd2.Cmd.pfeedback`
+- :meth:`~.cmd2.Cmd.ppaged`
 
 
 Error Messages
 --------------
 
+When an error occurs in your program, you can display it on ``sys.stderr`` by
+calling the :meth:`~.cmd2.Cmd.perror` method.
 
 
 Warning Messages
 ----------------
 
+:meth:`~.cmd2.Cmd.pwarning` is just like :meth:`~.cmd2.Cmd.perror` but applies
+:meth:`cmd2.ansi.style_warning` to the output.
+
 
 Feedback
 --------
@@ -116,33 +108,57 @@ 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
 :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.
+command to run will be output as feedback. You can use the
+:meth:`~.cmd2.Cmd.pfeedback` method to produce this type of output, and
+several :ref:`features/settings:Settings` control how it 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 :ref:`features/settings:quiet` setting is ``True``, then calling
+:meth:`~.cmd2.Cmd.pfeedback` produces no output. If
+:ref:`features/settings:quiet` is ``False``, the
+:ref:`features/settings:feedback_to_output` setting is consulted to determine
+whether to send the output to ``stdout`` or ``stderr``.
 
 
 Exceptions
 ----------
 
+If your app catches an exception and you would like to display the exception to
+the user, the :meth:`~.cmd2.Cmd.pexcept` method can help. The default behavior
+is to just display the message contained within the exception. However, if the
+:ref:`features/settings:debug` setting is ``True``, then the entire stack trace
+will be displayed.
+
 
 Paging Output
 -------------
 
+If you know you are going to generate a lot of output, you may want to display
+it in a way that the user can scroll forwards and backwards through it. If you
+pass all of the output to be displayed in a single call to
+:meth:`~.cmd2.Cmd.ppaged`, it will be piped to an operating system appropriate
+shell command to page the output. On Windows, the output is piped to ``more``;
+on Unix-like operating systems like MacOS and Linux, it is piped to ``less``.
+
 
 Centering Text
 --------------
 
-utils.center_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
+will figure out the width of the terminal and return you a new string,
+appropriately padded so it will be centered.
 
 
 Columnar Output
 ---------------
 
-Using wcswidth() and ansi.ansi_safe_wcswidth()
+When generating output in multiple columns, you often need to calculate the
+width of each item so you can pad it appropriately with spaces. However, there
+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
+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.
diff --git a/docs/features/settings.rst b/docs/features/settings.rst
index 25162aed..f117c171 100644
--- a/docs/features/settings.rst
+++ b/docs/features/settings.rst
@@ -32,33 +32,6 @@ the ``set`` command like so::
 
     (Cmd) set allow_ansi Never
 
-Timing
-~~~~~~
-
-Setting ``App.timing`` to ``True`` outputs timing data after every application
-command is executed.  |settable|
-
-
-Echo
-~~~~
-
-If ``True``, each command the user issues will be repeated to the screen before
-it is executed.  This is particularly useful when running scripts.
-
-
-Debug
-~~~~~
-
-Setting ``App.debug`` to ``True`` will produce detailed error stacks whenever
-the application generates an error.  |settable|
-
-.. |settable| replace:: The user can ``set`` this parameter
-                        during application execution.
-                        (See :ref:`parameters`)
-
-.. _parameters:
-
-
 allow_ansi
 ~~~~~~~~~~
 
@@ -83,6 +56,50 @@ This setting can be one of three values:
 - ``Always`` - ANSI escape sequences are always passed through, regardless
 
 
+debug
+~~~~~
+
+The default value of this setting is ``False``, which causes the
+:meth:`~.cmd2.Cmd.pexcept` method to only display the message from an
+exception. However, if the debug setting is ``True``, then the entire stack
+trace will be printed.
+
+
+echo
+~~~~
+
+If ``True``, each command the user issues will be repeated to the screen before
+it is executed.  This is particularly useful when running scripts.
+
+
+feedback_to_output
+~~~~~~~~~~~~~~~~~~
+
+Controls whether feedback generated with the :meth:`~cmd2.cmd2.Cmd.pfeedback`
+method is sent to ``sys.stdout`` or ``sys.stderr``. If ``False`` the output
+will be sent to ``sys.stderr``
+
+If ``True`` the output is sent to ``stdout`` (which is often the screen but may
+be :ref:`redirected <features/redirection:Output Redirection and Pipes>`). The
+feedback output will be mixed in with and indistinguishable from output
+generated with :meth:`~cmd2.cmd2.Cmd.poutput`.
+
+
+quiet
+~~~~~
+
+If ``True``, output generated by calling :meth:`~cmd2.Cmd.pfeedback` is
+suppressed. If ``False``, the :ref:`features/settings:feedback_to_output`
+setting controls where the output is sent.
+
+
+timing
+~~~~~~
+
+Setting ``App.timing`` to ``True`` outputs timing data after every application
+command is executed.  |settable|
+
+
 Create New Settings
 -------------------