1. Introduction
2. Hacking 
      2.1 Important notes
      2.2 Adding files
3. Language specific remarks
      3.1 Fortran
      3.2 C
      3.3 Perl


--------------------------------


1. Introduction
The GVIB package is a set of independent programs glued 
together by a perl script. This way one can easily add new
computation methods and use other people's packages written in 
whatever programming language they liked.

Generally, the action of the subprograms is controlled by enviroment
variables starting with the prefix 'GVIB_'. These variables most
often tell the subprograms where are the locations of the input 
and output files, but can also specify various parameters.
The subprograms take their input data from files and their outputs
are files again. If the file formats are well defined and documented,
they can be used as a starting point for other subprograms.

To get a complete list of the variables used by the programs, run
      grep GVIB_ *f *c
      
For explanation of the variables, run
      gvib -h

Gvib actions are defined in a module file (by default 'Actions.pm')
which can be easily adjusted to suit one's needs. User can also
supply his own module. (See the --module option to gvib and
the comments in Actions.pm for more on this.)



2. Hacking
Generally, when adding a new computation method, one must 
edit two files:
 - Actions.pm (MyModule.pm) ... to tell gvib what programs should
      be run, what are the dependencies and what variables should be
      set for you.
 - Actions.conf (MyModule.conf) ... here should be a WORKABLE template
      of a config file, so that by minor editing of my.conf generated by
	    gvib -h > my.conf
      and running
	    gvib my.conf
      a user can obtain meaningful results. That means, some default values 
      should always be specified!
      
At the present state, gvib may be run just with a molecule geometry
as a parameter and gvib takes care of creating configuration file, 
of running Gaussian etc. We wish that it stays this way.

Note that the gvib script unsets any variables with the GVIB_ prefix,
which was set in the enviroment. Every variable must be specified 
explicitly in the Actions.pm and Actions.conf file. This way we want 
to restrain use of undocumented features and parameters.



2.1 Important notes
Please AVOID USE OF RUN-TIME QUESTIONS to the user.
All parameters must be obtained from the configuration file and
preferably, some default value should be always specified.


2.2 Adding files
When adding a new source file, it must be added in the appropriate 
Makefile.am. When a brand new directory is added, building of the new Makefile from
Makefile.am must be requested in configure.in and autogen.sh must be run 
again.


3. Language specific remarks
3.1 If developing in fortran:
      - Many convenient declarations can be obtained by inclusion
        of common.h
	
      - All variables defined in the configuration file are easily 
        accessible via convenient subroutines
	    getopt_or_die(var), getopt(var,default), getint...
        defined in the getopt.f. 

      - Sometimes modularity in Fortran is hard to enforce because
        fortran uses global file descriptors. Therefore, convenient
	routines init_fdpool(), get_fd() and close_and_free_fd() 
	were implemented to prevent file descriptors conflicts.
	
      - Logging messages should be written to a descriptor log_fd,
        after initializing it by calling 'init_fdpool' and 'start_logging'
	subroutines. At the end of the program, 'stop_logging' subroutine
	should be called. (See any run_*.f file for an example.)

      - Verbose mode of the program is specified by the 'verbose'
        variable defined in common.h and initialized in the 
	'start_logging' subroutine. If set to false, no messages
	should appear on the screen.

      - When exiting on error from a program, a subroutine 
        'exit_nicely' should be used to clean-up and return 
	proper code to gvib.

      - Concepts of modular and structured programming should not
        be ignored even in Fortran.

3.2 If developing in c:
      - Basicaly, everything which was said above for fortran is
      also true for c. Look in cgvib.h for predefined macros and
      utility functions.

3.3 When writing Perl scripts:
      - To access Perl subroutines defined in Gvib modules, add
      the lines 
            # Script living in the Gvib home:
            #   use FindBin;
            #   use lib "$FindBin::Bin";
            #
            # Script not living in the Gvib home:
            #   use lib "$ENV{GVIB_HOME}/bin";
            #
            use Gvib;               # Access to gvib config and utilities
            use parse_glog;         # Reading and parsing gaussian outputs
            use mcm;                # Reading and writing MCM files
            use ioGvib;             # Reading and writing Gvib files
            use geometry;           # Methods for calculating angles, etc.
      There is no seperate documentation of subroutines available in 
      these modules, but at least few comment lines are always available
      there.

Keep everything commented & well documented. Good luck!