Add to the documentation

3 files changed, 67 insertions, 23 deletions

diff --git a/doc/man/crystfel_geometry.1 b/doc/man/crystfel_geometry.1
index 0deb058e..8a3f0903 100644
--- a/doc/man/crystfel_geometry.1
+++ b/doc/man/crystfel_geometry.1
@@ -7,10 +7,8 @@
 .\"
 
 .TH CRYSTFEL\_GEOMETRY 1
-.SH NAME
-CrystFEL detector geometry files
 
-.SH OVERVIEW
+.SH CRYSTFEL DETECTOR GEOMETRY FILES
 
 The detector geometry is taken from a text file rather than hardcoded into the
 program.  Programs which care about the geometry (particularly indexamajig,
@@ -37,7 +35,9 @@ of pixel values in the HDF5 file, defined in terms only of the "fast scan" and
 "slow scan" directions, and the laboratory coordinate system defined as follows:
 
 +z is the beam direction, and points along the beam (i.e. away from the source)
+.br
 +y points towards the zenith (ceiling).
+.br
 +x completes the right-handed coordinate system.
 
 Naively speaking, this means that CrystFEL at the images from the "into the
@@ -50,73 +50,119 @@ form:
 ; Lines which should be ignored start with a semicolon.
 
 ; The name before the slash indicates which panel is referred to.  You can use
+.br
 ; any name as long as it doesn't start with "bad" (see below).
+.br
 ; The range of pixels in the HDF5 file which correspond to a panel are given:
+.br
 panel0/min_fs = 0
+.br
 panel0/min_ss = 0
+.br
 panel0/max_fs = 193
+.br
 panel0/max_ss = 184
 
 ; The readout direction (x, y or 0).  If more than three peaks are found in
+.br
 ; the same readout region, they are all discarded.  This helps to avoid
+.br
 ; problems due to streaks appearing along the readout direction.
+.br
 ; If the badrow direction is '-', then the culling described above will not
+.br
 ; be performed for this panel.
+.br
 panel0/badrow_direction = -
 
 ; The resolution (in pixels per metre) for this panel
+.br
 panel0/res = 9090.91
 
 ; The characteristic peak separation in pixels.  The peak detection will assume
+.br
 ; that genuine peaks are separated by at least this amount.
+.br
 panel0/peak_sep = 6.0
 
 ; You need to specify the peak integration radius, which should be a little
+.br
 ; larger than the actual radii of the peaks in pixels
+.br
 panel0/integr_radius = 2.0
 
 ; The camera length (in metres) for this panel
+.br
 ; You can also specify the HDF path to a scalar floating point value containing
+.br
 ; the camera length in millimetres.
+.br
 panel0/clen = /LCLS/detectorPosition
 
 ; For this panel, the fast and slow scan directions correspond to the given
+.br
 ; directions in the lab coordinate system described above, measured in pixels.
+.br
 panel0/fs = +y
+.br
 panel0/ss = -x
 
 ; The corner of this panel, defined as the first point in the panel to appear in
+.br
 ; the HDF5 file, is now given a position in the lab coordinate system.
+.br
 ; Note that "first point in the panel" is a conceptual simplification.  We refer
+.br
 ; to that corner, and to the very corner of the pixel - NOT, for example, to the
+.br
 ; centre of the first pixel to appear.
+.br
 panel0/corner_x = 429.39
+.br
 panel0/corner_y = -17.30
 
 ; You can suppress indexing for this panel if required, by setting "no_index" to
+.br
 ; "true" or "1".
+.br
 panel0/no_index = 0
 
 ; You can also specify bad regions.  Peaks with centroid locations within such
+.br
 ; a region will not be integrated nor indexed.  Bad regions are specified in
+.br
 ; pixel units, but in the lab coordinate system (i.e. "y" points at the ceiling,
+.br
 ; "z" is the beam direction and "x" completes the right-handed system).
+.br
 badregionA/min_x = -20.0
+.br
 badregionA/max_x = +20.0
+.br
 badregionA/min_y = -100.0
+.br
 badregionA/max_y = +100.0
 
 ; If you have a bad pixel mask, you can include it in the HDF5 file as an
+.br
 ; unsigned 16-bit integer array of the same size as the data.  You need to
+.br
 ; give its path within each HDF5 file, and two bitmasks.  The pixel is
+.br
 ; considered good if all of the bits which are set in "mask_good" are set, AND
+.br
 ; if none of the bits which are set in "mask_bad" are set.
+.br
 mask = /processing/hitfinder/masks
+.br
 mask_good = 0x27
+.br
 mask_bad = 0x00
 
 ; Any of the per-panel values can be given without a panel prefix, for example:
+.br
 peak_sep = 6.0
+.br
 ; in which case the value will be used for all *subsequent* panels.
 
 
diff --git a/doc/man/indexamajig.1 b/doc/man/indexamajig.1
index fcb1afc4..501ed896 100644
--- a/doc/man/indexamajig.1
+++ b/doc/man/indexamajig.1
@@ -29,7 +29,11 @@ indexing, and that you'd like the program to output a list of intensities for
 each successfully indexed pattern.  Here is what the minimal use might look like
 on the command line:
 
-indexamajig -i mypatterns.lst -j 10 -g mygeometry.geom --indexing=mosflm,dirax --peaks=hdf5 --cell-reduction=reduce -b myxfel..beam -o test.stream -p mycell.pdb --record=integrated
+indexamajig -i mypatterns.lst -j 10 -g mygeometry.geom \
+.br
+            --indexing=mosflm,dirax --peaks=hdf5 --cell-reduction=reduce
+.br
+            -b myxfel.beam -o test.stream -p mycell.pdb --record=integrated
 
 More typical use includes all the above, but might also include a noise or
 common mode filter (--filter-noise or --filter-cm respectively) if detector
@@ -46,21 +50,16 @@ array, where the first two columns contain fast scan and slow scan coordinates
 at the given location.  The value will be spread in a small cross centred on
 that location.
 
-See doc/geometry for information about how to create a geometry description
-file.
+See `man crystfel_geometry' for information about how to create a geometry description file.
 
 You can control what information is included in the output stream using
 ' --record=<flags>'.  Possible flags are:
 
- pixels            Include a list of sums of pixel values within the
-                    integration domain, correcting for individual pixel
-                    solid angles.
-
  integrated        Include a list of reflection intensities, produced by
-                    integrating around predicted peak locations.
+                   integrating around predicted peak locations.
 
  peaks             Include peak locations and intensities from the peak
-                    search.
+                   search.
 
  peaksifindexed    As 'peaks', but only if the pattern could be indexed.
 
diff --git a/doc/man/pattern_sim.1 b/doc/man/pattern_sim.1
index d53aeae5..b9c8fa33 100644
--- a/doc/man/pattern_sim.1
+++ b/doc/man/pattern_sim.1
@@ -16,21 +16,20 @@ pattern\_sim \- Simulation of nanocrystallographic diffraction patterns
 
 .SH DESCRIPTION
 
-pattern_sim does not know about symmetry, so your input reflection list
-(give with "-i") must be expanded.  You can do this with:
+Pattern_sim simulaties diffraction patterns from small crystals probed with femtosecond pulses of X-rays from a free electron laser.  Typical use might be of the form:
 
-$ get_hkl -i myfile.hkl -o output.hkl -y mypointgroup -e 1
+pattern_sim -g mydetector.geom -b my.beam -p my.pdb -r -i myintensities.hkl
+
+The unit cell geometry will be taken from the CRYST1 line in the PDB file you provide, and the intensities of the reflections will be interpolated from the reflection list file you provide.  The reflection list format is the same as that output by process_hkl and handled by get_hkl.  You also need beam and geometry description files (-b and -g respectively).  See `man crystfel_geometry' for details of how to create a geometry file.  Examples of both files can be found in the installation directory, which is normally /usr/local/share/doc/crystfel.
 
-get_hkl does not currently understand symmetry, which means you'll have to
-expand any molecular model (the PDB) out to P1 to get the correct results.  You
-can achieve that, for example, by loading it into Mercury, turning on "Packing"
-and re-saving.  Alternatively, you can do this using CCP4 with a command like:
+The result will be written to an HDF5 file in the current directory with the name `sim.h5'.
 
-$ echo symgen P63 | pdbset xyzin model.pdb xyzout model-P1.pdb
+.SH REFLECTION LISTS
 
-While on this subject, you might also want to include hydrogens in the model
-using something like:
-$ echo HYDROGENS APPEND | hgen xyzin model.pdb xyzout model-with-H.pdb
+pattern_sim does not know about symmetry, so your input reflection list
+(give with "-i") must be expanded.  You can do this with:
+
+$ get_hkl -i myfile.hkl -o output.hkl -y mypointgroup -e 1
 
 Please be sure to read the "Note about Unit Cell Settings" in the documentation
 for indexamajig.