Switch to markdown for README

3 files changed, 134 insertions, 228 deletions

diff --git a/AUTHORS b/AUTHORS
index b00a2a08..8b49d146 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -1,23 +1,3 @@
-Funding acknowledgements
-------------------------
-
-Development of CrystFEL is primarily funded by the Helmholtz Association via
-programme-oriented funds.
-
-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).
-
-Additional funding for CrystFEL is provided by 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.
-
-
-Contributors
-------------
-
 * Thomas White <taw@physics.org>
   Lead author, architecture, "vision" and so on.
 
diff --git a/README b/README
deleted file mode 100644
index d74ea8c6..00000000
--- a/README
+++ /dev/null
@@ -1,208 +0,0 @@
-CrystFEL - Data processing for serial crystallography
------------------------------------------------------
-
-Copyright © 2012-2020 Deutsches Elektronen-Synchrotron DESY,
-                      a research centre of the Helmholtz Association.
-
-Authors:
-  Thomas White <taw@physics.org>
-  Richard Kirian <rkirian@asu.edu>
-  Kenneth Beyerlein <kenneth.beyerlein@desy.de>
-  Andrew Aquila <andrew.aquila@cfel.de>
-  Andrew Martin <andrew.martin@desy.de>
-  Lorenzo Galli <lorenzo.galli@desy.de>
-  Chun Hong Yoon <chun.hong.yoon@desy.de>
-  Kenneth Beyerlein <kenneth.beyerlein@desy.de>
-  Karol Nass <karol.nass@desy.de>
-  Nadia Zatsepin <nadia.zatsepin@asu.edu>
-  Anton Barty <anton.barty@desy.de>
-  Cornelius Gati <cornelius.gati@desy.de>
-  Fedor Chervinskii <fedor.chervinskii@gmail.com>
-  Alexandra Tolstikova <alexandra.tolstikova@desy.de>
-  Wolfgang Brehm <wolfgang.brehm@gmail.com>
-  Valerio Mariani <valerio.mariani@desy.de>
-  Parker de Waal <Parker.deWaal@vai.org>
-  Takanori Nakane <nakane.t@gmail.com>
-  Keitaro Yamashita <k.yamashita@spring8.or.jp>
-  Mamoru Suzuki <mamoru.suzuki@protein.osaka-u.ac.jp>
-  Thomas Grant <tgrant@hwi.buffalo.edu>
-  Steve Aplin <steve.aplin@desy.de>
-  Oleksandr Yefanov <oleksandr.yefanov@desy.de>
-  Helen Ginn  <helen@strubi.ox.ac.uk>
-  Nicolas Riebesel <nicolas.riebesel@tuhh.de>
-  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
-version.
-
-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.
-
-You should have received a copy of the GNU General Public License along with
-CrystFEL.  If not, see <http://www.gnu.org/licenses/>.
-
---------------------------------------------------------------------------------
-
-CrystFEL is a suite of programs for processing (and simulating) Bragg
-diffraction data from "serial crystallography" experiments, often (but not
-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.
-
-- Many patterns (thousands) are required - high throughput is needed.
-
-- The crystal orientations in each pattern are random and uncorrelated, meaning
-  that:
-
-- Merging into lower symmetry point groups may require the resolution of
-  indexing ambiguities.
-
-
-CrystFEL includes programs for simulating and processing patterns subject to the
-above characteristics.  The main data processing pipeline is defined by four
-programs:
-
-	- indexamajig, for bulk indexing and integration of diffraction patterns
-
-	- process_hkl, for quickly merging per-pattern lists of intensities into
-	               a single reflection list
-
-	- partialator, for merging patterns more accurately (and much more
-	               slowly) using scaling, partiality modelling and
-		       post refinement
-
-	- ambigator, for resolving indexing ambiguities
-
-There are two tools for calculating figures of merit for reflection data:
-
-	- compare_hkl, for figures of merit that involve comparing two sets of
-	               data, like CC* and R_split
-
-	- 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:
-
-	- cell_explorer, for examining distributions of lattice parameters
-
-	- hdfsee, an image viewer
-
-	- render_hkl, for turning reflection lists into pretty graphics
-
-CrystFEL can also simulate data, e.g. for methods development:
-
-	- pattern_sim, which performs a Fourier image calculation
-
-	- partial_sim, which calculates reflection intensities based on a
-	               partiality calculation and optionally plots the peaks
-		       in an image
-
-There are also five utility programs:
-
-	- 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 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, 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 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
-
-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
-
-The path to HDF5 can be set similarly:
-   cmake -DHDF5_ROOT=/path/to/hdf5 (... /include, /lib etc)
-
-To install CrystFEL in a custom location, use:
-   cmake -DCMAKE_INSTALL_PREFIX=/path/for/crystfel/installation
-
-
-Funding acknowledgements
-------------------------
-
-Development of CrystFEL is primarily funded by the Helmholtz Association.
-
-Partial funding for CrystFEL has previously been 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).
-
-- The BMBF German-Russian Cooperation "SyncFELMed", grant 05K14CHA (2014-2017).
-
-- BioStruct-X, a project funded by the Seventh Framework Programme (FP7) of the
-  European Commission (2011-2016).
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..8306c030
--- /dev/null
+++ b/README.md
@@ -0,0 +1,134 @@
+CrystFEL - Data processing for serial crystallography
+=====================================================
+
+Copyright © 2012-2021 Deutsches Elektronen-Synchrotron DESY,
+                      a research centre of the Helmholtz Association.
+
+See AUTHORS for full details of contributors.
+
+Introduction
+------------
+
+CrystFEL is a suite of programs for processing (and simulating) Bragg
+diffraction data from "serial crystallography" experiments, often (but not
+always) performed using an X-ray Free-Electron Laser.  Compared to rotation data,
+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.
+
+* Many patterns (thousands) are required - high throughput is needed.
+
+* The crystal orientations in each pattern are random and uncorrelated.
+
+* Merging into lower symmetry point groups may require the resolution of
+  indexing ambiguities.
+
+
+Getting started
+---------------
+
+The best way to get started, after installation, is to run command ```crystfel```
+to start the graphical user interface.
+
+
+Installation
+------------
+
+CrystFEL installation is supported on GNU/Linux and Mac OS X.  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).
+
+Here are the mandatory dependencies - you cannot install CrystFEL without these:
+
+* Either [CMake](https://cmake.org/) 3.12 or later or [Meson](https://mesonbuild.com/) (Meson is preferred)
+* [HDF5](https://www.hdfgroup.org/downloads/hdf5/) 1.8.0 or later (1.10.0 or later is required for many recent data formats)
+* [GNU Scientific Library (GSL)](https://www.gnu.org/software/gsl/)
+* [Bison](https://www.gnu.org/software/bison/) 2.6 or later
+* [Flex](https://www.gnu.org/software/flex/)
+* [Zlib](https://www.zlib.net/) (1.2.3.5 or later preferred for better decompression speed)
+
+The following dependencies are "optional", in the sense that you can install
+CrystFEL without them.  However, a CrystFEL installation without these will lack
+important features such as the graphical user interface:
+
+* GTK3 or later
+* Cairo
+* Pango
+* gdk-pixbuf
+* NCurses
+* libPNG
+* [libccp4](ftp://ftp.ccp4.ac.uk/opensource/)
+
+Note that all of the dependencies mentioned above (including libccp4) should be
+available from your Linux distribution's package manager, or from
+[Homebrew](https://brew.sh/) on Mac OS.  You should not need to download and
+install any of them separately from source, and we emphatically recommend
+against trying to do so!
+
+Note that using the libraries from the full CCP4 suite is not recommended.  CCP4
+includes so many other libraries that it becomes very difficult to link using
+the correct versions of everything.
+
+Processing data relies on indexing algorithms.  The more of the following are
+installed, the better your experience will be:
+
+* [FFTW3](http://fftw.org/)
+* [XGandalf](https://stash.desy.de/users/gevorkov/repos/xgandalf)
+* [PinkIndexer](https://stash.desy.de/users/gevorkov/repos/pinkindexer)
+* [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/)
+
+Installation follows the normal CMake procedure:
+
+```
+$ mkdir build
+$ cd build
+$ cmake ..
+$ make
+$ sudo make install
+```
+
+Or, with Meson:
+
+```
+$ meson . build
+$ ninja -C build
+$ sudo ninja -C build install
+```
+
+
+Licence
+-------
+
+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.
+
+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.
+
+You should have received a copy of the GNU General Public License along with
+CrystFEL.  If not, see <http://www.gnu.org/licenses/>.
+
+
+Funding acknowledgements
+------------------------
+
+Development of CrystFEL is primarily funded by the Helmholtz Association.
+
+Partial funding for CrystFEL has previously been 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).
+
+- The BMBF German-Russian Cooperation "SyncFELMed", grant 05K14CHA (2014-2017).
+
+- BioStruct-X, a project funded by the Seventh Framework Programme (FP7) of the
+  European Commission (2011-2016).
+