Improve instructions of how to run p-scripts

- add link in each script usage to the instructions

9 files changed, 118 insertions, 63 deletions

diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 9e0310c29..107f35914 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -6,6 +6,63 @@ Command-Line Pyramid
 Your :app:`Pyramid` application can be controlled and inspected using a variety
 of command-line utilities.  These utilities are documented in this chapter.
 
+We commonly refer to this collection of utilities as "p-scripts", which is short for "Pyramid console scripts".
+
+Each p-script's command line usage details is available in the :ref:`pscripts_documentation`.
+
+
+.. index::
+    single: running p-scripts
+    pair: running; p-scripts
+
+.. _running-pscripts:
+
+Running p-scripts
+-----------------
+
+All of the Pyramid console scripts may be run either:
+
+*   by its name
+*   through a Python interpreter
+
+
+.. index::
+    single: running p-script by name
+    triple: p-script; running; name
+
+.. _running-pscripts-by-name:
+
+Running by ``p*`` script name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each of Pyramid's console scripts may be run by its name.  For example:
+
+.. code-block:: bash
+
+    $VENV/bin/pserve development.ini --reload
+
+.. note:: ``$VENV/bin/`` represents the ``bin`` directory in a virtual environment, where ``$VENV`` is an environment variable representing its path.
+
+
+.. index::
+    single: running p-scripts via Python
+    triple: p-script; running; Python
+
+.. _custom-arguments-to-python:
+
+Using Custom Arguments to Python when Running ``p*`` Scripts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.5
+
+Each of Pyramid's console scripts (``pserve``, ``pviews``, etc.) can be run
+using ``python3 -m``, allowing custom arguments to be sent to the
+Python interpreter at runtime. For example:
+
+.. code-block:: bash
+
+    python3 -m pyramid.scripts.pserve development.ini --reload
+
 
 .. index::
    pair: matching views; printing
@@ -13,8 +70,8 @@ of command-line utilities.  These utilities are documented in this chapter.
 
 .. _displaying_matching_views:
 
-Displaying Matching Views for a Given URL
------------------------------------------
+``pviews``: Displaying Matching Views for a Given URL
+-----------------------------------------------------
 
 .. seealso:: See also the output of :ref:`pviews --help <pviews_script>`.
 
@@ -31,7 +88,7 @@ to be ``main``.
 
 Here is an example for a simple view configuration using :term:`traversal`:
 
-.. code-block:: text
+.. code-block:: bash
     :linenos:
 
     $VENV/bin/pviews development.ini#tutorial /FrontPage
@@ -54,7 +111,7 @@ permissions and predicates that are part of that view configuration.
 
 A more complex configuration might generate something like this:
 
-.. code-block:: text
+.. code-block:: bash
     :linenos:
 
     $VENV/bin/pviews development.ini#shootout /about
@@ -114,8 +171,8 @@ found* message.
 
 .. _interactive_shell:
 
-The Interactive Shell
----------------------
+``pshell``: The Interactive Shell
+---------------------------------
 
 .. seealso:: See also the output of :ref:`pshell --help <pshell_script>`.
 
@@ -144,7 +201,7 @@ have an ``[app:main]`` section that looks like so:
 If so, you can use the following command to invoke a debug shell using the name
 ``main`` as a section name:
 
-.. code-block:: text
+.. code-block:: bash
 
     $VENV/bin/pshell starter/development.ini#main
     Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32)
@@ -178,7 +235,7 @@ default :term:`root factory`, ``registry``, and ``request`` will be available.
 You can also simply rely on the ``main`` default section name by omitting any
 hash after the filename:
 
-.. code-block:: text
+.. code-block:: bash
 
     $VENV/bin/pshell starter/development.ini
 
@@ -252,7 +309,7 @@ By defining the ``setup`` callable, we will create the module ``myapp.lib.pshell
 
 When this ``.ini`` file is loaded, the extra variable ``models`` will be available for use immediately. Since a ``setup`` callable was also specified, it is executed and new variables ``testapp``, ``tm``, and ``dbsession`` are exposed, and the request is configured to generate URLs from the host ``http://www.example.com``. For example:
 
-.. code-block:: text
+.. code-block:: bash
 
     $VENV/bin/pshell starter/development.ini
     Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32)
@@ -296,13 +353,13 @@ installed such as ``pyramid_ipython`` it will normally be auto-selected and
 used. You may also specifically invoke your choice with the ``-p choice`` or
 ``--python-shell choice`` option.
 
-.. code-block:: text
+.. code-block:: bash
 
     $VENV/bin/pshell -p ipython development.ini#MyProject
 
 You may use the ``--list-shells`` option to see the available shells.
 
-.. code-block:: text
+.. code-block:: bash
 
     $VENV/bin/pshell --list-shells
     Available shells:
@@ -363,8 +420,8 @@ specify a list of preferred shells.
 
 .. _displaying_application_routes:
 
-Displaying All Application Routes
----------------------------------
+``proutes``: Displaying All Application Routes
+----------------------------------------------
 
 .. seealso:: See also the output of :ref:`proutes --help <proutes_script>`.
 
@@ -378,7 +435,7 @@ the ``section_name`` is ``main`` and can be omitted.
 
 For example:
 
-.. code-block:: text
+.. code-block:: bash
     :linenos:
 
     $VENV/bin/proutes development.ini
@@ -415,7 +472,7 @@ and use those as defaults.
 
 For example you may remove the request method and place the view first:
 
-.. code-block:: text
+.. code-block:: ini
     :linenos:
 
     [proutes]
@@ -425,7 +482,7 @@ For example you may remove the request method and place the view first:
 
 You can also separate the formats with commas or spaces:
 
-.. code-block:: text
+.. code-block:: ini
     :linenos:
 
     [proutes]
@@ -446,8 +503,8 @@ include. The current available formats are ``name``, ``pattern``, ``view``, and
 
 .. _displaying_tweens:
 
-Displaying "Tweens"
--------------------
+``ptweens``: Displaying "Tweens"
+--------------------------------
 
 .. seealso:: See also the output of :ref:`ptweens --help <ptweens_script>`.
 
@@ -462,7 +519,7 @@ standard Python dotted name in the ``ptweens`` output.
 For example, here's the ``ptweens`` command run against a system configured
 without any explicit tweens:
 
-.. code-block:: text
+.. code-block:: bash
     :linenos:
 
     $VENV/bin/ptweens development.ini
@@ -480,10 +537,10 @@ without any explicit tweens:
 Here's the ``ptweens`` command run against a system configured *with* explicit
 tweens defined in its ``development.ini`` file:
 
-.. code-block:: text
+.. code-block:: bash
     :linenos:
 
-    ptweens development.ini
+    $VENV/bin/ptweens development.ini
     "pyramid.tweens" config value set (explicitly ordered tweens used)
 
     Explicit Tween Chain (used)
@@ -534,8 +591,8 @@ See :ref:`registering_tweens` for more information about tweens.
 
 .. _invoking_a_request:
 
-Invoking a Request
-------------------
+``prequest``: Invoking a Request
+--------------------------------
 
 .. seealso:: See also the output of :ref:`prequest --help <prequest_script>`.
 
@@ -553,9 +610,11 @@ There are two required arguments to ``prequest``:
 - The path: this should be the non-URL-quoted path element of the URL to the
   resource you'd like to be rendered on the server.  For example, ``/``.
 
-For example::
+For example:
+
+.. code-block:: bash
 
-   $ $VENV/bin/prequest development.ini /
+    $VENV/bin/prequest development.ini /
 
 This will print the body of the response to the console on which it was
 invoked.
@@ -564,16 +623,20 @@ Several options are supported by ``prequest``.  These should precede any config
 file name or URL.
 
 ``prequest`` has a ``-d`` (i.e., ``--display-headers``) option which prints the
-status and headers returned by the server before the output::
+status and headers returned by the server before the output:
+
+.. code-block:: bash
 
-   $ $VENV/bin/prequest -d development.ini /
+    $VENV/bin/prequest -d development.ini /
 
 This will print the status, headers, and the body of the response to the
 console.
 
-You can add request header values by using the ``--header`` option::
+You can add request header values by using the ``--header`` option:
+
+.. code-block:: bash
 
-   $ $VENV/bin/prequest --header=Host:example.com development.ini /
+    $VENV/bin/prequest --header=Host:example.com development.ini /
 
 Headers are added to the WSGI environment by converting them to their CGI/WSGI
 equivalents (e.g., ``Host=example.com`` will insert the ``HTTP_HOST`` header
@@ -584,21 +647,11 @@ in the WSGI environment.
 By default, ``prequest`` sends a ``GET`` request.  You can change this by using
 the ``-m`` (aka ``--method``) option.  ``GET``, ``HEAD``, ``POST``, and
 ``DELETE`` are currently supported.  When you use ``POST``, the standard input
-of the ``prequest`` process is used as the ``POST`` body::
-
-   $ $VENV/bin/prequest -mPOST development.ini / < somefile
-
-
-Using Custom Arguments to Python when Running ``p*`` Scripts
-------------------------------------------------------------
-
-.. versionadded:: 1.5
+of the ``prequest`` process is used as the ``POST`` body:
 
-Each of Pyramid's console scripts (``pserve``, ``pviews``, etc.) can be run
-directly using ``python3 -m``, allowing custom arguments to be sent to the
-Python interpreter at runtime. For example::
+.. code-block:: bash
 
-      python3 -m pyramid.scripts.pserve development.ini
+    $VENV/bin/prequest -mPOST development.ini / < somefile
 
 
 .. index::
@@ -608,8 +661,8 @@ Python interpreter at runtime. For example::
 
 .. _showing_distributions:
 
-Showing All Installed Distributions and Their Versions
-------------------------------------------------------
+``pdistreport``: Showing All Installed Distributions and Their Versions
+-----------------------------------------------------------------------
 
 .. versionadded:: 1.5
 
@@ -618,17 +671,19 @@ Showing All Installed Distributions and Their Versions
 
 You can use the ``pdistreport`` command to show the :app:`Pyramid` version in
 use, the Python version in use, and all installed versions of Python
-distributions in your Python environment::
-
-   $ $VENV/bin/pdistreport
-   Pyramid version: 1.5dev
-   Platform Linux-3.2.0-51-generic-x86_64-with-debian-wheezy-sid
-   Packages:
-     authapp 0.0
-       /home/chrism/projects/foo/src/authapp
-     beautifulsoup4 4.1.3
-       /home/chrism/projects/foo/lib/python2.7/site-packages/beautifulsoup4-4.1.3-py2.7.egg
-   ... more output ...
+distributions in your Python environment:
+
+.. code-block:: bash
+
+    $VENV/bin/pdistreport
+    Pyramid version: 1.5dev
+    Platform Linux-3.2.0-51-generic-x86_64-with-debian-wheezy-sid
+    Packages:
+      authapp 0.0
+        /home/chrism/projects/foo/src/authapp
+      beautifulsoup4 4.1.3
+        /home/chrism/projects/foo/lib/python2.7/site-packages/beautifulsoup4-4.1.3-py2.7.egg
+    # ... more output ...
 
 ``pdistreport`` takes no options.  Its output is useful to paste into a
 pastebin when you are having problems and need someone with more familiarity
diff --git a/docs/pscripts/pcreate.rst b/docs/pscripts/pcreate.rst
index c48a70acd..e2c45626a 100644
--- a/docs/pscripts/pcreate.rst
+++ b/docs/pscripts/pcreate.rst
@@ -6,4 +6,4 @@
 .. autoprogram:: pyramid.scripts.pcreate:PCreateCommand.parser
     :prog: pcreate
 
-.. seealso:: :ref:`creating_a_project`
+.. seealso:: :ref:`creating_a_project` and :ref:`running-pscripts`.
diff --git a/docs/pscripts/pdistreport.rst b/docs/pscripts/pdistreport.rst
index b3c9dffd8..fa07f53ad 100644
--- a/docs/pscripts/pdistreport.rst
+++ b/docs/pscripts/pdistreport.rst
@@ -6,4 +6,4 @@
 .. autoprogram:: pyramid.scripts.pdistreport:get_parser()
     :prog: pdistreport
 
-.. seealso:: :ref:`showing_distributions`
+.. seealso:: :ref:`showing_distributions` and :ref:`running-pscripts`.
diff --git a/docs/pscripts/prequest.rst b/docs/pscripts/prequest.rst
index 64ed01739..3767506fb 100644
--- a/docs/pscripts/prequest.rst
+++ b/docs/pscripts/prequest.rst
@@ -6,4 +6,4 @@
 .. autoprogram:: pyramid.scripts.prequest:PRequestCommand.parser
     :prog: prequest
 
-.. seealso:: :ref:`invoking_a_request`
+.. seealso:: :ref:`invoking_a_request` and :ref:`running-pscripts`.
diff --git a/docs/pscripts/proutes.rst b/docs/pscripts/proutes.rst
index ee7c209e3..282ef327f 100644
--- a/docs/pscripts/proutes.rst
+++ b/docs/pscripts/proutes.rst
@@ -6,4 +6,4 @@
 .. autoprogram:: pyramid.scripts.proutes:PRoutesCommand.parser
     :prog: proutes
 
-.. seealso:: :ref:`displaying_application_routes`
+.. seealso:: :ref:`displaying_application_routes` and :ref:`running-pscripts`.
diff --git a/docs/pscripts/pserve.rst b/docs/pscripts/pserve.rst
index 991976aea..cc3c80c91 100644
--- a/docs/pscripts/pserve.rst
+++ b/docs/pscripts/pserve.rst
@@ -6,4 +6,4 @@
 .. autoprogram:: pyramid.scripts.pserve:PServeCommand.parser
     :prog: pserve
 
-.. seealso:: :ref:`running_the_project_application`
+.. seealso:: :ref:`running_the_project_application` and :ref:`running-pscripts`.
diff --git a/docs/pscripts/pshell.rst b/docs/pscripts/pshell.rst
index 4e2ce74cb..7c9050826 100644
--- a/docs/pscripts/pshell.rst
+++ b/docs/pscripts/pshell.rst
@@ -6,4 +6,4 @@
 .. autoprogram:: pyramid.scripts.pshell:PShellCommand.parser
     :prog: pshell
 
-.. seealso:: :ref:`interactive_shell`
+.. seealso:: :ref:`interactive_shell` and :ref:`running-pscripts`.
diff --git a/docs/pscripts/ptweens.rst b/docs/pscripts/ptweens.rst
index f586e1467..fe9c27abd 100644
--- a/docs/pscripts/ptweens.rst
+++ b/docs/pscripts/ptweens.rst
@@ -6,4 +6,4 @@
 .. autoprogram:: pyramid.scripts.ptweens:PTweensCommand.parser
     :prog: ptweens
 
-.. seealso:: :ref:`displaying_tweens`
+.. seealso:: :ref:`displaying_tweens` and :ref:`running-pscripts`.
diff --git a/docs/pscripts/pviews.rst b/docs/pscripts/pviews.rst
index da4660779..0726cb6aa 100644
--- a/docs/pscripts/pviews.rst
+++ b/docs/pscripts/pviews.rst
@@ -6,4 +6,4 @@
 .. autoprogram:: pyramid.scripts.pviews:PViewsCommand.parser
     :prog: pviews
 
-.. seealso:: :ref:`displaying_matching_views`
+.. seealso:: :ref:`displaying_matching_views` and :ref:`running-pscripts`.