Created a new documentation section on "Output redirection and pipes"

Also:
- Moved existing output redirection documentation from "Generating Output" section there
- Significantly expanded upon this
- Improved documentation on Command Scripts
- Added missing setting to Settings documentation section

6 files changed, 89 insertions, 38 deletions

diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst
index c03f8778..2ee820f1 100644
--- a/docs/features/generating_output.rst
+++ b/docs/features/generating_output.rst
@@ -42,40 +42,6 @@ messages. Users can control whether they would like to see these messages by
 changing the value of the ``quiet`` setting.
 
 
-Output Redirection
-------------------
-
-As in a Unix shell, output of a command can be redirected:
-
-  - sent to a file with ``>``, as in ``mycommand args > filename.txt``
-  - appended to a file with ``>>``, as in ``mycommand args >> filename.txt``
-  - piped (``|``) as input to operating-system commands, as in
-    ``mycommand args | wc``
-
-
-
-.. note::
-
-   If you wish to disable cmd2's output redirection and pipes features, you can
-   do so by setting the ``allow_redirection`` attribute of your ``cmd2.Cmd``
-   class instance to ``False``.  This would be useful, for example, if you want
-   to restrict the ability for an end user to write to disk or interact with
-   shell commands for security reasons::
-
-       from cmd2 import Cmd
-       class App(Cmd):
-           def __init__(self):
-               self.allow_redirection = False
-
-   cmd2's parser will still treat the ``>``, ``>>``, and `|` symbols as output
-   redirection and pipe symbols and will strip arguments after them from the
-   command line arguments accordingly.  But output from a command will not be
-   redirected to a file or piped to a shell command.
-
-If you need to include any of these redirection characters in your command, you
-can enclose them in quotation marks, ``mycommand 'with > in the argument'``.
-
-
 Colored Output
 --------------
 
diff --git a/docs/features/index.rst b/docs/features/index.rst
index a793efbd..c3f68107 100644
--- a/docs/features/index.rst
+++ b/docs/features/index.rst
@@ -20,6 +20,7 @@ Features
    os
    plugins
    prompt
+   redirection
    scripting
    settings
    shortcuts_aliases_macros
diff --git a/docs/features/redirection.rst b/docs/features/redirection.rst
new file mode 100644
index 00000000..677c573d
--- /dev/null
+++ b/docs/features/redirection.rst
@@ -0,0 +1,80 @@
+Output Redirection and Pipes
+============================
+
+As in POSIX shells, output of a command can be redirected and/or piped.  This
+feature is fully cross-platform and works identically on Windows, macOS, and
+Linux.
+
+Output Redirection
+------------------
+
+Redirect to a file
+~~~~~~~~~~~~~~~~~~
+
+Redirecting the output of a ``cmd2`` command to a file works just like in
+POSIX shells:
+
+  - send to a file with ``>``, as in ``mycommand args > filename.txt``
+  - append to a file with ``>>``, as in ``mycommand args >> filename.txt``
+
+If you need to include any of these redirection characters in your command, you
+can enclose them in quotation marks, ``mycommand 'with > in the argument'``.
+
+Redirect to the clipboard
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``cmd2`` output redirection supports an additional feature not found in most
+shells - if the file name following the ``>`` or ``>>`` is left blank, then
+the output is redirected to the operating system clipboard so that it can
+then be pasted into another program.
+
+  - overwrite the clipboard with ``mycommand args >``
+  - append to the clipboard with ``mycommand args >>``
+
+Pipes
+-----
+Piping the output of a ``cmd2`` command to a shell command works just like in
+POSIX shells:
+
+  - pipe as input to a shell command with ``|``, as in ``mycommand args | wc``
+
+Multiple Pipes and Redirection
+------------------------------
+Multiple pipes, optionally followed by a redirect, are supported.  Thus, it is
+possible to do something like the following::
+
+    (Cmd) help | grep py | wc > output.txt
+
+The above runs the **help** command, pipes its output to **grep** searching for
+any lines containing *py*, then pipes the output of grep to the **wc**
+"word count" command, and finally writes redirects the output of that to a file
+called *output.txt*.
+
+Disabling Redirection
+---------------------
+
+.. note::
+
+   If you wish to disable cmd2's output redirection and pipes features, you can
+   do so by setting the ``allow_redirection`` attribute of your ``cmd2.Cmd``
+   class instance to ``False``.  This would be useful, for example, if you want
+   to restrict the ability for an end user to write to disk or interact with
+   shell commands for security reasons::
+
+       from cmd2 import Cmd
+       class App(Cmd):
+           def __init__(self):
+               self.allow_redirection = False
+
+   cmd2's parser will still treat the ``>``, ``>>``, and `|` symbols as output
+   redirection and pipe symbols and will strip arguments after them from the
+   command line arguments accordingly.  But output from a command will not be
+   redirected to a file or piped to a shell command.
+
+Limitations of Redirection
+--------------------------
+
+Some limitations apply to redirection and piping within ``cmd2`` applications:
+
+- Can only pipe to shell commands, not other ``cmd2`` application commands
+- **stdout** gets redirected/piped, **stderr** does not
diff --git a/docs/features/scripting.rst b/docs/features/scripting.rst
index 52fab405..f20f3765 100644
--- a/docs/features/scripting.rst
+++ b/docs/features/scripting.rst
@@ -32,8 +32,11 @@ line, exactly as you would type it inside a ``cmd2`` application.
 Running Command Scripts
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Command script files can be executed using the built-in ``run_script`` command.
-Both ASCII and UTF-8 encoded unicode text files are supported.
+Command script files can be executed using the built-in ``run_script`` command
+or ``@`` shortcut. Both ASCII and UTF-8 encoded unicode text files are
+supported. The ``run_script`` command supports tab-completion of file system
+paths.  There is a variant ``_relative_run_script`` command or ``@@``
+shortcut for use within a script which uses paths relative to the first scrip.
 
 
 Comments
diff --git a/docs/features/settings.rst b/docs/features/settings.rst
index 21d5a9ee..b0575468 100644
--- a/docs/features/settings.rst
+++ b/docs/features/settings.rst
@@ -53,6 +53,7 @@ with::
     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
diff --git a/docs/features/transcripts.rst b/docs/features/transcripts.rst
index fe074cfa..9f524e0a 100644
--- a/docs/features/transcripts.rst
+++ b/docs/features/transcripts.rst
@@ -153,8 +153,8 @@ the path instead of specifying it verbatim, or we can escape the slashes::
    This could make the actual data generated by your app different than the
    text you pasted into the transcript, and it might not be readily obvious why
    the transcript is not passing. Consider using
-   :ref:`features/generating_output:Output Redirection` to the clipboard or to
-   a file to ensure you accurately capture the output of your command.
+   :ref:`features/redirection:Output Redirection and Pipes` to the clipboard or
+   to a file to ensure you accurately capture the output of your command.
 
    If you aren't using regular expressions, make sure the newlines at the end
    of your transcript exactly match the output of your commands. A common cause