Move documentation to manpages

7 files changed, 74 insertions, 131 deletions

diff --git a/doc/0-INDEX b/doc/0-INDEX
deleted file mode 100644
index 7bf5aec7..00000000
--- a/doc/0-INDEX
+++ /dev/null
@@ -1,22 +0,0 @@
-Index to the CrystFEL documentation
------------------------------------
-
-quickstart.txt
-	Basic usage information and suggested workflow.
-
-indexamajig.txt
-pattern_sim.txt
-process_hkl.txt
-	Information about the individual programs and their use.
-
-geometry.txt
-	Information about detector geometry description files.
-
-twin-calculator.pdf
-	Symmetry tables (in two formats).
-
-symmetry.txt
-	How CrystFEL uses symmetry.
-
-examples/
-	Contains example geometry files.
diff --git a/doc/geometry.txt b/doc/man/crystfel_geometry.1
index c215d27c..0deb058e 100644
--- a/doc/geometry.txt
+++ b/doc/man/crystfel_geometry.1
@@ -1,5 +1,16 @@
+.\"
+.\" Geometry man page
+.\"
+.\" (c) 2009-2011 Thomas White <taw@physics.org>
+.\"
+.\" Part of CrystFEL - crystallography with a FEL
+.\"
+
+.TH CRYSTFEL\_GEOMETRY 1
+.SH NAME
 CrystFEL detector geometry files
---------------------------------
+
+.SH OVERVIEW
 
 The detector geometry is taken from a text file rather than hardcoded into the
 program.  Programs which care about the geometry (particularly indexamajig,
diff --git a/doc/indexamajig.txt b/doc/man/indexamajig.1
index c7097851..fcb1afc4 100644
--- a/doc/indexamajig.txt
+++ b/doc/man/indexamajig.1
@@ -1,5 +1,20 @@
-indexamajig - bulk indexing and data reduction program
-------------------------------------------------------
+.\"
+.\" indexamajig man page
+.\"
+.\" (c) 2009-2011 Thomas White <taw@physics.org>
+.\"
+.\" Part of CrystFEL - crystallography with a FEL
+.\"
+
+.TH INDEXAMAJIG 1
+.SH NAME
+indexamajig \- bulk indexing and data reduction program
+.SH SYNOPSIS
+.PP
+.B indexamajig
+[options]
+
+.SH DESCRIPTION
 
 The "indexamajig" program takes as input a list of diffraction image files,
 currently in HDF5 format.  For each image, it attempts to find peaks and then
@@ -14,13 +29,7 @@ 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 --indexing=mosflm,dirax --peaks=hdf5 --cell-reduction=reduce -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
@@ -34,8 +43,8 @@ a method for estimating the intensities of saturated peaks.  It goes in
 /processing/hitfinder/peakinfo_saturated, and should be an n*3 two dimensional
 array, where the first two columns contain fast scan and slow scan coordinates
 (in that order) and the third contains the value which should belong in a peak
-at the given location.  The value will be divided by 5 and spread in a small
-cross centred on that location.
+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.
@@ -65,9 +74,7 @@ which could not be indexed, you might use
 "--record=integrated,peaksifnotindexed" and then use "check-peak-detection" from
 the "scripts" folder to visualise the results of the peak detection.
 
-
-Peak Detection
---------------
+.SH PEAK DETECTION
 
 You can control the peak detection on the command line.  Firstly, you can choose
 the peak detection method using "--peaks=<method>".  Currently, two possible
@@ -96,8 +103,7 @@ You can suppress peak detection altogether for a panel in the geometry file by
 specifying the "no_index" value for the panel as non-zero.
 
 
-Indexing Methods
-----------------
+.SH INDEXING METHODS
 
 You can choose between a variety of indexing methods.  You can choose more than
 one method, in which case each method will be tried in turn until the later cell
@@ -111,9 +117,7 @@ have the dirax or ipmosflm binaries in your PATH.
 
 Example:  --indexing=dirax,mosflm
 
-
-Cell Reduction
---------------
+.SH CELL REDUCTION
 
 You can choose from various options for cell reduction with the
 "--cell-reduction=" option.  The choices are "none", "reduce" and "compare".
@@ -158,8 +162,7 @@ F), you should be careful when using "compare" for the cell reduction, since
 be converted to the non-primitive conventional cell from the PDB.
 
 
-Tuning CPU affinities for NUMA hardware
----------------------------------------
+.SH TUNING CPU AFFINITIES FOR NUMA HARDWARE
 
 If you are running indexamajig on a NUMA (non-uniform memory architecture)
 machine, a performance gain can sometimes be made by preventing the kernel from
@@ -203,16 +206,14 @@ This would dedicate half of the CPUs to one instance, and the other half to the
 other.
 
 
-A Note about Unit Cell Settings
--------------------------------
+.SH A NOTE ABOUT UNIT CELL SETTINGS
 
 CrystFEL's core symmetry module only knows about one setting for each unit cell.
 You must use the same setting.  That means that the unique axis (for cells which
 have one) must be "c".
 
 
-"Gotchas"
----------
+.SH KNOWN BUGS
 
 Don't run more than one indexamajig jobs simultaneously in the same working
 directory - they'll overwrite each other's DirAx or MOSFLM files, causing subtle
diff --git a/doc/pattern_sim.txt b/doc/man/pattern_sim.1
index cbbcb749..d53aeae5 100644
--- a/doc/pattern_sim.txt
+++ b/doc/man/pattern_sim.1
@@ -1,13 +1,26 @@
+.\"
+.\" pattern_sim man page
+.\"
+.\" (c) 2009-2011 Thomas White <taw@physics.org>
+.\"
+.\" Part of CrystFEL - crystallography with a FEL
+.\"
+
+.TH PATTERN\_SIM 1
+.SH NAME
+pattern\_sim \- Simulation of nanocrystallographic diffraction patterns
+.SH SYNOPSIS
+.PP
+.B pattern\_sim
+[options]
+
+.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:
 
 $ get_hkl -i myfile.hkl -o output.hkl -y mypointgroup -e 1
 
-
-
-The symmetry of the molecular model (the space group)
------------------------------------------------------
-
 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"
@@ -19,9 +32,5 @@ 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
 
-
-A Note about Unit Cell Settings
--------------------------------
-
 Please be sure to read the "Note about Unit Cell Settings" in the documentation
 for indexamajig.
diff --git a/doc/process_hkl.txt b/doc/man/process_hkl.1
index 3c5e40f9..6c626e31 100644
--- a/doc/process_hkl.txt
+++ b/doc/man/process_hkl.1
@@ -1,5 +1,20 @@
-process_hkl - data scaling and merging program
-----------------------------------------------
+.\"
+.\" process_hkl man page
+.\"
+.\" (c) 2009-2011 Thomas White <taw@physics.org>
+.\"
+.\" Part of CrystFEL - crystallography with a FEL
+.\"
+
+.TH PROCESS\_HKL 1
+.SH NAME
+process\_hkl \- Monte Carlo merging program
+.SH SYNOPSIS
+.PP
+.B process\_hkl
+-i mypatterns.stream -o mydata.hkl -y mypointgroup [options]
+
+.SH DESCRIPTION
 
 This program takes as input the data stream from "indexamajig".  It merges the
 many individual intensities together to form a single list of reflection
@@ -9,9 +24,7 @@ Typical usage is of the form:
 
 $ process_hkl -i mypatterns.stream -o mydata.hkl -y mypointgroup
 
-
-How to choose the point group
------------------------------
+.SH CHOICE OF POINT GROUP FOR MERGING
 
 One of the main features of serial crystallography is that the orientations of
 individual crystals are random.  That means that the orientation of each
@@ -34,13 +47,5 @@ this information, process_hkl will try to resolve the remaining orientational
 ambiguities to get from the apparent symmetry to the true symmetry (given with
 "-y").  Currently, it won't do a very good job of it.
 
-Commit number 5cdcaad6277c on the 13th of October 2010 altered indexamajig such
-that it always finds a right-handed unit cell.  That means that no ambiguity due
-to inversion exists in streams produced by versions later than that.  For
-streams produced by copies of indexamajig older than that, you DO need to use
-the corresponding holohedral Laue class (not point group) as the apparent
-symmetry (with -a).  However, since the ambiguity resolution used by process_hkl
-doesn't really work, this detail is somewhat academic.
-
 The document twin-calculator.pdf contains more detailed information about this
 issue, as well as tables which contain all the required information.
diff --git a/doc/quickstart.txt b/doc/quickstart.txt
deleted file mode 100644
index 5af7120e..00000000
--- a/doc/quickstart.txt
+++ /dev/null
@@ -1,5 +0,0 @@
-Quick start guide for CrystFEL
-------------------------------
-
-So, you have a folder full of thousands of diffraction patterns, and you want to
-analyse them.  You've come to the right place.
diff --git a/doc/symmetry.txt b/doc/symmetry.txt
deleted file mode 100644
index c190f8ee..00000000
--- a/doc/symmetry.txt
+++ /dev/null
@@ -1,56 +0,0 @@
-How CrystFEL handles symmetry
------------------------------
-
-Most programs in CrystFEL understand point group symmetry.  The exception is
-"get_hkl", which you can read about below.  You give the point group following
-the "-y" option to the programs.
-
-Please read doc/process_hkl for important information on how symmetry is used
-during the indexing and merging procedures.  It's important to understand how
-this works before, for example, trying to merge a dataset.
-
-Symmetry definitions are included in src/symmetry.c.  Point group definitions
-are required for merging and the display of merged results, but space groups are
-not taken into account since merging does not care about systematic absences -
-as far as CrystFEL is concerned, systematic absences are just measurements
-which happen to have values of zero.  Each space group belongs to exactly one
-point group, which you can look up in the International Tables for X-Ray
-Crystallography.  Alternatively, "twin-calculator.pdf" in the same directory as
-this file lists all the space groups according to point group, Laue class and
-holohedry.
-
-
-Adding a new point group
-------------------------
-
-Point groups are being added here as they are required, so it's likely that the
-exact one you want hasn't been added yet.  Here's how to add a new one by
-editing src/symmetry.c.
-
-First, expand the check_cond() function to include a description of the
-asymmetric reciprocal unit cell for the point group.  Every reflection in the
-whole of reciprocal space must map onto exactly one reflection in the asymmetric
-unit cell so defined.  The asymmetric cell is usually defined with positive h, k
-and l, but it doesn't really matter.  Working out the required condition means
-visualising the cell and taking care to properly handle situations such as the
-(000) reflection.  Get this right, otherwise you'll go crazy when it breaks in
-weird ways.
-
-Next, expand the num_general_equivs() function.  Given a point group, this
-function must return the number of equivalent reflections for a general
-reflection, including the input reflection.  High-symmetry reflections (usually
-ones with zeroes in their indices) have fewer equivalents, but the num_equivs()
-function will work this out for you.
-
-Finally, add the new point group to the get_general_equiv() function.  This
-function takes a set of Miller indices, a point group and an index "n", and
-returns (by reference) the indices of the "n"th equivalent reflection. You just
-have to worry about the general position, because get_equiv() will work out the
-special positions for you.  get_general_equiv() must return the original indices
-when idx=0.
-
-If you want the new point group to be used for simulation on the GPU, you will
-also need to modify src/diffraction-gpu.c and data/diffraction.cl.  Choose a
-simple capitalised name for the point group and add it to the list of OpenCL
-preprocessor definitions in setup_gpu().  Then add a corresponding list of
-equivalents following the established pattern in molecule_factor().  That's it.