Index: sasmodels/models/onion.py
===================================================================
--- sasmodels/models/onion.py	(revision 0507e09b26f5789862db8a175d64657cf4f3b829)
+++ sasmodels/models/onion.py	(revision 62dc8895694e8dcacf8cb65a82b543b1efa56f42)
@@ -6,6 +6,8 @@
 solvent. We currently provide up to 9 shells with this model.
 
-NB: *radius* represents the core radius $r_0$ and
-*thickness[k]* represents the thickness of the shell, $r_{k+1} - r_k$.
+.. note::
+
+    *radius* represents the core radius $r_0$ and *thickness[k]* represents 
+    the thickness of the shell, $r_{k+1} - r_k$.
 
 Definition
@@ -56,8 +58,10 @@
     j_1(x) = \frac{\sin(x)}{x^2} - \frac{\cos(x)}{x}
 
-and the volume is $V(r) = \frac{4\pi}{3}r^3$. The volume of the particle
-is determined by the radius of the outer shell, so $V_\text{particle} = V(r_N)$.
-
-Now lets consider the SLD of a shell defined by
+and the volume is $V(r) = \frac{4\pi}{3}r^3$.
+
+The volume of the particle is determined by the radius of the outer 
+shell, so $V_\text{particle} = V(r_N)$.
+
+Now consider the SLD of a shell defined by
 
 .. math::
@@ -74,5 +78,10 @@
 thickness of the $k^\text{th}$ shell in the equation above, respectively.
 
-For $A > 0$,
+.. figure:: img/onion_geometry.png
+
+    Example of an onion model profile.
+
+
+**Exponential SLD profiles** ($A > 0$ or $A < 0$):
 
 .. math::
@@ -87,5 +96,5 @@
         - 3CV(r_{\text{shell}-1}) \frac{j_1(\beta_\text{in})}{\beta_\text{in}}
 
-for
+where
 
 .. math::
@@ -95,22 +104,29 @@
     B&=\frac{\rho_\text{out} - \rho_\text{in}}{e^A-1}
          & C &= \frac{\rho_\text{in}e^A - \rho_\text{out}}{e^A-1} \\
+         
     \alpha_\text{in} &= A\frac{r_{\text{shell}-1}}{\Delta t_\text{shell}}
          & \alpha_\text{out} &= A\frac{r_\text{shell}}{\Delta t_\text{shell}} \\
+         
     \beta_\text{in} &= qr_{\text{shell}-1}
         & \beta_\text{out} &= qr_\text{shell} \\
     \end{align*}
 
-where $h$ is
+and
 
  .. math::
 
-    h(x,y) = \frac{x \sin(y) - y\cos(y)}{(x^2+y^2)y}
+     h(x,y) = \frac{x \sin(y) - y\cos(y)}{(x^2+y^2)y}
                - \frac{(x^2-y^2)\sin(y) - 2xy\cos(y)}{(x^2+y^2)^2y}
 
 
-For $A \sim 0$, e.g., $A = -0.0001$, this function converges to that of the
-linear SLD profile with
-$\rho_\text{shell}(r) \approx A(r-r_{\text{shell}-1})/\Delta t_\text{shell})+B$,
-so this case is equivalent to
+
+**Linear SLD profile** ($A \sim 0$):
+
+For small $A$, say, $A = -0.0001$, the function converges to that of of a linear 
+SLD profile with
+
+     $\rho_\text{shell}(r) \approx A(r-r_{\text{shell}-1})/\Delta t_\text{shell})+B$,
+
+which is equivalent to
 
 .. math::
@@ -140,5 +156,8 @@
     \end{align*}
 
-For $A = 0$, the exponential function has no dependence on the radius (so that
+
+**Constant SLD** ($A = 0$):
+
+When $A = 0$ the exponential function has no dependence on the radius (meaning 
 $\rho_\text{out}$ is ignored in this case) and becomes flat. We set the constant
 to $\rho_\text{in}$ for convenience, and thus the form factor contributed by
@@ -153,8 +172,4 @@
             \frac{j_1(qr_\text{in})}{qr_\text{in}}
 
-.. figure:: img/onion_geometry.png
-
-    Example of an onion model profile.
-
 The 2D scattering intensity is the same as $P(q)$ above, regardless of the
 orientation of the $q$ vector which is defined as
@@ -184,5 +199,5 @@
 * **Author:** 
 * **Last Modified by:** 
-* **Last Reviewed by:** 
+* **Last Reviewed by:** Steve King **Date:** March 28, 2019
 * **Source added by :** Steve King **Date:** March 25, 2019
 """
@@ -284,5 +299,5 @@
 
 description = """\
-Form factor of mutishells normalized by the volume. Here each shell is
+Form factor of multishells normalized by the volume. Here each shell is
 described by an exponential function;
 
@@ -297,5 +312,5 @@
 	II) For the exact point of A_shell == 0,
 		f(r) = sld_in ,i.e., it crosses over flat function
-	Note that the 'sld_out' becaomes NULL in this case.
+	Note that the 'sld_out' becomes NULL in this case.
 
 	background:background,
@@ -312,4 +327,7 @@
 # TODO: n is a volume parameter that is not polydisperse
 
+# NOTE: Joachim Wuttke has suggested an alternative parameterisation
+#       in Ticket #1107
+
 # pylint: disable=bad-whitespace, line-too-long
 #   ["name", "units", default, [lower, upper], "type","description"],
@@ -318,5 +336,5 @@
     ["radius_core", "Ang", 200., [0, inf], "volume", "Radius of the core"],
     ["sld_solvent", "1e-6/Ang^2", 6.4, [-inf, inf], "sld", "Solvent scattering length density"],
-    ["n_shells", "", 1, [0, 10], "volume", "number of shells"],
+    ["n_shells", "", 1, [0, 10], "volume", "number of shells (must be integer)"],
     ["sld_in[n_shells]", "1e-6/Ang^2", 1.7, [-inf, inf], "sld", "scattering length density at the inner radius of shell k"],
     ["sld_out[n_shells]", "1e-6/Ang^2", 2.0, [-inf, inf], "sld", "scattering length density at the outer radius of shell k"],
