Index: doc/developer/overview.rst
===================================================================
--- doc/developer/overview.rst	(revision da5536f0d03ab140552048df710e20a4d61bef14)
+++ doc/developer/overview.rst	(revision eda8b306f3ccd288f34d3e66c7fcf5754162bb2c)
@@ -165,4 +165,6 @@
 Further details are provided in the next section,
 :ref:`Calculator_Interface`
+
+.. _orientation_developer:
 
 Orientation and Numerical Integration
Index: doc/guide/orientation/orientation.rst
===================================================================
--- doc/guide/orientation/orientation.rst	(revision da5536f0d03ab140552048df710e20a4d61bef14)
+++ doc/guide/orientation/orientation.rst	(revision eda8b306f3ccd288f34d3e66c7fcf5754162bb2c)
@@ -42,5 +42,6 @@
 cylinder cross section. (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. Some experimentation may be required to
-understand the 2d patterns fully. A number of different shapes of distribution are available, as described for polydispersity.
+understand the 2d patterns fully. A number of different shapes of distribution are available, as described for 
+polydispersity, see :ref:`polydispersityhelp` .
 
 Earlier versions of SasView had numerical integration issues in some circumstances when 
@@ -52,9 +53,9 @@
 values of Npts and Nsigs, the number of steps used in the integration and the range spanned in number of standard deviations.
 The standard deviation is entered in units of degrees. For a rectangular (uniform) distribution the full width 
-should be $\pm\sqrt(3)$ ~ 1.73 standard deviations.
+should be $\pm\sqrt(3)$ ~ 1.73 standard deviations (this may be changed soon).
 
 Where appropriate, for best numerical results, keep $a < b < c$ and the $\theta$ distribution narrower than the $\phi$ distribution.
 
-Some more detailed technical notes are provided in the Developer section of this manual.
+Some more detailed technical notes are provided in the developer section of this manual :ref:`orientation_developer` .
     
 *Document History*
Index: doc/guide/pd/polydispersity.rst
===================================================================
--- doc/guide/pd/polydispersity.rst	(revision 1f058ea138185c6cca6e665e2b2fe668ace3e775)
+++ doc/guide/pd/polydispersity.rst	(revision eda8b306f3ccd288f34d3e66c7fcf5754162bb2c)
@@ -6,10 +6,12 @@
 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
 
+.. _polydispersityhelp:
+
 Polydispersity Distributions
 ----------------------------
 
-With some models in sasmodels we can calculate the average form factor for a
+With some models in sasmodels we can calculate the average intensity for a
 population of particles that exhibit size and/or orientational
-polydispersity. The resultant form factor is normalized by the average
+polydispersity. The resultant intensity is normalized by the average
 particle volume such that
 
Index: sasmodels/models/bcc_paracrystal.py
===================================================================
--- sasmodels/models/bcc_paracrystal.py	(revision 8f04da467b56e4e22291910958adebc417b57c19)
+++ sasmodels/models/bcc_paracrystal.py	(revision eda8b306f3ccd288f34d3e66c7fcf5754162bb2c)
@@ -65,11 +65,13 @@
     \end{array}
 
-**NB**: The calculation of $Z(q)$ is a double numerical integral that must
-be carried out with a high density of points to properly capture the sharp
-peaks of the paracrystalline scattering. So be warned that the calculation
-is SLOW. Go get some coffee. Fitting of any experimental data must be
-resolution smeared for any meaningful fit. This makes a triple integral.
-Very, very slow. Go get lunch!
+.. note::
 
+  The calculation of $Z(q)$ is a double numerical integral that
+  must be carried out with a high density of points to properly capture
+  the sharp peaks of the paracrystalline scattering.     
+  So be warned that the calculation is slow. Fitting of any experimental data 
+  must be resolution smeared for any meaningful fit. This makes a triple integral
+  which may be very slow.
+  
 This example dataset is produced using 200 data points,
 *qmin* = 0.001 |Ang^-1|, *qmax* = 0.1 |Ang^-1| and the above default values.
@@ -77,5 +79,7 @@
 The 2D (Anisotropic model) is based on the reference below where $I(q)$ is
 approximated for 1d scattering. Thus the scattering pattern for 2D may not
-be accurate.
+be accurate, particularly at low $q$. For general details of the calculation and angular 
+dispersions for oriented particles see :ref:`orientation` .
+Note that we are not responsible for any incorrectness of the 2D model computation.
 
 .. figure:: img/parallelepiped_angle_definition.png
Index: sasmodels/models/core_shell_parallelepiped.py
===================================================================
--- sasmodels/models/core_shell_parallelepiped.py	(revision 8f04da467b56e4e22291910958adebc417b57c19)
+++ sasmodels/models/core_shell_parallelepiped.py	(revision eda8b306f3ccd288f34d3e66c7fcf5754162bb2c)
@@ -85,14 +85,16 @@
 effective radius, for $S(Q)$ when $P(Q) * S(Q)$ is applied.
 
-To provide easy access to the orientation of the parallelepiped, we define the
-axis of the cylinder using three angles $\theta$, $\phi$ and $\Psi$.
-(see :ref:`cylinder orientation <cylinder-angle-definition>`).
-The angle $\Psi$ is the rotational angle around the *long_c* axis against the
-$q$ plane. For example, $\Psi = 0$ when the *short_b* axis is parallel to the
-*x*-axis of the detector.
+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.
 
 .. 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 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.
 
 .. figure:: img/parallelepiped_angle_projection.png
Index: sasmodels/models/cylinder.py
===================================================================
--- sasmodels/models/cylinder.py	(revision 31df0c91cf57174acd8e9cbe5f9caadffdc880ba)
+++ sasmodels/models/cylinder.py	(revision eda8b306f3ccd288f34d3e66c7fcf5754162bb2c)
@@ -54,8 +54,8 @@
 when $P(q) \cdot S(q)$ is applied.
 
-For oriented cylinders, we define the direction of the
+For 2d scattering from oriented cylinders, we define the direction of the
 axis of the cylinder using two angles $\theta$ (note this is not the
 same as the scattering angle used in q) and $\phi$. Those angles
-are defined in :numref:`cylinder-angle-definition` .
+are defined in :numref:`cylinder-angle-definition` , for further details see :ref:`orientation` .
 
 .. _cylinder-angle-definition:
@@ -63,7 +63,8 @@
 .. figure:: img/cylinder_angle_definition.png
 
-    Definition of the $\theta$ and $\phi$ orientation angles for a cylinder relative
-    to the beam line coordinates, plus an indication of their orientation distributions
-    which are described as rotations about each of the perpendicular axes $\delta_1$ and $\delta_2$
+    Angles $\theta$ and $\phi$ orient the cylinder relative
+    to the beam line coordinates, where the beam is along the $z$ axis. Rotation $\theta$, initially 
+    in the $xz$ plane, is carried out first, then rotation $\phi$ about the $z$ axis. Orientation distributions
+    are described as rotations about two perpendicular axes $\delta_1$ and $\delta_2$
     in the frame of the cylinder itself, which when $\theta = \phi = 0$ are parallel to the $Y$ and $X$ axes.
 
@@ -73,9 +74,4 @@
 
 The $\theta$ and $\phi$ parameters to orient the cylinder only appear in the model when fitting 2d data.
-On introducing "Orientational Distribution" in the angles, "distribution of theta" and "distribution of phi" parameters will
-appear. These are actually rotations about the axes $\delta_1$ and $\delta_2$ of the cylinder, which when $\theta = \phi = 0$ are parallel
-to the $Y$ and $X$ axes of the instrument respectively. Some experimentation may be required to understand the 2d patterns fully.
-(Earlier implementations had numerical integration issues in some circumstances when orientation distributions passed through 90 degrees, such
-situations, with very broad distributions, should still be approached with care.)
 
 Validation
Index: sasmodels/models/ellipsoid.py
===================================================================
--- sasmodels/models/ellipsoid.py	(revision 92708d848f008b10a92e0dbb50db7019836f02bb)
+++ sasmodels/models/ellipsoid.py	(revision eda8b306f3ccd288f34d3e66c7fcf5754162bb2c)
@@ -53,11 +53,11 @@
     r = R_e \left[ 1 + u^2\left(R_p^2/R_e^2 - 1\right)\right]^{1/2}
 
-To provide easy access to the orientation of the ellipsoid, we define
-the rotation axis of the ellipsoid using two angles $\theta$ and $\phi$.
-These angles are defined in the
+For 2d data from oriented ellipsoids the direction of the rotation axis of 
+the ellipsoid is defined using two angles $\theta$ and $\phi$ as for the 
 :ref:`cylinder orientation figure <cylinder-angle-definition>`.
 For the ellipsoid, $\theta$ is the angle between the rotational axis
 and the $z$ -axis in the $xz$ plane followed by a rotation by $\phi$
-in the $xy$ plane.
+in the $xy$ plane, for further details of the calculation and angular 
+dispersions see :ref:`orientation` .
 
 NB: The 2nd virial coefficient of the solid ellipsoid is calculated based
Index: sasmodels/models/elliptical_cylinder.py
===================================================================
--- sasmodels/models/elliptical_cylinder.py	(revision d9ec8f9cf8c3196125717d175f8a281d82eed86f)
+++ sasmodels/models/elliptical_cylinder.py	(revision eda8b306f3ccd288f34d3e66c7fcf5754162bb2c)
@@ -1,12 +1,4 @@
 # pylint: disable=line-too-long
 r"""
-Definition for 2D (orientated system)
--------------------------------------
-
-The angles $\theta$ and $\phi$ define the orientation of the axis of the
-cylinder. The angle $\Psi$ is defined as the orientation of the major
-axis of the ellipse with respect to the vector $Q$. A gaussian polydispersity
-can be added to any of the orientation angles, and also for the minor
-radius and the ratio of the ellipse radii.
 
 .. figure:: img/elliptical_cylinder_geometry.png
@@ -44,8 +36,5 @@
 
 
-Definition for 1D (no preferred orientation)
---------------------------------------------
-
-The form factor is averaged over all possible orientation before normalized
+For 1D scattering, with no preferred orientation, the form factor is averaged over all possible orientations and normalized
 by the particle volume
 
@@ -54,16 +43,15 @@
     P(q) = \text{scale}  <F^2> / V
 
-To provide easy access to the orientation of the elliptical cylinder, we
-define the axis of the cylinder using two angles $\theta$, $\phi$ and $\Psi$
-(see :ref:`cylinder orientation <cylinder-angle-definition>`). The angle
-$\Psi$ is the rotational angle around its own long_c axis.
+For 2d data the orientation of the particle is required, described using a different set 
+of angles as in the diagrams below, for further details of the calculation and angular 
+dispersions  see :ref:`orientation` .
 
-All angle parameters are valid and given only for 2D calculation; ie, an
-oriented system.
 
 .. figure:: img/elliptical_cylinder_angle_definition.png
 
-    Definition of angles for oriented elliptical cylinder, where axis_ratio is drawn >1,
-    and angle $\Psi$ is now a rotation around the axis of the cylinder.
+    Note that the angles here are not the same as in the equations for the scattering function.
+    Rotation $\theta$, initially in the $xz$ 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.
 
 .. figure:: img/elliptical_cylinder_angle_projection.png
@@ -73,10 +61,5 @@
 
 The $\theta$ and $\phi$ parameters to orient the cylinder only appear in the model when fitting 2d data.
-On introducing "Orientational Distribution" in the angles, "distribution of theta" and "distribution of phi" parameters will
-appear. These are actually rotations about the axes $\delta_1$ and $\delta_2$ of the cylinder, the $b$ and $a$ axes of the
-cylinder cross section. (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. Some experimentation may be required to
-understand the 2d patterns fully. (Earlier implementations had numerical integration issues in some circumstances when orientation
-distributions passed through 90 degrees, such situations, with very broad distributions, should still be approached with care.)
+
 
 NB: The 2nd virial coefficient of the cylinder is calculated based on the
Index: sasmodels/models/fcc_paracrystal.py
===================================================================
--- sasmodels/models/fcc_paracrystal.py	(revision 8f04da467b56e4e22291910958adebc417b57c19)
+++ sasmodels/models/fcc_paracrystal.py	(revision eda8b306f3ccd288f34d3e66c7fcf5754162bb2c)
@@ -64,14 +64,18 @@
     \end{array}
 
-**NB**: The calculation of $Z(q)$ is a double numerical integral that
-must be carried out with a high density of points to properly capture
-the sharp peaks of the paracrystalline scattering. So be warned that the
-calculation is SLOW. Go get some coffee. Fitting of any experimental data
-must be resolution smeared for any meaningful fit. This makes a triple
-integral. Very, very slow. Go get lunch!
+.. note::
+
+  The calculation of $Z(q)$ is a double numerical integral that
+  must be carried out with a high density of points to properly capture
+  the sharp peaks of the paracrystalline scattering.     
+  So be warned that the calculation is slow. Fitting of any experimental data 
+  must be resolution smeared for any meaningful fit. This makes a triple integral
+  which may be very slow.
 
 The 2D (Anisotropic model) is based on the reference below where $I(q)$ is
 approximated for 1d scattering. Thus the scattering pattern for 2D may not
-be accurate. Note that we are not responsible for any incorrectness of the
+be accurate particularly at low $q$. For general details of the calculation 
+and angular dispersions for oriented particles see :ref:`orientation` .
+Note that we are not responsible for any incorrectness of the
 2D model computation.
 
Index: sasmodels/models/parallelepiped.py
===================================================================
--- sasmodels/models/parallelepiped.py	(revision ca04add3266620969b29737a0578ec91730bc91c)
+++ sasmodels/models/parallelepiped.py	(revision eda8b306f3ccd288f34d3e66c7fcf5754162bb2c)
@@ -74,7 +74,7 @@
 $S(q)$ when $P(q) \cdot S(q)$ is applied.
 
-To provide easy access to the orientation of the parallelepiped, we define
-three angles $\theta$, $\phi$ and $\Psi$. The definition of $\theta$ and
-$\phi$ is the same as for the cylinder model (see also figures below).
+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:
@@ -89,13 +89,9 @@
 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 z-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 around $z$ and $\phi$ degrees around $y$,
-before doing a final rotation of $\Psi$ degrees around the resulting $C$ to
-obtain the final orientation of the parallelepiped.
-For example, for $\theta = 0$ and $\phi = 90$, we have that $\Psi = 0$
-corresponds to $A$ along $x$ and $B$ along $y$,
-while for $\theta = 90$ and $\phi = 0$, $\Psi = 0$ corresponds to
-$A$ along $z$ and $B$ along $x$.
+$\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:
@@ -114,7 +110,5 @@
 (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. (Earlier implementations had numerical integration issues in some circumstances when orientation
-distributions passed through 90 degrees, such situations, with very broad distributions, should still be approached with care.)
-
+understand the 2d patterns fully as discussed in :ref:`orientation` . 
 
 For a given orientation of the parallelepiped, the 2D form factor is
Index: sasmodels/models/sc_paracrystal.py
===================================================================
--- sasmodels/models/sc_paracrystal.py	(revision 8f04da467b56e4e22291910958adebc417b57c19)
+++ sasmodels/models/sc_paracrystal.py	(revision eda8b306f3ccd288f34d3e66c7fcf5754162bb2c)
@@ -73,13 +73,14 @@
     carried out with a high density of points to properly capture the sharp
     peaks of the paracrystalline scattering.
-    So be warned that the calculation is SLOW. Go get some coffee.
-    Fitting of any experimental data must be resolution smeared for any
-    meaningful fit. This makes a triple integral. Very, very slow.
-    Go get lunch!
+    So be warned that the calculation is slow. Fitting of any experimental data 
+    must be resolution smeared for any meaningful fit. This makes a triple integral
+    which may be very slow.
 
 The 2D (Anisotropic model) is based on the reference below where *I(q)* is
 approximated for 1d scattering. Thus the scattering pattern for 2D may not
-be accurate. Note that we are not responsible for any incorrectness of the 2D
-model computation.
+be accurate particularly at low $q$. For general details of the calculation 
+and angular dispersions for oriented particles see :ref:`orientation` .
+Note that we are not responsible for any incorrectness of the
+2D model computation.
 
 .. figure:: img/parallelepiped_angle_definition.png
Index: sasmodels/models/stacked_disks.py
===================================================================
--- sasmodels/models/stacked_disks.py	(revision 8f04da467b56e4e22291910958adebc417b57c19)
+++ sasmodels/models/stacked_disks.py	(revision eda8b306f3ccd288f34d3e66c7fcf5754162bb2c)
@@ -74,10 +74,14 @@
     the layers.
 
-To provide easy access to the orientation of the stacked disks, we define
-the axis of the cylinder using two angles $\theta$ and $\varphi$.
+2d scattering from oriented stacks is calculated in the same way as for cylinders,
+for further details of the calculation and angular dispersions see :ref:`orientation` . 
 
 .. figure:: img/cylinder_angle_definition.png
 
-    Examples of the angles against the detector plane.
+    Angles $\theta$ and $\phi$ orient the stack of discs relative
+    to the beam line coordinates, where the beam is along the $z$ axis. Rotation $\theta$, initially 
+    in the $xz$ plane, is carried out first, then rotation $\phi$ about the $z$ axis. Orientation distributions
+    are described as rotations about two perpendicular axes $\delta_1$ and $\delta_2$
+    in the frame of the cylinder itself, which when $\theta = \phi = 0$ are parallel to the $Y$ and $X$ axes.
 
 
