
   Nightfall is an interactive binary star application for 
   fun, education, and science. 
   FOR MORE INFORMATION, read the manual: *** UserManual.html ***.
   There is also on-line help available in the interactive version.

   Nightfall is copyright (c) Rainer Wichmann (rwichman@lsw.uni-heidelberg.de)
   and is distributed under the terms of the GNU General Public License 
   (see the file 'COPYING'). Nightfall is provided 'as is', and comes
   with ABSOLUTELY NO WARRANTY.


INDEX OF THIS FILE:
==================

1. Requirements
2. Installation
3. Quick start
4. Compilation problems
5. Internationalization


1. REQUIREMENTS:
===============

  If you have a recent Linux distribution, you should already have all 
  you need (in particular, the GNUPLOT program and the Gtk+ library). 
  If in doubt, read this section.

  Graphic Output:
  --------------

    For (optional) graphic output, you need either
 
       * a recent version of the GNUPLOT program 
         (one that supports the 'set multiplot' option).

     or
 
       * the PGPLOT graphics subroutine library
         version 5.2 (older version may or may not work). 
         If installed, 'configure' might find it by itself; otherwise 
         you may need to use the 'configure' options
         '--with-pgplot-include=PFX' (Prefix where PGPLOT header file 
	 cpgplot.h is installed), and 
         '--with-pgplot-lib=PFX' (Prefix where PGPLOT library files 
	 libpgplot.a, libcpgplot.a are installed).

    PGPLOT is available at http://astro.caltech.edu/~tjp/pgplot, 
    and free for non-commercial use. Precompiled binaries
    are available on the 'Linux for Astronomy' CD-ROMs
    (http://www.randomfactory.com/lfa.html) and for Debian GNU/Linux
    (http://www.debian.org).

    Note: Personally, I use mostly PGPLOT, as it produces nicer plots. 
    The GNUPLOT version works, but plots are not that nice sometimes.
    However, the animation runs smoother with GNUPLOT, flickers a lot 
    with PGPLOT.


  Graphical User Interface:
  ------------------------

    For interactive use, an (optional) graphical user interface is 
    provided. To use it, you need the GTK+ library installed on your
    system (version > 1.0.4; again, older version may or may not work). 
    GTK+ is distributed under the terms
    of the GNU Public License and available at http://www.gtk.org.
    NOTE: In your Linux distribution, GTK may be split in two packages
    (run-time libraries and 'development' files). You will need both !

    Nightfall will parse a file $HOME/.nightfallrc on startup.

  Gnome:
  -----

    Nightfall will build with support for the Gnome Desktop, if you have
    installed it. It does *not* require Gnome - it compiles just as well
    without it.


  It is possible to compile just the kernel (i.e. the part of the program
  that computes the ligtcurve), without any plotting/interactive
  options. This will be very boring, but will yield the fastest code.
  Minimum requirement: an ANSI C compiler.


2. INSTALLATION:
===============

   To install Nightfall on your system, execute the following commands
   (where '$' is your shell prompt, and '{version.number}' should be 
   replaced with the actual version number of Nightfall):

    $ gunzip -c nightfall-{version.number}.tar.gz | tar -xvf -
    $ cd nightfall-{version.number}
    $ ./DoInstall.sh

  The 'DoInstall.sh' script will query you for some information,
  (e.g. the root directory under which to install),
  and then (optionally) build, test, and install the application.

  If you want to do it by hand, instead of './DoInstall.sh' run 
  the following sequence of commands:

    $ ./configure <options> 
    $ make
    $ make install

    (type './configure --help' for a full list of options.)

  Install Directories:
  -------------------

    The binary will be installed in /usr/local/bin by default.

    Nightfall can read configuration files and datafiles containing 
    observational data. Example files are in the subdirectories 'data'/'cfg'. 
    The files there will be installed in /usr/local/share/Nightfall/cfg'
    and '/usr/local/share/Nightfall/data'
    by default. 

    HTML documentation and helpfiles for online help will be installed
    in '/usr/local/share/Nightfall/doc' by default.

    ** Change the default **: for installing somewhere else than 
    /usr/local, use the 'configure' option --prefix=/what/ever to replace 
    /usr/local by /what/ever (the 'DoInstall.sh' script will ask for this).
    Avoid trailing '/', i.e. use /what/ever, NOT /what/ever/

    Use --with-doc-prefix=/what/ever (..-data-prefix, ..) to change
    the default install path for individual data subdirectories (doc/, cfg/,
    data/, locale/).

    If data subdirectories have been moved 'by hand' after installation,
    you need to set the environment variable NIGHTFALL_DATAROOT to the
    root path where doc/ (on-line help), cfg/ (sample binary stars), 
    data/ (sample lightcurves), locale/ (language support) can be found. 
    Alternatively, you can
    set NIGHTFALL_DATA_DIR, NIGHTFALL_DOC_DIR, NIGHTFALL_CFG_DIR,
    NIGHTFALL_LOCALE_DIR seperately.

    To uninstall, use 'make uninstall'.


3. QUICK STARTUP:
================

    After installing Nightfall, two examples of usage would be:

  Non-interactive:
  ---------------

    $ nightfall -A -Db 0.9 80 1.0 0.7 4000. 5000.

    This should produce an animated view of a binary system.

  Interactive:
  -----------

    $ nightfall -U 

    This starts in interactive mode. You can then (e.g.) use the
    menu option 'File->Config.File' to read in a configuration file, then  
    switch on 'ANIMATE' and click on 'COMPUTE' to compute the lightcurve, 
    an finally click 'PlotCurve' to see the final lightcurve with the 
    data overlayed.


 -- READ THE MANUAL FOR MORE DETAILS --


4. COMPILATION PROMLEMS:
=======================

   Note: Use 'make distclean' to delete any files you
         have already created before running 'configure'
         with some different option.

   Second note: By default, nightfall will compile with
         support for internationalization, and will try
         to use whatever preinstalled utility is available
         on your system. These preinstalled utilities
         may be BROKEN, thus causing compile problems.
	 Read v), or the file ABOUT-NLS, for two possible
	 easy fixes to this problem.

i) Have gnuplot, but configure does not find it
   
   -- is gnuplot in your path ?
    if no, update your PATH environment variable

   -- does it support 'set multiplot' ?
      ( start interactively by typing 'gnuplot',
          then type 'set multiplot' to test)
    if no, update your gnuplot

   -- does 'gnuplot_x11 -persist' work, or does it
      give an error message like:
         gnuplot: bad option: -persist ?
    if error, update your gnuplot

   -- There was at least one gnuplot version that
      supports the required 'multiplot' option, but does not
      list it as supported. 
      In this case, enforce gnuplot support with:
      ./configure --with-gnuplot
    
ii) Have gnuplot and pgplot, want gnuplot support

   -- use:
      ./configure --with-gnuplot



iii) Have pgplot, but configure does not find it

  -- do you have a fortran compiler (required) ?

  -- the following files are required:
      cpgplot.h, libcpgplot.a, libpgplot.a
     Use 
     ./configure --with-pgplot-include=/my/pgplot/include/dir --with-pgplot-lib=/my/pgplot/lib/dir
     where '/my/pgplot/include/dir' is the directory where
     cpgplot.h is located, and '/my/pgplot/lib/dir' is the directory
     where libcpgplot.a, libpgplot.a are located.


iv) Have pgplot, get compile error

  -- maybe your fortran compiler does not understand the
     link options required by Gtk.
     upgrade to a recent version of g77.

  -- maybe pgplot was compiled with a different fortran compiler.
     recompile it from source.

v) Other compile errors:

  -- There might be problems related to internationalization,
     that may be caused by a broken installation of a respective
     utility on your system.
     For solving this, you should choose one of the
     following switches for the 'configure' script:

      --disable-nls
      --with-included-gettext

     like, e.g.:    ./configure --with-included-gettext

     The first switch will completely disable internationalization,
     i.e. only the english version will be available.
     The second switch will use the internationalization
     program that is included in this source code distribution,
     thus bypassing any preinstalled, maybe broken, utility on
     your system.


5. INTERNATIONALIZATION:
=======================

     Currently, besides the default language (english), only
     german is supported. If you want to make use of this
     feature, you should:
 
	NOT USE at compile time the 'configure' option
        --disable-nls

	at runtime set the environment variable LANG to 'de'
	before starting the application
	(if your shell is csh:  setenv LANG de 
	else: LANG=de; export LANG)

     NOTE: Currently, the datafiles are installed without changing
     the decimal point character. Therefore, nightfall enforces the
     use of the dot, even if (e.g. in the german locale) a comma would
     be appropriate, otherwise the datafiles would be read incorrectly.
 
     Please read the file ABOUT-NLS for more details about 
     internationalization.
