Update scripting docs. Closes #765.

3 files changed, 38 insertions, 17 deletions

diff --git a/docs/api/cmd.rst b/docs/api/cmd.rst
index dd3d3abe..4124912a 100644
--- a/docs/api/cmd.rst
+++ b/docs/api/cmd.rst
@@ -63,3 +63,9 @@ cmd2.Cmd
 
         Set an introduction message which is displayed to the user before
         the :ref:`features/hooks:Command Processing Loop` begins.
+
+    .. attribute:: py_bridge_name
+
+        The symbol name which :ref:`features/scripting:Python Scripts` run
+        using the :ref:`features/builtin_commands:run_pyscript` command can use
+        to reference the parent ``cmd2`` application.
diff --git a/docs/features/builtin_commands.rst b/docs/features/builtin_commands.rst
index 0db05c96..e08b5c24 100644
--- a/docs/features/builtin_commands.rst
+++ b/docs/features/builtin_commands.rst
@@ -83,6 +83,15 @@ This command runs commands in a script file that is encoded as either ASCII
 or UTF-8 text.  See :ref:`features/scripting:Command Scripts` for more
 information.
 
+_relative_run_script
+~~~~~~~~~~~~~~~~~~~~
+
+This command is hidden from the help that's visible to end users. It runs a
+script like :ref:`features/builtin_commands:run_script` but does so using a
+path relative to the script that is currently executing. This is useful when
+you have scripts that run other scripts. See :ref:`features/scripting:Running
+Command Scripts` for more information.
+
 set
 ~~~
 
diff --git a/docs/features/scripting.rst b/docs/features/scripting.rst
index 1128f5e1..efcb8261 100644
--- a/docs/features/scripting.rst
+++ b/docs/features/scripting.rst
@@ -21,9 +21,10 @@ Creating Command Scripts
 Command scripts can be created in several ways:
 
 - creating a text file using any method of your choice
-- using the built-in ``edit`` command to create or edit an existing text file
-- saving previously entered commands to a script file using ``history -s``. See
-  :ref:`features/history:History` for more details.
+- using the built-in :ref:`features/builtin_commands:edit` command to
+  create or edit an existing text file
+- saving previously entered commands to a script file using
+  :ref:`history -s <features/history:For Users>`
 
 If you create create a text file from scratch, just include one command per
 line, exactly as you would type it inside a ``cmd2`` application.
@@ -32,11 +33,15 @@ 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
-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 script.
+Command script files can be executed using the built-in
+:ref:`features/builtin_commands:run_script` command or the ``@`` shortcut (if
+your application is using the default shortcuts). Both ASCII and UTF-8 encoded
+unicode text files are supported. The
+:ref:`features/builtin_commands:run_script` command supports tab completion of
+file system paths.  There is a variant
+:ref:`features/builtin_commands:_relative_run_script` command or ``@@``
+shortcut (if using the default shortcuts) for use within a script which uses
+paths relative to the first script.
 
 
 Comments
@@ -64,8 +69,8 @@ Python Scripts
 
 If you require logic flow, loops, branching, or other advanced features, you
 can write a python script which executes in the context of your ``cmd2`` app.
-This script is run using the ``run_pyscript`` command. A simple example of
-using ``run_pyscript`` is shown below  along with the arg_printer_ script::
+This script is run using the :ref:`features/builtin_commands:run_pyscript`
+command. Here's a simple example that uses the arg_printer_ script::
 
     (Cmd) run_pyscript examples/scripts/arg_printer.py foo bar 'baz 23'
     Running Python script 'arg_printer.py' which was called with 3 arguments
@@ -73,17 +78,18 @@ using ``run_pyscript`` is shown below  along with the arg_printer_ script::
     arg 2: 'bar'
     arg 3: 'baz 23'
 
-``run_pyscript`` supports tab completion of file system paths, and as shown
-above it has the ability to pass command-line arguments to the scripts invoked.
+:ref:`features/builtin_commands:run_pyscript` supports tab completion of file
+system paths, and as shown above it has the ability to pass command-line
+arguments to the scripts invoked.
 
-Python scripts executed with ``run_pyscript`` can run ``cmd2`` application
-commands by using the syntax::
+Python scripts executed with :ref:`features/builtin_commands:run_pyscript` can
+run ``cmd2`` application commands by using the syntax::
 
     app(‘command args’)
 
 where:
 
 * ``app`` is a configurable name which can be changed by setting the
-  ``py_bridge_name`` attribute of your ``cmd2.Cmd`` class instance
-* ``command`` and ``args`` are entered exactly like they would be entered on
-  the command line of your ``cmd2`` application
+  :data:`cmd2.Cmd.py_bridge_name` attribute
+* ``command`` and ``args`` are entered exactly like they would be entered by
+  a user of your application.