#!/bin/sh
#==============================================================================
#
#  Name   :  RASSHelp
#
#  Version:  1.3
#
#  Purpose:  Gives some getting started help for RASS-Sun users
#
#  Remark :  This script is a RASS-Sun utility
#                       
#==============================================================================
# Implementation and Revisions:
#------------------------------------------------------------------------------
#
# Author  Date      Description
# ------  ----      -----------
# af      28/07/00  First implementation
# af      04/08/00  Minor improvements
# af      17/08/00  Improving language for more understandable behavior
# af      19/08/00  Explaining use of subdirectory sources
# af      27/08/00  RASS v 3.0.3 (as of this date, still under development)
# af      10/09/00  V 1.0.5: setRASSmailto replaces setmailto
# af      24/10/00  V 1.0.6: new job tutorial mentioned
# af      05/03/03  V 1.0.7: for RASS v 3.0.6: mentions also reprep
#                   Minor fix for bash vs. csh default shells
# af      29/03/03  V 1.1 updating text in tutorial to latest release
# af      27/04/05  V 1.1.1 for RASS 3.2.0 fis utility added
# af      11/07/05  V 1.1.2 for RASS 3.2.7 some polishing
# af      04/01/06  V 1.2 for RMSP1 1.42 - RASS 3.2.9 
#                   - hints on useful web sites added
# af      29/05/11  V 1.3 - RASS-Sun 3.5.6 - RAMSES 3.5.6 - RMSP1 2.6
#                   - Fixing URLs and further polishing
#                   - Shebang changed to /bin/sh instead of less used /bin/tcsh
#                     (makes testing under OS X possible)
#                   - Introducing var 'm2configfile' for consistent output
#
#==============================================================================
m2configfile="config.M2PATH"
echo "-------------------------------------------------------------------------"
echo "RASSHelp:  To get started with RASS-Sun follow these steps:"
echo ""
echo " 1) Create a new master directory for your RASS project. E.g. type"
echo ""
echo "            mkdir myfirst"
echo ""
echo " 2) Transfer all files of your RASS project to this directory."
echo "    On a Mac there are several ways to accomplish this: First use 'Fetch' or" 
echo "    the Finder's 'Connect to Server...' command (under Classic the 'Chooser')"
echo "    and connect to the RASS host, e.g. huron.ethz.ch. Then upload or copy all"
echo "    your files."
echo "    Note: All files means sources, i.e. all Modula-2 files of your Model"
echo "    Definition Program (MDP) plus possibly needed input files. These files"
echo "    ought to be of type TEXT. Optionally keep all sources in a subdirectory"
echo "    named 'RASS_Sources' within 'myfirst'."
echo ""
echo " 3) Make directory 'myfirst' your current working directory ('cd myfirst')"
echo "    type the following to rename, convert, compile, link etc."
echo ""
echo "            prepare"
echo ""
echo "    4) Optional (only needed if prepare does not succeed right away):"
echo "       a) edit your files if necessary, e.g. if a EOL (end of line)"
echo "          is missing at the end of a source file, e.g. using Alpha or vi"
echo "       b) execute command 'make' or even command 'prepare' once more."
echo "       Repeat a) and b) till all compilation and linking succeeds."
echo ""
echo " 5) Type command          job"
echo "                    or"
echo "                          run"
echo ""
echo "    to execute your RASS program.  'job' executes it interactively, 'run'"
echo "    executes it in batch mode.  The latter is convenient when a simulation"
echo "    experiment requires lots of time, since this allows you to logout while"
echo "    the job is still running.  You get a so-called experiment-directory"
echo "    with all your results. Hint: type 'job tutorial' to learn more on this."
echo "    IMPORTANT: Don't alter file 'job' as long as it is running! Instead"
echo "               make a copy and edit the copy to program a new experiment."
echo ""
echo " There are also 2 Systems Ecology Reports, number 20 and 21, describing"
echo " RASS. In particular Systems Ecology report #21 contains a RASS User's Guide."
echo " Find them at http://www.sysecol.ethz.ch/publications/reports"
echo ""
echo " RASS-Sun comes with following utilities:"
echo ""
echo "  - RASSHelp        (this file)"
echo "  - prepare         prepares your RASS project (alias 'prep')"
echo "                    (if '.cshrc' or '.profile' defines alias: 'prep')"
echo "  - reprep          prepare once more, preserves settings like E-mail etc."
echo "  - RASSMakeMake    generates Makefile" 
echo "  - autoedit        Adjusts sources containing compiler flags to RASS-Sun code"
echo "  - make            Unix utility to remake the program (see 'make help')"
echo "  - make help       mk generates a Makefile, use 'make help' to learn more"
echo "  - job             execute RASS program in foreground (job -o lists output)"
echo "  - run             execute RASS program in batch mode"
echo "  - setRASSmailto   sets, shows E-mail address(es)"
echo "  - setprojdescr    sets, shows, clears a project descriptor (alias: 'prj')"
echo "  - getjob          creates a new file 'job' in current directory"
echo "  - getm2config     creates a new file '${m2configfile}' in current dir"
echo "  - cleanup         cleans current directory, asks for deletion of job results"
echo "  - fis             find in sources"
echo "  - DEF2def, MOD2mod, def2DEF, mod2MOD, mac2unix, unix2mac conversion utils"
echo ""
echo "  Most utilities give help or respond to arguments such as show. Ex.:"
echo "  'setRASSmailto help', 'prj show', 'make show', or 'job tutorial'."
echo ""
echo "  Edit '${m2configfile}' for a User.Profile mechanism as in MacMETH." 
echo ""
echo "  Visit http://www.sysecol.ethz.ch/ramses/layer/RASS and"
echo "  http://www.sysecol2.ethz.ch/intranet/Unix_Hints.html#RASS for"
echo "  further info, e.g. on how to use the debugger or for literature."
echo ""
echo " Enjoy!"
echo "-------------------------------------------------------------------------"
echo ""