updated formatting of examples

murrayrm · murrayrm · commit b8aa47834e3d · 2020-01-01T14:10:40.000-08:00
diff --git a/doc/cruise-control.rst b/doc/cruise-control.rst
@@ -1,5 +1,5 @@
-Cruise control example from FBS
--------------------------------
+Cruise control design example (as a nonlinear I/O system)
+---------------------------------------------------------
 
 Code
 ....
diff --git a/doc/examples.rst b/doc/examples.rst
@@ -5,26 +5,39 @@
 Examples
 ********
 
+The source code for the examples below are available in the `examples/`
+subdirecory of the source code distribution.  The can also be accessed online
+via the [python-control GitHub repository](https://github.com/python-control/python-control/tree/master/examples).
+  
+
 Python scripts
 ==============
 
+The following Python scripts document the use of a variety of methods in the
+Python Control Toolbox on examples drawn from standard control textbooks and
+other sources.
+
 .. toctree::
    :maxdepth: 1
 
    secord-matlab
-   cruise-control
    pvtol-nested
    pvtol-lqr
    rss-balred
    phaseplots
    robust_siso
    robust_mimo
+   cruise-control
    steering-gainsched
    kincar-flatsys
 
 Jupyter notebooks
 =================
 
+The examples below use `python-control` in a Jupyter notebook environment.
+These notebooks demonstrate the use of modeling, anaylsis, and design tools
+using running examples in FBS2e.
+
 .. toctree::
    :maxdepth: 1
 
diff --git a/doc/kincar-flatsys.rst b/doc/kincar-flatsys.rst
@@ -1,6 +1,10 @@
 Differentially flat system - kinematic car
 ------------------------------------------
 
+This example demonstrates the use of the `flatsys` module for
+generating trajectories for differentially flat systems.  The example
+is drawn from Chapter 8 of FBS2e.
+
 Code
 ....
 .. literalinclude:: kincar-flatsys.py
diff --git a/doc/phaseplots.rst b/doc/phaseplots.rst
@@ -1,5 +1,5 @@
-Phase  plots
-------------
+Phase  plot examples
+--------------------
 
 Code
 ....
diff --git a/doc/pvtol-lqr.rst b/doc/pvtol-lqr.rst
@@ -1,5 +1,5 @@
-Planar vertical takeoff and landing (PVTOL) LQR controller
-----------------------------------------------------------
+LQR control design for vertical takeoff and landing aircraft
+------------------------------------------------------------
 
 This script demonstrates the use of the python-control package for
 analysis and design of a controller for a vectored thrust aircraft
diff --git a/doc/pvtol-nested.rst b/doc/pvtol-nested.rst
@@ -1,5 +1,5 @@
-Planar vertical takeoff and landing (PVTOL) nested controller
--------------------------------------------------------------
+Inner/outer control design for vertical takeoff and landing aircraft
+--------------------------------------------------------------------
 
 This script demonstrates the use of the python-control package for
 analysis and design of a controller for a vectored thrust aircraft
diff --git a/doc/rss-balred.rst b/doc/rss-balred.rst
@@ -1,5 +1,5 @@
-Balanced model reduction
-------------------------
+Balanced model reduction examples
+---------------------------------
 
 Code
 ....
diff --git a/doc/secord-matlab.rst b/doc/secord-matlab.rst
@@ -1,5 +1,8 @@
-Secord order system (MATLAB)
-----------------------------
+Secord order system (MATLAB module example)
+-------------------------------------------
+
+This example computes time and frequency responses for a second-order
+system using the MATLAB compatibility module.
 
 Code
 ....
diff --git a/examples/cruise.ipynb b/examples/cruise.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Feedback Examples: Cruise Control\n",
+    "# Cruise control\n",
     "\n",
     "Richard M. Murray and Karl J. Åström  \n",
     "17 Jun 2019\n",
diff --git a/examples/rss-balred.py b/examples/rss-balred.py
@@ -10,8 +10,8 @@
 
 plt.close('all')
 
-# controllable canonical realization computed in Matlab for the transfer function:
-# num = [1 11 45 32], den = [1 15 60 200 60]
+# controllable canonical realization computed in MATLAB for the
+# transfer function: num = [1 11 45 32], den = [1 15 60 200 60]
 A = np.array([
     [-15., -7.5, -6.25, -1.875],
     [8., 0., 0., 0.],
@@ -53,4 +53,3 @@
 
 if 'PYCONTROL_TEST_EXAMPLES' not in os.environ:
     plt.show()
-
diff --git a/examples/steering.ipynb b/examples/steering.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Vehicle Steering\n",
+    "# Vehicle steering\n",
     "Karl J. Astrom and Richard M. Murray  \n",
     "23 Jul 2019\n",
     "\n",

-Original file line number
+Diff line change
@@ @@ -1,5 +1,5 @@ @@
 -Cruise control example from FBS
 --------------------------------
 +Cruise control design example (as a nonlinear I/O system)
 +---------------------------------------------------------
 Code
 ....