Add caveat about OpenMP build to README

Also, clean up README.rst and INSTALL.rst a little.

Addresses #248.

INSTALL.rst

@@ -91,21 +91,6 @@ environment variable settings are necessary, and you do not need to set
 Then, unpack each of the above packages and build them with the usual
 ``configure; make; make install`` recipe.
 
-Known issues
-------------
-
-* Incompatibility with ``cfitisio`` from ``HEASOFT``: due to a conflict of
-  header file names it is currently not possible to use the cfitsio library
-  provided with the HEASOFT package for compilation of Healpix C++. HEASOFT's
-  include directory contains a file called "rotmatrix.h" which clashes with
-  Healpix's own rotmatrix.h.
-
-* Compilation problems in the C++ package: some gcc versions (we have reports
-  for 4.4.5 and 4.4.6) crash with an internal compiler error during compilation
-  of libsharp. Unfortunately we have not found a workaround for this compiler
-  problem. To our knowledge, it has been fixed in gcc 4.4.7 and in the 4.5.x
-  and newer versions.
-
 Development install
 -------------------
 

README.rst

@@ -15,7 +15,7 @@ Description
 Healpy provides a python package to manipulate healpix maps. It is based on the
 standard numeric and visualisation tools for Python, Numpy and matplotlib.
 
-To find more information about Healpix, please visit its home page at
+To find more information about HEALPix, please visit its home page at
 http://healpix.sourceforge.net/.
 
 The documentation can be found at http://healpy.readthedocs.org, tutorial at
@@ -31,7 +31,7 @@ Characteristics
 
 * plotting capabilities (mollweide and gnomonic projection)
 
-* reading and writing of Healpix FITS maps and alm
+* reading and writing of HEALPix FITS maps and alm
 
 Requirements
 ------------
@@ -67,7 +67,7 @@ for further details and other installation options.
 Optional
 --------
 
-Healpy depends on the Healpix C++ and cfitsio C libraries. Source code is
+Healpy depends on the HEALPix C++ and cfitsio C libraries. Source code is
 include with Healpy and you do not have to install them separately.
 
 However, if you have them installed already, Healpy should detect and reuse
@@ -85,11 +85,39 @@ HEALPix and cfitsio, you will also need:
 See `INSTALL.rst <https://github.com/healpy/healpy/blob/master/INSTALL.rst>`_
 for further instructions.
 
-Known Issues
+Known issues
 ------------
 
-healpy pixel functions, e.g. ang2pix, do not support 32bit platforms, we are
-working on fixing this issue.
+* Building with OpenMP support: the underlying HEALPix C++ library can be built
+  to use `OpenMP <http://openmp.org/wp/>`_ to speed up some operations on
+  systems with multiple cores. Most, but not all, modern C/C++ compilers support
+  OpenMP, `the notable exception being clang <http://openmp.llvm.org>`_.
+
+  If your Healpy build fails with an error message about being unable to link
+  against `-lgomp`, then this typically means that Healpy detected an
+  already-installed HEALPix C++ library that was built with OpenMP support, but
+  you are trying to build Healpy with a compiler that does not support OpenMP.
+  Try cleaning the build with `python setup.py clean --all`, and set the
+  environment variables `CC` and `CXX` to point to an OpenMP-capable compiler,
+  such as gcc/g++.
+
+* Healpy does not currently support Windows.
+  See https://github.com/healpy/healpy/issues/25.
+
+* Incompatibility with ``cfitisio`` from ``HEASOFT``: due to a conflict of
+  header file names it is currently not possible to use the cfitsio library
+  provided with the HEASOFT package for compilation of HEALPix C++. HEASOFT's
+  include directory contains a file called "rotmatrix.h" which clashes with
+  HEALPix's own rotmatrix.h.
+
+* Compilation problems in the C++ package: some gcc versions (we have reports
+  for 4.4.5 and 4.4.6) crash with an internal compiler error during compilation
+  of libsharp. Unfortunately we have not found a workaround for this compiler
+  problem. To our knowledge, it has been fixed in gcc 4.4.7 and in the 4.5.x
+  and newer versions.
+
+* Healpy pixel functions, e.g. ``ang2pix``, do not support 32-bit platforms.
+  See https://github.com/healpy/healpy/issues/194.
 
 Support
 -------
@@ -98,8 +126,8 @@ For specific *HOWTO* questions please create a question on StackOverflow_ and
 tag it with the `healpy` tag, so that answers will be easily searchable on
 google.
 
-If you think you found a bug or you have install issues, open an issue on github:
-https://github.com/healpy/healpy/issues?state=open
+If you think you found a bug or you have install issues, open an issue on GitHub:
+https://github.com/healpy/healpy/issues
 
 For more general discussion, you can write to the healpy mailing list:
 https://groups.google.com/d/forum/healpy