Reorganise User documentation.

Jürgen Knödlseder
1 parent 2ffff33d
Showing 14 changed files with 353 additions and 250 deletions
doc/source/_templates/index.html
doc/source/_themes/sphinx13/layout.html
doc/source/about.rst
doc/source/contents.rst
doc/source/develop.rst
doc/source/download.rst
doc/source/faq.rst
doc/source/gammalib-logo.jpg
doc/source/help.rst
doc/source/installation.rst
doc/source/issues.rst
doc/source/user_manual/getting.rst
doc/source/user_manual/introduction.rst
doc/source/user_manual/modules/cta_irf.rst
@@ -2,45 +2,46 @@
 body %}
 <h1>{{ _('GammaLib') }}</h1>
  
-<h2 style="margin-bottom: 0">{%trans%}About{%endtrans%}</h2>
-
-<p>{%trans%} The GammaLib is a versatile toolbox for the high-level
-	analysis of astronomical gamma-ray data. It is implemented as a C++
-	library that is fully scriptable in the Python scripting language. The
-	library provides core functionalities such as data input and output,
-	interfaces for parameter specifications, and a reporting and logging
-	interface. It implements instruments specific functionalities such as
-	instrument response functions and data formats. Instrument specific
-	functionalities share a common interface to allow for extension of the
-	GammaLib to include new gamma-ray instruments. The GammaLib provides an
-	abstract data analysis framework that enables simultaneous
-	multi-mission analysis. {%endtrans%}</p>
+<p>{%trans%} GammaLib is a versatile toolbox for the high-level analysis
+of astronomical gamma-ray data. It consists of a C++ library and a
+Python module that exposes the full functionality of the library
+to Python. The library provides an abstract data analysis framework
+that is independent of any specific gamma-ray telescope. Instrument
+specific aspects, such as handling of data formats and response
+functions, are implemented as isolated and well defined modules sharing
+an identical abstract interface. This enables a joint multi-instrument
+analysis of data, allowing for consistent broad-band spectral fitting
+or imaging. So far, GammaLib supports analysis of data obtained with
+COMPTEL, Fermi/LAT, and Cherenkov telescopes (CTA, H.E.S.S., MAGIC,
+VERITAS). {%endtrans%}</p>
  
 <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
-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. So far, GammaLib supports
-analysis of COMPTEL, Fermi/LAT, and Cherenkov telescope data 
-(CTA, H.E.S.S., MAGIC, VERITAS). {%endtrans%}</p>
+the FITS interface, GammaLib does not rely on any third-party 
+software. All functionalities are implemented natively. {%endtrans%}</p>
+
+<p>{%trans%} ctools are developed by a team of enthousiastic gamma-ray
+astronomers with support from engineers. We regularily organise
+<a href=https://cta-redmine.irap.omp.eu/projects/ctools/wiki/Coding_sprints>coding sprints</a>
+where key developers but also newcomers meet to discuss the developments 
+and next steps, and advance with the coding of the software. {%endtrans%}</p>
  
 <p>{%trans%} GammaLib is free software distributed under the
 <a href="http://www.gnu.org/licenses/gpl.html">GNU GPL license version 3</a> {%endtrans%}</p>
  
-<h2 style="margin-bottom: 0">{%trans%}Documentation{%endtrans%}</h2>
+<h2 style="margin-bottom: 0">{%trans%}Getting started{%endtrans%}</h2>
  
 <ul>
 <li><a class="smalllink" href="{{ pathto("installation") }}">{%trans%}Installation{%endtrans%}</a></li> 
 <li><a class="smalllink" href="{{ pathto("quickstart") }}">{%trans%}Quickstart{%endtrans%}</a></li> 
+</ul>
+
+<h2 style="margin-bottom: 0">{%trans%}Documentation{%endtrans%}</h2>
+
+<ul>
 <li><a class="smalllink" href="{{ pathto("user_manual/index") }}">{%trans%}User Manual{%endtrans%}</a></li> 
 <li><a class="smalllink" href="{{ pathto("howto/index") }}">{%trans%}How To{%endtrans%}</a></li> 
+<li><a class="smalllink" href="{{ pathto("faq") }}">{%trans%}Frequently asked questions{%endtrans%}</a></li> 
+<li><a class="smalllink" href="{{ pathto("issues") }}">{%trans%}Known issues{%endtrans%}</a></li> 
 <li><a class="smalllink" href="{{ pathto("coding/index") }}">{%trans%}Coding conventions{%endtrans%}</a></li> 
 <li><a class="smalllink" href="doxygen/index.html">{%trans%}Code documentation (Doxygen){%endtrans%}</a></li> 
 </ul>
@@ -49,5 +50,5 @@ analysis of COMPTEL, Fermi/LAT, and Cherenkov telescope data
  
 <ul>
 	<li><a href="https://cta-redmine.irap.omp.eu/projects/gammalib">Developer's pages</a></li>
-	<li><a href="https://www.ohloh.net/p/GammaLib">Gammalib on Ohloh</a>{% endblock %}</li>
+	<li><a href="https://www.openhub.net/p/GammaLib">Gammalib on Open HUB</a>{% endblock %}</li>
 </ul>
@@ -67,19 +67,20 @@
 {% block header %}
 <div class="pageheader">
   <ul>
-    <li><a href="{{ pathto('index') }}">Home</a></li>
-    <li><a href="{{ pathto('installation') }}">Get it</a></li>
-    <li><a href="{{ pathto('contents') }}">Docs</a></li>
-    <li><a href="https://cta-redmine.irap.omp.eu/projects/gammalib">Extend/Develop</a></li>
+    <li><a href="{{ pathto('about') }}">About</a></li>
+    <li><a href="{{ pathto('download') }}">Download</a></li>
+    <li><a href="{{ pathto('contents') }}">Documentation</a></li>
+    <li><a href="{{ pathto('develop') }}">Develop</a></li>
+    <li><a href="{{ pathto('help') }}">Help</a></li>
   </ul>
   <div>
     <a href="{{ pathto('index') }}">
       <div class=banner_part>
-      <img src="{{ pathto('_static/logo.png', 1) }}" height="64" alt="SPHINX" />
+      <img src="{{ pathto('_static/logo.png', 1) }}" height="64" alt="GammaLib" />
       </div>
       <div class=banner_part>
       	<span id="banner_text1">GammaLib</span><br/>
-      	<span id="banner_text2">A versatile toolbox for scientific analysis of astronomical gamma-ray data</span>
+        <span id="banner_text2">A versatile toolbox for scientific analysis of astronomical gamma-ray data</span>
       </div>
     </a>
    </div>
+.. _about:
+
+About
+=====
+
+GammaLib is a versatile toolbox for the high-level analysis
+of astronomical gamma-ray data. It consists of a C++ library and a
+Python module that exposes the full functionality of the library
+to Python. The library provides an abstract data analysis framework
+that is independent of any specific gamma-ray telescope. Instrument
+specific aspects, such as handling of data formats and response
+functions, are implemented as isolated and well defined modules sharing
+an identical abstract interface. This enables a joint multi-instrument
+analysis of data, allowing for consistent broad-band spectral fitting
+or imaging. So far, GammaLib supports analysis of data obtained with
+COMPTEL, Fermi/LAT, and Cherenkov telescopes (CTA, H.E.S.S., MAGIC,
+VERITAS).
+
+Except for HEASARC's cfitsio library that is used to implement
+the FITS interface, GammaLib does not rely on any third-party 
+software. All functionalities are implemented natively.
+
+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.
+
+
+Acknowledging or citing GammaLib
+--------------------------------
+
+If you use GammaLib for work/research presented in a publication we ask you
+that you include the following standard acknowledgment:
+
+   *This research made use of GammaLib, a community-developed toolbox for
+   the high-level analysis of astronomical gamma-ray data.*
+
+If you wish, you can also include a link to http://cta.irap.omp.eu/gammalib/
+(if the journal allows this) in addition to the above text.
+
+If you are giving a presentation or talk featuring work/research that makes
+use of GammaLib, we suggest using this logo on your title slide:
+
+.. figure:: gammalib-logo.jpg
+   :width: 150px
+   :align: center
+
+
+License
+-------
+
+GammaLib is free software distributed under the GNU GPL license version 3.
@@ -9,8 +9,14 @@ Documentation
 .. toctree::
    :maxdepth: 2
  
+   about
+   download
    installation
    quickstart
    user_manual/index
    howto/index
+   faq
+   issues
    coding/index
+   develop
+   help
 \ No newline at end of file
+.. _develop:
+
+Develop
+=======
+
+GammaLib is an open source projet and you are highly welcome to contribute 
+to the development.
+Contributions can come in any areas: writing C++ code, contributing Python 
+scripts, writing documentation, testing code, etc.
+
+The GammaLib development is managed by a development platform that is 
+accessible at `<https://cta-redmine.irap.omp.eu/projects/gammalib/>`_.
+Please check out the 
+`Wiki <https://cta-redmine.irap.omp.eu/projects/gammalib/wiki/Contributing_to_GammaLib>`_
+on that platform that contains information on how to contribute to the
+GammaLib development.
+
+You may also want to get in the GammaLib information flow by subscribing to 
+the ctools@irap.omp.eu mailing list.
+To subscribe simply send an e-mail to ctools-subscribe@irap.omp.eu.
+
+We are organising regular `Coding sprints <https://cta-redmine.irap.omp.eu/projects/ctools/wiki/Coding_sprints>`_
+to allow newcomers to get familiar with the code base and the coding
+practices.
+You are highly invited to join one of the next coding sprints.
+
+You can also follow `@gammalib <https://twitter.com/gammalib>`_ on
+twitter to get informed about new release of GammaLib.
 \ No newline at end of file
+.. _download:
+
+Download
+========
+
+GammaLib can be obtained in form of releases or directly from the git 
+development repository. Prefer a release if you intend using GammaLib
+for production (and publications). Clone the code from git if you need
+the most recent code that implements new features and corrects known
+bugs.
+
+
+Releases
+--------
+
+The latest GammaLib release is
+`gammalib-0.11.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-0.11.0.tar.gz>`_
+(1 November 2015).
+
+To download an older release, click on the corresponding release number:
+`0.10.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-0.10.0.tar.gz>`_
+`0.9.1 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-00-09-01.tar.gz>`_
+`0.9.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-00-09-00.tar.gz>`_
+`0.8.1 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-00-08-01.tar.gz>`_
+`0.8.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-00-08-00.tar.gz>`_
+`0.7.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-00-07-00.tar.gz>`_
+`0.6.2 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-00-06-02.tar.gz>`_
+`0.6.1 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-00-06-01.tar.gz>`_
+`0.5.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-00-05-00.tar.gz>`_
+`0.4.2 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-00-04-02.tar.gz>`_
+`0.4.11 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-00-04-11.tar.gz>`_
+`0.4.10 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-00-04-10.tar.gz>`_
+`0.4.9 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-00-04-09.tar.gz>`_
+`0.4.7 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-00-04-07.tar.gz>`_
+
+
+Git repository
+--------------
+
+To clone the gammalib source code, type
+
+.. code-block:: bash
+
+   $ git clone https://cta-git.irap.omp.eu/gammalib
+  
+This will create a gammalib directory under the current working directory
+that will contain the gammalib source code. In case that the cloning does
+not work you may try adding
+
+.. code-block:: bash
+
+   $ export GIT_SSL_NO_VERIFY=true
+
+or
+
+.. code-block:: bash
+
+   $ git config --global http.sslverify "false"
+
+before retrieving the code.
+Before you will be able to compile the code you need to generate the
+configuration file using the ``autogen.sh`` script.
+Also make sure that you're actually on the devel branch of the git
+repository. GammaLib can be compiled and configured using
+the following command sequence (the code will be installed into the 
+``/usr/local/gamma`` directory):
+
+.. code-block:: bash
+
+   $ cd gammalib
+   $ git checkout devel
+   $ ./autogen.sh
+   $ ./configure
+   $ make
+   $ make check
+   $ sudo make install
+   $ export GAMMALIB=/usr/local/gamma
+   $ source $GAMMALIB/bin/gammalib-init.sh
+
+Please read the :ref:`installation` section if you need more information on
+how to install GammaLib.
+
+.. note::
+
+  You need `swig <http://www.swig.org/>`_ on your system to build the
+  Python wrappers when you get the code from Git. Python wrappers are
+  not stored in the Git repository but are built using
+  `swig <http://www.swig.org/>`_ from interface files located in the
+  pyext folder. However, you do not need `swig <http://www.swig.org/>`_
+  when fetching a release as the Python wrappers are bundled with the
+  release tarballs.
+.. _faq:
+
+Frequently asked questions
+==========================
+
+This page will collect a list of frequently asked questions that has been 
+compiled from your user experience and feedback.
+.. _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/issues/new>`_
+or the
+`mailing list <mailto:ctools@irap.omp.eu>`_.
 \ No newline at end of file
@@ -262,111 +262,3 @@ To check man support, type for example ::
    $ man GObservations
  
 and you should see the documentation for the GObservations C++ class.
-
-.. _issues:
-
-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
-   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
-   3.250. The problems have been reported to the cfitsio developer team,
-   and are likely to be solved in the future. For the time being, it is
-   recommended to use cfitsio version 3.250 on Solaris.
-
-.. 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 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++
-
-   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/issues/new>`_
-or the
-`mailing list <mailto:ctools@irap.omp.eu>`_.
 \ No newline at end of file
+.. _issues:
+
+Known issues
+============
+
+Below you will find a list of known issues.
+
+- :ref:`Many (but not all) unit tests fail <issue_test_fail>`
+- :ref:`Python module does not work <issue_python>`
+- :ref:`Python unit test fails on El Capitan <issue_elcapitan>`
+- :ref:`Mac OS X <issue_macosx>`
+- :ref:`Solaris <issue_solaris>`
+- :ref:`OpenSolaris <issue_opensolaris>`
+
+.. _issue_test_fail:
+
+.. topic:: Many (but not all) unit tests fail
+
+   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.
+
+.. _issue_python:
+
+.. 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.
+
+.. _issue_elcapitan:
+
+.. topic:: Python unit test fails 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``.
+
+.. _issue_macosx:
+
+.. 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.
+
+.. _issue_solaris:
+
+.. 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
+   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
+   3.250. The problems have been reported to the cfitsio developer team,
+   and are likely to be solved in the future. For the time being, it is
+   recommended to use cfitsio version 3.250 on Solaris.
+
+.. _issue_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 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++
+
+   They avoid excess warnings during compilation.
@@ -533,109 +533,3 @@ can type ::
  
 which then returns the synopsis and detailed documentation for the
 requested class.
-
-Getting support
----------------
-
-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 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
-   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
-   3.250. The problems have been reported to the cfitsio developer team,
-   and are likely to be solved in the future. For the time being, it is
-   recommended to use cfitsio version 3.250 on Solaris.
-
-.. 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 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++
-
-   They avoid excess warnings during compilation.
@@ -49,7 +49,7 @@ 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
 (using the gcc compiler) and many Linux flavours. Pre-packed binary
 versions of the code are also available for Mac OS X. For known problems
-with specific platforms, please refer to the :ref:`sec_known_problems`
+with specific platforms, please refer to the :ref:`issues`
 section.
  
 GammaLib makes heavily use of C++ classes. Instrument independency is achieved
@@ -102,7 +102,6 @@ We regularily organise
 where key developers but also newcomers meet to discuss the developments 
 and next steps, and advance with the coding of the software.
  
-
 The development of GammaLib has been initiated by scientists from `IRAP (Institut
 de Recherche en Astrophysique et Planetologie) <http://www.irap.omp.eu/>`_, an
 astrophysics laboratory of CNRS and of the `University Paul Sabatier 
@@ -34,6 +34,8 @@ Performance tables.
 Response formats
 ^^^^^^^^^^^^^^^^
  
+.. _sec_cta_rsptable:
+
 Response tables
 ===============
  
@@ -72,6 +74,8 @@ An example of a CTA response file is shown below:
    :width: 100%
  
  
+.. _sec_cta_xspec:
+
 Xspec response format
 =====================
  
@@ -87,6 +91,7 @@ the sake of the 1DC, a simple one-dimensional vector had been implemented.
 GammaLib still supports handling of the 1DC files, but there are no plans 
 to use this format in the future.
  
+.. _sec_cta_perftable:
  
 Performance table
 =================