.ig
  Copyright (C) 1993,1994 by the author(s).
 
 This software is published in the hope that it will be useful, but
 WITHOUT ANY WARRANTY for any part of this software to work correctly
 or as described in the manuals. See the ShapeTools Public License
 for details.

 Permission is granted to use, copy, modify, or distribute any part of
 this software but only under the conditions described in the ShapeTools 
 Public License. A copy of this license is supposed to have been given
 to you along with ShapeTools in a file named LICENSE. Among other
 things, this copyright notice and the Public License must be
 preserved on all copies.


 Author: Juergen.Nickelsen@cs.tu-berlin.de

 $Header: rcs2atfs.1[3.0] Tue Jun 29 16:38:28 1993 andy@cs.tu-berlin.de frozen $
..
.de CR
\\fC\\$1\\fP\\fR\\$2\\fP
..
.de RB
\\$1\\fB\\$2\\fP
..
.TH rcs2atfs 1 "Tue Jun 29 16:38:28 1993" "rcs2atfs-1.9" "ShapeTools"
.SH NAME
rcs2atfs \- convert RCS archives to AtFS format
.SH SYNOPSIS
.B rcs2atfs 
.RB [ \-o 
.IR outputfile ]
.RB [
.BR \-q ]
.IR archive " ..."
.br
.B rcs2atfs 
.RB [ \-o 
.IR outputfile ]
.RB [
.BR \-q ]
.B \-R 
.IR directory " ..."
.SH DESCRIPTION
.B Rcs2atfs
converts version histories from RCS archives to ShapeTools' AtFS
format. It uses 
.IR rlog (1)
to get information about an RCS archive and issues shell commands
(usually through a pipe directly to 
.CR /bin/sh )
to
check out the RCS revisions and check the files in as AtFS versions,
trying to keep as many attributes as possible.
.LP
.B The RCS archives are left unchanged.
.LP
It is recommended to create a special directory with the name
\fCRCS\fP
for the RCS archives, but AtFS histories are 
.I always
kept in a special directory 
.CR AtFS .
.LP
.B Rcs2atfs 
treats its arguments as names of RCS archives.
These can be the names of the archive files themselves, ending
with
.CR ,v ,
or the names of the files stored in the archives.
.LP
If the 
.B \-R 
option is given, the arguments are interpreted as directory names.
.B Rcs2atfs
recursively descends each directory tree (symbolic links are followed)
and converts the RCS archives it finds. The correspondig AtFS archives
are created where the RCS archives are found.
.LP
.B Rcs2atfs
tries to keep the revision numbers of the RCS history
also as AtFS version numbers. This is impossible if an RCS history
contains branches. In this case the revisions are saved as AtFS
versions in the order of their check-in date. In either case the RCS
revision number is kept as a symbolic name for the corresponding AtFS
version, e.g. the AtFS version of RCS revision 1.2 will have the
symbolic name ``\fCr1.2\fP''.
.SS Attributes that don't change:
.IP \(bu 0.3c
author
.IP \(bu
log message
.IP \(bu
comment leader
.IP \(bu
description
.IP \(bu
symbolic names (with the exception of the
.I additional
symbolic name derived from the RCS revision number)
.SS Other attributes:
.TP
mtime
set to the check-in date of the RCS revision
.TP
state
The value of this attribute is given to the AtFS attribute RCSstate.
If it has the value 
.CR Exp ,
the state of the AtFS version will
be 
.CR saved ,
if 
.CR Stab , 
it will be 
.CR proposed ,
if 
.CR Rel , 
it will be 
.CR published .
.SH OPTIONS
.TP
.B \-R
(recursive)
.br
The arguments are treated as directories. 
.B Rcs2atfs
recursively descends
the directory tree (symbolic links are followed) and builds an AtFS
archive for each RCS archive it 
finds.
.TP
.BI \-o " outputfile"
.B rcs2atfs
writes shell commands to 
.IR outputfile , 
not directly to
\fC/bin/sh\fP, and no conversion is done.
If this shell script is executed from the directory where
.B rcs2atfs
was invoked, the archives are converted as if 
.B rcs2atfs
had been invoked without
.BR \-o .
.br
The main use of this option is to investigate problems with the
conversion of archives.
.TP
.B \-q
(quiet)
.br
The names and revision numbers of converted archives are not echoed
on standard output.
.SH EXAMPLES
The command
.IP
\fCrcs2atfs -R $HOME/development\fP
.LP
traverses the directory tree
\fC$HOME/development\fP
and converts every RCS archive in it into an AtFS archive. During the
conversion, the name of every RCS archive and every revision number is
echoed on standard output.
.IP
\fCrcs2atfs -q RCS/*\fP
.LP
Each archive in the RCS directory is converted to an AtFS history. The
names and revision numbers of the converted archives are not echoed.
.SH SEE ALSO
sh(1), rcsintro(1), rcs(1), rlog(1), co(1), vcintro(1), save(1), vadm(1),
utime(1)
.SH DIAGNOSTICS
.SS Warnings
.TP
\fC-R flag not set, directory skipped\fP
If the
.B \-R
flag is not set, directories given as arguments in the command line
are ignored.
.TP
\fClocked version(s) exist\fP
A revision of the specified RCS history is locked. This is not really
a problem, but perhaps
.B rcs2atfs
does not convert the most recent version of the file.
.TP
\fCbranches exist, can't keep revision numbers\fP
If the RCS history contains branches, the numbers of AtFS versions
cannot be the same as those of the corresponding RCS revisions.
.TP
\fCsymbolic name to non-existent revision\fP
.I rlog
has reported a symbolic name of a revision that does not exist in this
archive. Probably this never happens (I don't know), but if, the
symbolic name is ignored.
.SS Errors
.TP
\fCATFS history exists, file skipped\fP
The specified file is already known to AtFS as a history or a busy
version. This file will nor be converted.
.LP
\fCcolon after symbolic name missing, file skipped\fP
.br
\fCrevision not found, file skipped\fP
.br
\fCdate not found, file skipped\fP
.br
\fCauthor not found, file skipped\fP
.br
\fCstatus not found, file skipped\fP
.br
\fCrlog information missing, file skipped\fP
.IP
These messages indicate problems with the
.I rlog
output, perhaps an old rlog version is used.
.RB ( rcs2atfs
works correctly with 
.I rlog
version 5.5.)
.br
The specified file will not be converted. 
.TP
\fCrlog command failed, file skipped\fP
For some unknown reason
.I rlog
returned a non-zero exit status.
.I rlog
should have provided an explanatory message.
.SS Fatal Errors
.TP
\fCpopen to rlog command failed\fP
The 
.I rlog
command could not be invoked.
.TP
\fCpopen to shell failed\fP
The shell could not be invoked.
.TP
\fCno more core\fP
.B Rcs2atfs
could not allocate enough memory. The amount of memory in your machine
should be increased.
.SS Internal Errors
.LP
\fCOops? Unknown reader state in readin_rcsfile!\fP
.br
\fCrevision numbers corrupted\fP
.br
\fCnumber of revisions is wrong!\fP
.IP
You should never see these error messages.
.SH CAVEATS
If 
.B rcs2atfs
visits the same RCS archive twice (e.g. because a symbolic link is
followed to a directory which is also accessed directly), the check for
existing AtFS archives may be done a second time before the conversion
commands from the first visit are executed by the shell. This results
in lots of annoying messages and duplicate AtFS versions of RCS
revisions. To avoid this, make sure that
.B rcs2atfs
doesn't reach a directory twice.
.SH BUGS
.B Rcs2atfs
is rather slow since it invokes a shell command for every action.
.LP
Attribute citations in files are not translated from RCS to AtFS (e.g.
``\fC$Header: ... $\fP'' to ``\fC$__\&Header$\fP'').
.LP
.B Rcs2atfs
strongly relies on the format of
.IR rlog 's
output. Since I don't know any other
.I rlog
than our version (5.5), it may fail to work with other versions.
.LP
Due to the lack of serious RCS archives, 
.B rcs2atfs
isn't thoroughly tested yet. (Well, we use ShapeTools. :\-)
.SH AUTHOR
Juergen.Nickelsen@cs.tu-berlin.de