INTRO_EXP(4)                     RPN UTILITY                      INTRO_EXP(4)
NAME 
        intro_exp -   introduction to the etagere system 
                      (environnement  de   travail   automatise   de   gestion
                      d'experiences avec RCS). 

DESCRIPTION

        etagere is  a source  code  management system  based on  RCS.  etagere
allows multiple users  to modify source  code files that  are kept in  various
source libraries known as RCS master directories. All modifications done to  a
set of source files  can be saved  in a local  RCS sub-directory (RCS  working
directory) and serve as the starting point for further modifications. Each set
of modifications that is saved creates  a new revision in the rcs files of the
rcs working directory. A new revision constitutes an experiment.

        The basic commands of the etagere system allow a user to open,  close,
extract, delete an  experiment, to obtain  working copies of  modules, and  to
maintain a history file for all the  experiments saved in a given RCS  working
directory.

        Additional commands  are provided  to  ease the  work in  the  etagere
environment.  They  are used for  instance, to  list the contents  of all  RCS
master directories, list all possible revisions for a given module, search for
a regular expression in all the modules of all RCS master directories, etc.

        Finally,  menu_exp(1) (a  general entry point  command used to  access
all the other commands) and etagere(1)  (a command that displays the list  and
usage summary of all the etagere  commands) may be used to further  facilitate
source code development using the etagere environment.

DEFINITION OF TERMS USED IN THE ETAGERE DOCUMENTATION
        
        MODULE-                 a  source  code  file.    Presently,   etagere
                                recognizes files with  extensions .ftn,  .ptn,
                                .cdk,  .f, .c, .s, .h and .txt.

                                A compileable  fortran  file  is  produced  by
                                submitting  a  .ftn  or  .ptn file  to  the  c
                                preprocessor cpp. The treatment of .cdk  files
                                is similar to that of C header files and thus,
                                are included in a .ftn or .ptn file via a  cpp
                                directive of the form: 
                                      #include "afile.cdk"

                                When processing  a  .ptn   file,  the  PROGRAM
                                statement  it  contains   is  replaced  by   a
                                SUBROUTINE statement.

                                A .txt file  is a  text file such  as a  shell
                                script.  When a writable .txt file is found in
                                the current  working  directory,  it  will  be
                                deposited as a  new revision  in the RCS  sub-
                                directory when the experiment is closed.

        EXPERIMENT-             any modifications  done to  a related  set  of
                                source  code   files  (adding,   deleting   or
                                modifying modules)  for which the user  wishes
                                to  keep   a  permanent   record  for   future
                                reference.     An  experiment   is  saved   by
                                depositing a new revision of all the  modified
                                modules in  the  RCS  working  directory.    A
                                symbolic  name  is  associated  to  the  newly
                                deposited revision  and any  reference to  the
                                revision is done  through this symbolic  name.
                                In etagere, the symbolic  name is referred  to
                                as the experiment name.

        RCS MASTER DIRECTORY-   a directory containing a related set of source
                                code files (modules) with which a user  wishes
                                to work.  The files are kept in rcs format.

        RCS WORKING DIRECTORY-  a sub-directory  of  the    working  directory
                                where all  the modules  of an  experiment  are
                                saved as new       revisions in  corresponding
                                rcs files upon closing the experiment.

                                The RCS working directory, which must be named
                                RCS, is created by etagere if necessary.

        BASE-                   the name of the experiment that serves as  the
                                starting  point  of  the  current  experiment.
                                BASE corresponds to a  revision number in  the
                                RCS working  directory.    If  BASE=base,  any
                                module obtained via an etagere command will be
                                extracted  from   one   of  the   RCS   master
                                directories.

        RCSPATH-                An etagere environment variable that  contains
                                the path  to all  the RCS  master  directories
                                associated with the current experiment.

                                This variable is kept in the .exper_cour file.

        RCSBASE-                An etagere environment variable that  contains
                                the name of the experiment (i.e., the symbolic
                                rcs  revision  number)  which  serves  as  the
                                starting point for the current experiment.

                                This variable is kept in the .exper_cour file.

        RCS-                    Revision Control System. RCS manages  multiple
                                versions or revisions of a text file.  An  RCS
                                file is  an  archive file  that  contains  all
                                revisions of a particular file.
                                information.

FILES 
        .exper_cour-            a file  kept in  the local  working  directory
                                used  to  store  the  values  of  RCSBASE  and
                                RCSPATH  for  the   current  experiment.   The
                                environment   variables    contained   in    a
                                .exper_cour file  (RCSBASE and  RCSPATH)  have
                                precedence  over  the   RCSBASE  and   RCSPATH
                                initialized via a setenv command.

        RCS/histoire,v-         a rcs file that  contains the history of  all
                                the experiments  that  have been  saved  in  a
                                given RCS working directory.

ENVIRONMENT VARIABLES
        RCSPATH-                contains  the  list  of  all  the  RCS  master
                                directories for the current experiment.   This
                                environment   variable   is   kept   in    the
                                .exper_cour file.

        RCSBASE-                name of the experiment  used as the basis  for
                                the current experiment.

        CMCLNG-                 environment variable  used  to  determine  the
                                language of operation of the etagere commands.

                                To obtain french versions of etagere commands,
                                enter the following line:

                                setenv CMCLNG francais

        TMPDIR-                 name of the directory where temporary  working
                                files are stored.

        CCLARGS-                environnement variable used to indicate  which
                                version of cclargs should be used (full-screen
                                or line mode) for the recuperation of  command
                                line  arguments.  The   full-screen  mode   of
                                operation relies on the curses library and may
                                yield   different    results   on    different
                                platforms.  Full-screen  mode   may  even   be
                                unusable on some machines.

                                When the full-screen mode of operation of  the
                                etagere  scripts   turns out to be  inadequate
                                on your system or terminal, you should add the
                                following line to your .login file:

                                      setenv CCLARGS cclargsx

                                This will  force scripts  to prompt  for  user
                                supplied information in a line editor fashion.

AUTHOR 
        James Caveen - RPN
        Latest revision: November 1993

NOTES 
        See also clt_exp(1), cltr_exp(1), dir_exp(1), eff_exp(1),  etagere(1),
frm_exp(1), grep_exp(1),  hst_exp(1),  make_exp(1),  mdm_exp(1),  menu_exp(1),
mrcs_exp(1),  omd_exp(1),  omdr_exp(1),  ouv_exp(1),  qui_exp(1),  rev_exp(1),
smod_exp(1) and sor_exp(1).

        For other  related  utilities,  you should  also  consult  globrev(1),
refuse(1),     rcsintro(1),  ci(1),   co(1),  rcs(1),   rlog(1),   rcsdiff(1),
rcsmerge(1),  rcsfile(4), cpp(1) and make(1).