Index: doc/guide/plugin.rst
===================================================================
--- doc/guide/plugin.rst	(revision 94bfa4260b733d3fccfaf1e8ee85838ce89b4230)
+++ doc/guide/plugin.rst	(revision 94bfa4260b733d3fccfaf1e8ee85838ce89b4230)
@@ -302,8 +302,8 @@
 
 **Note: The order of the parameters in the definition will be the order of the
-parameters in the user interface and the order of the parameters in Iq(),
-Iqac(), Iqabc() and form_volume(). And** *scale* **and** *background*
-**parameters are implicit to all models, so they do not need to be included
-in the parameter table.**
+parameters in the user interface and the order of the parameters in Fq(), Iq(),
+Iqac(), Iqabc(), form_volume() and shell_volume().
+And** *scale* **and** *background* **parameters are implicit to all models,
+so they do not need to be included in the parameter table.**
 
 - **"name"** is the name of the parameter shown on the FitPage.
@@ -374,6 +374,6 @@
     scattered intensity.
 
-  - "volume" parameters are passed to Iq(), Iqac(), Iqabc() and form_volume(),
-    and have polydispersity loops generated automatically.
+  - "volume" parameters are passed to Fq(), Iq(), Iqac(), Iqabc(), form_volume()
+    and shell_volume(), and have polydispersity loops generated automatically.
 
   - "orientation" parameters are not passed, but instead are combined with
@@ -503,4 +503,16 @@
 used.
 
+Hollow shapes, where the volume fraction of particle corresponds to the
+material in the shell rather than the volume enclosed by the shape, must
+also define a *shell_volume(par1, par2, ...)* function.  The parameters
+are the same as for *form_volume*.  The *I(q)* calculation should use
+*shell_volume* squared as its scale factor for the volume normalization.
+The structure factor calculation needs *form_volume* in order to properly
+scale the volume fraction parameter, so both functions are required for
+hollow shapes.
+
+Note: Pure python models do not yet support direct computation of the
+average of $F(q)$ and $F^2(q)$.
+
 Embedded C Models
 .................
@@ -514,5 +526,4 @@
 This expands into the equivalent C code::
 
-    #include <math.h>
     double Iq(double q, double par1, double par2, ...);
     double Iq(double q, double par1, double par2, ...)
@@ -523,4 +534,7 @@
 *form_volume* defines the volume of the shape. As in python models, it
 includes only the volume parameters.
+
+*form_volume* defines the volume of the shell for hollow shapes. As in
+python models, it includes only the volume parameters.
 
 **source=['fn.c', ...]** includes the listed C source files in the
@@ -559,4 +573,33 @@
 The INVALID define can go into *Iq*, or *c_code*, or an external C file
 listed in *source*.
+
+Structure Factors
+.................
+
+Structure factor calculations may need the underlying $<F(q)>$ and $<F^2(q)>$
+rather than $I(q)$.  This is used to compute $\beta = <F(q)>^2/<F^2(q)>$ in
+the decoupling approximation to the structure factor.
+
+Instead of defining the *Iq* function, models can define *Fq* as
+something like::
+
+    double Fq(double q, double *F1, double *F2, double par1, double par2, ...);
+    double Fq(double q, double *F1, double *F2, double par1, double par2, ...)
+    {
+        // Polar integration loop over all orientations.
+        ...
+        *F1 = 1e-2 * total_F1 * contrast * volume;
+        *F2 = 1e-4 * total_F2 * square(contrast * volume);
+        return I(q, par1, par2, ...);
+    }
+
+If the volume fraction scale factor is built into the model (as occurs for
+the vesicle model, for example), then scale *F1* by $\surd V_f$ so that
+$\beta$ is computed correctly.
+
+Structure factor calculations are not yet supported for oriented shapes.
+
+Note: only available as a separate C file listed in *source*, or within
+a *c_code* block within the python model definition file.
 
 Oriented Shapes
@@ -1023,10 +1066,11 @@
           "radius": 120., "radius_pd": 0.2, "radius_pd_n":45},
          0.2, 0.228843],
-        [{"radius": 120., "radius_pd": 0.2, "radius_pd_n":45}, "ER", 120.],
-        [{"radius": 120., "radius_pd": 0.2, "radius_pd_n":45}, "VR", 1.],
+        [{"radius": 120., "radius_pd": 0.2, "radius_pd_n":45},
+         0.1, None, None, 120., None, 1.],  # q, F, F^2, R_eff, V, form:shell
+        [{"@S": "hardsphere"}, 0.1, None],
     ]
 
 
-**tests=[[{parameters}, q, result], ...]** is a list of lists.
+**tests=[[{parameters}, q, Iq], ...]** is a list of lists.
 Each list is one test and contains, in order:
 
@@ -1040,7 +1084,13 @@
 - input and output values can themselves be lists if you have several
   $q$ values to test for the same model parameters.
-- for testing *ER* and *VR*, give the inputs as "ER" and "VR" respectively;
-  the output for *VR* should be the sphere/shell ratio, not the individual
-  sphere and shell values.
+- for testing effective radius, volume and form:shell volume ratio, use the
+  extended form of the tests results, with *None, None, R_eff, V, V_r*
+  instead of *Iq*.  This calls the kernel *Fq* function instead of *Iq*.
+- for testing F and F^2 (used for beta approximation) do the same as the
+  effective radius test, but include values for the first two elements,
+  $<F(q)>$ and $<F^2(q)>$.
+- for testing interaction between form factor and structure factor, specify
+  the structure factor name in the parameters as *{"@S": "name", ...}* with
+  the remaining list of parameters defined by the *P@S* product model.
 
 .. _Test_Your_New_Model:
