Update README

1 files changed, 99 insertions, 60 deletions

diff --git a/README b/README
index f1ed68c3..d74ea8c6 100644
--- a/README
+++ b/README
@@ -1,5 +1,5 @@
-CrystFEL - Crystallography with a FEL
--------------------------------------
+CrystFEL - Data processing for serial crystallography
+-----------------------------------------------------
 
 Copyright © 2012-2020 Deutsches Elektronen-Synchrotron DESY,
                       a research centre of the Helmholtz Association.
@@ -33,6 +33,8 @@ Authors:
   Yaroslav Gevorkov <yaroslav.gevorkov@desy.de>
   Omri Mor <omor1@asu.edu>
 
+--------------------------------------------------------------------------------
+
 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
@@ -45,8 +47,7 @@ PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 You should have received a copy of the GNU General Public License along with
 CrystFEL.  If not, see <http://www.gnu.org/licenses/>.
 
-
-Thank you for reading the documentation. :-)
+--------------------------------------------------------------------------------
 
 CrystFEL is a suite of programs for processing (and simulating) Bragg
 diffraction data from "serial crystallography" experiments, often (but not
@@ -54,116 +55,154 @@ always) performed using an X-ray Free-Electron Laser.  Some of the particular
 characteristics of such data which call for a specialised software suite are:
 
 - The sliced, rather than integrated, measurement of intensity data.  Many, if
-   not all reflections are partially integrated.
+  not all reflections are partially integrated.
 
 - Many patterns (thousands) are required - high throughput is needed.
 
 - The crystal orientations in each pattern are random and uncorrelated, meaning
-   that:
+  that:
 
 - Merging into lower symmetry point groups may require the resolution of
-   indexing ambiguities.
+  indexing ambiguities.
 
 
 CrystFEL includes programs for simulating and processing patterns subject to the
-above characteristics.  The main programs are:
+above characteristics.  The main data processing pipeline is defined by four
+programs:
 
-	- indexamajig, a "batch indexer" and data reduction program.
+	- indexamajig, for bulk indexing and integration of diffraction patterns
 
-	- process_hkl, for merging per-pattern lists of intensities into a
-	               single reflection list.
+	- process_hkl, for quickly merging per-pattern lists of intensities into
+	               a single reflection list
 
-	- cell_explorer, for examining distributions of lattice parameters.
+	- partialator, for merging patterns more accurately (and much more
+	               slowly) using scaling, partiality modelling and
+		       post refinement
 
-	- ambigator, a tool for resolving indexing ambiguities,
+	- ambigator, for resolving indexing ambiguities
 
-	- geoptimiser, for refining detector geometry.
+There are two tools for calculating figures of merit for reflection data:
 
-	- whirligig, for finding multiple shots from single crystals.
+	- compare_hkl, for figures of merit that involve comparing two sets of
+	               data, like CC* and R_split
 
-	- partialator, for merging patterns more accurately (and much more
-	               slowly) using post refinement.
+	- check_hkl, for figures of merit based on only one set of data, like
+	             completeness, redundancy and twinning tests
+
+Three tools are provided for visualising data:
 
-In addition, there is also:
+	- cell_explorer, for examining distributions of lattice parameters
 
-	- get_hkl, for doing various simple operations on reflection lists.
+	- hdfsee, an image viewer
 
-	- compare_hkl, for working out the differences (e.g. a q-dependent
-	               scaling factor) between two lists of reflections.
+	- render_hkl, for turning reflection lists into pretty graphics
 
-	- check_hkl, for determining things like completeness.
+CrystFEL can also simulate data, e.g. for methods development:
 
-	- pattern_sim, for simulating patterns.
+	- pattern_sim, which performs a Fourier image calculation
 
-	- partial_sim, for calculating partial reflection intensities.
+	- partial_sim, which calculates reflection intensities based on a
+	               partiality calculation and optionally plots the peaks
+		       in an image
 
-	- hdfsee, a simple viewer for images stored in HDF5 format.
+There are also five utility programs:
 
-	- render_hkl, for turning reflection lists into pretty graphics.
+	- get_hkl, for doing various simple operations on reflection lists such
+	           as expanding by symmetry or adding noise
+
+	- cell_tool, for doing operations on unit cells such as applying
+	             transformations or looking for indexing ambiguities
+
+	- geoptimiser, for refining detector geometry.
 
 	- list_events, for creating event lists from multi-event files.
 
-	- make_pixelmap, for creating pixel maps for Cheetah, OnDA etc.
+	- make_pixelmap, for creating HDF5 pixel map files for other programs
+	                 like Cheetah and OnDA
+
+	- whirligig, for finding multiple shots from single crystals.
 
-There is also a folder full of scripts for achieving many related tasks.
 
-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.
+There is also a folder full of scripts for achieving many related tasks, such as
+file format conversion.
 
 Standard "man" pages are provided for documentation, or you can invoke any
 program with the argument "--help" to get a summary of options.  There are some
-example geometry and beam description files in doc/examples, and development
-documentation created using GTK-Doc.
+example geometry and beam description files in doc/examples, and API
+documentation created using Doxygen.
 
 
 Installation
 ------------
 
+The terse installation instructions below should be enough if you're experienced
+with installing software from source.  More detailed installation information is
+available on the website:
+https://www.desy.de/~twhite/crystfel/install.html
+
+Mandatory dependencies:
+	- CMake 3.12 or later
+	- HDF5 1.8.0 or later (1.10.0 or later preferred)
+	- GNU Scientific Library (GSL)
+	- Bison 2.6 or later
+	- Flex
+	- Zlib (1.2.3.5 or later preferred)
+
+"Optional" dependencies:
+	- GTK2 or later (GTK3 preferred)
+	- Cairo
+	- Pango
+	- gdk-pixbuf
+	- NCurses
+	- libPNG
+	- libTIFF
+	- FFTW3
+	- XGandalf (https://stash.desy.de/users/gevorkov/repos/xgandalf)
+
+"Optional" run-time dependencies:
+	- Mosflm (https://www.mrc-lmb.cam.ac.uk/mosflm/mosflm/)
+	- DirAx (http://www.crystal.chem.uu.nl/distr/dirax/)
+	- XDS (http://xds.mpimf-heidelberg.mpg.de/)
+
+Note that "optional" means that you *can* install CrystFEL without them, however
+your installation will lack important components such as the visualisation
+tools and certain indexing algorithms.
+
+For processing electron diffraction or wide-bandwidth X-ray data, you should
+also install PinkIndexer from:
+https://stash.desy.de/users/gevorkov/repos/pinkindexer
+
+Installation follows the normal CMake procedure:
+
 $ mkdir build
 $ cd build
 $ cmake ..
 $ make
 $ sudo make install
 
-At a minimum, you will need the HDF5 library (version 1.8.0 or later) and the
-GNU Scientific Library (GSL).  For a full installation, you will also need
-libTIFF, libPNG, Cairo, FFTW3 and GTK2.  All of these should be
-installed from your distribution's package manager.  Be sure to install the
-development files for each package, which will have a name like "gtk+-2.0-dev"
-or "gtk+-2.0-devel", depending on which distribution you use.
-
 If external libraries have been installed in non-standard locations, you can set
 the path like this, for example for Xgandalf:
-cmake -DXGANDALF_INCLUDES=/path/to/xgandalf/include \
-      -DXGANDALF_LIBRARIES=/path/to/xgandalf/lib/libxgandalf.so
+   cmake -DXGANDALF_INCLUDES=/path/to/xgandalf/include \
+         -DXGANDALF_LIBRARIES=/path/to/xgandalf/lib/libxgandalf.so
 
 The path to HDF5 can be set similarly:
-cmake -DHDF5_ROOT=/path/to/hdf5 (... /include, /lib etc)
+   cmake -DHDF5_ROOT=/path/to/hdf5 (... /include, /lib etc)
 
 To install CrystFEL in a custom location, use:
--DCMAKE_INSTALL_PREFIX=/path/for/crystfel/installation
-
-If you get an error mentioning fftw3 and telling you to recompile with -fPIC,
-then your version of FFTW3 is not compiled in a suitable way.  You'll need to
-install it again (from source) adding "--enable-shared" to its ./configure
-command line.
-
+   cmake -DCMAKE_INSTALL_PREFIX=/path/for/crystfel/installation
 
 
 Funding acknowledgements
 ------------------------
 
-Development of CrystFEL is primarily funded by the Helmholtz Association via
-programme-oriented funds.
+Development of CrystFEL is primarily funded by the Helmholtz Association.
+
+Partial funding for CrystFEL has previously been provided by:
 
-Additional funding for CrystFEL is provided by "X-Probe", a project of the
-European Union's 2020 Research and Innovation Program Under the Marie
-Skłodowska-Curie grant agreement 637295 (2015-2018).
+- "X-Probe", a project of the European Union's 2020 Research and Innovation
+  Program Under the Marie Skłodowska-Curie grant agreement 637295 (2015-2018).
 
-Additional funding for CrystFEL is provided by the BMBF German-Russian
-Cooperation "SyncFELMed", grant 05K14CHA (2014-2017).
+- The BMBF German-Russian Cooperation "SyncFELMed", grant 05K14CHA (2014-2017).
 
-Past funding for CrystFEL has been received from BioStruct-X, a project funded
-by the Seventh Framework Programme (FP7) of the European Commission.
+- BioStruct-X, a project funded by the Seventh Framework Programme (FP7) of the
+  European Commission (2011-2016).