Fix : -> :: (rst markup) in README; document setupools/distrubute fork.

[sawsim.git] / README

diff --git a/README b/README
index 414faca2858872cf9148c17d7435974efd98d0e2..12f94540e77789d54c5e676aca3f944b95e032e7 100644 (file)
--- a/README
+++ b/README
@@ -1,22 +1,22 @@
 Compiling
 ---------
 
-Check out the source:
+Check out the source::
 
   $ git clone http://www.physics.drexel.edu/~wking/code/git/sawsim.git sawsim
   $ cd sawsim
 
-Sawsim is written in noweb_.  Extract the `Makefile` and compile with:
+Sawsim is written in noweb_.  Extract the `Makefile` and compile with::
 
   $ notangle -Rmakefile src/sawsim.nw | sed 's/        /\t/' > Makefile
   $ make
 
-Run the unit tests with:
+Run the unit tests with::
 
   $ make check
 
 If you're using the Python bindings (`pysawsim` or `bin/*.py`), you
-should run the `pysawsim` unit tests with:
+should run the `pysawsim` unit tests with::
 
   $ ./misc/hooks/pre-commit-pysawsim-check
 
@@ -24,7 +24,7 @@ should run the `pysawsim` unit tests with:
 Upgrading
 ~~~~~~~~~
 
-Upgrade to the most recent version:
+Upgrade to the most recent version::
 
   sawsim$ git pull
   sawsim$ make && make check && ./misc/hooks/pre-commit-pysawsim-check
@@ -63,13 +63,23 @@ pbs-python_   pysawsim pbs manager   [2]_               [2]_
 .. _pbs-python: http://subtrac.sara.nl/oss/pbs_python
 
 .. [1] mpi4py has no Debian package, but you can install it with
-   setuputils` (Debian: python-setuptools) via:
+   distribute_ (a `setuptools` fork) (Debian: python-distribute,
+   Gentoo: setuptools/setuptools) via::
 
-     easy_install --user mpi4py
+     $ easy_install --user mpi4py
+
+   For systems with earlier versions of `distribute`/`setuptools`,
+   which lack the `--user` option, try something along the lines of::
+
+     $ easy_install --user mpi4py
+     $ easy_install --prefix $HOME/.local/ mpi4py
 
 .. [2] pbs-python has no Debian or Gentoo packages, but you can
    install it from source.  See the `pbs-python homepage`_.
 
+.. _distribute: http://pypi.python.org/pypi/distribute
+
+
 PYTHONPATH
 ~~~~~~~~~~
 
@@ -92,7 +102,7 @@ to run many repetitions to generate enough data for significant
 statistical analysis.  To facilitate this, we provide the `pysawsim`
 module which provides a higher level interface to `sawsim`.
 
-Ensure that . is in your PYTHONPATH_, and run the pysawsim tests:
+Ensure that . is in your PYTHONPATH_, and run the pysawsim tests::
 
   sawsim$ ./misc/hooks/pre-commit-pysawsim-check
 
@@ -126,17 +136,17 @@ runs.  However, if you are repeatedly running sawsim with the same
 parameters, you probably want to enable caching (`-C/--use-cache`).
 The output of each `sawsim` run will be stored in your cache directory
 (`-d/--cache-dir`) and recycled for future runs with the same sawsim
-parameters.  For example, if you place 200 runs in the cache:
+parameters.  For example, if you place 200 runs in the cache::
 
   $ bin/sawsim_hist.py -s bin/sawsim -N 200 --use-cache
 
-And then generate another histogram with the same `sawsim` parameters:
+And then generate another histogram with the same `sawsim` parameters::
 
   $ bin/sawsim_hist.py -s bin/sawsim -N 300 --use-cache
 
 The second call will only execute an additional 100 `sawsim` runs.
 
-If you ask for *fewer* runs than are contained in the cache, e.g.:
+If you ask for *fewer* runs than are contained in the cache, e.g.::
 
   $ bin/sawsim_hist.py -s bin/sawsim -N 100 --use-cache
 
@@ -147,7 +157,7 @@ at random from the cache.
 Help
 ----
 
-As always, run
+As always, run::
 
   sawim$ bin/<whatever> --help