@database words.hyper
@node MAIN

@{FG shine}Revision Control for GoldED  EXPERIMENTAL BETA RELEASE@{FG text}

@{b}CONTENTS@{ub}

  @{" Introduction                 " link INTRODUCTION }
  @{" What is RCS ?                " link WHAT         }
  @{" RCS for GoldED               " link GOLDED       }
  @{" Toolbar                      " link TOOLBAR      }
  @{" Glossary                     " link GLOSSARY     }
  @{" Reference                    " link "RCS:/hwgrcs/man/rcs.guide/main"}

  The reference pages are only available if you have installed HWRCS !

@{b}COPYRIGHT@{ub}

  All programs/files belong to their authors.

@{b}DISCLAIMER@{ub}

  RCS for GoldED is an experimental beta version. Use at your own risk.  No
  warranties are made. No liability or responsibility is assumed.

@{b}DISTRIBUTION@{ub}

  This package may be made available by online  services  for  downloading.
  Aminet   distribution   permitted.   All  other  forms  of  distribution,
  including, but  not  limited  to,  CD-ROM  distribution  require  written
  permission.

@{b}CONTACT INFO@{ub}

  Dietmar Eilert
  Mies-v-d-Rohe-Str.31, 52074 Aachen, Germany
  Phone: +49-(0)179-5987061 German/English
  E-Mail: Dietmar.Eilert@post.rwth-aachen.de
  E-Mail: dietmar_eilert@yahoo.de (alternative address)
  WWW:    http://members.tripod.com/golded
  Mirror: http://members.xoom.com/golded

  Heinz Wrobel (HWRCS)
  Karlstrae 16
  82131 Gauting
  Germany
  FAX +49 89 850 5125
  <heinz@hwg.muc.de>

@endnode
@node INTRODUCTION Introduction

@{b}INTRODUCTION@{ub}

  RCS for GoldED is a preconfigured HWRCS setup to be used with GoldED.  It
  seamlessly  integrates HWRCS with GoldED using a set of ARexx scripts and
  allows you to use the benefits of a revision control system  without  the
  hassle  of  dealing  with shell commands (at least for most of the time).
  RCS stand for revision control system. HWRCS is Heinz Wrobel's Amiga port
  of  GNU RCS. Please note that RCS for GoldED supports only a small subset
  of what RCS and HWRCS have to offer. In particular, multiple branches  of
  development and revision merging are not supported.

@endnode
@node WHAT "What is a revision control system ?"

@{b}WHAT IS A REVISION CONTROL SYSTEM ?@{ub}

  A  revision  control  system  supports  maintenance  of  large   projects
  consisting  of  many  files  modified  frequently  (possibly  by  various
  authors). Large programming projects obviously fall into  this  category.
  Functions of RCS:

  o Store and retrieve multiple  revisions  of  text.  RCS  saves  all  old
    revisions  in  a  space  efficient  way.  Changes no longer destroy the
    original, because the previous revisions remain  accessible.

  o Maintain  a  complete  history  of  changes.  RCS  logs   all   changes
    automatically.  Besides  the  text  of  each  revision,  RCS stores the
    author, the date and time of check-in, and a  log  message  summarizing
    the  change.  The  logging makes it easy to find out what happened to a
    module, without having to compare source listings or  having  to  track
    down colleagues.

  o Resolve access conflicts. When two or more programmers wish  to  modify
    the  same  revision,  RCS  alerts  the  programmers  and  prevents  one
    modification from corrupting the other.

  o Control releases and configurations. Revisions can be assigned symbolic
    names  and  marked  as  released, stable, experimental, etc. With these
    facilities, configurations of  modules  can  be  described  simply  and
    directly.

@endnode
@node GOLDED "Using GoldED as RCS frontend"

@{b}USING GOLDED AS RCS FRONTEND@{ub}

  The major advantage of using GoldED as frontend for RCS is that you won't
  have  to  deal  with  check-in and check-out operations directly on shell
  command  level.  Instead,  all  basic  procedures   including   check-in,
  check-out  and project setup can be accessed via a toolbar in GoldED (the
  toolbar functions are based on fairly  complex  ARexx  macros).  However,
  many  advanced  RCS  operations  still require that you are familiar with
  using RCS commands directly. You'll find links to the manual pages of RCS
  and  RCS  commands  below  (these  pages  are  only available if you have
  installed HWRCS).

  @{" INTRODUCTION " link "RCS:/hwgrcs/man/rcs.guide/RCSINTRO" } Introduction to RCS commands
  @{" CI           " link "RCS:/hwgrcs/man/rcs.guide/CI"       } Check in RCS revisions
  @{" CO           " link "RCS:/hwgrcs/man/rcs.guide/CO"       } Check out RCS revisions
  @{" RCS          " link "RCS:/hwgrcs/man/rcs.guide/CO"       } Change RCS file attributes
  @{" INDEX        " link "RCS:/hwgrcs/man/rcs.guide/main"     } Index

@{b}HOW IT WORKS - IN A NUTSHELL@{ub}

  RCS for GoldED will create a subdirectory "RCS" in your project directory
  where  it will save your project's documents in a space-efficient format.
  The term "project" refers to a set of related files stored  in  the  same
  directory (for example a collection of source codes forming a programming
  project). RCS will remove the documents from your  project  directory  so
  that  none  of the files can be modified directly. Instead, you will have
  to "check out" a document before you can edit it. Checking out means that
  RCS  will place a revision (usually the latest revision) of the requested
  document in your working directory where you can edit it. You'll check-in
  the  file again if you are satisfied with your modifications. Checking in
  the file means that RCS will move the  new  revision  from  your  working
  directory  back to the RCS directory. This will remove the file from your
  working directory. No other user can check in the same file while you are
  holding  a  lock  on it. That's how RCS prevents access conflicts. Please
  note that read-only copies of each files can still be checked out by  you
  or other users as RCS only supervises check-ins. RCS for GoldED uses this
  feature ("check-out without obtaining a lock")  to  maintain  a  snapshot
  directory  were  it  will always store recent read-only revisions of your
  files. The snapshot directory could be  the  place  where  your  compiler
  finds the files.

  See also: @{"PROJECT DIRECTORY" link GLOSSARY}, @{"WORKING DIRECTORY" link GLOSSRAY}, @{"CHECK-IN" link GLOSSARY}, @{"CHECK-OUT" link GLOSSARY}

@endnode
@node TOOLBAR "Toolbar"

  Toolbar

  Symbol   Description                     Technically speaking
  -----------------------------------------------------------------------
  @{FG shine}Face@{FG text}     Logs in  to  RCS  so  that RCS  Sets   environment    variable
           knows who you are.              LOGNAME  to  your  user  name.
                                           Creates    a    new    working
                                           directory  if  a  user logs in
                                           for the first time.

  @{FG shine}Wizard@{FG text}   This   wizards   guides    you  Creates the RCS repository and
           through  the steps required to  RCS configuration files in the
           put  a  directory  under   RCS  project path. Prompts  you  to
           control.                        select the documents to be put
                                           under RCS control.  Checks  in
                                           all   files.  Configures  your
                                           working directory. Initializes
                                           the snapshot directory.

  @{FG shine}Input@{FG text}    Assigns a symbolic name  (like  Runs  rcs  for  each  file  to
  @{FG shine}field@{FG text}    Initial  Release  1.0) to your  assign the choosen name to the
           current set of files.           latest revision of each  file.
                                           Please  note  that  spaces  in
                                           symbolic  names  are  silently
                                           converted  to  shifted  spaces
                                           because RCS doesn't allow  raw
                                           spaces in symbolic names.

  @{FG shine}Header@{FG text}   Inserts program header.         Inserts sample  header  (C/C++
                                           format)  into your document to
                                           demonstrate usage of  reserved
                                           RCS placeholders.

  @{FG shine}Pen@{FG text}      Performs a full check out  and  Runs co with the -l option  to
           opens    the   latest   locked  check   out   and   lock   the
           revision of the specified file  specified  file.  Places   the
           in  a  new  editor window. The  file     it    your    working
           same file can  not  be  locked  directory.
           again by other users until you
           check it in.  Hold  the  SHIFT
           key  to  check  out a specific
           revision.

  @{FG shine}Glasses@{FG text}  Performs a read-only check out  Runs  co  to  check  out   the
           and   opens   the  file  in  a  specified     file     without
           read-only editor window  where  obtaining a lock.  Places  the
           you  can  view  the  document.  read-only   document  in  your
           Hold down the SHIFT key  while  working directory.
           clicking  at  this  gadget  to
           check out a specific revision.

  @{FG shine}Ok@{FG text}       Performs a  check-in  for  the  Moves  the  file   from   your
           current     document,     thus  working   directory   to   the
           releasing the lock you hold on  project directory and runs  ci
           the  file. Will prompt you for  to check in the document.
           a     log     message      and
           automatically   assign  a  new
           revision code to the  modified
           document (SHIFT-click to set a
           specific      version.revision
           code).  Please  note  that RCS
           automatically reverts  to  the
           last  revision if you check in
           an   unmodified   file.   This
           operation will remove the file
           from  your  working  directory
           and clear the editor window.

  @{FG shine}Cancel@{FG text}   Deletes the current  document.  Deletes  the  file   in   your
           Modifications added after  the  working   directory.  Runs  co
           file  has been checked out are  with the -l option  to  obtain
           lost. Releases  your  lock  on  the  previous  revision and ci
           the file.                       to release your  lock  on  the
                                           file.

  @{FG shine}List@{FG text}     Shows  a   detailed   revision  Runs rlog to obtain statistics
           report for a document.          for    the    file   currently
                                           displayed   in   the    editor
                                           window.

  @{FG shine}Help@{FG text}     Displays this guide.

@endnode
@node GLOSSARY "Glossary"

@{FG shine}GLOSSARY@{FG text}

  @{b}PROJECT DIRECTORY@{ub}

    The directory where you kept your documents before  you  started  using
    RCS.  RCS for GoldED will create the RCS subdirectory ("repository") in
    the project directory and  use  this  directory  as  storage  path  for
    revisions.   It   will  additionally  create  the  configuration  files
    "RCS_link" and "RCS_config" in your project directory.

  @{b}CHECK-OUT@{ub}

    The check-out operation places a specific revision - usually the latest
    revision  -  of a specific file in your working directory. Files can be
    checked-out in a read-only mode  (lock-less)  or  in  full-access  mode
    (locked).

  @{b}WORKING DIRECTORY@{ub}

    The  directory  where  you  edit  files.  RCS  for  GoldED  will  place
    checked-out  files  in  the  work  directory of the user performing the
    check-out. The working directory  can  be  the  same  as  your  project
    directory  but  a  dedicated  private  working directory helps to avoid
    conflicts with other users on the same network.

  @{b}CHECK-IN@{ub}

    The check-in operation stores a new revision  of  a  file  in  the  RCS
    repository.  Only  files checked out in full access mode can be checked
    back in after modifications. The check-in must be performed by the user
    who has initiated the check-out.

  @{b}SNAPSHOT DIRECTORY@{ub}

    The path where RCS will maintain a mirror of your projects's files (the
    latest  read-only revision of each file). The snapshot directory can be
    used to publish the current state of your project on a network.

  @{b}LOGIN@{ub}

    Users must login to RCS before RCS commands  can  be  used.  The  login
    procedure  consists of setting the environment variable LOGNAME to your
    user name (RCS for GoldED will handle this aspect  of  logging  in  for
    you). Please note that user names are case-sensitive.

  @{b}PLACEHOLDERS@{ub}

    Placeholder strings of the form $<keyword>$ embedded in  documents  are
    replaced with strings of the form $<keyword>:<value>$ during check-out.
    Keyword and value are pairs listed below. Keywords may be  embedded  in
    literal strings or comments to identify a revision.

    Placeholder  Description
    -----------------------------------------------------------------------
    @{FG shine}$Author$@{FG text}     The login name of the user who checked in the revision.

    @{FG shine}$Date$@{FG text}       The date and time (UTC) the revision was checked in.

    @{FG shine}$Header$@{FG text}     A standard header containing the full pathname of the  RCS
                 file, the revision number, the date (UTC), the author, the
                 state, and the locker (if locked).

    @{FG shine}$Id$@{FG text}         Same as $Header$, except that the RCS filename is  without
                 a path.

    @{FG shine}$Locker$@{FG text}     The login name of the user who locked the revision  (empty
                 if not locked).

    @{FG shine}$Log$@{FG text}        The log message supplied during  checkin,  preceded  by  a
                 header  containing  the RCS filename, the revision number,
                 the author, and the date (UTC). Existing log messages  are
                 not  replaced.  Instead,  the  new log message is inserted
                 after  $Log:...$.  This  is  useful  for  accumulating   a
                 complete change log in a source file.

    @{FG shine}$RCSfile$@{FG text}    The name of the RCS file without a path.

    @{FG shine}$Revision$@{FG text}   The revision number assigned to the revision.

    @{FG shine}$Source$@{FG text}     The full pathname of the RCS file.

    @{FG shine}$State$@{FG text}      The state assigned to the revision with the -s  option  of
                 rcs or ci.
@endnode
