Tweak manual pages

4 files changed, 118 insertions, 61 deletions

diff --git a/doc/man/crystfel_geometry.5 b/doc/man/crystfel_geometry.5
index c7b0ed0e..812b3c24 100644
--- a/doc/man/crystfel_geometry.5
+++ b/doc/man/crystfel_geometry.5
@@ -1,7 +1,7 @@
 .\"
 .\" Geometry man page
 .\"
-.\" Copyright © 2012-2014 Thomas White <taw@physics.org>
+.\" Copyright © 2012-2015 Thomas White <taw@physics.org>
 .\"
 .\" Part of CrystFEL - crystallography with a FEL
 .\"
@@ -13,7 +13,7 @@ CRYSTFEL DETECTOR GEOMETRY DESCRIPTION FILES
 .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
-\fBindexamajig\fR and \fBpattern_sim\fR take an argument
+\fBindexamajig\fR and \fBpattern_sim\fR) take an argument
 \fB--geometry=\fR\fIfilename\fR, where \fIfilename\fR contains the geometry.
 .PP
 A flexible (and pedantic) representation of the detector has been developed to
@@ -68,7 +68,7 @@ The geometry file should contain lines of the following form:
 You can also specify values without a panel name, for example:
 
 .IP
-peak_sep = 6.0
+clen = 0.560
 
 .PP
 In this case, the value will be used for all \fBsubsequent\fR panels appearing in the file which do not have their own specific values for the property, or until you specify another default value further down the file.  Panel-specific values always have priority over default values, and changing the default value has no effect for panels which had already be mentioned at the point in the file where the default value was specified.
@@ -94,27 +94,32 @@ The CrystFEL programs will look for the first event at /data/event1_name/rawdata
 .IP \fBdim\fIn\fR\fR
 .PD
 Information about the layout of the data block identified by the 'data' property. \fIn\fR is an integer number identifying an axis in a multidimensional HDF5 data block. The property value defines the kind of information encoded by the axis. Possible values are:
-.br
-% : event placeholder,the axis encodes events
-.br
-ss: the axis encodes the slow scan index
-.br
-fs: the axis encodes the fast scan index
-.br
-CrystFEL assumes that the data block defined by the 'data' property has a dimensionality equal to the axis with the highest value of \fIn\fR defined by the 'dim' property, and requires the user to provide information about each of the
-axes in the data block. When no 'dim' property is defined in the geometry file, CrystFEL assumes the data block to be 2-dimensional, with the two axes encoding slow scan and fast scan information respectively.
+.RS
+.IP %
+.PD
+event placeholder,the axis encodes events
+.IP ss
+.PD
+the axis encoding the slow scan index
+.IP fs
+.PD
+the axis encodes the fast scan index
+.RE
+.IP
+CrystFEL assumes that the data block defined by the 'data' property has a dimensionality equal to the axis with the highest value of \fIn\fR defined by the 'dim' property, and requires the user to provide information about each of the axes in the data block. When no 'dim' property is defined in the geometry file, CrystFEL assumes the data block to be 2-dimensional, with the two axes encoding slow scan and fast scan information respectively.
+Note that this means you can assign the fast scan coordinates to the slow scan axis of the data block, and vice versa!  This "quirk" helps backwards compatibility with geometry files from older versions of CrystFEL.
 
 Example:
-.br
-.br
+.RS
+.IP
 dim0 = %
-.br
+.IP
 dim1 = ss
-.br
+.IP
 dim2 = fs
-.br
-.br
-The data block is 3-dimensional. The first axis encodes events, the second the slow scan panel coordinate, and the third the fast scan panel coordinate
+.RE
+.IP
+The above snippet specifies that the data block is 3-dimensional. The first axis represents the event number, the second the slow scan panel coordinate, and the third the fast scan panel coordinate.
 
 .PD 0
 .IP \fBmin_fs\fR
@@ -216,19 +221,21 @@ badregionB/max_ss = 512
 
 .SH RIGID GROUPS AND RIGID GROUP COLLECTIONS
 
-Sometimes, some programs in CrystFEL need to treat a group of panels as a single rigid body. This often happens when the panels are physically connected (for example, a pair of adjacent ASICs in the CSPAD detector).
-Rigid groups can be defined in the geometry file by listing the panels belonging to each group and assigning the group a name.  At a higher level, collections of rigid groups can be defined when rigid groups belong to the same
-conceptual grouping scheme (for example, a collection of the four rigid groups defining quadrants in the CSPAD detector). Definitions of rigid groups and rigid groups collection can appear at any place in the geometry file and can be declared using the following global properties (these are not panel properties and don't follow the usual panel/property syntax):
-
-.PD 0
-.IP "\fBrigid_group_\fIname\fR = panel1 <, panel2> <, panel3> ...\fR"
-.PD
-This property defines the rigid group \fIname\fR, and lists the panels that belong to it
-
-.PD 0
-.IP "\fBrigid_group_collection_\fIname\fR = rigidgroup1 <, rigidgroup2> <, rigidgroup3> ...\fR"
-.PD
-This property defines the rigid group collection \fIname\fR, and lists the rigid groups that it contains
+Some operations in CrystFEL, such as refining the detector geometry, need a group of panels to be treated as a single rigid body.  Such "rigid groups" might describe the fact that certain panels are physically connected to one another, for example, a pair of adjacent ASICs in the CSPAD detector.  Rigid groups can be defined in the geometry file by listing the panels belonging to each group and assigning the group a name, like this:
+.RS
+.IP "\fBrigid_group_\fIname\fR = \fIpanel1\fR,\fIpanel2\fR"
+.RE
+.PP
+This creates a rigid group called \fIname\fR, containing panels \fIpanel1\fR and \fIpanel2\fR.
+.PP
+You can specify multiple sets of rigid groups.  For example, as well as specifying the relationships between pairs of ASICs mentioned above, you may also want to specify that certain groups of panels belong to an independently-movable quadrant of the detector.  You can declare and name such "rigid group collections" as follows:
+.RS
+.IP "\fBrigid_group_collection_\fIname\fR = \fIrigidgroup1\fR,\fIrigidgroup2\fR"
+.RE
+.PP
+This creates a rigid group collection called \fIname\fR, containing rigid groups \fIrigidgroup1\fR and \fIrigidgroup2\fR.
+.PP
+Definitions of rigid groups and rigid groups collection can appear at any place in the geometry file and can be declared using the following global properties.  They are not panel properties, and therefore don't follow the usual panel/property syntax.  You can assign any number of panels to a rigid group, and any number of rigid groups to a rigid group collection.  A panel can be a member of any number of rigid groups.
 
 .PP
 See the "examples" folder for some examples (look at the ones ending in .geom).
@@ -257,7 +264,7 @@ This page was written by Thomas White and Valerio Mariani.
 Report bugs to <taw@physics.org>, or visit <http://www.desy.de/~twhite/crystfel>.
 
 .SH COPYRIGHT AND DISCLAIMER
-Copyright © 2012-2014 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
+Copyright © 2012-2015 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
 .P
 CrystFEL is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
 .P
diff --git a/doc/man/geoptimiser.1 b/doc/man/geoptimiser.1
index 171ebb24..19ce4534 100644
--- a/doc/man/geoptimiser.1
+++ b/doc/man/geoptimiser.1
@@ -1,7 +1,7 @@
 .\"
 .\" geoptimiser man page
 .\"
-.\" Copyright © 2012-2014 Deutsches Elektronen-Synchrotron DESY,
+.\" Copyright © 2012-2015 Deutsches Elektronen-Synchrotron DESY,
 .\"                       a research centre of the Helmholtz Association.
 .\"
 .\" Part of CrystFEL - crystallography with a FEL
@@ -13,18 +13,14 @@ geoptimiser \- detector geometry refinement
 .SH SYNOPSIS
 .PP
 .BR geoptimiser
-\fB-i\fR \fIinput.stream\fR \fB-g\fR \fIinput.geom\fR \fB-o\fR \fIoutput.geom\fR \fB-c=\fR\fIconnected_rigidgroup_coll\fR \fB-q=\fR\quadrant_rigigroup_coll\fR
+\fB-i \fIinput.stream \fB-g \fIinput.geom \fB-o \fIoutput.geom \fB-c \fIconnected_rigidgroup_coll \fB-q \fI\quadrant_rigidgroup_coll\fR
 [\fBoptions\fR] \fB...\fR
 .PP
 \fBgeoptimiser --help\fR
 
 .SH DESCRIPTION
 
-\fBgeoptimiser\fR refines and optimizes the detector geometry by comparing the location of observed Bragg peaks in a set of indexed patterns with the spot locations predicted from
-the crystal indexing procedure. It can refine position, rotation and distance of each module ('panel') relative to the interaction region. It requires a stream file with indexed patterns,
-a geometry file with the detector geometry to refine, and some parameters to specify which modules are physically connected to each other and which are attached to the same physical support
-(for example, all panels in a quadrant of the CSPAD detector). The output is a geometry file with the optimized detector geometry and a set of diagnostic error maps in HDF5 format.
-Several options are available to tweak the number of peaks included in the optimization procedure based on a range of criteria.
+\fBgeoptimiser\fR refines and optimizes the detector geometry by comparing the locations of observed Bragg peaks in a set of indexed patterns with the spot locations predicted from the crystal indexing procedure. It can refine position, rotation and distance of each panel relative to the interaction region. It requires a stream file with indexed patterns, a geometry file with the detector geometry to refine, and some parameters to specify which panels are physically connected to each other and which are attached to the same physical support (for example, all panels in a quadrant of the CSPAD detector). The output is a geometry file with the optimized detector geometry and a set of diagnostic error maps in HDF5 format.  Several options are available to tweak the number of peaks included in the optimization procedure based on a range of criteria.
 For a complete description of the optimization algorithm, see the following paper:
 
 .IP
@@ -32,13 +28,7 @@ O. Yefanov, V. Mariani, C. Gati, T. A. White, H. N. Chapman, and A. Barty. "Accu
 
 .PP
 For minimal basic use, you need to provide a stream file with diffraction patterns, a geometry file to optimize, a filename for the output optimized geometry, and
-the name of two rigid group collections defined in the geometry file: one describing which modules in the detector are physically connected (and hence whose geometry should
-be optimized as if they were a single panel), and one to describe which modules are attached to the same underlying support (whose position and orientation are likely to be correlated).
-Here is what the minimal use might look like on the command line:
-
-.IP \fBgeoptimiser\fR
-.PD
--i input.stream -g input.geom -o output.geom -c connected_rg_coll_name -q same_support_rg_coll_name
+the name of two rigid group collections defined in the geometry file: one describing which panels in the detector are physically connected (and hence whose geometry should be optimized as if they were a single panel), and one to describe which panels are attached to the same underlying support (whose position and orientation are likely to be correlated).
 
 .PP
 See \fBman crystfel_geometry\fR for information on how to create a file describing the detector geometry, and guidelines to define the required rigid groups and rigid groups collections.
@@ -63,32 +53,34 @@ Read the detector geometry to optimize from the \fIfilename\fR file.
 Write the optimized detector geometry to \fIfilename\fR.
 
 .PD 0
-.IP "\fB-c\fR \fIname\fR"
-.IP \fB--connected=\fR\fIname\fR
+.IP "\fB-c \fIname\fR"
+.IP \fB--connected=\fIname\fR
 .PD
-Sets the rigid group collection for connected panels to \fIname\fR.  This rigid group collection describes how the panels are physically connected in the detector.
-A set of rigid groups must be defined in the geometry file, with each group containing only panels that are physically connected to each other (for example the pairs of physically-connected ASICs in the
-CSPAD detector). The rigid group collection chosen using this option must also be defined in the geometry file, and must collect all these groups.
+Specifies the name of the rigid group collection for connected panels.  This rigid group collection describes how the panels are physically connected in the detector.
+A set of rigid groups must be defined in the geometry file, with each group containing only panels that are physically connected to each other (for example the pairs of ASICs sharing the same piece of detector silicon in the CSPAD detector).
+.sp
+If a given rigid group is a member of \fIname\fR, then panels which are members of that rigid group will be kept strictly in the same relative position and orientation relative to one another.
 
 .PD 0
 .IP "\fB-q\fR \fIname\fR"
 .IP \fB--quadrants=\fR\fIname\fR
 .PD
-Sets the rigid group collection for quadrants to \fIname\fR.  This rigid group collection describes how panels are connected to the underlying support of the detector.
-A set of rigid groups must be defined in the geometry file, with each group containing only panels that are attached to the same underlying support (for example, all panels belonging to the same quadrant of the CSPAD detector).
-The rigid group collection chosen using this option must also be defined in the geometry file and must collect all these groups.
+Specifies the name of the rigid group collection for detector 'quadrants'.  This rigid group collection describes how panels are connected to the underlying support of the detector, for example, the panels belonging to the same quadrant of the CSPAD detector.
+.sp
+If a given rigid group is a member of \fIname\fR, then panels which are members of that rigid group and which do not contain enough peaks for positional refinement will be moved according to the average movement of the other panels in the group.
+
 
 .PD 0
 .IP "\fB-x\fR \fIn\fR"
 .IP \fB--min-num-peaks-per-pixel=\fR\fIn\fR
 .PD
-Sets to \fIn\fR the minimum number of peaks that should fall within a pixel, across all indexed patterns, to contribute to the geometry optimization. The default value is 3.
+Sets the minimum number of peaks that should fall within a pixel, across all indexed patterns, to contribute to the geometry optimization. The default value is 3.
 
 .PD 0
 .IP "\fB-p\fR \fIn\fR"
 .IP \fB--min-num-peaks-per-panel=\fR\fIn\fR
 .PD
-Sets to \fIn\fR the minimum number of peaks that should appear in a panel for the panel's geometry to be optimized independently. The default value is 100.
+Sets the minimum number of peaks that should appear in a panel for the panel's geometry to be optimized independently. The default value is 100.
 
 .PD 0
 .IP "\fB-l\fR"
@@ -117,13 +109,13 @@ to be included in the optimization process. The default maximum distance is 8 pi
 By default, geoptimiser refines the distance between the detector and the sample. This option turns off this optimization.
 
 .SH AUTHOR
-This page was written by Valerio Mariani and Oleksandr Yefanov.
+This page was written by Valerio Mariani, Oleksandr Yefanov and Thomas White.
 
 .SH REPORTING BUGS
 Report bugs to <taw@physics.org>, or visit <http://www.desy.de/~twhite/crystfel>.
 
 .SH COPYRIGHT AND DISCLAIMER
-Copyright © 2012-2014 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
+Copyright © 2012-2015 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
 .P
 geoptimiser, and this manual, are part of CrystFEL.
 .P
diff --git a/doc/man/indexamajig.1 b/doc/man/indexamajig.1
index 9d82dde5..f8178b54 100644
--- a/doc/man/indexamajig.1
+++ b/doc/man/indexamajig.1
@@ -334,7 +334,7 @@ Mark all pixels on the detector higher than \fIn\fR Angstroms as bad.  This migh
 
 .SH IDENTIFYING SINGLE PATTERNS IN THE INPUT FILE
 
-By default indexamajig processes all diffraction patterns ("events") in each of the data files listed in the input list. It is however, possible, to only process single events in a multi-event file, by adding in the list an event description string after the data filename. The event description always includes a first section with alphanumeric strings separated by forward slashes ("/") and a second section with integer numbers also separated by forward slashes. The two sections are in turn separated by a double forward slash ('//'). Any of the two sections can be empty, but the double forward slash separator must always be present.  Indexmamajig matches the strings and the numbers in the event description with the event placeholders ('%') present respectively in the 'data' and 'dim' properties defined in the geometry file, and tries to retrieve the full HDF path to the event data and the the its location in a multi-dimensional data space. Consider the following examples:
+By default indexamajig processes all diffraction patterns ("events") in each of the data files listed in the input list. It is however, possible, to only process single events in a multi-event file, by adding in the list an event description string after the data filename. The event description always includes a first section with alphanumeric strings separated by forward slashes ("/") and a second section with integer numbers also separated by forward slashes. The two sections are in turn separated by a double forward slash ('//'). Any of the two sections can be empty, but the double forward slash separator must always be present.  Indexamajig matches the strings and the numbers in the event description with the event placeholders ('%') present respectively in the 'data' and 'dim' properties defined in the geometry file, and tries to retrieve the full HDF path to the event data and the the its location in a multi-dimensional data space. Consider the following examples:
 
 Example 1:
 .br
@@ -392,7 +392,7 @@ This page was written by Thomas White.
 Report bugs to <taw@physics.org>, or visit <http://www.desy.de/~twhite/crystfel>.
 
 .SH COPYRIGHT AND DISCLAIMER
-Copyright © 2012-2014 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
+Copyright © 2012-2015 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
 .P
 indexamajig, and this manual, are part of CrystFEL.
 .P
diff --git a/doc/man/list_events.1 b/doc/man/list_events.1
new file mode 100644
index 00000000..d1e080e3
--- /dev/null
+++ b/doc/man/list_events.1
@@ -0,0 +1,58 @@
+.\"
+.\" list_events man page
+.\"
+.\" Copyright © 2015 Thomas White <taw@physics.org>
+.\"
+.\" Part of CrystFEL - crystallography with a FEL
+.\"
+
+.TH LIST_EVENTS 1
+.SH NAME
+list_events \- generate event lists
+.SH SYNOPSIS
+.PP
+\fBlist_events -i \fIfiles.lst \fB-o \fIevents.lst \fB-g \fIgeometry.geom
+.PP
+\fBlist_events --help\fI
+
+.SH DESCRIPTION
+list_events expands a list of filenames, where each file contains events in a multi-event format (e.g. the CXI format, http://www.cxidb.org/), into a list of individual events.
+
+.SH OPTIONS
+
+.IP "\fB-i \fIfilename\fR"
+.IP \fB--input=\fIfilename\fR
+.PD
+Read the list of input filenames from \fIfilename\fR.
+
+.IP "\fB-g \fIfilename\fR"
+.IP \fB--geometry=\fIfilename\fR
+.PD
+Read the data layout (and detector geometry) from \fIfilename\fR.
+
+.IP "\fB-o \fIfilename\fR"
+.IP \fB--output=\fIfilename\fR
+.PD
+Write the list of events to \fIfilename\fR.
+
+.SH AUTHOR
+This page was written by Thomas White.
+
+.SH REPORTING BUGS
+Report bugs to <taw@physics.org>, or visit <http://www.desy.de/~twhite/crystfel>.
+
+.SH COPYRIGHT AND DISCLAIMER
+Copyright © 2015 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
+.P
+list_events, and this manual, are part of CrystFEL.
+.P
+CrystFEL is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+.P
+CrystFEL is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+.P
+You should have received a copy of the GNU General Public License along with CrystFEL.  If not, see <http://www.gnu.org/licenses/>.
+
+.SH SEE ALSO
+.BR crystfel (7),
+.BR indexamajig (1),
+.BR crystfel_geometry (5)