Refactored the Windows vs macOS/Linux conditional in ppaged()

Aslo:
- Added some documentation for ppaged()
- Updated CHANGELOG
- Added line about ppaged() in README

Author: tleonhardt

CHANGELOG.md

@@ -16,6 +16,8 @@
     * ``exclude_from_help`` and ``excludeFromHistory`` are now instance instead of class attributes
     * Added flag and index based tab completion helper functions
         * See [tab_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/tab_completion.py)
+    * Added support for displaying output which won't fit on the screen via a pager using ``ppaged()``
+        * See [paged_output.py](https://github.com/python-cmd2/cmd2/blob/master/examples/paged_output.py)
 * Attributes Removed (**can cause breaking changes**)
     * ``abbrev`` - Removed support for abbreviated commands
         * Good tab completion makes this unnecessary and its presence could cause harmful unintended actions

README.md

@@ -26,6 +26,7 @@ Main Features
 - Redirect command output to file with `>`, `>>`; input from file with `<`
 - Bare `>`, `>>` with no filename send output to paste buffer (clipboard)
 - `py` enters interactive Python console (opt-in `ipy` for IPython console)
+- Option to display long output using a pager with ``cmd2.Cmd.ppaged()``
 - Multi-line commands
 - Special-character command shortcuts (beyond cmd's `@` and `!`)
 - Settable environment parameters

cmd2.py

@@ -1229,14 +1229,15 @@ def ppaged(self, msg, end=os.linesep):
 
                 # Don't attempt to use a pager that can block if redirecting or running a script (either text or Python)
                 if not self.redirecting and not self._in_py and not self._script_dir:
-                    # Here is the meaning of the various flags we are using with the less command:
-                    # -S causes lines longer than the screen width to be chopped (truncated) rather than wrapped
-                    # -R causes ANSI "color" escape sequences to be output in raw form (i.e. colors are displayed)
-                    # -X disables sending the termcap initialization and deinitialization strings to the terminal
-                    # -F causes less to automatically exit if the entire file can be displayed on the first screen
-                    pager_cmd = 'less -SRXF'
                     if sys.platform.startswith('win'):
                         pager_cmd = 'more'
+                    else:
+                        # Here is the meaning of the various flags we are using with the less command:
+                        # -S causes lines longer than the screen width to be chopped (truncated) rather than wrapped
+                        # -R causes ANSI "color" escape sequences to be output in raw form (i.e. colors are displayed)
+                        # -X disables sending the termcap initialization and deinitialization strings to the terminal
+                        # -F causes less to automatically exit if the entire file can be displayed on the first screen
+                        pager_cmd = 'less -SRXF'
                     self.pipe_proc = subprocess.Popen(pager_cmd, shell=True, stdin=subprocess.PIPE)
                     try:
                         self.pipe_proc.stdin.write(msg_str.encode('utf-8', 'replace'))

docs/unfreefeatures.rst

@@ -147,21 +147,23 @@ There are a couple functions which can globally effect how arguments are parsed
 .. _argparse: https://docs.python.org/3/library/argparse.html
 
 
-poutput, pfeedback, perror
-==========================
+poutput, pfeedback, perror, ppaged
+==================================
 
 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')``, and ``self.perror('errmsg')``
+``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 :ref:`quiet` parameter.
+- Option to display long output using a pager via ``ppaged()``
 
 .. automethod:: cmd2.Cmd.poutput
 .. automethod:: cmd2.Cmd.perror
 .. automethod:: cmd2.Cmd.pfeedback
+.. automethod:: cmd2.Cmd.ppaged
 
 
 color