Oversee and update user documentation.

The documentation was not extended, but it was updated for better reading.

Oversee and update user documentation.
The documentation was not extended, but it was updated for better reading.
Jürgen Knödlseder
1 parent 2207cf93
Showing 7 changed files with 384 additions and 206 deletions
doc/source/_templates/index.html
doc/source/coding/rules.rst
doc/source/installation.rst
doc/source/quickstart.rst
doc/source/user_manual/getting.rst
doc/source/user_manual/introduction.rst
doc/source/user_manual/structure.png
@@ -16,8 +16,9 @@ body %}
 	abstract data analysis framework that enables simultaneous
 	multi-mission analysis. {%endtrans%}</p>
  
-<p>{%trans%} GammaLib does not rely on any third-party software, except 
-of HEASARC's cfitsio library that is used to implement the FITS interface.
+<p>{%trans%} Except for HEASARC's cfitsio library that is used to implement
+the FITS interface, GammaLib does not rely on any other third-party 
+software.
 Large parts of the code treat gamma-ray observations in an abstract
 representation, and do neither depend on the characteristics of the
 employed instrument, nor on the particular formats in which data and
@@ -150,8 +150,8 @@ Python rules
 ------------
  
 All code must be compatible with Python 2.6, 2.7 as well as 3.2 or later.
-As of 2014 most users still have Python 2, even though Python 3 has been
-out for five years, so using Python 3 features is out of the question.
+As of 2015 most users still have Python 2, even though Python 3 has been
+out for seven years, so using Python 3 features is out of question.
 Also GammaLib is mostly a C++ library with only some high-level analysis
 scripts (e.g. running a complete simulation or analysis or plotting some results)
 that are simple Python code and wouldn't profit much from using new Python 3 features.
+.. _installation:
+
 Installation
 ============
  
-
 .. note ::
  
-   These installation instructions apply to gammalib-0.10.0 and
-   later. gammalib-0.10.0 has been built, installed and tested
+   These installation instructions apply to gammalib-0.11.0 and
+   later. gammalib-0.11.0 has been built, installed and tested
    successfully on Debian, Ubuntu, Mandriva, OpenSUSE, Scientific Linux,
-   CentOS, gentoo, Mac OS X, FreeBSD, and OpenSolaris (using gcc), so
+   CentOS, Mac OS X, FreeBSD, and OpenSolaris (using gcc), so
    hopefully it also installs on your distribution. In case you encounter
    problems, please post a report on the bug tracker or send an e-mail to the
-   `mailing list <mailto:gammalib-users@lists.soureforge.net>`_.
+   `mailing list <mailto:ctools@irap.omp.eu>`_.
+
+.. _getting:
  
 Getting GammaLib
 ----------------
  
 The latest version of the GammaLib source code, documentation, and
 example programs are available on the World-Wide Web from
-`https://sourceforge.net/projects/gammalib/ <https://sourceforge.net/projects/gammalib/>`_.
+`http://cta.irap.omp.eu/ctools/download.html <http://cta.irap.omp.eu/ctools/download.html>`_.
+
+.. _prerequisits:
  
 Prerequisites
 -------------
  
-GammaLib should compile on every modern Unix system without any need to
-install other libraries. To enable support for FITS file handling,
-however, the cfitsio library from HEASARC needs to be installed. cfitsio
-exists on many distributions as a prebuilt library, so in general you
-can directly install it using your package manager. Make sure that you
+GammaLib should compile on every modern Unix system and on Mac OS X,
+Windows is not supported. To enable support for FITS file handling
+the cfitsio library from HEASARC needs to be installed. cfitsio exists
+on many Linux distributions as a prebuilt library, so in general you
+can directly install it using your package manager. Make sure that you 
 install the library and the development package, as the cfitsio header
-file (which usually comes in the development package) is needed to
-compiling GammaLib.
+file (which usually comes only in the development package) is needed 
+to compiling GammaLib.
  
 If cfitsio is not available as a prebuilt package, or if you encounter
 some problems with the prebuilt package, cfitsio can be downloaded from
 `http://heasarc.gsfc.nasa.gov/fitsio <http://heasarc.gsfc.nasa.gov/fitsio>`_
-and be installed from the source (for details, please refer to the
+and installed from the source files (for details, please refer to the
 installation instructions on the
 `HEASARC <http://heasarc.gsfc.nasa.gov/fitsio>`_ site). We recommend
 installation of cfitsio in the default GammaLib install directory as a
@@ -49,19 +54,54 @@ provides line-editing and history capabilities for text input (GammaLib
 offers however also full functionality without having readline
 installed). readline (which depends on ncurses) is available on most
 system as a prebuilt library, so also here we recommend to use your
-package manager to install the libraries. Also here, the readline (and
-ncurses) development packages are required, so that the header files
-become available and the symbolic links are set correctly.
+package manager to install the libraries if they are not already there.
+Also here, the readline (and ncurses) development packages are required,
+so that the header files become available.
  
 If readline and ncurses are not available as a prebuilt package, or if
 you encounter some problems with the prebuilt packages, both libraries
 can be downloaded from
-`http://ftp.gnu.org/gnu/ <http://ftp.gnu.org/gnu/>`_.
+`http://ftp.gnu.org/gnu/ <http://ftp.gnu.org/gnu/>`_
+and installed from the source files. We recommend to put also those in the
+default GammaLib install directory ``/usr/local/gamma``.
+
+.. _build:
  
 Building GammaLib
 -----------------
  
-Download the latest source tarball, save it in an appropriate location,
+.. note ::
+
+   You will now learn how to build the GammaLib library from the source files.
+   For Mac OS X there exist also binary packages that are bundled together 
+   with ctools, and we recommend using directly these binary packages. The
+   Mac OS X binary packages can be downloaded 
+   `here <http://cta.irap.omp.eu/ctools/download.html>`_.
+
+.. note ::
+
+   If you need the latest source code from the git repository that has not 
+   yet been released you may also clone the gammalib git repository using ::
+
+   $ git clone https://cta-git.irap.omp.eu/gammalib
+
+   In case you encounter an SSL certificat problem, type ::
+
+   $ export GIT_SSL_NO_VERIFY=true
+
+   before cloning from git. Step then in the cloned ``gammalib`` directory
+   and type ::
+
+   $ git checkout devel
+   $ ./autogen.sh
+
+   This will make sure that you use the validated development trunk and 
+   creates the configuration file that is needed to configure 
+   GammaLib before compilation. Continue then with the procedure below
+   starting with ``./configure``.
+
+To build GammaLib from the source files, download the latest release
+tarball, save it in an appropriate location,
 and type ::
  
    $ tar xvfz gammalib-x.y.z.tar.gz
@@ -77,14 +117,13 @@ and build GammaLib by typing ::
    $ make
  
 at the operating system prompt. The configuration command customizes the
-Makefiles for the particular system, the make command compiles the
-source files and builds the library, and the make install command
-installs the library in the install directory. Type ``./configure`` and not
-simply configure to ensure that the configuration script in the current
-directory is run and not some other system-wide configuration script. By
-default, the install directory is set to ``/usr/local/gamma``. To change the
-install directory an optional ``--prefix`` argument should be given, for
-example ::
+Makefiles for your particular system, the make command compiles the
+source files and builds the C++ library and Python module. Type
+``./configure`` and not simply ``configure`` to ensure that the configuration
+script in the current directory is used and not some other system-wide
+configuration script. By default, the install directory is set to 
+``/usr/local/gamma``. To change the install directory an optional 
+``--prefix`` argument should be given, for example ::
  
    $ ./configure --prefix=/usr/local
  
@@ -99,10 +138,13 @@ A full list of configuration options can be found using ::
  
    $ ./configure --help
  
+.. _test:
+
 Testing GammaLib
 ----------------
  
-GammaLib should be tested by typing::
+Before you install GammaLib you should test the C++ library and Python 
+module by typing::
  
    $ make check
  
@@ -118,22 +160,23 @@ locations. In this case, add the library directories to the
 ``LD_LIBRARY_PATH`` environment variables (``DYLD_LIBRARY_PATH`` on Mac OS
 X), e.g. ::
  
-   export LD_LIBRARY_PATH=/opt/local/lib:$LD_LIBRARY_PATH
-
-or ::
-
-   setenv LD_LIBRARY_PATH /opt/local/lib:$LD_LIBRARY_PATH
+   $ export LD_LIBRARY_PATH=/opt/local/lib:$LD_LIBRARY_PATH
  
-on C shell variants.
+.. _install:
  
 Installing GammaLib
 -------------------
  
-Install GammaLib by typing ::
+Now you are ready to install GammaLib by typing ::
  
    $ make install
  
-at the operating system prompt.
+at the operating system prompt. You may need to prepend a ``sudo`` in
+case that you need administrator privileges to access the install
+directory. If you do not have such privileges, chose an install directory
+that you can access using the ``--prefix`` option.
+
+.. _setup:
  
 Setting up your environment
 ---------------------------
@@ -143,20 +186,36 @@ will be done automatically by an initialisation script that will be
 installed in the bin directory. Assuming that you have installed
 GammaLib in the default directory ``/usr/local/gamma`` you need to add the
 following to your ``$HOME/.bashrc`` or ``$HOME/.profile`` script on a Linux
-machine::
+machine:
+
+.. code-block:: bash
  
    export GAMMALIB=/usr/local/gamma
    source $GAMMALIB/bin/gammalib-init.sh
  
 If you use C shell or a variant then add the following to your
-``$HOME/.cshrc`` or ``$HOME/.tcshrc`` script::
+``$HOME/.cshrc`` or ``$HOME/.tcshrc`` script:
+
+.. code-block:: csh
  
    setenv GAMMALIB /usr/local/gamma
    source $GAMMALIB/bin/gammalib-init.csh
  
+.. _documentation:
+
 Installing documentation
 ------------------------
  
+.. note ::
+
+   The documentation of the latest GammaLib release can be found at
+   `http://cta.irap.omp.eu/gammalib/ <http://cta.irap.omp.eu/gammalib/>`_.
+   The documentation corresponding to the git development branch can be
+   found at
+   `http://cta.irap.omp.eu/gammalib-devel/ <http://cta.irap.omp.eu/gammalib-devel/>`_.
+   You can however also install the GammaLib documentation locally on your
+   machine, and this section describes how to do that.
+
 The GammaLib documentation is shipped together with the source code and
 will be installed in the directory ``$(prefix)/share/doc/gammalib/html``,
 where ``$(prefix)`` is the installation base path, by default
@@ -173,8 +232,8 @@ on your system
 the Doxygen package).
 Doxygen will scan the source files for code annotations, and compiles a
 complete documentation of the implemented C++ classes in a set of html
-pages. In addition, it will create a set of man files that can be used by
-the man command.
+pages. In addition, it will create a set of man files that can be accessed 
+using the ``man`` command.
  
 To build and install all documentation, type the following::
  
@@ -204,40 +263,78 @@ To check man support, type for example ::
  
 and you should see the documentation for the GObservations C++ class.
  
-Known Problems
---------------
+.. _issues:
+
+Known issues
+------------
+
+.. topic:: Many (but not all) unit tests fails
  
-* cfitsio library not found
    Occasionally it may happen that the cfitsio library is not found when
-   configuring GammaLib. This will result is lots of errors during the
-   unit tests. If you are sure that cfitsio is installed, but the path
-   where the library and the path where the fitsio.h reside are
-   non-standard, you may add the paths explicitly during configuration
-   using::
+   configuring GammaLib. The library will compile successfully without
+   cfitsio, but in that case FITS I/O will not be supported. Consequently,
+   many unit tests will fail. If you are sure that cfitsio is installed,
+   but the path where the library and the path where the ``fitsio.h`` header
+   reside are non-standard, you may add the paths explicitly during
+   configuration using::
  
       $ ./configure LDFLAGS='-L/path/to/cftsio/library' CPPFLAGS='-I/path/to/fitsio.h/header'
  
    The same logic applies for finding the readline and ncurses libraries,
-   thought these libraries are not manadatory for getting the full
-   GammaLib functionnalities.
-
-* Python support
-   GammaLib comes with Python wrappers so that all classes can be directly
-   used from Python. To compile-in Python support, GammaLib needs the
-   Python.h header file, which on many distributions is not installed by
-   default. To make Python.h available, install the Python developer
-   package in your distribution using the package manager. Otherwise you
-   will not be able to use GammaLib from Python.
-
-* Mac OS X
-   The Python development package is not installed as default on Mac OS X,
-   and consequently, the Python.h header file is missing that is needed to
-   compile in the Python bindings. The configure script recognises this
-   fact and adjust the build procedure accordingly, but you will not be
-   able to use GammaLib from Python. So better install the Python
-   development package before installing GammaLib (see above).
-
-* Solaris
+   although these libraries are not manadatory for getting the full
+   GammaLib functionalities.
+
+.. topic:: Python module does not work
+
+   GammaLib includes a Python module that is built from so called wrapper 
+   files that are autogenerated using the `swig <http://www.swig.org/>`_
+   tool. These wrapper files are shipped with a GammaLib release, but if
+   you use the code from git you need `swig <http://www.swig.org/>`_
+   to generate the wrapper files during the build step. In any case,
+   to compile the Python module GammaLib needs the ``Python.h`` header file
+   which may not necessarily be installed on your system. Check the output
+   of ``./configure`` to examine the configuration that GammaLib has
+   detected. You may see the following::
+
+    * Python                       (yes)
+    * Python.h                     (yes)
+    * Python wrappers              (yes)
+    * swig                         (yes)
+
+   Recall, if the wrappers exist you do not need `swig <http://www.swig.org/>`_,
+   but if the wrappers don't exist you need `swig <http://www.swig.org/>`_.
+   If the ``Python.h`` header file does not exist then install the Python
+   development package.
+
+.. topic:: Python unit test fail on El Capitan
+
+    On Mac OS X 10.11 (El Capitan) the Python unit tests fail when GammaLib 
+    is not installed due to the way the ``DYLD_LIBRARY_PATH`` environment
+    variable is handled by the operating system. A (not very elegant)
+    workaround is to install GammaLib before running the unit test using 
+    ``make check``.
+
+
+.. topic:: Mac OS X
+
+   Dependent on the Mac OS X version you are using, not everything that
+   is needed to install GammaLib may be available (e.g. automake, libtool, 
+   etc...). The easiest way to get the needed software is using a package 
+   management system such as `MacPorts <https://www.macports.org/>`_ or 
+   `Homebrew <http://brew.sh/>`_. On a fresh El Capitan install you need 
+   for example the following from `Homebrew <http://brew.sh/>`_::
+
+     $ brew install automake
+     $ brew install libtool
+     $ brew install cfitsio
+     $ brew install swig
+
+   `swig <http://www.swig.org/>`_ is only necessary if you installed the 
+   code from git. Dependening on your system, you also may need to install
+   the Python development package.
+
+.. topic:: Solaris
+
    Although GammaLib builds on Solaris using the Sun compiler, there are
    problems with global symbols in shared libraries and exception catching,
    which prevents the FITS interface to work correctly. GammaLib has
@@ -248,26 +345,28 @@ Known Problems
    and are likely to be solved in the future. For the time being, it is
    recommended to use cfitsio version 3.250 on Solaris.
  
-* OpenSolaris
+.. topic:: OpenSolaris
+
    On OpenSolaris, the same problems concerning the SunStudio compiler
    occur as for Solaris, and also here, the GNU compiler is the recommended
    tool to build GammaLib. Also here, cfitsio version 3.250 is the
    recommended library as more recent version feature relocation
    problems. GammaLib has been tested using gcc 4.3.2 on OpenSolaris
-   2009.06. Make sure to create the symbolic links ::
+   2009.06. Make sure to create the following symbolic links if they do
+   not yet exist on your system ::
  
       $ ln -s /usr/bin/gcc4.3.2 /usr/bin/gcc
       $ ln -s /usr/bin/g++4.3.2 /usr/bin/g++
  
-   which are not there by default to avoid excess warnings during
-   compilation.
+   They avoid excess warnings during compilation.
  
+.. _help:
  
 Getting Help
 ------------
  
 Any questions, bug reports, or suggested enhancements related to
 GammaLib should be submitted via the
-`issue tracker <https://cta-redmine.irap.omp.eu/projects/gammalib>`_
+`issue tracker <https://cta-redmine.irap.omp.eu/projects/gammalib/issues/new>`_
 or the
-`mailing list <mailto:gammalib-users@lists.soureforge.net>`_.
 \ No newline at end of file
+`mailing list <mailto:ctools@irap.omp.eu>`_.
 \ No newline at end of file
+.. _quickstart:
+
 Getting started
 ===============
  
+.. _firststeps:
+
 First steps with GammaLib
 -------------------------
  
 GammaLib comes with a Python interface, and as first step you should
 verify that the Python interface works correctly. You do this by
-typing::
+typing:
+
+.. code-block:: python
  
    >>> import gammalib
+   >>> gammalib.test()
  
-If everything works fine you should just get a new Python prompt after
-importing GammaLib. If you get an error message, make sure that you've
-setup correctly the GammaLib environment. You basically need the
+The first command loads the GammaLib Python module, the second command 
+executes the Python unit tests. If all tests are ok the GammaLib Python
+module has been installed successfully. In case of problems, make sure 
+that you've setup correctly the GammaLib environment. You basically need the
 ``PYTHONPATH`` variable set to GammaLib's Python site-package, and you also
 have to make sure that GammaLib and any dependent library (cfitsio,
 readline, ncurses) is in the library load path (eventually you may need
-to adjust ``LD_LIBRARY_PATH``). This is all done automatically if you set
-up the environment as described
-`here <installation.html#Setting_up_your_environment>`_.
+to adjust ``LD_LIBRARY_PATH``, or ``DYLD_LIBRARY_PATH`` if you are on Mac 
+OS X). This is all done automatically if you set up the environment as 
+described :ref:`here <setup>`.
+
+Now try:
  
-Now try::
+.. code-block:: python
  
    >>> models = gammalib.GModels()
    >>> print(models)
@@ -31,7 +41,9 @@ Now try::
 You just alloacted your first GammaLib object, which is an empty model
 container.
  
-Now let's append a model to this container. For this, type::
+Now let's append a model to this container. For this, type:
+
+.. code-block:: python
  
     >>> pos = gammalib.GSkyDir()
     >>> pos.radec_deg(83.6331, 22.0145)
@@ -68,8 +80,8 @@ spatial component of a sky model using ``GModelSpatialPointSource``. As the name
 suggests, the spatial component is a point source. Next, you defined the
 spectral component using ``GModelSpactralPlaw``: a power law with
 normalisation of 1 and a spectral index of -2. Then, you combined the spatial
-and spectral components in a point source model using ``GModelSky``. And
-finally you appended the point source to the model container allocated
+and spectral components in a sky model using ``GModelSky``. And
+finally you appended the sky model to the model container allocated
 previously using the append method. When you then print the model
 container you see that is contains now one model with 6 parameters.
 Among them, you find the specified source position (parameters ``RA`` and
@@ -79,7 +91,9 @@ normalisation has been set to 100 MeV (parameter ``PivotEnergy``)
 and the temporal component has been set by default to a constant (parameter ``Constant``).
  
 Suppose you want to change one of these parameters, such as the
-``PivotEnergy`` that you want to set to 1 TeV. This can be done using::
+``PivotEnergy`` that you want to set to 1 TeV. This can be done using:
+
+.. code-block:: python
  
    >>> models[0]['PivotEnergy'].value(1e6)
    >>> print(models)
@@ -95,11 +109,15 @@ the container using ``models[0]`` (counting in GammaLib always starts from
 value of a particular parameter.
  
 After all this hard work, you may save your model into a XML file by
-typing::
+typing:
+
+.. code-block:: python
  
    >>> models.save('test.xml')
  
-and you can load it from an XML file in memory using::
+and you can load it from an XML file in memory using:
+
+.. code-block:: python
  
    >>> new_models = gammalib.GModels('test.xml')
    >>> print(new_models)
@@ -117,6 +135,6 @@ Getting Help
  
 Any questions, bug reports, or suggested enhancements related to
 GammaLib should be submitted via the
-`issue tracker <https://cta-redmine.irap.omp.eu/projects/gammalib>`_
+`issue tracker <https://cta-redmine.irap.omp.eu/projects/gammalib/issues/new>`_
 or the
-`mailing list <mailto:gammalib-users@lists.soureforge.net>`_.
+`mailing list <mailto:ctools@irap.omp.eu>`_.
+.. _um_getting:
+
 Getting GammaLib
 ================
  
@@ -63,11 +65,12 @@ Installing cfitsio
 HEASARC's cfitsio library comes on many Linux distributions as
 pre-compiled binary, and there are good chances that the package is
 already installed on your system. For Mac OS X, cfitsio can be installed
-from Mac Ports. If you use a pre-compiled binary, make sure that also
-the developer package is installed on your system. The developer package
-provides the ``cfitsio.h`` header file which is needed to compile in FITS
-file support in GammaLib. Please refer to the documentation of your Linux
-distribution to learn how to install pre-compiled binary packages (note
+from `MacPorts <https://www.macports.org/>`_ or
+`Homebrew <http://brew.sh/>`_. If you use a pre-compiled binary, make sure
+that also the developer package is installed on your system. The developer
+package provides the ``cfitsio.h`` header file which is needed to compile
+in FITS file support in GammaLib. Please refer to the documentation of your
+Linux distribution to learn how to install pre-compiled binary packages (note
 that the installation of pre-compiled binary packages usually requires
 system administrator privileges).
  
@@ -75,12 +78,12 @@ If you need (or prefer) to install cfitsio from source, you can download
 the latest source code from http://heasarc.gsfc.nasa.gov/fitsio.
 Detailed installation instructions can also be found on this site. We
 recommend that you install cfitsio as a shared library in the same
-directory in which you will install , so that cfitsio is automatically
+directory in which you will install GammaLib, so that cfitsio is automatically
 found by the GammaLib configure script. By default, GammaLib gets installed
 into the directory ``/usr/local/gamma``.
  
-You can install version 3.290 of cfitsio (the latest version that was
-available during writing this manual) by executing the following command
+You can install version 3.290 of cfitsio (the version that was
+available when writing this manual) by executing the following command
 sequence ($ denotes the UNIX shell prompt)::
  
     $ wget ftp://heasarc.gsfc.nasa.gov/software/fitsio/c/cfitsio3290.tar.gz
@@ -140,12 +143,13 @@ Downloading
 ~~~~~~~~~~~
  
 To get the latest version of GammaLib, please visit the site
-https://sourceforge.net/projects/gammalib/. The code can be downloaded
-from this site by clicking on the download button. Alternatively, the
-code can be downloaded and unpacked from the UNIX prompt using::
+http://cta.irap.omp.eu/ctools/download.html. The code can be downloaded
+from this site by selection the gammalib package from the table.
+Alternatively, the code can be downloaded and unpacked from the UNIX prompt
+using::
  
-    $ wget --no-check-certificate https://downloads.sourceforge.net/project/gammalib/gammalib/gammalib-0.10.0.tar.gz
-    $ tar xfz gammalib-0.10.0.tar.gz
+    $ wget --no-check-certificate http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-0.11.0.tar.gz
+    $ tar xfz gammalib-0.11.0.tar.gz
  
 The GammaLib source code can also be cloned using git. This method is
 recommended if you plan to contribute to the development of the GammaLib
@@ -154,11 +158,13 @@ GammaLib using::
  
     $ git clone https://cta-git.irap.omp.eu/gammalib
  
-In case that you get::
+In case that you get:
+
+.. code-block:: bash
  
     error: SSL certificate problem, verify that the CA cert is OK.
  
-you may add::
+you should add::
  
     $ export GIT_SSL_NO_VERIFY=true
  
@@ -175,7 +181,7 @@ source code directory and type ::
     $ ./configure
  
 to configure the library for compilation. Make sure that you type
-``./configure`` and not simply configure to ensure that the configuration
+``./configure`` and not simply ``configure`` to ensure that the configuration
 script in the current directory is invoked and not some other
 system-wide configuration script.
  
@@ -223,7 +229,7 @@ gives the directories in which the cfitsio library and the header file
 resides), whether readline and ncurses have been found, and whether
 Python including the Python.h header file is available. Although none of
 these items is mandatory, we highly recommend to install cfitsio to
-support FITS file reading and writing (see section [sec:cfitsio]), and
+support FITS file reading and writing (see :ref:`sec_cfitsio`), and
 to install Python to enable GammaLib scripting.
  
 If cfitsio is installed on your system but not found by the configure
@@ -245,16 +251,16 @@ has to prefix the header file path. With the same method, you may
 specify any non-standard location for the readline and ncurses
 libraries.
  
-The configuration script also checks for the presence of swig, which is
-used for building the Python wrapper files. Normally, swig is not needed
-to create the Python bindings as the necessary wrapper files are shipped
-with the GammaLib source code. If you plan, however, to modify or to extend the
-Python interface, you will need swig to rebuild the Python wrappers
-following changes to the interface.
+The configuration script also checks for the presence of `swig <http://www.swig.org/>`_,
+which is used for building the Python wrapper files. Normally,
+`swig <http://www.swig.org/>`_ is not needed to create the Python bindings as the
+necessary wrapper files are shipped with the GammaLib source code. If you plan, however,
+to modify or to extend the Python interface, you will need `swig <http://www.swig.org/>`_ 
+to rebuild the Python wrappers following changes to the interface.
  
 The configuration summary informs also about all instrument dependent
 interfaces that will be compiled into the GammaLib library. By default, all
-available interfaces (multi-wavelength, *Fermi*-LAT, COMPTEL and CTA) will be
+available interfaces (multi-wavelength, Fermi/LAT, COMPTEL and CTA) will be
 compiled into GammaLib. If you wish to disable a particular interface, you may
 use the configure options ``--without-mwl``, ``--without-lat``, 
 ``--without-com`` or ``--without-cta``.
@@ -262,17 +268,16 @@ For example, ::
  
     $ ./configure --without-mwl --without-lat --without-com
  
-will compile GammaLib without the multi-wavelength, the *Fermi*-LAT and 
+will compile GammaLib without the multi-wavelength, the Fermi/LAT and 
 the COMPTEL interfaces. In this case, only CTA data analysis will be supported.
  
-GammaLib uses `Doxygen <http://www.doxygen.org/>`_ for code documentation, 
-and the latest GammaLib reference manual can be found at
-http://gammalib.sourceforge.net/doxygen/. In case that you want to
-install the reference manual also locally on your machine, Doxygen is
-needed to create the reference manual from the source code. Doxygen is
+GammaLib uses `Doxygen <http://www.doxygen.org/>`_ for code documentation.
+In case that you want to install the reference manual also locally on your
+machine, `Doxygen <http://www.doxygen.org/>`_ is needed to create the reference
+manual from the source code. `Doxygen <http://www.doxygen.org/>`_ is
 also needed if you plan to modify or extend the GammaLib library to allow
 rebuilding the reference documentation after changes. Please read see
-section [sec:doxygen] to learn how to build and to install the reference
+:ref:`sec_doxygen` to learn how to build and to install the reference
 manual locally.
  
 Finally, there exist a number of options that define how exactly GammaLib
@@ -398,8 +403,8 @@ Testing
 ~~~~~~~
  
 GammaLib comes with an extensive unit test that allows to validate the library
-prior to installation. **We highly recommend to run this unit test
-before installing the library (see section [sec:install]).**
+prior to installation. We highly recommend to run this unit test
+before installing the library (see :ref:`sec_install`).
  
 To run the unit test type::
  
@@ -407,9 +412,9 @@ To run the unit test type::
  
 This will start a test of all GammaLib modules by using dedicated executables
 which will print some progress and success information into the
-terminal. After completion of all tests (and assuming that all
+console. After completion of all tests (and assuming that all
 instrument dependent modules are enabled), you should see the following
-message in your terminal::
+message in your console::
  
     ===================
     All 20 tests passed
@@ -491,8 +496,8 @@ as this would considerably increase the size of the tarball. In case
 that you want to install the reference manual also locally on your
 machine, you first have to create the documentation using Doxygen.
  
-Assuming that Doxygen is available on your machine (see section
-:ref:`sec_configure`) you can create the reference documentation by typing ::
+Assuming that Doxygen is available on your machine (see :ref:`sec_configure`)
+you can create the reference documentation by typing ::
  
     $ make doxygen
  
@@ -532,35 +537,87 @@ requested class.
 Getting support
 ---------------
  
-Any question, bug report, or suggested enhancement related to GammaLib should be
-submitted via the Tracker on https://cta-redmine.irap.omp.eu/projects/gammalib
-or by sending an e-mail to the mailing list.
+Any questions, bug reports, or suggested enhancements related to
+GammaLib should be submitted via the
+`issue tracker <https://cta-redmine.irap.omp.eu/projects/gammalib/issues/new>`_
+or the
+`mailing list <mailto:ctools@irap.omp.eu>`_.
  
 .. _sec_known_problems:
  
-Known problems
---------------
-
-* Python support
-   GammaLib comes with Python wrappers so that all classes can be directly
-   used from Python. To compile-in Python support, GammaLib needs the
-   Python.h header file, which on many distributions is not installed by
-   default. To make Python.h available, install the Python developer
-   package in your distribution using the package manager. Otherwise you
-   will not be able to use GammaLib from Python.
-
-* Mac OS X
-   The Python development package is not installed as default on Mac OS X,
-   and consequently, the Python.h header file is missing that is needed to
-   compile in the Python bindings. The configure script recognises this
-   fact and adjust the build procedure accordingly, but you will not be
-   able to use GammaLib from Python. So better install the Python
-   development package before installing GammaLib (see above).
-
-* Solaris
-   Although GammaLib builds on Solaris using the Sun compiler, there are
+Known issues
+------------
+
+.. topic:: Many (but not all) unit tests fails
+
+   Occasionally it may happen that the cfitsio library is not found when
+   configuring GammaLib. The library will compile successfully without
+   cfitsio, but in that case FITS I/O will not be supported. Consequently,
+   many unit tests will fail. If you are sure that cfitsio is installed,
+   but the path where the library and the path where the ``fitsio.h`` header
+   reside are non-standard, you may add the paths explicitly during
+   configuration using::
+
+      $ ./configure LDFLAGS='-L/path/to/cftsio/library' CPPFLAGS='-I/path/to/fitsio.h/header'
+
+   The same logic applies for finding the readline and ncurses libraries,
+   although these libraries are not manadatory for getting the full
+   GammaLib functionalities.
+
+.. topic:: Python module does not work
+
+   GammaLib includes a Python module that is built from so called wrapper 
+   files that are autogenerated using the `swig <http://www.swig.org/>`_
+   tool. These wrapper files are shipped with a GammaLib release, but if
+   you use the code from git you need `swig <http://www.swig.org/>`_
+   to generate the wrapper files during the build step. In any case,
+   to compile the Python module GammaLib needs the ``Python.h`` header file
+   which may not necessarily be installed on your system. Check the output
+   of ``./configure`` to examine the configuration that GammaLib has
+   detected. You may see the following::
+
+    * Python                       (yes)
+    * Python.h                     (yes)
+    * Python wrappers              (yes)
+    * swig                         (yes)
+
+   Recall, if the wrappers exist you do not need `swig <http://www.swig.org/>`_,
+   but if the wrappers don't exist you need `swig <http://www.swig.org/>`_.
+   If the ``Python.h`` header file does not exist then install the Python
+   development package.
+
+.. topic:: Python unit test fail on El Capitan
+
+    On Mac OS X 10.11 (El Capitan) the Python unit tests fail when GammaLib 
+    is not installed due to the way the ``DYLD_LIBRARY_PATH`` environment
+    variable is handled by the operating system. A (not very elegant)
+    workaround is to install GammaLib before running the unit test using 
+    ``make check``.
+
+
+.. topic:: Mac OS X
+
+   Dependent on the Mac OS X version you are using, not everything that
+   is needed to install GammaLib may be available (e.g. automake, libtool, 
+   etc...). The easiest way to get the needed software is using a package 
+   management system such as `MacPorts <https://www.macports.org/>`_ or 
+   `Homebrew <http://brew.sh/>`_. On a fresh El Capitan install you need 
+   for example the following from `Homebrew <http://brew.sh/>`_::
+
+     $ brew install automake
+     $ brew install libtool
+     $ brew install cfitsio
+     $ brew install swig
+
+   `swig <http://www.swig.org/>`_ is only necessary if you installed the 
+   code from git. Dependening on your system, you also may need to install
+   the Python development package.
+
+.. topic:: Solaris
+
+   Although GammaLib builds on Solaris using the Sun compiler, there are
    problems with global symbols in shared libraries and exception catching,
-   which prevents the FITS interface to work correctly. GammaLib has
+   which prevents the FITS interface to work correctly. GammaLib has
    however been built and tested successfully using the GNU compiler, and
    this is the only build method that is currently supported. Problems have
    also been encountered when compiling cfitsio versions more recent than
@@ -568,16 +625,17 @@ Known problems
    and are likely to be solved in the future. For the time being, it is
    recommended to use cfitsio version 3.250 on Solaris.
  
-* OpenSolaris
+.. topic:: OpenSolaris
+
    On OpenSolaris, the same problems concerning the SunStudio compiler
    occur as for Solaris, and also here, the GNU compiler is the recommended
-   tool to build GammaLib. Also here, cfitsio version 3.250 is the
+   tool to build GammaLib. Also here, cfitsio version 3.250 is the
    recommended library as more recent version feature relocation
-   problems. GammaLib has been tested using gcc 4.3.2 on OpenSolaris
-   2009.06. Make sure to create the symbolic links ::
+   problems. GammaLib has been tested using gcc 4.3.2 on OpenSolaris
+   2009.06. Make sure to create the following symbolic links if they do
+   not yet exist on your system ::
  
       $ ln -s /usr/bin/gcc4.3.2 /usr/bin/gcc
       $ ln -s /usr/bin/g++4.3.2 /usr/bin/g++
  
-   which are not there by default to avoid excess warnings during
-   compilation.
+   They avoid excess warnings during compilation.
+.. _um_intro:
+
 Introduction
 ============
  
 Scope
 -----
  
-This User Manual provides a complete description of the GammaLib C++ library.
-It is equally well suited for beginners as for experienced users.
+This User Manual provides a complete description of the GammaLib C++ library
+and its Python module. It is equally well suited for beginners as for
+experienced users.
  
 Overview
 --------
  
 GammaLib is a self-contained, instrument independent, open source,
-multi-platform C++ library that implements all code required for the
-scientific analysis of astronomical gamma-ray data. GammaLib works with
-high-level data, which are data that are already calibrated and that
-generally come in form of event lists or histograms.
-
-GammaLib does not rely on any third-party software, with the only exception of
-the cfitsio library from HEASARC that is used to implement the FITS
-interface. This makes GammaLib basically independent of any other software
+multi-platform C++ library and Python module that implements all code
+required for the scientific analysis of astronomical gamma-ray data.
+GammaLib works with high-level data, which are data that are already
+calibrated and that generally come in form of event lists or histograms.
+
+Except for HEASARC's cfitsio library that is used to implement the FITS
+interface, GammaLib does not rely on any other third-party software.
+This makes GammaLib basically independent of any other software
 package, increasing the maintainability and enhancing the portability of
 the library.
  
-GammaLib potentially supports any gamma-ray astronomy instrument. Large parts of
-the code treat gamma-ray observations in an abstract representation, and
-do neither depend on the characteristics of the employed instrument, nor
-on the particular formats in which data and instrument response
+GammaLib potentially supports any gamma-ray astronomy instrument. Large
+parts of the code treat gamma-ray observations in an abstract representation,
+and do neither depend on the characteristics of the employed instrument,
+nor on the particular formats in which data and instrument response
 functions are delivered. Instrument specific aspects are implemented as
 isolated and well defined modules that interact with the rest of the
 library through a common interface. This philosophy also enables the
 joint analysis of data from different instruments, providing a framework
 that allows for consistent broad-band spectral fitting or imaging.
  
-GammaLib source code is freely available under the GNU General Public license
-version 3. The latest source code can be downloaded from
-https://sourceforge.net/projects/gammalib/.
-The issue tracker can be found at 
-https://cta-redmine.irap.omp.eu/projects/gammalib/issues.
-Further information and documentation on GammaLib can be found at
-http://cta.irap.omp.eu/gammalib/.
-The present document applies to GammaLib version 0.10.
+GammaLib source code is freely available under the GNU General Public
+license version 3. Relevant links for download, issues and documentation
+are:
+
+* Download: http://cta.irap.omp.eu/ctools/download.html
+* Issue tracker: https://cta-redmine.irap.omp.eu/projects/gammalib/issues
+* Documentation: http://cta.irap.omp.eu/gammalib/
+
+The present document applies to GammaLib version 0.11.
  
 GammaLib is designed to compile on any POSIX compliant platform. So far, 
 GammaLib has been successfully compiled and tested on Mac OS X, OpenBSD, OpenSolaris
@@ -66,12 +70,6 @@ correspond to the folders in the source code distribution):
    (model), sky maps and sky coordinates (sky), and for the generation
    of analysis executables in form of ftools (app).
  
--  **Instrument specific modules**
-
-   GammaLib support the analysis of data from the Cherenkov Telescope Array
-   (cta), the *Fermi*/LAT telescope (lat), the COMPTEL telescope (com),
-   and any multi-wavelength information in form of spectral data points (mwl).
-
 -  **Core services**
  
    GammaLib comprise modules for numerical computations (numerics), linear
@@ -81,22 +79,29 @@ correspond to the folders in the source code distribution):
 -  **Interfaces**
  
    are implemented for reading and writing of FITS files (fits), XML
-   files (xml), Xspec data (xspec) and Virtual Observatory 
-   interoperability (vo).
+   files (xml), and Virtual Observatory interoperability (vo).
+
+-  **Instrument specific modules**
+
+   GammaLib support the analysis of data from the Cherenkov Telescope Array
+   (cta), the Fermi/LAT telescope (lat), the COMPTEL telescope (com),
+   and any multi-wavelength information in form of spectral data points (mwl).
  
 .. _fig_structure:
  
 .. figure:: structure.png
-   :width: 100%
+   :width: 75%
+   :align: center
  
-   GammaLib structure
+   *GammaLib structure*
  
+GammaLib is developed by a team of enthousiastic gamma-ray 
+astronomers with support from engineers.
+We regularily organise
+`coding sprints <https://cta-redmine.irap.omp.eu/projects/ctools/wiki/Coding_sprints>`_
+where key developers but also newcomers meet to discuss the developments 
+and next steps, and advance with the coding of the software.
  
-GammaLib can be used as C++ application program interface (API) or as a Python
-module (provided that Python is installed on your system). The GammaLib Python
-bindings were built using `swig <http://www.swig.org/>`_ version 3.0.2, and are
-shipped together with the source code. This enables using all
-GammaLib functionalities from within Python.
  
 The development of GammaLib has been initiated by scientists from `IRAP (Institut
 de Recherche en Astrophysique et Planetologie) <http://www.irap.omp.eu/>`_, an
@@ -104,11 +109,8 @@ astrophysics laboratory of CNRS and of the `University Paul Sabatier
 <http://www.univ-tlse3.fr/>`_ situated in
 Toulouse, France. GammaLib is based on past experience gained in developing
 software for gamma-ray space missions, such as the COMPTEL telescope
-aboard *CGRO*, the SPI telescope aboard *INTEGRAL*, and the LAT
-telescope aboard *Fermi*. Initial elements of GammaLib can be found in the
-``spi_toolslib`` that is part of the Off-line Science Analysis (OSA)
-software distributed by ISDC for the science analysis of *INTEGRAL*
-data. The development of GammaLib is nowadays mainly driven by the advances in
-ground-based gamma-ray astronomy, and in particular by the development
-of the CTA observatory.
+aboard CGRO, the SPI telescope aboard INTEGRAL, and the LAT
+telescope aboard Fermi. Today, the development of GammaLib is mainly driven
+by the needs in ground-based gamma-ray astronomy, and in particular by the
+development of the CTA observatory.