Index: sasmodels/models/core_shell_parallelepiped.py
===================================================================
--- sasmodels/models/core_shell_parallelepiped.py	(revision 96153e4bfa35f23278f5f9bdbe4d891544f8c683)
+++ sasmodels/models/core_shell_parallelepiped.py	(revision fc7bcd59db1fc447402feceb04fd32d3687db1fd)
@@ -8,6 +8,6 @@
 parallelepiped (strictly here a cuboid) may be given in *any* size order as
 long as the particles are randomly oriented (i.e. take on all possible
-orientations see notes on 2D below). To avoid multiple fit solutions, e
-specially with Monte-Carlo fit methods, it may be advisable to restrict their
+orientations see notes on 2D below). To avoid multiple fit solutions,
+especially with Monte-Carlo fit methods, it may be advisable to restrict their
 ranges. There may be a number of closely similar "best fits", so some trial and
 error, or fixing of some dimensions at expected values, may help.
@@ -17,5 +17,5 @@
 .. math::
 
-    I(q) = \frac{\text{scale}}{V} \langle P(q,\alpha,\beta) \rangle 
+    I(q) = \frac{\text{scale}}{V} \langle P(q,\alpha,\beta) \rangle
     + \text{background}
 
@@ -110,38 +110,43 @@
 ~~~~~~~~~~~~~
 
-There are many parameters in this model. Hold as many fixed as possible with
-known values, or you will certainly end up at a solution that is unphysical.
-
-
-NB: The 2nd virial coefficient of the core_shell_parallelepiped is calculated
-based on the the averaged effective radius $(=\sqrt{(A+2t_A)(B+2t_B)/\pi})$
-and length $(C+2t_C)$ values, after appropriately sorting the three dimensions
-to give an oblate or prolate particle, to give an effective radius
-for $S(q)$ when $P(q) * S(q)$ is applied.
-
-For 2d data the orientation of the particle is required, described using
-angles $\theta$, $\phi$ and $\Psi$ as in the diagrams below, for further details
-of the calculation and angular dispersions see :ref:`orientation` .
-
-The angle $\Psi$ is the rotational angle around the $C$ axis.
-For $\theta = 0$ and $\phi = 0$, $\Psi = 0$ corresponds to the $B$ axis
-oriented parallel to the y-axis of the detector with $A$ along the x-axis.
-For other $\theta$, $\phi$ values, the parallelepiped has to be first rotated
-$\theta$ degrees in the $z-x$ plane and then $\phi$ degrees around the $z$ axis,
-before doing a final rotation of $\Psi$ degrees around the resulting $C$ axis
-of the particle to obtain the final orientation of the parallelepiped.
+#. There are many parameters in this model. Hold as many fixed as possible with
+   known values, or you will certainly end up at a solution that is unphysical.
+
+#. The 2nd virial coefficient of the core_shell_parallelepiped is calculated
+   based on the the averaged effective radius $(=\sqrt{(A+2t_A)(B+2t_B)/\pi})$
+   and length $(C+2t_C)$ values, after appropriately sorting the three
+   dimensions to give an oblate or prolate particle, to give an effective radius
+   for $S(q)$ when $P(q) * S(q)$ is applied.
+
+#. For 2d data the orientation of the particle is required, described using
+   angles $\theta$, $\phi$ and $\Psi$ as in the diagrams below, where $\theta$
+   and $\phi$ define the orientation of the director in the laboratry reference
+   frame of the beam direction ($z$) and detector plane ($x-y$ plane), while
+   the angle $\Psi$ is effectively the rotational angle around the particle
+   $C$ axis. For $\theta = 0$ and $\phi = 0$, $\Psi = 0$ corresponds to the
+   $B$ axis oriented parallel to the y-axis of the detector with $A$ along
+   the x-axis. For other $\theta$, $\phi$ values, the order of rotations
+   matters. In particular, the parallelepiped must first be rotated $\theta$
+   degrees in the $x-z$ plane before rotating $\phi$ degrees around the $z$
+   axis (in the $x-y$ plane). Applying orientational distribution to the
+   particle orientation (i.e  `jitter` to one or more of these angles) can get
+   more confusing as `jitter` is defined **NOT** with respect to the laboratory
+   frame but the particle reference frame. It is thus highly recmmended to
+   read :ref:`orientation` for further details of the calculation and angular
+   dispersions.
 
 .. note:: For 2d, constraints must be applied during fitting to ensure that the
-   inequality $A < B < C$ is not violated, and hence the correct definition
-   of angles is preserved. The calculation will not report an error,
-   but the results may be not correct.
+   order of sides chosen is not altered, and hence that the correct definition
+   of angles is preserved. For the default choice shown here, that means
+   ensuring that the inequality $A < B < C$ is not violated,  The calculation
+   will not report an error, but the results may be not correct.
 
 .. figure:: img/parallelepiped_angle_definition.png
 
     Definition of the angles for oriented core-shell parallelepipeds.
-    Note that rotation $\theta$, initially in the $xz$ plane, is carried
+    Note that rotation $\theta$, initially in the $x-z$ plane, is carried
     out first, then rotation $\phi$ about the $z$ axis, finally rotation
-    $\Psi$ is now around the axis of the particle. The neutron or X-ray
-    beam is along the $z$ axis.
+    $\Psi$ is now around the $C$ axis of the particle. The neutron or X-ray
+    beam is along the $z$ axis and the detecotr defines the $x-y$ plane.
 
 .. figure:: img/parallelepiped_angle_projection.png
Index: sasmodels/models/parallelepiped.py
===================================================================
--- sasmodels/models/parallelepiped.py	(revision 96153e4bfa35f23278f5f9bdbe4d891544f8c683)
+++ sasmodels/models/parallelepiped.py	(revision fc7bcd59db1fc447402feceb04fd32d3687db1fd)
@@ -5,5 +5,5 @@
 ----------
 
-This model calculates the scattering from a rectangular parallelepiped
+This model calculates the scattering from a rectangular solid
 (:numref:`parallelepiped-image`).
 If you need to apply polydispersity, see also :ref:`rectangular-prism`. For
@@ -72,72 +72,10 @@
 applied.
 
-NB: The 2nd virial coefficient of the parallelepiped is calculated based on
-the averaged effective radius, after appropriately sorting the three
-dimensions, to give an oblate or prolate particle, $(=\sqrt{AB/\pi})$ and
-length $(= C)$ values, and used as the effective radius for
-$S(q)$ when $P(q) \cdot S(q)$ is applied.
-
-For 2d data the orientation of the particle is required, described using
-angles $\theta$, $\phi$ and $\Psi$ as in the diagrams below, for further details
-of the calculation and angular dispersions see :ref:`orientation` .
-
-The angle $\Psi$ is the rotational angle around the $C$ axis.
-For $\theta = 0$ and $\phi = 0$, $\Psi = 0$ corresponds to the $B$ axis
-oriented parallel to the y-axis of the detector with $A$ along the x-axis.
-For other $\theta$, $\phi$ values, the parallelepiped has to be first rotated
-$\theta$ degrees in the $z-x$ plane and then $\phi$ degrees around the $z$ axis,
-before doing a final rotation of $\Psi$ degrees around the resulting $C$ axis
-of the particle to obtain the final orientation of the parallelepiped.
-
-.. note:: For 2d, constraints must be applied during fitting to ensure that the
-   inequality $A < B < C$ is not violated, and hence the correct definition
-   of angles is preserved. The calculation will not report an error,
-   but the results may be not correct.
-   
-.. _parallelepiped-orientation:
-
-.. figure:: img/parallelepiped_angle_definition.png
-
-    Definition of the angles for oriented parallelepiped, shown with $A<B<C$.
-
-.. figure:: img/parallelepiped_angle_projection.png
-
-    Examples of the angles for an oriented parallelepiped against the
-    detector plane.
-
-On introducing "Orientational Distribution" in the angles, "distribution of
-theta" and "distribution of phi" parameters will appear. These are actually
-rotations about axes $\delta_1$ and $\delta_2$ of the parallelepiped,
-perpendicular to the $a$ x $c$ and $b$ x $c$ faces. (When $\theta = \phi = 0$
-these are parallel to the $Y$ and $X$ axes of the instrument.) The third
-orientation distribution, in $\psi$, is about the $c$ axis of the particle,
-perpendicular to the $a$ x $b$ face. Some experimentation may be required to
-understand the 2d patterns fully as discussed in :ref:`orientation` .
-
-For a given orientation of the parallelepiped, the 2D form factor is
-calculated as
-
-.. math::
-
-    P(q_x, q_y) = \left[\frac{\sin(\tfrac{1}{2}qA\cos\alpha)}{(\tfrac{1}
-                   {2}qA\cos\alpha)}\right]^2
-                  \left[\frac{\sin(\tfrac{1}{2}qB\cos\beta)}{(\tfrac{1}
-                   {2}qB\cos\beta)}\right]^2
-                  \left[\frac{\sin(\tfrac{1}{2}qC\cos\gamma)}{(\tfrac{1}
-                   {2}qC\cos\gamma)}\right]^2
-
-with
-
-.. math::
-
-    \cos\alpha &= \hat A \cdot \hat q, \\
-    \cos\beta  &= \hat B \cdot \hat q, \\
-    \cos\gamma &= \hat C \cdot \hat q
-
-and the scattering intensity as:
-
-.. math::
-
-    I(q_x, q_y) = \frac{\text{scale}}{V} V^2 \Delta\rho^2 P(q_x, q_y)
+For **oriented** particles, the 2D scattering intensity, $I(q_x, q_y)$, is
+given as:
+
+.. math::
+
+    I(q_x, q_y) = \frac{\text{scale}}{V} (\Delta\rho \cdot V)^2 P(q_x, q_y)
             + \text{background}
 
@@ -151,4 +89,81 @@
    with scale being the volume fraction.
 
+Where $P(q_x, q_y)$ for a given orientation of the form factor is calculated as
+
+.. math::
+
+    P(q_x, q_y) = \left[\frac{\sin(\tfrac{1}{2}qA\cos\alpha)}{(\tfrac{1}
+                   {2}qA\cos\alpha)}\right]^2
+                  \left[\frac{\sin(\tfrac{1}{2}qB\cos\beta)}{(\tfrac{1}
+                   {2}qB\cos\beta)}\right]^2
+                  \left[\frac{\sin(\tfrac{1}{2}qC\cos\gamma)}{(\tfrac{1}
+                   {2}qC\cos\gamma)}\right]^2
+
+with
+
+.. math::
+
+    \cos\alpha &= \hat A \cdot \hat q, \\
+    \cos\beta  &= \hat B \cdot \hat q, \\
+    \cos\gamma &= \hat C \cdot \hat q
+
+
+FITTING NOTES
+~~~~~~~~~~~~~
+
+#. The 2nd virial coefficient of the parallelepiped is calculated based on
+   the averaged effective radius, after appropriately sorting the three
+   dimensions, to give an oblate or prolate particle, $(=\sqrt{AB/\pi})$ and
+   length $(= C)$ values, and used as the effective radius for
+   $S(q)$ when $P(q) \cdot S(q)$ is applied.
+
+#. For 2d data the orientation of the particle is required, described using
+   angles $\theta$, $\phi$ and $\Psi$ as in the diagrams below, where $\theta$
+   and $\phi$ define the orientation of the director in the laboratry reference
+   frame of the beam direction ($z$) and detector plane ($x-y$ plane), while
+   the angle $\Psi$ is effectively the rotational angle around the particle
+   $C$ axis. For $\theta = 0$ and $\phi = 0$, $\Psi = 0$ corresponds to the
+   $B$ axis oriented parallel to the y-axis of the detector with $A$ along
+   the x-axis. For other $\theta$, $\phi$ values, the order of rotations
+   matters. In particular, the parallelepiped must first be rotated $\theta$
+   degrees in the $x-z$ plane before rotating $\phi$ degrees around the $z$
+   axis (in the $x-y$ plane). Applying orientational distribution to the
+   particle orientation (i.e  `jitter` to one or more of these angles) can get
+   more confusing as `jitter` is defined **NOT** with respect to the laboratory
+   frame but the particle reference frame. It is thus highly recmmended to
+   read :ref:`orientation` for further details of the calculation and angular
+   dispersions.
+
+.. note:: For 2d, constraints must be applied during fitting to ensure that the
+   order of sides chosen is not altered, and hence that the correct definition
+   of angles is preserved. For the default choice shown here, that means
+   ensuring that the inequality $A < B < C$ is not violated,  The calculation
+   will not report an error, but the results may be not correct.
+   
+.. _parallelepiped-orientation:
+
+.. figure:: img/parallelepiped_angle_definition.png
+
+    Definition of the angles for oriented parallelepiped, shown with $A<B<C$.
+
+.. figure:: img/parallelepiped_angle_projection.png
+
+    Examples of the angles for an oriented parallelepiped against the
+    detector plane.
+
+.. Comment by Paul Butler
+   I am commenting this section out as we are trying to minimize the amount of
+   oritentational detail here and encourage the user to go to the full
+   orientation documentation so that changes can be made in just one place.
+   below is the commented paragrah:
+   On introducing "Orientational Distribution" in the angles, "distribution of
+   theta" and "distribution of phi" parameters will appear. These are actually
+   rotations about axes $\delta_1$ and $\delta_2$ of the parallelepiped,
+   perpendicular to the $a$ x $c$ and $b$ x $c$ faces. (When $\theta = \phi = 0$
+   these are parallel to the $Y$ and $X$ axes of the instrument.) The third
+   orientation distribution, in $\psi$, is about the $c$ axis of the particle,
+   perpendicular to the $a$ x $b$ face. Some experimentation may be required to
+   understand the 2d patterns fully as discussed in :ref:`orientation` .
+
 
 Validation
@@ -158,5 +173,4 @@
 to the angular average of the output of a 2D calculation over all possible
 angles.
-
 
 References
