Update GammaLib user documentation.

Jürgen Knödlseder
1 parent bd7675d0
Showing 10 changed files with 72 additions and 57 deletions
doc/source/coding/design.rst
doc/source/coding/rules.rst
doc/source/download.rst
doc/source/installation.rst
doc/source/user_manual/getting.rst
doc/source/user_manual/index.rst
doc/source/user_manual/introduction.rst
doc/source/user_manual/modules/support.rst
doc/source/user_manual/modules/uml_support.png
doc/source/user_manual/quickstart.rst
@@ -18,9 +18,11 @@ file:
     #include <config.h>
     #endif
  
-Note that **the ``config.h`` file should not be included in header files**,
-since header files are used by the outside world without any knowledge
-about ``config.h``.
+.. warning::
+
+   **The config.h file should never be included in header files.**
+   The header files are used by the outside world without any knowledge
+   about ``config.h``.
  
 One of the most commonly used configuration options used throughout
 GammaLib is related to range checking. Range checks are usually
@@ -305,11 +307,13 @@ following guidelines should be respected as far as possible:
 -  Avoid as far as possible methods that are only defined in the derived
    class.
  
-Also note that **for a derived class, ``init_members()``,
-``copy_members(const &A a)`` and ``free_members()`` should only act on derived
-class members but not on base class members**. Any exception from this
-rule needs very careful documentation since it can easily be the source
-of memory leaks.
+.. warning::
+
+   **For a derived class, init_members(), copy_members(const &A a) and
+   free_members() should only act on derived class members but not on base
+   class members**. Any exception to this rule needs very careful
+   documentation since it can easily be the source of memory leaks.
+
  
 Method naming conventions
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -8,7 +8,7 @@ C++ rules
 ---------
  
 All GammaLib C++ code must be compatible with ISO standard C++98.
-Do not use C++11 features.
+Do not use C++11 features
 (see `here <http://en.wikipedia.org/wiki/C%2B%2B#Standardization>`__
 if you don't know what C++98 and C++11 is and note that C++03 is
 just a minor correction of C++98).
@@ -189,16 +189,12 @@ Code semantics
  
      >>> import gammalib
      >>> energy = gammalib.GEnergy(10, 'TeV')
-     >>> import numpy as np
-     >>> import matplotlib.pyplot as plt  
  
   In interactive sessions (`IPython <http://ipython.org/>`_ is recommended) to save
   typing you can use ``import *`` to import everything into your local namespace::
  
      >>> from gammalib import *
      >>> energy = GEnergy(10, 'TeV')
-     >>> from numpy import *
-     >>> from matplotlib.pyplot import *
  
   Using ``import *`` in Python scripts is not recommended. Some reason are given in
   `this section <http://docs.python.org/3/howto/doanddont.html#from-module-import>`__
@@ -14,10 +14,11 @@ 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).
+`gammalib-1.0.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-1.0.0.tar.gz>`_
+(12 December 2015).
  
 To download an older release, click on the corresponding release number:
+`0.11.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-0.11.0.tar.gz>`_
 `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>`_
@@ -5,8 +5,8 @@ Installation
  
 .. note ::
  
-   These installation instructions apply to gammalib-0.11.0 and
-   later. gammalib-0.11.0 has been built, installed and tested
+   These installation instructions apply to gammalib-1.0.0 and
+   later. gammalib-1.0.0 has been built, installed and tested
    successfully on Debian, Ubuntu, Mandriva, OpenSUSE, Scientific Linux,
    CentOS, Mac OS X, FreeBSD, and OpenSolaris (using gcc), so
    hopefully it also installs on your distribution. In case you encounter
@@ -51,7 +51,7 @@ shared library by typing ::
  
 GammaLib can also benefit from the presence of the readline library that
 provides line-editing and history capabilities for text input (GammaLib
-offers however also full functionality without having readline
+offers however 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 if they are not already there.
@@ -83,7 +83,7 @@ Building GammaLib
    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
+   $ git clone https://cta-gitlab.irap.omp.eu/gammalib/gammalib.git
  
    In case you encounter an SSL certificat problem, type ::
  
@@ -95,7 +95,7 @@ Building GammaLib
    $ git checkout devel
    $ ./autogen.sh
  
-   This will make sure that you use the validated development trunk and 
+   This will make sure that you use the development trunk. It also
    creates the configuration file that is needed to configure 
    GammaLib before compilation. Continue then with the procedure below
    starting with ``./configure``.
@@ -122,19 +122,19 @@ 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 ::
+``/usr/local/gamma``. To change the install directory, provide an optional
+``--prefix`` argument, for example ::
  
    $ ./configure --prefix=/usr/local
  
 If cfitsio and/or readline is not installed in a standard location for
-libraries (such as ``/usr/lib`` or ``/usr/local/lib``), the appropriate
-location(s) can be specified using the ``LDFLAGS`` (for the library
+libraries (such as ``/usr/lib`` or ``/usr/local/lib``), you can specify
+the appropriate location(s) using the ``LDFLAGS`` (for the library
 directory) and ``CPPFLAGS`` (for the include directory) options::
  
    $ ./configure LDFLAGS='-L/opt/local/lib' CPPFLAGS='-I/opt/local/include'
  
-A full list of configuration options can be found using ::
+You can find a full list of configuration options using ::
  
    $ ./configure --help
  
@@ -148,15 +148,15 @@ 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 http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-0.11.0.tar.gz
-    $ tar xfz gammalib-0.11.0.tar.gz
+    $ wget --no-check-certificate http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-1.0.0.tar.gz
+    $ tar xfz gammalib-1.0.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
 library. Assuming that git is installed on your system, you may clone
 GammaLib using::
  
-    $ git clone https://cta-git.irap.omp.eu/gammalib
+    $ git clone https://cta-gitlab.irap.omp.eu/gammalib/gammalib.git
  
 In case that you get:
  
@@ -7,7 +7,6 @@ User Manual
  
    introduction
    getting
-   quickstart
    modules/index
    internals
    manual/index
@@ -43,7 +43,7 @@ are:
 * 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.
+The present document applies to GammaLib version 1.0.
  
 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
@@ -38,10 +38,17 @@ and a string storage, respectively. As most of the classes are unrelated,
 they will be described individually in the following sections.
  
  
-Column Separated Value tables
+Bilinear interpolation
+~~~~~~~~~~~~~~~~~~~~~~
+
+The :doxy:`GBilinear` class handles bilinear interpolation of values in a 
+two-dimensional table.
+
+
+Comma-Separated Value tables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
-The :doxy:`GCsv` class handles column separated value tables. Column separated 
+The :doxy:`GCsv` class handles comma-separated value tables. Comma-separated 
 value tables are ASCII files representing a table, where individual table
 columns a separated by a specific character (for example a whitespace or a 
 comma).
@@ -113,6 +120,37 @@ Runtime exceptions              Usage
 =============================== =====
  
  
+Filename handling
+~~~~~~~~~~~~~~~~~
+
+The :doxy:`GFilename` class handles file names in GammaLib, including 
+extensions for FITS files in the cfitsio format. The following file name 
+formats are supported ::
+
+   myfile.fits
+   myfile.fits[EVENTS]
+   myfile.fits[EVENTS,2]
+   myfile.fits[3,2]
+
+The class decomposes the input string into the filename and the extension.
+The filename can be access using the :doxy:`GFilename::filename`
+method, the extension name using the :doxy:`GFilename::extname` method,
+the extension number using the :doxy:`GFilename::extno` method and the 
+extension version using the :doxy:`GFilename::extver` method. The latter
+three methods take an argument that specifies the default value that 
+should be used in case that no extension information is specified. Below
+a usage example that extracts by default the ``EBOUNDS`` table from a
+FITS file:
+
+.. code-block:: cpp
+   :linenos:
+
+    GFits     file;
+    GFilename fname(filename);
+    file.open(fname.filename());
+    const GFitsTable& table = *file.table(fname.extname("EBOUNDS"));
+ 
+
 Linear interpolation
 ~~~~~~~~~~~~~~~~~~~~
  
@@ -279,9 +317,11 @@ Function                       Description
 ``gammalib::plaw_energy_flux`` Compute energy flux under a power law.
 ``gammalib::elogmean``         Computes geometric mean of energy.
 ``gammalib::file_exists``      Check whether a file exists.
+``gammalib::file_exists_gzip`` Check whether a file (or a gzipped version of it) exists.
 ``gammalib::dir_exists``       Check whether a directory exists.
 ``gammalib::is_infinite``      Check whether a double precision value is infinite.
 ``gammalib::is_notanumber``    Check whether a double precision value is not a number.
+``gammalib::is_fits``          Check whether a file is a FITS file.
 ``gammalib::contains``         Check whether a string contains a sub-string.
 ``gammalib::warning``          Dump warning in console.
 ``gammalib::xml2str``          Converts XML to string.
-Getting started with GammaLib
-=============================
-
-A quick GammaLib tutorial
--------------------------
-
-To be written ...
-
-
-Using GammaLib from Python
---------------------------
-
-To be written ...
-
-
-Programming guidelines
-----------------------
-
-To be written ...
-
-
-Frequently asked questions
---------------------------
-
-To be written ...