# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

###########################################################################
# FUNCTION:
# To recursively walk through a PVCS archive directory tree (archives
# located in VCS/ or vcs/ subdirectories) and convert them to RCS archives.
# The RCS archive name is the PVCS workfile name with ",v" appended.
#
# SYNTAX:
# pvcs_to_rcs.pl --help
#
# where -l indicates the operation is to be performed only in the current
# directory (no recursion)
# 
# EXAMPLE:
# pvcs_to_rcs
# Would walk through every VCS or vcs subdir starting at the current directory,
# and produce corresponding RCS archives one level above the VCS or vcs subdir.
# (VCS/../RCS/)
#
# NOTES:
# * This script performs little error checking and logging
#   (i.e. USE AT YOUR OWN RISK)
# * This script was last tested using ActiveState's port of Perl 5.005_02
#   (internalcut #507) under Win95, though it does compile under Perl-5.00404
#   for Solaris 2.4 run on a Solaris 2.6 system.  The script crashed
#   occasionally under ActiveState's port of Perl 5.003_07 but this stopped
#   happening with the update so if you are having problems, try updating Perl.
#   Upgrading to cut #507 also seemed to coincide with a large speed
#   improvement, so try and keep up, hey?  :)  It was executed from MKS's
#   UNIX tools version 6.1 for Win32's sh.  ALWAYS redirect your output to
#   a log!!!
# * PVCS archives are left intact
# * RCS archives are created in VCS/../RCS/ (or ./RCS using '-pflat')
# * Branch labels in this script will be attached to the CVS magic
#   revision number.  For branch a.b.c of a particular file, this means
#   the label will be attached to revision a.b.0.c of the converted
#   file.  If you use the TrunkTip (1.*) label, be aware that it will convert
#   to RCS revision 0.1, which is useless to RCS and CVS.  You'll probably
#   have to delete these.
# * All revisions are saved with correct "metadata" (i.e. check-in date,
#   author, and log message).  Any blank log message is replaced with
#   "no comment".  This is because RCS does not allow non-interactive
#   check in of a new revision without a comment string.
# * Revision numbers are incremented by 1 during the conversion (since
#   RCS does not allow revision 1.0).
# * All converted branch numbers are even (the CVS paradigm)
# * Version labels are assigned to the appropriate (incremented) revision
#   numbers.  PVCS allows spaces and periods in version labels while RCS
#   does not.  A global search and replace converts spaces, commas,
#   periods, slashes (forward and backward), brackets, and braces to
#   underscore.  There may be other cases that ought to be added.
# * Any workfile within the VCS/../ or vcs/../ (or possibly ./ with '-pflat')
#   will be deleted (or overwritten) depending on your mode of
#   operation since it is used in the checkout of each revision
# * Locks on PVCS archives should be removed (or the workfiles should be
#   checked-in) prior to conversion, although the script will blaze through
#   the archive nonetheless (But you would lose any checked out revision(s))
# * The -kb option is added to the RCS archive for workfiles with the following
#   extensions: .bin .out .btl .rom .a07 .lib .exe .tco .obj .t8u .c8u .o .lku
#   .a and a few others.  The %bin_ext variable holds these values in regexp
#   form.
# * the --force-binary option can be used to convert binary files which don't
#   have proper extensions.
# * This script will abort occasionally with the error "invalid revision
#   number".  This is known to happen when a revision comment has
#   /^\s*Rev/ (Perl regexp notation) in it.  Fix the comment and start over.
#   (The directory locks and existance checking make this a fairly quick
#   process.)
# * This script writes lockfiles in the RCS/ directories.  It will also not
#   convert an archive if it finds the RCS Archive existant in the RCS/
#   directory.  This enables the conversion to quickly pick up where it left
#   off after errors or interrupts occur.  If you interrupt the script make
#   sure you delete the last RCS Archive File which was being written.
#   If you recieve the "Invalid revision number" error, then the RCS archive
#   file for that particular PVCS file will not have been created yet.
# * This script will not create lockfiles when processing single
#   filenames passed into the script, for hopefully obvious reasons.
# * Log the output to a file.  That makes it real easy to grep for errors
#   later.  (grep for "^[ \t]*(rcs|ci):" and be aware I might have missed
#   a few cases (get?  vcs?) !!!) *** Also note that this script will
#   exibit some harmless RCS errors.  Namely, it will attempt to lock
#   branches which haven't been created yet. ***
# * I tried to keep the error and warning info up to date, but it seems
#   to mean very little.  This script almost always exits with a warning
#   or an error that didn't seem to cause any harm.  I didn't trace it
#   and our imported source checks out and builds...
#   It is probably happening when trying to convert empty directories
#   or read files (possibly checked out workfiles ) which are not
#   pvcs_archives.
# * You must use the -pflat option when processing single filenames
#   passed as arguments to the script.  This is probably a bug.
#########################################################################