Documentation update

7 files changed, 251 insertions, 66 deletions

diff --git a/Makefile.am b/Makefile.am
index 7b94dc3b..c99b1a23 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -98,8 +98,8 @@ crystfel_DATA = data/diffraction.cl data/hdfsee.ui
 
 EXTRA_DIST += $(crystfel_DATA)
 
-man_MANS = doc/man/check_hkl.1 doc/man/compare_hkl.1 \
-           doc/man/crystfel_geometry.1 doc/man/get_hkl.1 doc/man/hdfsee.1 \
+man_MANS = doc/man/crystfel.7 doc/man/check_hkl.1 doc/man/compare_hkl.1 \
+           doc/man/crystfel_geometry.5 doc/man/get_hkl.1 doc/man/hdfsee.1 \
            doc/man/indexamajig.1 doc/man/partialator.1 doc/man/partial_sim.1 \
            doc/man/pattern_sim.1 doc/man/powder_plot.1 doc/man/process_hkl.1 \
            doc/man/render_hkl.1
diff --git a/README b/README
index 4c2c3622..61cc9664 100644
--- a/README
+++ b/README
@@ -2,10 +2,11 @@ CrystFEL - Crystallography with a FEL
 -------------------------------------
 
 Copyright © 2012 Thomas White <taw@physics.org>
+Copyright © 2012 Richard Kirian <rkirian@asu.edu>
 Copyright © 2012 Andrew Aquila <andrew.aquila@cfel.de>
 Copyright © 2012 Andrew Martin <andrew.martin@desy.de>
 Copyright © 2012 Lorenzo Galli <lorenzo.galli@desy.de>
-Copyright © 2012 Richard Kirian <rkirian@asu.edu>
+
 Please read the AUTHORS file for a full list of contributions and contributors.
 See the COPYING file for licence conditions.  Summary: GPLv3+.
 
@@ -60,8 +61,6 @@ In addition, there is also:
 
 	- check_hkl, for determining things like completeness.
 
-	- calibrate_detector, for refining detector geometry.
-
 	- partial_sim, for calculating partial reflection intensities.
 
 
diff --git a/doc/man/crystfel.7 b/doc/man/crystfel.7
new file mode 100644
index 00000000..751261fb
--- /dev/null
+++ b/doc/man/crystfel.7
@@ -0,0 +1,113 @@
+.\"
+.\" CrystFEL main man page
+.\"
+.\" Copyright © 2012 Thomas White <taw@physics.org>
+.\"
+.\" Part of CrystFEL - crystallography with a FEL
+.\"
+
+.TH CRYSTFEL 7
+.SH NAME
+CrystFEL - data processing for FEL crystallography
+
+.SH DESCRIPTION
+CrystFEL is a suite of programs for processing Bragg diffraction data acquired with a free electron laser in a "serial" manner.  Some of the particular characteristics of such data which call for a specialised software suite are:
+
+.RS
+Each crystal is used for only one exposure, and there is no oscillation, rotation nor a large bandwidth or divergence.  Therefore, many or all reflections are partially integrated.
+.PP
+The crystals might be very small and the illumination highly coherent, leading to significant Fourier truncation effects on the detector.
+.PP
+Many patterns, numbering tens of thousands or more, are required, so high throughput automated processing is import.
+.PP
+The crystal orientations in each pattern are random and uncorrelated, which leads to special considerations during scaling and merging.
+.RE
+
+CrystFEL includes programs for simulating and processing patterns subject to the
+above characteristics.  Four programs form the core of CrystFEL.  They are:
+
+.IP \fBindexamajig\fR
+Batch indexing, integration and data reduction program, which produces a "stream" containing the indexing and integration results for each diffraction pattern.
+
+.IP \fBpattern_sim\fR
+A diffraction pattern simulation tool.
+
+.IP \fBprocess_hkl\fR
+A tool merging intensities from many patterns into a single reflection list, via the Monte Carlo method.
+
+.IP \fBpartialator\fR
+Full scaling and post-refinement process for accurate merging of data and outlier rejection.
+
+.PP
+In addition, there is also:
+
+.IP \fBget_hkl\fR
+A tool for manipulating reflection lists, such as performing symmetry expansion.
+
+.IP \fBpowder_plot\fR
+A tool for the calculation of one-dimensional "powder" traces.
+
+.IP \fBcompare_hkl\fR and \fBcheck_hkl\fR
+Tools for calculating figures of merit, such as completeness and R-factors.
+
+.IP \fBpartial_sim\fB
+A tool for calculating partial reflection intensities, perhaps for testing the convergence of Monte Carlo merging.
+
+.IP \fBhdfsee\fR
+A simple viewer for images stored in HDF5 format.
+
+.IP \fBrender_hkl\fR
+A tool for rendering slices of reciprocal space in two dimensions.
+
+.PP
+There is also a folder full of scripts for achieving many related tasks.
+
+.PP
+CrystFEL mostly works with images stored in HDF5 format, unit cell data in PDB
+format, and reflection lists in plain text format (i.e. not MTZ).  There are
+scripts for converting both ways between plain text reflection lists and MTZ
+files.
+
+.PP
+Please see the individual manual pages for the CrystFEL programs for detailed information.
+
+.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
+.PD 0
+Copyright © 2012 Thomas White <taw@physics.org>
+.LP
+Copyright © 2012 Richard Kirian <rkirian@asu.edu>
+.LP
+Copyright © 2012 Andrew Aquila <andrew.aquila@cfel.de>
+.LP
+Copyright © 2012 Andrew Martin <andrew.martin@desy.de>
+.LP
+Copyright © 2012 Lorenzo Galli <lorenzo.galli@desy.de>
+.PD
+.PP
+Please read the AUTHORS file in the CrystFEL source code distribution for a full list of contributions and contributors.
+.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 indexamajig (1),
+.BR process_hkl (1),
+.BR partialator (1),
+.BR pattern_sim (1),
+.BR partial_sim (1),
+.BR compare_hkl (1),
+.BR check_hkl (1),
+.BR render_hkl (1),
+.BR powder_plot (1),
+.BR hdfsee (1),
+.BR get_hkl (1),
+.BR crystfel_geometry (1).
diff --git a/doc/man/crystfel_geometry.1 b/doc/man/crystfel_geometry.5
index 708086ff..4b3b7aee 100644
--- a/doc/man/crystfel_geometry.1
+++ b/doc/man/crystfel_geometry.5
@@ -6,7 +6,7 @@
 .\" Part of CrystFEL - crystallography with a FEL
 .\"
 
-.TH CRYSTFEL\_GEOMETRY 1
+.TH CRYSTFEL\_GEOMETRY 5
 
 .SH CRYSTFEL DETECTOR GEOMETRY FILES
 
diff --git a/doc/man/hdfsee.1 b/doc/man/hdfsee.1
index 15bcdd51..1eff27ad 100644
--- a/doc/man/hdfsee.1
+++ b/doc/man/hdfsee.1
@@ -8,10 +8,94 @@
 
 .TH HDFSEE 1
 .SH NAME
-hdfsee \- HDF5 image viewer
+hdfsee - HDF5 image viewer
 .SH SYNOPSIS
 .PP
-.B hdfsee
-[options]
+.B hdfsee \fIimage.h5\fR [\fIoptions\fR] \fB...\fR
 
 .SH DESCRIPTION
+hdfsee is a simple image viewer for images stored in HDF5 files.
+
+.SH OPTIONS
+.PD 0
+.IP "\fB-p\fR \fIfilename\fR"
+.IP \fB--peak-overlay=\fR\fIfilename\fR
+.PD
+Peak locations will be read from \fIfilename\fR and displayed on the image.  The peak location file can use the format used in CrystFEL stream files for lists of integrated reflections, i.e. including the Miller indices.  If a line cannot be read using this format, it will be assumed to be a simple two-column list of fast scan and slow scan coordinates.  Any text beyond the second column will be ignored.  If the line cannot be read in either format, it will be ignored.
+
+.PD 0
+.IP \fB--ring-size=\fR\fIradius\fR
+.PD
+Set the radius of the rings used for displaying peak locations.  The radius is given in pixels on the screen, i.e. the circles are drawn \fIafter\fR binning the image data.
+
+.PD 0
+.IP "\fB-b\fR \fIb\fR"
+.IP \fB--binning=\fR\fIb\fR
+.PD
+Show the image after binning down by a factor of \fIb\fR.
+
+.PD 0
+.IP "\fB-e\fR \fIpath\fR"
+.IP \fB--image=\fR\fIpath\fR
+.PD
+Get the image data to display from \fIpath\fR inside the HDF5 file.  For example: \fI/data/rawdata\fR.
+
+.PD 0
+.IP "\fB-g\fR \fIfilename\fR"
+.IP \fB--geometry=\fR\fIfilename\fR
+.PD
+Display the image data according to the geometry description in \fIfilename\fR.  Out of plane components of the geometry will be ignored.  This is required, in addition to a wavelength in the HDF5 file (as /LCLS/photon_wavelength_nm or /LCLS/photon_wavelength_A), to display resolution rings.
+
+.PD 0
+.IP "\fB-i\fR \fIn\fR"
+.IP \fB--int-boost=\fR\fIn\fR
+.PD
+Multiply the intensity in the image by \fIn\fR before displaying.  With n=1, the top of the colour scale will represent the maximum pixel intensity found in the image.
+
+.PD 0
+.IP \fB--show-rings\fR
+.PD
+Show resolution rings on the image at 1 Angstrom intervals.
+
+.PD 0
+.IP \fB--simple-rings=\fR\fIradii\fR
+.PD
+Show rings on the image with the radii specified.  \fIradii\fR can be a comma-deliminated list of several values, for example \fI100,200\fR.  The radii have units of pixels on the detector before bininng.
+
+.PD 0
+.IP \fB-c\fR \fIscale\fR
+.IP \fB--colscale=\fR\fIscale\fR
+.PD
+Use \fIscale\fR as the colour scale.  Possible scales are: \fBmono\fR, \fBinvmono\fR and \fBcolour\fR.
+
+.PD 0
+.IP \fB--filter-cm\fR
+.PD
+Attempt to subtract common-mode noise from the image.
+
+.PD 0
+.IP \fB--filter-noise\fR
+.PD
+Apply a noise filter to the image with checks 3x3 squares of pixels and sets all of them to zero if any of the nine pixels have a negative value.
+
+.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
+Copyright © 2012 Thomas White <taw@physics.org>
+.P
+partial_sim is 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 pattern_sim (1)
+and
+.BR crystfel_geometry (5).
diff --git a/doc/man/partial_sim.1 b/doc/man/partial_sim.1
index ea786856..e8d608b4 100644
--- a/doc/man/partial_sim.1
+++ b/doc/man/partial_sim.1
@@ -11,33 +11,21 @@
 partial_sim \- calculate partial reflections
 .SH SYNOPSIS
 .PP
-.B partial_sim
--o simulated.stream -g geometry.geom -b xrays.beam -p unitcell.pdb
-.BR [options]
+.BR partial_sim
+\fB-o\fR \fIsimulated.stream\fR
+\fB-g\fR \fIgeometry.geom\fR
+\fB-b\fR \fIxrays.beam\fR
+\fB-p\fR \fIunitcell.pdb\fR
+[\fIoptions\fR] \fB...\fR
 
-.B partial_sim
---help
+.BR partial_sim
+\fB--help\fR
 
 .SH DESCRIPTION
 partial_sim calculates the intensities of idealised partial reflections from crystals in random orientations, which is useful for testing the convergence of Monte Carlo integration or scaling/post-refinement techniques.
 
 .P
-You need to provide a CrystFEL geometry file (with
-.BR --geometry=my.geom
-or
-.BR "-g my.geom" ),
-a beam description file (with
-.BR --beam=my.beam
-or
-.BR "-b my.beam" ),
-a PDB file containing at least a CRYST1 line specifying the unit cell to use for the simulation (with
-.BR --pdb=my.pdb
-or
-.BR "-p my.pdb" ),
-and an output filename with
-.BR --output=my.stream
-or
-.BR "-o my.stream" .
+You need to provide a CrystFEL geometry file (with \fB--geometry=\fR\fImy.geom\fR or \fB-g\fR \fImy.geom\fR), a beam description file (with \fB--beam=\fR\fImy.beam\fR or \fB-b\fR \fImy.beam\fR), a PDB file containing at least a CRYST1 line specifying the unit cell to use for the simulation (with \fB--pdb=\fR\fImy.pdb\fR or \fB-p\fR \fImy.pdb\fR), and an output filename with \fB--output=\fR\fImy.stream\fR or \fB-o\fR \fImy.stream\fR.
 
 For each randomly generated orientation, partial_sim calculates which reflections would appear on the detector with the specified beam parameters.  It calculates the partiality for each reflection and multiplies it by the fully integrated intensity to produce a partial intensity.  The fully integrated intensities can be taken from a file you provide (see below), otherwise they will be randomly generated (by taking the absolute value of a Gaussian random number, mean zero and standard deviation 1000).  All the partial intensities for the orientation are multiplied by an overall scaling factor, which is randomly generated with a Gaussian distribution with mean 1 and standard deviation 0.3.  The partial intensities are written to the output stream, and the process repeated for as many different orientations as you ask for (see below, default: 2).
 
@@ -49,43 +37,39 @@ for information about CrystFEL geometry description files.
 .SH OPTIONS
 .PD 0
 .B
-.IP "-i <file.hkl>"
+.IP "-i \fIfile.hkl\fR"
 .B
-.IP --input=<file.hkl>
+.IP --input=\fIfile.hkl\fR
 .PD
-Take the fully integrated reflection intensities from <file.hkl>, instead of generating them randomly.
+Take the fully integrated reflection intensities from \fIfile.hkl\fR, instead of generating them randomly.
 
 .B
-.IP -n <n>
+.IP -n \fIn\fR
 Specify the number of different orientations to simulate.  Default: 2.
 
 .PD 0
 .B
-.IP "-r <random.hkl>"
+.IP "-r \fIrandom.hkl\fR"
 .B
-.IP --save-random=<random.hkl>
+.IP --save-random=\fIrandom.hkl\fR
 .PD
 If you did not provide your own fully integrated reflection intensities, they will be generated randomly for you.  Use this option to save the random intensities for future comparisons.
 
 .PD 0
 .B
-.IP "-y <pointgroup>"
+.IP "\fB-y\fR \fIpointgroup\fR"
 .B
-.IP --symmetry=<pointgroup>
+.IP \fB--symmetry=\fR\fIpointgroup\fR
 .PD
-Specifies the symmetry of the input reflection list (with
-.B -i ,
-or the symmetry of the randomly generated intensities.
+When combined with with \fB-i\fR, specifies the symmetry of the input reflection list.  Otherwise, specifies the symmetry of the randomly generated intensities.
 
 .PD 0
 .B
-.IP "-c <val>"
+.IP "\fB-c\fR \fIval\fR"
 .B
-.IP "--cnoise=<val>
+.IP "\fB--cnoise=\fR\fIval\fR
 .PD
-Add random values with a flat distribution to the components of the reciprocal lattice vectors written to the stream, simulating indexing errors.  The maximum value that will be added is +/-
-.BR <val>
-percent.
+Add random values with a flat distribution to the components of the reciprocal lattice vectors written to the stream, simulating indexing errors.  The maximum value that will be added is +/- \fIval\fR percent.
 
 .SH AUTHOR
 This page was written by Thomas White.
@@ -93,7 +77,7 @@ 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
+.SH COPYRIGHT AND DISCLAIMER
 Copyright © 2012 Thomas White <taw@physics.org>
 .P
 partial_sim is part of CrystFEL.
@@ -107,6 +91,5 @@ You should have received a copy of the GNU General Public License along with Cry
 .SH SEE ALSO
 .BR process_hkl (1),
 .BR partialator (1),
-.BR pattern_sim (1)
-and
-.BR crystfel_geometry (1).
+.BR pattern_sim (1),
+.BR crystfel_geometry (5).
diff --git a/doc/man/powder_plot.1 b/doc/man/powder_plot.1
index df185d61..9a1151fa 100644
--- a/doc/man/powder_plot.1
+++ b/doc/man/powder_plot.1
@@ -12,27 +12,30 @@ powder_plot \- generate 1D powder patterns
 .SH SYNOPSIS
 .PP
 .B powder_plot
--i <input.{hkl,h5,stream}> -o <output.dat>
-[--min=<1/d> --max=<1/d>]
+\fB-i\fR \fIinput.hkl\fR | \fB-i\fR \fIinput.h5\fR | \fB-i\fR \fIinput.stream\fR
+\fB-o\fR \fIoutput.dat\fR
+[\fB--min=\fR\fI1/d\fR \fB--max=\fR\fI1/d\fR]
+[\fIoptions\fR\] \fB...\fR
 
 .PP
-.B powder_plot
--i file.hkl [..] [--use-redundancy] [--no-d-scaling]
+.BR powder_plot
+\fB-i\fR \fIfile.hkl\fR [\fIoptions\fR\] \fB...\fR [\fB--use-redundancy\fR] [\fB--no-d-scaling\fR]
 
 .PP
-.B powder\_plot
--i file.h5 [..] -g <geometry.geom> -b <beam.beam> [--no-sat-corr]
-[--ring-corr]
+.BR powder_plot
+\fB-i\fR \fIfile.h5\fR [\fIoptions\fR\] \fB...\fR
+\fB-g\fR \fIgeometry.geom\fR
+\fB-b\fR \fIbeam.beam\fR [\fB--no-sat-corr\fR] [\fB--ring-corr\fR]
 
 .PP
-.B powder_plot
--i file.stream [..] --data=<type>
-[-g <geometry.geom>] [-b <beam.beam>] [--no-sat-corr] [--only-indexed]
-[--use-redundancy] [--ring-corr] [--no-d-scaling]
+.BR powder_plot
+\fB-i\fR \fIfile.stream\fR [\fIoptions\fR\] \fB...\fR --data=\fItype\fR
+[-g \fIgeometry.geom\fR] [-b \fIbeam.beam\fR] [\fB--no-sat-corr\fR] [\fB--only-indexed\fR]
+[\fB--use-redundancy\fR] [\fB--ring-corr\fR] [\fB--no-d-scaling\fR]
 
 .PP
-.B powder_plot
---help
+.BR powder_plot
+\fB--help\fR
 
 .SH DESCRIPTION
 
@@ -126,9 +129,12 @@ This page was written by Andrew Aquila and Thomas White.
 .SH REPORTING BUGS
 Report bugs to <taw@physics.org>, or visit <http://www.desy.de/~twhite/crystfel>.
 
-.SH COPYRIGHT
+.SH COPYRIGHT AND DISCLAIMER
 Copyright © 2012 Andrew Aquila <andrew.aquila@cfel.de>
+.PD 0
+.LP
 Copyright © 2012 Thomas White <taw@physics.org>
+.PD
 .P
 powder_plot is part of CrystFEL.
 .P
@@ -141,6 +147,6 @@ You should have received a copy of the GNU General Public License along with Cry
 .SH SEE ALSO
 .BR indexamajig (1),
 .BR process_hkl (1),
-.BR check_hkl (1)
-and
+.BR check_hkl (1),
+.BR crystfel_geometry (5),
 .BR render_hkl (1) .