.TH RVC-FILES 5 "Nov 22, 2009" ""
.SH NAME
rvc-files - Specification of the file structure in a remote version control
directory (typically $HOME/remote-vc).

.SH DESCRIPTION
At a designated place, called the remote version control directory,
(typically $HOME/remote-vc) there is one directory \fBrvc-installed\fR and
several other directories called "module directories". 
The directory \fBrvc-installed\fR keeps track of the versions of files
copied to the remote locations, to traces changes that happened there.

The module directories are intended to be working directories under
some form of version control. Nevertheless, this is not mandatory (and
each module may use a different version control system). The only
assumption is that each module contains a "places file" (usually
called "rvc-places") following the structure detailed below.

Additionally, each module may contain a directories file (usually
called "rvc-dirs"). This file explains ownership and permissions of
directories, in order to create them correctly, when needed.

.SH STRUCTURE OF THE PLACES FILE

For each file that remotely is under version control by this module
there is one line in the places file. Each line is of the format

<name> <owner> <group> <permissions> <place_to_reside>

where the fields name, owner, group and permissions are separated by
whitespace and the place to reside is terminated by the end of
line. Note that therefore the name (and groups) my not contain
whitespace characters and that the place to reside must start with a
non-white-space character and must not contain a newline
character. These restrictions should not be too severe in practise.

Here the meaning of the individual fields is the following.

\fBname\fR
.br
The name of the file that is remotely under version control ("to be
installed elsewhere"). Names are relative to the module directory and
must name a file in (a subdirectory of) the module
directory. Otherwise the behaviour is unspecified.

\fBowner\fR
.br
\fBgroup\fR
.br
The permission the file should have at the remote place. After an
rvc(1) install, a chown(1) with the specified owner and group will be
called.

\fBpermissions\fR
.br
The permissions the file should have at the remote place. After an
rvc(1) install, a chmod(1) with these permissions is called.

\fBplace to reside\fR
.br
The remote place of the file. This must be an absolute path into the
file system. It must not name anything in the remote version control
directory or below.

.SH STRUCTURE OF THE DIRECTORIES FILE

Each line describes one directory with ownership and permissions. The
form of a line is as follows

<directory> <owner> <group> <permissions> 

with owner, group and permissions having the same meaning as in the
places directory.

.SH STRUCTURE OF THE RVC-INSTALLED DIRECTORY
The directory \fBrvc-installed\fR contains several subdirectories, one
for each file that is currently "installed", i.e., where a copy is at
some remote place. The directory name is the quoted absolute path of
the place where the file is installed. Each directory contains the
following, where future extensions may specify new files or
subdirectories.

\fBmodule\fR
.br
a file containing the name of the module this file is installed from

\fBfile\fR
.br
a file containing the file name within the module

\fBperms\fR
.br
a file containing owner, group, and permissions, in that order,
separated by whitespace

\fBdata\fR
.br
a copy of the file that actually was installed. This allows
separate tracing of changes in the module directory and the remote
directory. 

In case of a composed installed file, there will be additional files
present. 

\fBpart.0 part.1 part.2 ...\fR
.br
Copies of the original splitting of the installed file. \fBpart.0\fR
refers to the major files, i.e., the file described by \fBmoulde\fR
and \fBfile\fR.

\fBmodule.1 module.2 ...\fR
.br
\fBfile.1 file.2 ...\fR
.br
The same as module and file, but for the appended parts of a multi
file.

The following files may be present, if a file is a multifile.

\fBsplit.0 split.1 split.2 ...\fR
.br
These files constitute a guessed splitting of the remote file into
parts corresponding to the parts of the installed file. These files
need not be present and may be overwritten by any command that reads
the remote file.


.SH QUOTING
A simple quoting mechanism is used. All but letters (a-zA-Z), digits
(0-9) and hyphens (-) are replaced by 
an underscore, followed by the decimal code of that character followed by another underscore. 
This way of quoting is a 1-1 function. Note that, in particular, "_" is quoted as "_95_".

.SH SEE ALSO
.BR rvc "(1), "chown "(1), "chmod "(1)"

.SH AUTHOR
Klaus Aehlig <aehlig@linta.de>