Index: sasmodels/models/core_shell_parallelepiped.c
===================================================================
--- sasmodels/models/core_shell_parallelepiped.c	(revision e0772316ffb087990c2e1b341c744594e3087097)
+++ sasmodels/models/core_shell_parallelepiped.c	(revision dbf1a60059f2daf9ef240db7a7fbf91cf5de9b9e)
@@ -59,17 +59,19 @@
 
     // outer integral (with gauss points), integration limits = 0, 1
+    // substitute d_cos_alpha for sin_alpha d_alpha
     double outer_sum = 0; //initialize integral
     for( int i=0; i<GAUSS_N; i++) {
         const double cos_alpha = 0.5 * ( GAUSS_Z[i] + 1.0 );
         const double mu = half_q * sqrt(1.0-cos_alpha*cos_alpha);
-
-        // inner integral (with gauss points), integration limits = 0, pi/2
         const double siC = length_c * sas_sinx_x(length_c * cos_alpha * half_q);
         const double siCt = tC * sas_sinx_x(tC * cos_alpha * half_q);
+
+        // inner integral (with gauss points), integration limits = 0, 1
+        // substitute beta = PI/2 u (so 2/PI * d_(PI/2 * beta) = d_beta)
         double inner_sum = 0.0;
         for(int j=0; j<GAUSS_N; j++) {
-            const double beta = 0.5 * ( GAUSS_Z[j] + 1.0 );
+            const double u = 0.5 * ( GAUSS_Z[j] + 1.0 );
             double sin_beta, cos_beta;
-            SINCOS(M_PI_2*beta, sin_beta, cos_beta);
+            SINCOS(M_PI_2*u, sin_beta, cos_beta);
             const double siA = length_a * sas_sinx_x(length_a * mu * sin_beta);
             const double siB = length_b * sas_sinx_x(length_b * mu * cos_beta);
@@ -91,8 +93,10 @@
             inner_sum += GAUSS_W[j] * f * f;
         }
+        // now complete change of inner integration variable (1-0)/(1-(-1))= 0.5
         inner_sum *= 0.5;
         // now sum up the outer integral
         outer_sum += GAUSS_W[i] * inner_sum;
     }
+    // now complete change of outer integration variable (1-0)/(1-(-1))= 0.5
     outer_sum *= 0.5;
 
Index: sasmodels/models/core_shell_parallelepiped.py
===================================================================
--- sasmodels/models/core_shell_parallelepiped.py	(revision 97be87700f140bc9317b791ad4691cc31fa30981)
+++ sasmodels/models/core_shell_parallelepiped.py	(revision f89ec96583ec917dee91d159ad08cdc6c4222b10)
@@ -4,6 +4,12 @@
 
 Calculates the form factor for a rectangular solid with a core-shell structure.
-The thickness and the scattering length density of the shell or
-"rim" can be different on each (pair) of faces.
+The thickness and the scattering length density of the shell or "rim" can be
+different on each (pair) of faces. The three dimensions of the core of the
+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,
+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.
 
 The form factor is normalized by the particle volume $V$ such that
@@ -11,47 +17,60 @@
 .. math::
 
-    I(q) = \text{scale}\frac{\langle f^2 \rangle}{V} + \text{background}
+    I(q) = \frac{\text{scale}}{V} \langle P(q,\alpha,\beta) \rangle
+    + \text{background}
 
 where $\langle \ldots \rangle$ is an average over all possible orientations
-of the rectangular solid.
-
-The function calculated is the form factor of the rectangular solid below.
-The core of the solid is defined by the dimensions $A$, $B$, $C$ such that
-$A < B < C$.
-
-.. image:: img/core_shell_parallelepiped_geometry.jpg
+of the rectangular solid, and the usual $\Delta \rho^2 \ V^2$ term cannot be
+pulled out of the form factor term due to the multiple slds in the model.
+
+The core of the solid is defined by the dimensions $A$, $B$, $C$ here shown
+such that $A < B < C$.
+
+.. figure:: img/parallelepiped_geometry.jpg
+
+   Core of the core shell parallelepiped with the corresponding definition
+   of sides.
+
 
 There are rectangular "slabs" of thickness $t_A$ that add to the $A$ dimension
 (on the $BC$ faces). There are similar slabs on the $AC$ $(=t_B)$ and $AB$
-$(=t_C)$ faces. The projection in the $AB$ plane is then
-
-.. image:: img/core_shell_parallelepiped_projection.jpg
-
-The volume of the solid is
+$(=t_C)$ faces. The projection in the $AB$ plane is
+
+.. figure:: img/core_shell_parallelepiped_projection.jpg
+
+   AB cut through the core-shell parallelipiped showing the cross secion of
+   four of the six shell slabs. As can be seen, this model leaves **"gaps"**
+   at the corners of the solid.
+
+
+The total volume of the solid is thus given as
 
 .. math::
 
     V = ABC + 2t_ABC + 2t_BAC + 2t_CAB
-
-**meaning that there are "gaps" at the corners of the solid.**
 
 The intensity calculated follows the :ref:`parallelepiped` model, with the
 core-shell intensity being calculated as the square of the sum of the
-amplitudes of the core and the slabs on the edges.
-
-the scattering amplitude is computed for a particular orientation of the
-core-shell parallelepiped with respect to the scattering vector and then
-averaged over all possible orientations, where $\alpha$ is the angle between
-the $z$ axis and the $C$ axis of the parallelepiped, $\beta$ is
-the angle between projection of the particle in the $xy$ detector plane
-and the $y$ axis.
-
-.. math::
-
-    F(Q)
+amplitudes of the core and the slabs on the edges. The scattering amplitude is
+computed for a particular orientation of the core-shell parallelepiped with
+respect to the scattering vector and then averaged over all possible
+orientations, where $\alpha$ is the angle between the $z$ axis and the $C$ axis
+of the parallelepiped, and $\beta$ is the angle between the projection of the
+particle in the $xy$ detector plane and the $y$ axis.
+
+.. math::
+
+    P(q)=\frac {\int_{0}^{\pi/2}\int_{0}^{\pi/2}F^2(q,\alpha,\beta) \ sin\alpha
+    \ d\alpha \ d\beta} {\int_{0}^{\pi/2} \ sin\alpha \ d\alpha \ d\beta}
+
+and
+
+.. math::
+
+    F(q,\alpha,\beta)
     &= (\rho_\text{core}-\rho_\text{solvent})
        S(Q_A, A) S(Q_B, B) S(Q_C, C) \\
     &+ (\rho_\text{A}-\rho_\text{solvent})
-        \left[S(Q_A, A+2t_A) - S(Q_A, Q)\right] S(Q_B, B) S(Q_C, C) \\
+        \left[S(Q_A, A+2t_A) - S(Q_A, A)\right] S(Q_B, B) S(Q_C, C) \\
     &+ (\rho_\text{B}-\rho_\text{solvent})
         S(Q_A, A) \left[S(Q_B, B+2t_B) - S(Q_B, B)\right] S(Q_C, C) \\
@@ -63,5 +82,5 @@
 .. math::
 
-    S(Q, L) = L \frac{\sin \tfrac{1}{2} Q L}{\tfrac{1}{2} Q L}
+    S(Q_X, L) = L \frac{\sin (\tfrac{1}{2} Q_X L)}{\tfrac{1}{2} Q_X L}
 
 and
@@ -69,50 +88,65 @@
 .. math::
 
-    Q_A &= \sin\alpha \sin\beta \\
-    Q_B &= \sin\alpha \cos\beta \\
-    Q_C &= \cos\alpha
+    Q_A &= q \sin\alpha \sin\beta \\
+    Q_B &= q \sin\alpha \cos\beta \\
+    Q_C &= q \cos\alpha
 
 
 where $\rho_\text{core}$, $\rho_\text{A}$, $\rho_\text{B}$ and $\rho_\text{C}$
-are the scattering length of the parallelepiped core, and the rectangular
+are the scattering lengths of the parallelepiped core, and the rectangular
 slabs of thickness $t_A$, $t_B$ and $t_C$, respectively. $\rho_\text{solvent}$
 is the scattering length of the solvent.
 
+.. note:: 
+
+   the code actually implements two substitutions: $d(cos\alpha)$ is
+   substituted for -$sin\alpha \ d\alpha$ (note that in the
+   :ref:`parallelepiped` code this is explicitly implemented with
+   $\sigma = cos\alpha$), and $\beta$ is set to $\beta = u \pi/2$ so that
+   $du = \pi/2 \ d\beta$.  Thus both integrals go from 0 to 1 rather than 0
+   to $\pi/2$.
+
 FITTING NOTES
 ~~~~~~~~~~~~~
 
-If the scale is set equal to the particle volume fraction, $\phi$, the returned
-value is the scattered intensity per unit volume, $I(q) = \phi P(q)$. However,
-**no interparticle interference effects are included in this calculation.**
-
-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 returned value is in units of |cm^-1|, on absolute scale.
-
-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 *long_c* axis. For example,
-$\Psi = 0$ when the *short_b* axis is parallel to the *x*-axis of the detector.
-
-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.
+#. 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
+   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 cylinder. 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
@@ -120,4 +154,13 @@
     Examples of the angles for oriented core-shell parallelepipeds against the
     detector plane.
+
+
+Validation
+----------
+
+Cross-checked against hollow rectangular prism and rectangular prism for equal
+thickness overlapping sides, and by Monte Carlo sampling of points within the
+shape for non-uniform, non-overlapping sides.
+
 
 References
@@ -135,9 +178,8 @@
 
 * **Author:** NIST IGOR/DANSE **Date:** pre 2010
-* **Converted to sasmodels by:** Miguel Gonzales **Date:** February 26, 2016
+* **Converted to sasmodels by:** Miguel Gonzalez **Date:** February 26, 2016
 * **Last Modified by:** Paul Kienzle **Date:** October 17, 2017
-* Cross-checked against hollow rectangular prism and rectangular prism for
-  equal thickness overlapping sides, and by Monte Carlo sampling of points
-  within the shape for non-uniform, non-overlapping sides.
+* **Last Reviewed by:** Paul Butler **Date:** May 24, 2018 - documentation
+  updated
 """
 
Index: sasmodels/models/parallelepiped.c
===================================================================
--- sasmodels/models/parallelepiped.c	(revision 108e70e22154db937a6d46f66be6dd70408cce6d)
+++ sasmodels/models/parallelepiped.c	(revision dbf1a60059f2daf9ef240db7a7fbf91cf5de9b9e)
@@ -38,4 +38,5 @@
             inner_total += GAUSS_W[j] * square(si1 * si2);
         }
+        // now complete change of inner integration variable (1-0)/(1-(-1))= 0.5
         inner_total *= 0.5;
 
@@ -43,4 +44,5 @@
         outer_total += GAUSS_W[i] * inner_total * si * si;
     }
+    // now complete change of outer integration variable (1-0)/(1-(-1))= 0.5
     outer_total *= 0.5;
 
Index: sasmodels/models/parallelepiped.py
===================================================================
--- sasmodels/models/parallelepiped.py	(revision ef07e950965796e2a3a8156fcade98ce5e403001)
+++ sasmodels/models/parallelepiped.py	(revision f89ec96583ec917dee91d159ad08cdc6c4222b10)
@@ -2,14 +2,12 @@
 # Note: model title and parameter table are inserted automatically
 r"""
-The form factor is normalized by the particle volume.
-For information about polarised and magnetic scattering, see
-the :ref:`magnetism` documentation.
-
 Definition
 ----------
 
- This model calculates the scattering from a rectangular parallelepiped
- (\:numref:`parallelepiped-image`\).
- If you need to apply polydispersity, see also :ref:`rectangular-prism`.
+This model calculates the scattering from a rectangular solid
+(:numref:`parallelepiped-image`).
+If you need to apply polydispersity, see also :ref:`rectangular-prism`. For
+information about polarised and magnetic scattering, see
+the :ref:`magnetism` documentation.
 
 .. _parallelepiped-image:
@@ -21,10 +19,13 @@
 
 The three dimensions of the parallelepiped (strictly here a cuboid) may be
-given in *any* size order. 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.
-
-The 1D scattering intensity $I(q)$ is calculated as:
+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, 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.
+
+The form factor is normalized by the particle volume and the 1D scattering
+intensity $I(q)$ is then calculated as:
 
 .. Comment by Miguel Gonzalez:
@@ -39,14 +40,16 @@
 
     I(q) = \frac{\text{scale}}{V} (\Delta\rho \cdot V)^2
-           \left< P(q, \alpha) \right> + \text{background}
+           \left< P(q, \alpha, \beta) \right> + \text{background}
 
 where the volume $V = A B C$, the contrast is defined as
-$\Delta\rho = \rho_\text{p} - \rho_\text{solvent}$,
-$P(q, \alpha)$ is the form factor corresponding to a parallelepiped oriented
-at an angle $\alpha$ (angle between the long axis C and $\vec q$),
-and the averaging $\left<\ldots\right>$ is applied over all orientations.
+$\Delta\rho = \rho_\text{p} - \rho_\text{solvent}$, $P(q, \alpha, \beta)$
+is the form factor corresponding to a parallelepiped oriented
+at an angle $\alpha$ (angle between the long axis C and $\vec q$), and $\beta$
+(the angle between the projection of the particle in the $xy$ detector plane
+and the $y$ axis) and the averaging $\left<\ldots\right>$ is applied over all
+orientations.
 
 Assuming $a = A/B < 1$, $b = B /B = 1$, and $c = C/B > 1$, the
-form factor is given by (Mittelbach and Porod, 1961)
+form factor is given by (Mittelbach and Porod, 1961 [#Mittelbach]_)
 
 .. math::
@@ -66,75 +69,13 @@
     \mu &= qB
 
-The scattering intensity per unit volume is returned in units of |cm^-1|.
-
-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` .
-
-.. Comment by Miguel Gonzalez:
-   The following text has been commented because I think there are two
-   mistakes. Psi is the rotational angle around C (but I cannot understand
-   what it means against the q plane) and psi=0 corresponds to a||x and b||y.
-
-   The angle $\Psi$ is the rotational angle around the $C$ axis against
-   the $q$ plane. For example, $\Psi = 0$ when the $B$ axis is parallel
-   to the $x$-axis of the detector.
-
-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.
-
-.. _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)
+where substitution of $\sigma = cos\alpha$ and $\beta = \pi/2 \ u$ have been
+applied.
+
+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}
 
@@ -148,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
@@ -156,11 +174,10 @@
 angles.
 
-
 References
 ----------
 
-P Mittelbach and G Porod, *Acta Physica Austriaca*, 14 (1961) 185-211
-
-R Nayuk and K Huber, *Z. Phys. Chem.*, 226 (2012) 837-854
+.. [#Mittelbach] P Mittelbach and G Porod, *Acta Physica Austriaca*,
+   14 (1961) 185-211
+.. [#] R Nayuk and K Huber, *Z. Phys. Chem.*, 226 (2012) 837-854
 
 Authorship and Verification
@@ -169,5 +186,6 @@
 * **Author:** NIST IGOR/DANSE **Date:** pre 2010
 * **Last Modified by:**  Paul Kienzle **Date:** April 05, 2017
-* **Last Reviewed by:**  Richard Heenan **Date:** April 06, 2017
+* **Last Reviewed by:**  Miguel Gonzales and Paul Butler **Date:** May 24,
+  2018 - documentation updated
 """
 
