More documentation work

6 files changed, 147 insertions, 17 deletions

diff --git a/doc/man/check_hkl.1 b/doc/man/check_hkl.1
index af830509..d01a8ecc 100644
--- a/doc/man/check_hkl.1
+++ b/doc/man/check_hkl.1
@@ -11,7 +11,61 @@
 check_hkl \- calculate figures of merit for reflection data
 .SH SYNOPSIS
 .PP
-.B check_hkl
-[options]
+\fBcheck_hkl\fR [\fIoptions\fR] \fB...\fR \fIfile.hkl\fR \fB-p\fR \fIcell.pdb\fR
 
 .SH DESCRIPTION
+check_hkl calculates figures of merit for reflection data, such as completeness and average signal strengths, in resolution shells.  check_hkl accepts a single reflection list in CrystFEL's format, and you must also provide a unit cell (in a PDB file).
+
+.SH OPTIONS
+.PD 0
+.IP \fB-p\fR \fIunitcell.pdb\fR
+.IP \fB--pdb=\fR\fIunitcell.pdb\fR
+.PD
+Specify the name of the PDB file containing at least a CRYST1 line describing the unit cell.
+
+.PD 0
+.IP \fB-y\fR \fpointgroup\fR
+.IP \fB--symmetry=\fR\fIpointgroup\fR
+.PD
+Specify the symmetry of the reflections.
+
+.PD 0
+.IP \fB--sigma-cutoff=\fR\fIn\fR
+.PD
+Discard reflections with I/sigma(I) < \fIn\fR.  Default: -infinity (no cutoff).
+
+.PD 0
+.IP \fB-p\fR \fIunitcell.pdb\fR
+.IP \fB--pdb=\fR\fIunitcell.pdb\fR
+.PD
+Specify the name of the PDB file containing at least a CRYST1 line describing the unit cell.
+
+.PD 0
+.IP \fB--rmin=\fR\fI1/d\fR
+.PD
+Fix the lower resolution limit for the resolutions shells, as 1/d in m^-1.
+
+.PD 0
+.IP \fB--rmax=\fR\fI1/d\fR
+.PD
+Fix the upper resolution limit for the resolutions shells, as 1/d in m^-1.
+
+.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
+check_hkl 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 compare_hkl (1)
diff --git a/doc/man/compare_hkl.1 b/doc/man/compare_hkl.1
index 3de81a01..c7a38ca7 100644
--- a/doc/man/compare_hkl.1
+++ b/doc/man/compare_hkl.1
@@ -11,7 +11,82 @@
 compare_hkl \- compare reflection data
 .SH SYNOPSIS
 .PP
-.B compare_hkl
-[options]
+compare_hkl \fR [\fIoptions\fR] \fB...\fR \fIfile1.hkl\fR \fIfile2.hkl\fR
 
 .SH DESCRIPTION
+compare_hkl compares two sets of reflection data and calculates figures of merit such as R-factors.  Several figures of merit will be displayed on the command line.  Figures of merit can also be calculated in resolution shells.  Reflections will be considered equivalent according to your choice of point group.  The ratios of the reflections can be written to a new file, perhaps to look for systematic effects.
+
+.SH OPTIONS
+.PD 0
+.IP \fB-y\fR \fpointgroup\fR
+.IP \fB--symmetry=\fR\fIpointgroup\fR
+.PD
+Specify the symmetry of the reflections.  The symmetry must be the same for both lists of reflections.  Default: 1 (no symmetry).
+
+.PD 0
+.IP \fB-p\fR \fIunitcell.pdb\fR
+.IP \fB--pdb=\fR\fIunitcell.pdb\fR
+.PD
+Specify the name of the PDB file containing at least a CRYST1 line describing the unit cell.
+
+.PD 0
+.IP \fB--rmin=\fR\fI1/d\fR
+.PD
+Fix the lower resolution limit for the resolutions shells, as 1/d in m^-1.  Reflections outside the specified resolution range will still be included in the calculation of overall figures of merit.
+
+.PD 0
+.IP \fB--rmax=\fR\fI1/d\fR
+.PD
+Fix the upper resolution limit for the resolutions shells, as 1/d in m^-1  Reflections outside the specified resolution range will still be included in the calculation of overall figures of merit.
+
+.PD 0
+.IP \fB--shells=\fR\fIFoM\fR
+.PD
+Calculate \fIFoM\fR in resolution shells.  Possible figures of merit for \fIFoM\fR are:
+.RS
+.IP \fBRsplit\fR
+.PD
+2^(-0.5) * sum(I1-kI2) / [ 0.5*sum(I1+kI2) ]
+.IP \fBR1f\fR
+.PD
+sum(F1-kF2) / sum(f1)
+.IP \fBR1i\fR
+.PD
+sum(I1-kI2) / sum(I1)
+.PP
+I1 and I2 are the intensities of the same reflection in both reflection lists.  F1 and F2 are the square roots of the intensities.  Negative intensity values are discarded if R1f is used.  The scale factor, k, is chosen to minimise the R-factor in all cases.
+.RE
+
+.PD 0
+.IP \fB-p\fR \fIunitcell.pdb\fR
+.IP \fB--pdb=\fR\fIunitcell.pdb\fR
+.PD
+Specify the name of the PDB file containing at least a CRYST1 line describing the unit cell.  This is required if \fB--shells\fR is used.
+
+.PD 0
+.IP \fB-o\fR \fIfilename\fR
+.IP \fB--ratio=\fR\fIfilename\fR
+.PD
+Write the ratios of the reflection intensities to \fIfilename\fR.  The ratio file will also be a CrystFEL reflection list (suitable for use with, for example, \fBrender_hkl\R), but the intensities column in the file will actually contain the ratios of intensities.
+
+.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
+compare_hkl 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 check_hkl (1)
+and
+.BR render_hkl (1)
diff --git a/doc/man/hdfsee.1 b/doc/man/hdfsee.1
index 1eff27ad..f71b9fa6 100644
--- a/doc/man/hdfsee.1
+++ b/doc/man/hdfsee.1
@@ -15,6 +15,8 @@ hdfsee - HDF5 image viewer
 
 .SH DESCRIPTION
 hdfsee is a simple image viewer for images stored in HDF5 files.
+.PP
+Most of the options that can be set on the command line can be changed via the user interface once the program is running.  The command line options are to help when running hdfsee from a script.
 
 .SH OPTIONS
 .PD 0
@@ -38,7 +40,7 @@ Show the image after binning down by a factor of \fIb\fR.
 .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.
+Get the image data to display from \fIpath\fR inside the HDF5 file.  For example: \fI/data/rawdata\fR.  If this is not specified, the default behaviour is to display the first two-dimensional dataset with both dimensions greater than 64.
 
 .PD 0
 .IP "\fB-g\fR \fIfilename\fR"
@@ -87,7 +89,7 @@ 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.
+hdfsee 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
diff --git a/src/check_hkl.c b/src/check_hkl.c
index bdcc838f..9473f9f6 100644
--- a/src/check_hkl.c
+++ b/src/check_hkl.c
@@ -53,9 +53,9 @@ static void show_help(const char *s)
 "\n"
 "  -h, --help                 Display this help message.\n"
 "  -y, --symmetry=<sym>       The symmetry of the input file.\n"
-"  -p, --pdb=<filename>       PDB file to use (default: molecule.pdb).\n"
-"      --rmin=<res>           Fix lower resolution limit for --shells (m^-1).\n"
-"      --rmax=<res>           Fix upper resolution limit for --shells (m^-1).\n"
+"  -p, --pdb=<filename>       PDB file to use.\n"
+"      --rmin=<res>           Fix lower resolution limit for resolution shells. (m^-1).\n"
+"      --rmax=<res>           Fix upper resolution limit for resolution shells. (m^-1).\n"
 "      --sigma-cutoff=<n>     Discard reflections with I/sigma(I) < n.\n"
 "\n");
 }
@@ -91,11 +91,6 @@ static void plot_shells(RefList *list, UnitCell *cell, const SymOpList *sym,
 	double bsx, bsy, bsz;
 	double csx, csy, csz;
 
-	if ( cell == NULL ) {
-		ERROR("Need the unit cell to plot resolution shells.\n");
-		return;
-	}
-
 	fh = fopen("shells.dat", "w");
 	if ( fh == NULL ) {
 		ERROR("Couldn't open 'shells.dat'\n");
@@ -382,7 +377,9 @@ int main(int argc, char *argv[])
 	file = strdup(argv[optind++]);
 
 	if ( pdb == NULL ) {
-		pdb = strdup("molecule.pdb");
+		ERROR("You need to provide a PDB file containing"
+		       " the unit cell.\n");
+		return 1;
 	}
 	cell = load_cell_from_pdb(pdb);
 	free(pdb);
diff --git a/src/compare_hkl.c b/src/compare_hkl.c
index 9d848fe1..3fc18fea 100644
--- a/src/compare_hkl.c
+++ b/src/compare_hkl.c
@@ -76,7 +76,7 @@ static void show_help(const char *s)
 "  -h, --help                 Display this help message.\n"
 "  -o, --ratio=<filename>     Specify output filename for ratios.\n"
 "  -y, --symmetry=<sym>       The symmetry of both the input files.\n"
-"  -p, --pdb=<filename>       PDB file to use (default: molecule.pdb).\n"
+"  -p, --pdb=<filename>       PDB file to use.\n"
 "      --shells=<FoM>         Plot this figure of merit in resolution shells.\n"
 "                              Choose from: 'Rsplit', 'R1f' and 'R1i'.\n"
 "      --rmin=<res>           Fix lower resolution limit for --shells (m^-1).\n"
diff --git a/src/render_hkl.c b/src/render_hkl.c
index ebb2947b..ceab672f 100644
--- a/src/render_hkl.c
+++ b/src/render_hkl.c
@@ -59,7 +59,7 @@ static void show_help(const char *s)
 "                           Default: 1,0,0.\n"
 "  -r, --right=<h>,<k>,<l> Indices for the axis in the 'right' (roughly)\n"
 "                           direction.  Default: 0,1,0.\n"
-"  -o, --output=<filename> Output filename (not for POV-ray).  Default: za.pdf\n"
+"  -o, --output=<filename> Output filename.  Default: za.pdf\n"
 "      --boost=<val>       Squash colour scale by <val>.\n"
 "  -p, --pdb=<file>        PDB file from which to get the unit cell.\n"
 "  -y, --symmetry=<sym>    Expand reflections according to point group <sym>.\n"
@@ -80,6 +80,8 @@ static void show_help(const char *s)
 "                                     reflection (no 'epsilon' correction).\n"
 "\n"
 "      --colour-key        Draw (only) the key for the current colour scale.\n"
+"                           The key will be written to 'key.pdf' in the\n"
+"                           current directory.\n"
 "\n"
 "  -h, --help              Display this help message.\n"
 );