Merge pull request #869 from python-cmd2/docs_os

Updated docs on integrating with various operating system features

2 files changed, 98 insertions, 31 deletions

diff --git a/docs/features/misc.rst b/docs/features/misc.rst
index 68a92b6a..aa791236 100644
--- a/docs/features/misc.rst
+++ b/docs/features/misc.rst
@@ -15,21 +15,6 @@ Exiting
 Mention quit, and EOF handling built into ``cmd2``.
 
 
-Shell Command
--------------
-
-``cmd2`` includes a ``shell`` command which executes it's arguments in the
-operating system shell::
-
-    (Cmd) shell ls -al
-
-If you use the default :ref:`features/shortcuts_aliases_macros:Shortcuts`
-defined in ``cmd2`` you'll get a ``!`` shortcut for ``shell``, which allows you
-to type::
-
-    (Cmd) !ls -al
-
-
 select
 ------
 
@@ -91,15 +76,6 @@ HelpCategories_ example for a demonstration.
 .. _HelpCategories: https://github.com/python-cmd2/cmd2/blob/master/examples/help_categories.py
 
 
-Exit code
----------
-
-The ``self.exit_code`` attribute of your ``cmd2`` application controls what
-exit code is returned from ``cmdloop()`` when it completes.  It is your job to
-make sure that this exit code gets sent to the shell when your application
-exits by calling ``sys.exit(app.cmdloop())``.
-
-
 Default to shell
 ----------------
 
diff --git a/docs/features/os.rst b/docs/features/os.rst
index b6f9b61f..07afc3cd 100644
--- a/docs/features/os.rst
+++ b/docs/features/os.rst
@@ -1,14 +1,70 @@
 Integrating with the OS
 =======================
 
-- how to redirect output
-- executing OS commands from within ``cmd2``
-- editors
-- paging
-- exit codes
-- Automation and calling cmd2 from other CLI/CLU tools via commands at
-  invocation and quit
+How to redirect output
+----------------------
 
+See :ref:`features/redirection:Output Redirection and Pipes`
+
+Executing OS commands from within ``cmd2``
+------------------------------------------
+
+``cmd2`` includes a ``shell`` command which executes it's arguments in the
+operating system shell::
+
+    (Cmd) shell ls -al
+
+If you use the default :ref:`features/shortcuts_aliases_macros:Shortcuts`
+defined in ``cmd2`` you'll get a ``!`` shortcut for ``shell``, which allows you
+to type::
+
+    (Cmd) !ls -al
+
+NOTE: ``cmd2`` provides user-friendly tab-completion throughout the process of
+running a shell command - first for the shell command name itself, and then for
+file paths in the argument section.
+
+Editors
+-------
+
+``cmd2`` includes the built-in ``edit`` command which runs a text editor and
+optionally opens a file with it::
+
+    (Cmd) edit foo.txt
+
+The editor used is determined by the ``editor`` settable parameter and can
+be either a text editor such as **vim** or a graphical editor such as
+**VSCode**. To set it::
+
+    set editor <program_name>
+
+If you have the ``EDITOR`` environment variable set, then this will be the
+default value for ``editor``.  If not, then ``cmd2`` will attempt to search
+for any in a list of common editors for your operating system.
+
+Terminal pagers
+---------------
+
+Output of any command can be displayed one page at a time using the
+:meth:`~.cmd2.Cmd.ppaged` method.
+
+Alternatively, a terminal pager can be invoked directly using the ability
+to run shell commands with the ``!`` shortcut like so::
+
+    (Cmd) !less foo.txt
+
+NOTE: Once you are in a terminal pager, that program temporarily has control
+of your terminal, **NOT** ``cmd2``.  Typically you can use either the arrow
+keys or <PageUp>/<PageDown> keys to scroll around or type ``q`` to quit the
+pager and return control to your ``cmd2`` application.
+
+Exit codes
+----------
+
+The ``self.exit_code`` attribute of your ``cmd2`` application controls what
+exit code is returned from ``cmdloop()`` when it completes.  It is your job to
+make sure that this exit code gets sent to the shell when your application
+exits by calling ``sys.exit(app.cmdloop())``.
 
 Invoking With Arguments
 -----------------------
@@ -84,3 +140,38 @@ your own argument parsing of the command line::
 
 Check the source code of this example, especially the ``main()`` function, to
 see the technique.
+
+Alternatively you can simply wrap the command plus arguments in quotes (either
+single or double quotes)::
+
+    $ python example/example.py "speak -p hello there"
+    ellohay heretay
+    (Cmd)
+
+Automating cmd2 apps from other CLI/CLU tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While ``cmd2`` is designed to create **interactive** command-line applications
+which enter a Read-Evaluate-Print-Loop (REPL), there are a great many times
+when it would be useful to use a ``cmd2`` application as a run-and-done
+command-line utility for purposes of automation and scripting.
+
+This is easily achieved by combining the following capabilities of ``cmd2``:
+
+#. Ability to invoke a ``cmd2`` application with arguments
+#. Ability to set an exit code when leaving a ``cmd2`` application
+#. Ability to exit a ``cmd2`` application with the  ``quit`` command
+
+Here is a simple example which doesn't require the quit command since the
+custom ``exit`` command quits while returning an exit code::
+
+    $ python examples/exit_code.py "exit 23"
+    'examples/exit_code.py' exiting with code: 23
+    $ echo $?
+    23
+
+Here is another example using ``quit``::
+
+    $ python example/example.py "speak -p hello there" quit
+    ellohay heretay
+    $