Archimedes RCS - File revision control system
---------------------------------------------

This port Copyright (C) 1990, Paul Moore.

Original Implementation Copyright (C) 1982 by Walter F. Tichy
                        Purdue University
                        Computer Science Department
                        West Lafayette, IN 47907



This Archimedes port of RCS was implemented by

Paul Moore,
10, Mulberry Rise,
Firdale Park,
Northwich,
Cheshire
CW8 4UQ

E-Mail: pmoore@cix.compulink.co.uk


Differences between this port and the Unix version of RCS
---------------------------------------------------------

1. As RISC OS is not a multi-user system, all files are considered to be
   owned by the user. This has implications when attempting to check in
   files with strict locking set OFF. This is the default condition (see
   rcs -L and rcs -U).

2. The username is assumed to be "root" if not specified. It is possible
   to specify a username to use, as the value of the OS variable
   <RCS$Name>. Thus, for example, I have set up in my !Boot file,

	*Set RCS$Name pmoore

   Note that there is no restriction on user names (they are only for
   documentation, after all).

3. The file naming conventions differ significantly. In the Unix
   environment, files are given suffixes such as ".c", ".h" etc, to
   determine their type. The RISC OS equivalent is to use directories
   ("C.", "H.", etc). Also, under Unix, RCS files have the same name as
   working files, with a ",v" appended (eg rcs.c,v). RCS files may be
   held in the current directory, or in subdirectory RCS.

   In contrast, under RISC OS, RCS files are always held in directory
   RCS, with the same name as the working file. So, for example, this
   file (ReadMe2) is stored in RCS file "RCS.ReadMe2".

   The working file name can have a directory prefix, which is stripped
   off before adding the "RCS". The only cases where this does not
   happen are when the directory prefix is one of the recognised
   prefixes (see the list in c.rcsfnms)

	Asm			Assembler
	C			C source
	F			Fortran
	H			C header
	L			Lex (Flex) source
	P			Pascal
	S			Assembler
	Tex			Tex source
	Y			Yacc (Bison) source

   This list can be tailored for other file "types". I would appreciate
   being informed about any "general" file types I might have missed,
   and I'll add them into the standard source. I also need to know how
   to specify comments in the language in question (for $Log$)

   Note that RCS will not create subdirectories of the RCS directory
   (yet!), so before doing a "ci C.Prog" make sure that RCS.C exists.

   If you don't like RCS files being in subdirectory RCS in the current
   directory (for example, in the RCS distribution, where directory RCS
   clashes with the executable rcs!), you can specify another location,
   by setting <RCS$Prefix>. This should be set to the prefix to be added
   before the working file name to get the RCS file (so it needs the
   dot).

   For example, in the RCS distribution, do

	*Set RCS$Prefix RCSFiles.

   before checking in/out etc.

   You can also do silly things like setting RCS$Prefix to ":0.$.",
   which will keep all RCS files on floppy disk 0, or "Ram:" to put them
   on ram disk (not very secure, this!). You could also set RCS$Prefix
   to something like "RCS_", to keep everything in the one directory
   (but watch out for file names longer than 10 characters! I can't
   guarantee that RCS will be too graceful in such pathological cases.
   But if it does fail, it IS a bug, and I want to know!!)

   This lot sounds fairly complicated, but it's fairly intuitive - just
   hard to explain clearly.

4. RCSFreeze does not exist yet. It's a shell script on Unix, and I
   haven't got round to porting it. The other two files in directory Sh
   (RCSMerge and RCSClean) do exist in C code form, though.

5. I haven't tried to implement SNOOP (logging of RCS commands). It's
   really for paranoid system administrators on multi-user systems. It
   should work if you just define SNOOPFILE correctly and re-build
   (adding snoop to the Makefile).


A couple of other notes
-----------------------

1. RCS only handles text files. This is a feature of the Unix version. I
   believe that some PC revision control packages handle binary files.
   It seems unlikely that RCS could be modified for binary files without
   a major rewrite, though.

2. To run RCS, you need some form of diff program (the Unix file
   comparison utility) available on Run$Path. An Archimedes port of Gnu
   Diff is available, either from me (send me a floppy), or on one of
   David Pilling's Archimedes disks (see his adverts in the magazines).

3. To build RCS, you need a small number of utility functions. These are
   supplied in my utilities library. I will include this on the final
   distribution disks (space permitting!), or you can get a copy from me
   (send a floppy to the above address).

   The functions are

getopt (int argc, char *argv, char *options)
   Unix standard argument processing

isatty (FILE *fd)
   Is fd connected to a terminal?

mktemp (char *name)
   Make a temporary file name from name.  The temporary name should be in
   temp_dir, if this is set.  The returned string is obtained from
   malloc(), and so can be freed.

strdup (char *str)
   Return a copy of str created by malloc().

strlcmp (char *s, char *t)
strnlcmp (char *s, char *t int n)
   Case-insensitive versions of strcmp() and strncmp().

dirscan (char *name)
   Scan the filing system for the first file name matching the
   wildcarded pattern name. dirscan(0) returns the next name. NULL is
   returned when there are no more names. The name returned is held in a
   static area, and will be overwritten next call. The function is
   designed to be used in a loop

	for (name = dirscan(patt); name; name = dirscan(0))
	{
		...
	}

fatal (int rc, char *msg, ...)
   Fatal error.

4. All RCS programs will accept a command option of -?, to give a brief
   summary of their syntax and options. For example, try "rcs -?".

5. RCS will preserve file types. For example, if you check in an Obey
   file, the RCS file will have a filetype of Obey (even though it can't
   be executed as such), and later checked-out versions will also be
   Obey files.

6. RCS can need a LOT of memory. In particularly bad cases, you can have
   (for example) co running merge, which runs diff. I think this is the
   worst it gets, but I'm not certain. As you can imagine, this eats ram
   FAST. I have a 4M machine, so I haven't really checked whether RCS
   works on smaller machines. But it does work from the desktop with a
   default wimpslot (640K), so it's not TOO gross (at least for basic
   uses).

7. Note the GNU general public license at the top of C.merge. C.merge
   was cribbed direct from Gnu Diff3 (to replace the shell script
   Sh.Rcsmerge) and so the license conditions apply. I think that
   because of this, the whole of Archimedes RCS may be under the Gnu
   license. Regardless, I'm going to put it under the Gnu license anyway
   (see file Copying) if I can - I'm not a lawyer, so I can't say for
   sure. But please note (as usual)

	I GIVE NO WARRANTY OF ANY KIND WITH THIS PROGRAM!!!!

	If RCS wrecks the only copy you have of your source code,
	I'm sorry but I'm afraid that's your problem. (Although
	obvoiusly, I have done all I can to make sure this doesn't
	happen - I'm using it on my source, after all!)


Paul Moore, 15/7/90.
