          QVCS -- Quma Version Control System $Version: 2.5.970301 $.
              $Copyright ©  1991-1997 Jim Voris.  ALL RIGHTS RESERVED. $

========================================================================
RIGHTS TO USE AND DISCLAIMER. This version of QVCS may be distributed
provided it is distributed in the same form that it was received. This
release of QVCS is "shareware". Any distribution MUST include the
readme.txt file and all the files listed in the readme.txt as files
contained in the qvcs1623.zip or qvcs3223.zip archive. Any use of QVCS
(commercial or non-commercial) is encouraged, though I provide NO
WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, THAT QVCS IS USEFUL FOR
ANYTHING. IN NO EVENT SHALL JIM VORIS BE LIABLE FOR ANY DAMAGES
WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS
OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF JIM VORIS HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. If after 60 days of use, you
want to continue to use QVCS, you must pay me (Jim Voris) a registration
fee. See the license.txt file for details.
========================================================================

This file briefly describes how to get started using QVCS.  If you've
gotten far enough to read this file, then you've succeeded in unzipping
the QVCS1623.ZIP (the 16-bit 2.3 release) or QVCS3223.ZIP (the 32-bit 2.3
release) archive.

Note:  Windows 3.1 users MUST first install Microsoft's latest (1.3) Win32s
before trying to run qwin.exe.  You can download the file pw1118.exe directly
from Microsoft by first going to their web page:  http://198.105.232.5/kb/softlib/
and from that page searching for the file pw1118.exe.

(Use: pkunzip -d qvcs1623.zip) The archive contains the files:

readme.txt	what you're reading
license.txt The QVCS license

qput.exe	    store (put) a revision in a logfile
qget.exe	    fetch (get) a revision
qlock.exe	    lock a revision
qlog.exe	    report logfile and revision info
qident.exe	    find QVCS keywords in any file
qmodhdr.exe	    modify logfile header info
qmerge.exe	    merge separate edits of same file
qdelrev.exe	    delete revisions from logfile
qmodrev.exe	    modify logfile info for specific revision
qdiff.exe	    compare files and/or revisions
qedit.exe	    apply results of qdiff to convert a file from one
                revision to another
qstamp.exe	    version stamp a logfile or set of logfiles
qunlock.exe	    unlock a revision
qunstamp.exe    remove a version stamp from a logfile or set of logfiles
qwin.exe        QVCS for Windows
qwin.hlp        Windows help file for qwin and QVCS.
qwinsamp.ini    Sample qwin.ini file.

qput.usa        usage file for qput.exe
qget.usa        usage file for qget.exe
qlock.usa       usage file for qlock.exe
qlog.usa        usage file for qlog.exe
qident.usa      usage file for qident.exe
qmodhdr.usa     usage file for qmodhdr.exe
qmerge.usa      usage file for qmerge.exe
qdelrev.usa     usage file for qdelrev.exe
qmodrev.usa     usage file for qmodrev.exe
qdiff.usa       usage file for qdiff.exe
qedit.usa       usage file for qedit.exe
qstamp.usa      usage file for qstamp.exe
qunlock.usa     usage file for qunlock.exe
qunstamp.usa    usage file for qunstamp.exe
qvcsmsgf        message file used by all QVCS utilities.

The Minimum you must do to use QVCS:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Create a single directory for all the files in this archive, and copy
   all the files to that directory.  If you plan on working
   on a network, put all the qvcs files into a network directory
   accessible to anyone that you expect to use it.  Make sure they
   have read/write rights to the directory.

2. Create an program group for qvcs, and/or a shortcut to qwin.exe.

3. Launch qwin.exe.  It will guide you through logging in for the
   first time.

4. Consult the on-line help for additional guidance.


Additional setup steps if you plan on using the command line utilities:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5. Edit your autoexec.bat to define 1 environment variable:

    	SET QVCS_ID=<YourName>

   where <YourName> is the name you use to login to qwin, and is the
   name that QVCS will use to identify you and the changes that you
   make.

6. Add an entry to your path for the the directory where you put the
   qvcs executables.


More setup steps for DOS users planning to use the command line utilities:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7. Edit you autoexec.bat to define two more environment variables:

        SET QVCS_ACCESSLIST=<YourName,etc>
        SET TZ=<Your time zone>

   For example, if you lived on the east coast, installed QVCS into C:\QVCSBIN
   and your name was John Smith, and you knew you also wanted Jane Smith to have
   access to QVCS controlled files you'd add these lines to your AUTOEXEC.BAT
   file:

    	SET QVCS_ACCESSLIST=JohnSmith,JaneSmith
    	SET TZ=EST5EDT

   The timezone environment variable tells QVCS your timezone so it can
   apply timestamps intelligently.  The four timezones in the contiguous
   U.S. are:  EST5EDT (Eastern), CST6CDT (Central), MST7MDT (Mountain), and
   PST8PDT (Pacific).  Other timezones are supported too; just make sure the
   4th character of the TZ environment variable identifies the offset of your
   time zone from Greenwich Mean Time.

8. Reboot so the changes to AUTOEXEC.BAT can take effect.


QVCS Briefly
~~~~~~~~~~~~
QVCS is a version control system.  It allows you to capture snapshots of
work in progress so you can safely move on to newer revisions of your
work.  It matches most of the features of the market leading products,
and introduces several features that make it uniquely valuable.

qwin.exe is a 32-bit Windows application.  It can run under Windows 3.1
provided you've already installed Win32s 1.3.  The other executables in
this release work from the command line.

For the command line utilities, typing the name of any QVCS utility with
no other command line arguments will display the usage file for that
utility.  Each usage file provides a synopsis of the utility and provides
some examples of how to use the utility.


Standard QVCS features include:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* save a file revision
* retrieve a file revision
* lock a revision for update
* unlock a locked revision
* parallel development of the same source file (branching)
* compress logfiles to minimize storage
* embed revision comments in source at point of revision.
* "floating" versions
* "automatic" branching
* etc...


Features unique to QVCS:
~~~~~~~~~~~~~~~~~~~~~~~~
* You can alter revision descriptions and have the altered descriptions
  appear in your source code without having to separately edit your source
  code.
* You can alter a module description and have the altered description
  appear in your source code without having to separately edit your source
  code.
* Unique $LogXX$ keyword allows you to show only the most recent XX
  revision descriptions in your source.  For example, a LogXX of Log5
  will expand only the 5 newest revision descriptions.
* Turn off keyword expansion when fetching revisions to leave keywords
  in their unexpanded state for ease in editing.
* The QVCS message file allows you to customize QVCS to suit your tastes.

This release of QVCS is shareware.  Please read license.txt for terms and
conditions of use.

I always welcome suggestions for improvements. Bug reports too, are welcome
from registered and unregistered users alike.


QVCS Keywords
~~~~~~~~~~~~~
If you enable keyword expansion, QVCS will expand keywords to provide
automated documentation for your source files.  QVCS supports the
following keywords (for expanded examples of the Version and Copyright
keywords, see the top of this file):

Author      expands to the author of the current revision.
Comment     allows you to embed revision comments within your
            workfile and have those comments automatically entered
            into the description of that revision when stored.
Copyright   expands to a copyright message of your own.
Date        expands to the edit date of the file used to create
            the current revision
Endlog      marks the end of and expanded log. You should NOT use
            this keyword!
Filename    expands to the name of the workfile into which the
            revision is being retrieved.
Header      expands to the name of the workfile, the current
            revision, the file date, and the file owner.
Log         expands to list ALL the revision descriptions.
LogX        expands to list the X most recent revision descriptions.
Logfile     expands to the full pathname of the logfile.
Owner       expands to the person who created the logfile.
Revision    expands to the revision number of the current revision.
VER         expands to the name of the source file (without the
            file extension), plus the version string associated
            with the current revision.
Version     expands the the version name associated with the current
            revision.


Limitations
~~~~~~~~~~~
* QVCS won't allow you to create logfiles for filenames that contain the
  $ or ! character.
* QVCS will only let you create branches to a depth of 20.
* QVCS does most of its work in memory.  If you work with really large
  files, you'll need lots of memory in order for QVCS utilities to
  succeed.
* For Windows 3.1 users, QVCS command line utilities in qvcs1622.zip use a
  DOS extender and therefore require a 386 or better CPU.
* Because of the DOS extender, The version of QVCS command utilities in
  qvcs1622.zip will not work under Windows NT.  Windows95 and Windows/NT
  users should make sure to use the utilities in qvcs3223.zip instead.



Bugs
~~~~
For the latest on bugs, see the WWW pages:

          For open bugs: http://www.clark.net/pub/jimv/bugs.htm
For recently fixed bugs: http://www.clark.net/pub/jimv/fixdbugs.htm
     For other new info: http://www.clark.net/pub/jimv/whatsnew.htm

To report bugs, please send me e-mail (jimv@clark.net) describing the
problem with as much detail as possible.


Updates
~~~~~~~
The latest version of QVCS for DOS/Windows 3.1 is always available via
anonymous FTP from:  ftp.clark.net in the file /pub/jimv/qvcs16xx.zip.
where xx is the release number.  The current release is 2.3, so the
archive is named qvcs1623.zip.

The latest version of QVCS for Windows95/NT is always available via
anonymous FTP from:  ftp.clark.net in the file /pub/jimv/qvcs32xx.zip.
The current release is 2.3, so the archive is named qvcs3223.zip.

Note that clark.net requires anonymous ftp users to supply
your e-mail address as the password.

I also generally post the latest info on the current release on my WEB
site instead of updating this readme file.  Check out the pages listed
in the Bugs section above to get the latest information.


Please communicate suggestions and bug reports to me at:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
jimv@clark.net or

Jim Voris
20 Warren Manor Court
Cockeysville, MD  21030

