Details of the port of RCS to RiscOS

CONFIGURATION

One of the trickiest parts of porting RCS to RiscOS was creating a good configuration file. Apart from the finicky bits about what POSIX routines are available and in which variant, the following decisions were made:

All subcommands are called by their name only, without any directory or variable before it. This means that things like gdiff must be in a location which is included in the search path, such as $.Library.
RCS files are always put in a subdirectory called RCS. The default suffix for RCS files (normally ,v) is set to an empty string (see also the -x option for ci). This was done because of the limit of 10 characters for RiscOS file names. Adding 2 characters for RCS files would limit the length of workfile names to 8 characters, which is very impractical.

FILE NAMES

Porting the Revision Control System to RiscOS had some nasty difficulties, mainly due to the special way path names are formed on RiscOS, as can be seen in this example path:
ADFS::Csite.$.C.develop.!Bang.c.main In particular:

Directory separators are periods . instead of slashes / as in Unix. On the other hand, file names may contain slashes but no periods.
Path names can include a $.
File suffixes take the form of a directory. In the example, the file main is a C source file. On Unix it would be called main.c

Point 1 is partly solved by UnixLib. It contains a routine __uname() which converts the Unix style file names used by the program to RiscOS style file names.

Point 2 wreaks havoc with pre-5.7 RCS, where it messes up the keywords. These start and end with a $, and the one in the file name gets mistaken for the end of a keyword. From v5.7 onwards, RCS replaces these characters with a special code to avoid this problem. Because it does not look nice and may cause confusion, the RiscOS port tries to keep the number of occurences of the $ to a minimum.

As for point 3, RCS uses the suffix of the file to determine what kind of string to use for the lines with which the $Log$ keyword is expanded. In a RiscOS environment, the programs would not be able to recognize the suffix of a file. This is solved by a special routine called roname(), which performs roughly the inverse action of __uname(). This routine is used to translate parameters passed to a program into Unix style names. When a file called src.c.main is passed to a program, roname() will translate it to src/main.c, thus turning a directory name into a suffix. The choice of which directories are translated into suffixes is the same for roname() as it is for __uname(), and is controlled by the environment variable <UnixFS$sfix>.

It turns out that point 3 is no longer an issue. GNU RCS v5.7 no longer uses the file suffix to determine prefix in the expansion of the $Log$ keyword. Instead, it uses the string which comes before the $Log$ keyword itself.

As a result, it is no longer necessary to let the program interpret certain directories as file suffixes. Consequently, the RCS directory can now be put in the same directory as the workfile. By setting UnixFS$sfix to an empty string, directories will no longer be recognised as file suffixes. A workfile src.c.main will be translated to src/c/main, and the RCS file will be src/c/RCS/main. This will be the default behaviour for future versions.

The -Z option is crucial in the manipulation of RiscOS file names. On RiscOS, the RCS commands will only translate the arguments from RiscOS style to Unix style if the -Z option is given. Equally important, when an RCS command calls another command, like gdiff, this sub-command will not get the -Z option, because it's parameters will already be Unix style.

FILE TYPES

Under RiscOS, files have a type. This is unknown in most other operating systems, including Unix. In the example, main is a file of type Text. On the other hand, a makefile also contains text, but has type Makefile. The file type is unrelated to the name or "suffix".

Without special measures, RCS would only be able to handle text files, and manipulating files of other types would be very tedious, as the user would have to re-set the type of the file after every RCS operation. A solution for this problem was not strictly necessary, but after some trials it was considered to be a good idea to make RCS retain the type of a file.

To achieve this, the RCS file was extended with an extra field in the header, the type field, which states the RiscOS file type. Every time a file is checked in, the type of the workfile is determined and written in the RCS file header. Whenever a file is checked out, the type of the file is set to the value found in the RCS file header.

The type field in the RCS file also includes a file type name. Whenever possible, the system will try to maintain the most informational name possible. Note that RiscOS does not usually know the names belonging to every file type. A type may have been known in an earlier session, but might not be known in a later session. So when a type name is set in the RCS file but no name can be attached to the type number from the RCS file, the system will not change the type name in the RCS file.

When checking in a file for the first time, ci attempts to find the type name corresponding to the type number of the file.

The file type is shown by the rlog command. It can be manipulated with the -F option of the rcs command.

OPTIONS

New option for all commands except ident and merge, but including gdiff and diff3:

-Z

Interpret the file name arguments as RiscOS style names and convert them to Unix style names for internal processing. For most operations under RiscOS, this parameter is essential. You should always pass it to every command. A good habit is to always give it as the first argument on the command line, e.g. ci -Z -u c.main.

Note that some RCS commands call other commands in turn. co will call gdiff to reproduce older revisions and rcsdiff calls co to produce temporary older revisions and calls gdiff to compare them. When a program calls on another program, it passes file arguments in Unix style to them. Changing every location where a program calls another one is very complicated and may be subject to change in future versions of RCS. Instead, a choice was made to introduce the -Z option, which should be passed when a user gives a command from RiscOS. Programs which are called by an RCS command will not get the -Z option, and so will (correctly) assume that their parameters are Unix style file names.

As a bonus, operation on Unix systems will not be disrupted if the RiscOS code gets merged back into the GNU RCS sources. Users on Unix will simply not pass the -Z option.

In future, a RiscOS frontend will become available which will pass the -Z option automatically.

New option for rcs:

-Ftype

Set the type number of the file to type. The value type must be a hex number, optionally preceded with a "&". This option enables you to change the filetype of an RCS controled file after the initial check-in.

Examples:

rcs -Z -Ffff c.main
Set the type of c.main to text (&fff)

rcs -Z -F&faf html.RiscOSPort
Set the type of html.RiscOSPort to HTML (&faf)

In future this option will have the syntax -Ftype:name. This means it will be possible to set the type name explicitly, or set file type using the name of the type only.

ENVIRONMENT VARIABLES

The following environment variables which are used by RCS have a new name which conforms better to the RISC OS standard of writing variables.

Unix / MSDOS RISC OS Purpose

LOGNAME, USER RCS$Name Name of the person doing the modifications

TMPDIR, TMP and TEMP RCS$TempDir Directory to keep temporary files

PWD RCS$CSD Override current working directory name

RCSINIT RCS$Init Set default options for commands

Unix / MSDOS	RISC OS	Purpose
LOGNAME, USER	RCS$Name	Name of the person doing the modifications
TMPDIR, TMP and TEMP	RCS$TempDir	Directory to keep temporary files
PWD	RCS$CSD	Override current working directory name
RCSINIT	RCS$Init	Set default options for commands

Apart from better conformance to RISC OS, it also solves problems. In particular, some applications on RISC OS use the variable 'tmp' as temporary variable in their !Boot or !Run Obey files. This usually just causes the RCS commands to fail and report an error, but may occasionally produce interesting effects with temporary files popping up all over the disk.

RCS FILE FORMAT

The format of the RCS file (see 5.rcsfile) has been slightly extended to allow the storage of the filetype.

admin	::=	head	{num};

		{ branch	{num}; }

		access	{id}*;

		symbols	{sym : num}*;

		locks	{id : num}*;  {strict  ;}

		{ comment	{string}; }

(New part)--->	{ type   	hex	{name} ; }

		{ expand	{string}; }

		{ newphrase }*


hex	::=	{ digit | a | b | c | d | e | f | A | B | C | D | E | F }+


name	::=	{ any valid type name character }+

The type field is optional. If it is missing, the type is assumed to be &fff (Text). If an RCS file with a type field is transported to another system which does not support this field, then the RCS commands will report a warning about this field but otherwise ignore it. This means that RCS files created with this version of RCS can still be used on other systems.

The type number should be a 3-digit hexadecimal number. If the number is longer, only the lowest 3 digits will be used.

The type name is normally set to the name corresponding to the type number. It is purely there for the information of the user and can be viewed with rlog. Internally the system always works with the type number. The type name is 8 characters long and can contain just about any character except newline.

ci will look at the type of the workfile and set the file type number field accordingly. It will also look up the corresponding file type name and set this field also. If no name is known, the name will be set to "&<hex>" (just like the Filer shows you in the Info box).

co will read the file type number field from the RCS file and set the type of the workfile accordingly.

rlog will report the file type number and name

The rcs -F option can be used to set the file type number field in the RCS file directly. Just like ci, it will try to look up the corresponding type name.

CAVEAT

Do not add the -Z option to the RCSINIT variable. This will defeat the purpose of the -Z option, as subprograms will then interpret their file name arguments as RiscOS style names while in reality they are Unix style names.
When interactively entering descriptions and log messages, use the delete key for corrections, not the backspace key.
The system has only been tested in a single-user environment.

KNOWN PROBLEMS

Occasionally RCS commands will do nothing and report "RCS file <name> is in use". This happens when a previous command did not terminate in a regular way. As a result, the lock file created by the command was not removed.
To remedy this, open the RCS directory and remove the lock file for the file you want to operate on. It has a name where the last letter of the original name is replaced with an underscore ("_")
File type numbers which are all decimal digits (only 0-9, no a-f) are not handled correctly (e.g. 111 or 934, but not 11f or a35). When an attempt is made to check the file out, an error is reported. This is because of bad parsing of the type field in the RCS file.
As a temporary remedy, set the filetype to a different value (using rcs -F), and manually set it to the correct value after each checkout.
This bug will be fixed in the next version of RCS for RiscOS.
The type name field only reflects the type name up to the first space. Normally this is not a problem, but if the file type name contains spaces, only the part up to the first space is included in the RCS file type field.
This bug has no effect on the operation of the RCS commands, as the name field is only used for the information of the user (e.g. in the rlog command).
This problem is due to the overzealousness of the programmer. Silly me.
When breaking a lock with rcs -u/-l the program attempts to send mail to the owner of the lock, but as /bin/mail is not available, an error is reported.
Despite the error, the lock is removed, so operation is not hindered by this bug. The error message can however be annoying and confusing. Besides that, this operation is very rare, especially in a single-user environment, so it will not be a great problem.
In future versions we hope to actually send mail in a RiscOS environment, as well as giving better support for a multi-user environment.

File identification:

$Id: RiscOSPort 1.9 2001/01/28 09:44:31 erikgrnh Exp $