***********************************************************************

 The present file (README.1ST) illustrates the installation and the
 gross features of the program CACAO.  More details are contained in the
 file MANUAL which can be found in the directory MOAN after a
 successfull installation. MANUAL is provided in different formats:

                1) MANUAL.TXT (ascii file)
                2) MANUAL.PS  (PostScript)
                3) MANUAL.DOC (WinWord2.0 Document)

***********************************************************************


      How to retrieve, install and get acquainted with CACAO:
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 CACAO is a multipurpose EHMO package with graphical interface written
 and distributed by:
 Drs. Carlo MEALLI and Davide M. PROSERPIO
 CACAO consists mainly of two programs (EHC.exe for EHMO calculations
 and CACAO.exe (for interactive analysis)

 The present version CACAO4.0 (July 1994) has many new improvements
 with respect to the previous ones.
 Compiled with Fortran Powerstation (V 1.0) by Microsoft, it allows to
 bypass the limit of DOS 640K, the limit being now given by the physical
 memory available in your computer and by the maximum array dimensions
 for atoms (125) and orbitals (500).

 Among the many features, CACAO offers the possibility of analyzing
 many different datasets (from different EHMO calculations) in a single
 interactive session for comparative purposes.
 The quality of the drawings and the speed to generate them is now
 improved. The hard copy of any drawing on the screen can be obtained
 in real time with a single key-stroke.

 The whole CACAO package is contained in the file cacao40.exe, available
 via FTP by logging at 149.139.10.2 (cacao.issecc.fi.cnr.it) as
 anonymous (use your e-mail as password).  Get the file in the binary
 mode.

 One can also get from the same FTP source in the subdirectory PRINTGL
 the distribution files related to the utilities PRINTGL which are used
 to print the CACAO drawings from inside and outside CACAO.
 !!!! CACAO is freeware, whereas PRINTGL is not. Read carefully
 the instructions coming with the latter in order to keep up with
 the requirements of the distributors. We decline any responsability
 for the improper usage of PRINTGL !!!!
 The interface between CACAO and PRINTGL consist of two BAT files
 (PL.BAT and PLOTF.BAT) resident in MOAN.
 The user can setup his own printer by modifying the file PLOTF.BAT
 The default settings are for HP LaserJet or Deskjet Color Printer
 if Postscript is required. In fact, an option of CACAO allows the user
 to choose the keys P or S for print on a Laserjet or on the
 Postscript Printer, respectively. As a further option a Poscript file
 can be created to be printed later.
 Outside CACAO type PL to find out about the printing options after a
 CACAO session.

                            INSTALLATION
                            ^^^^^^^^^^^^
 The file cacao40.exe is a self-extracting one. Thus, copy first the
 file in the Directory C:\MOAN (an acronym for MO ANalysis).
 It is important that MOAN is in your path. (Please, modify the file
 AUTOEXEC.BAT, accordingly)

 Then type:
 C:\MOAN> CACAO40.EXE -d

 The succesfully extraction creates the following files and one
 subdirectory:

 cacao.exe   ehc.exe     dosxmsf.exe   dosxnt.386
 eh.bat      pl.bat      plotf.bat     view.bat
 param.dat   readme.1st  biblio.txt
 manual.txt  manual.doc  manual.ps
 FILES      

 Two files DOSXMSF.exe  DOSXNT.386 are necessary for running the
 programs in the extended memory mode (you may already have them in
 your PC, if so, remove them from MOAN!). These files must be
 in the Pathway.

 To run the programs in a DOS section under Windows, you must
 add in the file \windows\SYSTEM.INI under the section [386Enh] the
 following line:
 DEVICE=X:\MOAN\dosxnt.386

 MOAN can have many working subdirectories containing your datasets.
 The command to run CACAO or to print (EH or PL) is issued from the
 working subdirectory.

 After completing the installation, start practicing. Read the
 supplied MANUAL and then try a few of the calculations proposed
 with the sample input files.

 EH is the major command file which concatenates all the operations and
 also it permits to edit the current input file, after a first trial
 EHMO calculation.
 The typical DOS command to start a CACAO session on the nitrogen
 molecule  is:

 e.g. >EH  FILES   N2    CON

 The first parameter specifies the working directory.  The second
 parameter (=filename, do no type the extension IN) specifies the
 input file, previously created with your favoured editor (modify EH.BAT
 if the latter is other than EDIT from DOS). The third parameter is
 relative to the output device and it can be CON or NUL or Blank (it
 creates N2.OUT, in the latter case).
 The third parameter is necessary only for EHMO calculations
 (EHC program).
 When EHC is finished, you will be prompted whether to run CACAO or to
 edit the input/output file or to quit.
 Although you can try immediatly the capability of CACAO to make
 drawings, you may run first another ehmo calculation, e.g. that for
 bending carbon dioxide. Thus, Quit at the prompt (=Q) and type:

 >EH FILES CO2 CON

 After EHC is over, start a CACAO session (=C option at the prompt).
 The two available datasets (N2 and CO2) can be analyzed at one time.
 In fact, at the beginning of the interactive session the available
 datasets are listed and the user can choose one of them by its number
 (type 2 for N2). Then, the user is piloted through the program by the
 questions proposed. In general, there are a few alternatives for each
 question.
 At any moment, the results for CO2 can be graphycally analyzed beside
 the current ones for N2.
 The possible drawings (Interaction or Walsh Diagrams), threedimensional
 MOs and their FMO components, evolution of a single MO along the
 deformational pathway, etc. can be seen on the screen and printed.

 An interactive CACAO session can be started without running EHC first,
 by using the command file EH without supplying any Filename but only
 the name of the working subdirectory, e.g.

 >EH FILES
   or
 >EH .
 (the dot supersedes the subdirectory name if you are already in FILES)


 At this point, you should be already an expert at least on using the
 programs if not in MO and Perturbation theories! Thus, you may
 experiment your own calculations. Create a directory MYDIR and, by
 using an editor, build up your INPUT file. Then, run the programs.
 Beware anyway, because assigning useful chemical meanings to the
 results, it's a completely different story!!!!


 Please contact us in case you need more specific help.

                Carlo Mealli e  Davide M. Proserpio

  C.M.
  Istituto per lo Studio della Stereochimica ed Energetica
  dei Composti di Coordinazione (ISSECC-C.N.R.)
  Via J.Nardi 39 - 50132 Florence (Italy)
  Tel. +39-55-243990 or 2346653 - FAX: +39-55-2478366
  e-mail  MEALLI@CACAO.ISSECC.FI.CNR.IT

  D.M.P.
  Istituto di Chimica Strutturistica Inorganica
  Universita' di Milano
  Via Venezian 31, 20133 Milano (Italy)
  Tel +39-2-70635120 - FAX : +39-2-70635288
  e-mail  DAVIDE@STINCH0.csmtbo.MI.CNR.IT