--- loncom/build/filecompare.pl	2001/11/14 13:19:36	1.3
+++ loncom/build/filecompare.pl	2001/11/16 20:06:08	1.4
@@ -1,26 +1,34 @@
 #!/usr/bin/perl
 
-# Scott Harrison
+# The LearningOnline Network witih CAPA
+#
+# filecompare.pl - script used to help probe and compare file statistics
+#
 # YEAR=2001
-# 9/27, 10/24, 10/25, 11/4
+# 9/27, 10/24, 10/25, 11/4 Scott Harrison
+# 11/14 Guy Albertelli
+# 11/16 Scott Harrison
+#
+# $Id: filecompare.pl,v 1.4 2001/11/16 20:06:08 harris41 Exp $
+###
 
-my $invocation=<<END;
 # ------------------------------------------------------------------ Invocation
-# filecompare.pl FILE1 FILE2
-# or
-# filecompare.pl DIR1 DIR2
-#
-# A list of space separated values (after the file/dir names)
-# can restrict the comparison.
-# These values can be: existence, cvstime, age, md5sum, size, lines,
-# and/or diffs.
-#
-# Flags (before file/dir names):
-# -p show all files the same
-# -n show all files different
-# -a show all files (with comparisons)
-# -q only show file names (based on first file/dir)
-# -v verbose mode (default)
+my $invocation=<<END;
+filecompare.pl [ options ... ] [FILE1] [FILE2] [ restrictions ... ]
+or
+filecompare.pl [ options ... ] [DIR1] [DIR2] [ restrictions ... ]
+
+Restrictions: a list of space separated values (after the file/dir names)
+can restrict the comparison.
+These values can be: existence, cvstime, age, md5sum, size, lines,
+and/or diffs.
+
+Options (before file/dir names):
+-p show all files that have the same comparison
+-n show all files that have different comparisons
+-a show all files (with comparisons)
+-q only show file names (based on first file/dir)
+-v verbose mode (default)
 END
 unless (@ARGV) {
     print $invocation;
@@ -155,110 +163,47 @@ if (%restrict) {
 }
 
 my %OUTPUT=(
-	 'existence'=>(
-		    sub {
-			print 'existence: '.@_[0];
-			return;
-		    }
-         ),
-	 'md5sum'=>(
-		    sub {
-			print 'md5sum: '.@_[0];
-			return;
-		    }
-         ),
-         'cvstime'=>(
-                    sub {
-	                print 'cvstime: '.@_[0];
-			return;
-		    }
-         ),
-         'age'=>(
-                    sub {
-	                print 'age: '.@_[0];
-			return;
-		    }
-         ),
-         'size'=>(
-                    sub {
-			print 'size: '.@_[0];
-			return;
-		    }
-         ),
-         'lines'=>(
-                    sub {
-			print 'lines: '.@_[0];
-			return;
-		    }
-         ),
-         'diffs'=>(
-                    sub {
-			print 'diffs: '.@_[0];
-			return;
-		    }
-         ),
+         'existence'=>( sub {print 'existence: '.@_[0]; return;}),
+	 'md5sum'=>(sub {print 'md5sum: '.@_[0];return;}),
+         'cvstime'=>(sub {print 'cvstime: '.@_[0];return;}),
+         'age'=>(sub {print 'age: '.@_[0];return;}),
+         'size'=>(sub {print 'size: '.@_[0];return;}),
+         'lines'=>(sub {print 'lines: '.@_[0];return;}),
+         'diffs'=>(sub {print 'diffs: '.@_[0];return;}),
 );
 
 my %MEASURE=(
-	 'existence' => (
-                    sub {
-			my ($file1,$file2)=@_;
+	 'existence' => ( sub { my ($file1,$file2)=@_;
 		        my $rv1=(-e $file1)?'yes':'no';
 			my $rv2=(-e $file2)?'yes':'no';
-			return ($rv1,$rv2);
-		    }
-         ),
-	 'md5sum'=>(
-		    sub {
-			my ($file1,$file2)=@_;
+			return ($rv1,$rv2); } ),
+	 'md5sum'=>( sub { my ($file1,$file2)=@_;
 			my ($rv1)=split(/ /,`md5sum $file1`); chop $rv1;
 			my ($rv2)=split(/ /,`md5sum $file2`); chop $rv2;
-			return ($rv1,$rv2);
-		    }
-         ),
-	 'cvstime'=>(
-		    sub {
-			my ($file1,$file2)=@_;
+			return ($rv1,$rv2); } ),
+	 'cvstime'=>( sub { my ($file1,$file2)=@_;
 			my $rv1=&cvstime($file1);
 			my @a=stat($file2); my $gmt=gmtime($a[9]);
 			my $rv2=&utctime($gmt);
-			return ($rv1,$rv2);
-		    }
-         ),
-         'age'=>(
-                    sub {
-			my ($file1,$file2)=@_;
+			return ($rv1,$rv2); } ),
+         'age'=>( sub {	my ($file1,$file2)=@_;
 			my @a=stat($file1); my $rv1=$a[9];
 			@a=stat($file2); my $rv2=$a[9];
-			return ($rv1,$rv2);
-		    }
-         ),
-         'size'=>(
-                    sub {
-			my ($file1,$file2)=@_;
+			return ($rv1,$rv2); } ),
+         'size'=>( sub { my ($file1,$file2)=@_;
 			my @a=stat($file1); my $rv1=$a[7];
 			@a=stat($file2); my $rv2=$a[7];
-			return ($rv1,$rv2);
-		    }
-         ),
-         'lines'=>(
-                    sub {
-			my ($file1,$file2)=@_;
+			return ($rv1,$rv2); } ),
+         'lines'=>( sub { my ($file1,$file2)=@_;
 			my $rv1=`wc -l $file1`; chop $rv1;
 			my $rv2=`wc -l $file2`; chop $rv2;
-			return ($rv1,$rv2);
-		    }
-         ),
-         'diffs'=>(
-                    sub {
-			my ($file1,$file2)=@_;
+			return ($rv1,$rv2); } ),
+         'diffs'=>( sub { my ($file1,$file2)=@_;
 			my $rv1=`diff $file1 $file2 | grep '^<' | wc -l`;
 			chop $rv1; $rv1=~s/^\s+//; $rv1=~s/\s+$//;
 			my $rv2=`diff $file1 $file2 | grep '^>' | wc -l`;
 			chop $rv2; $rv2=~s/^\s+//; $rv2=~s/\s+$//;
-			return ($rv1,$rv2);
-		    }
-         ),
+			return ($rv1,$rv2); } ),
 );
 
 FLOP: foreach my $file (@files) {
@@ -496,3 +441,73 @@ sub dowarn {
     my ($msg)=@_;
     warn($msg) unless $buildmode;
 }
+
+=head1 NAME
+
+filecompare.pl - script used to help probe and compare file statistics
+
+=head1 SYNOPSIS
+
+filecompare.pl [ options ... ] [FILE1] [FILE2] [ restrictions ... ]
+
+or
+
+filecompare.pl [ options ... ] [DIR1] [DIR2] [ restrictions ... ]
+
+Restrictions: a list of space separated values (after the file/dir names)
+can restrict the comparison.
+These values can be: existence, cvstime, age, md5sum, size, lines,
+and/or diffs.
+
+Options (before file/dir names):
+
+ -p show all files that have the same comparison
+
+ -n show all files that have different comparisons
+
+ -a show all files (with comparisons)
+
+ -q only show file names (based on first file/dir)
+
+ -v verbose mode (default)
+
+=head1 DESCRIPTION
+
+filecompare.pl can work in two modes: file comparison mode, or directory
+comparison mode.
+
+Comparisons can be a function of:
+* existence similarity
+* cvs time similarity (first argument treated as CVS source)
+* age similarity (modification time)
+* md5sum similarity
+* size similarity (bytes)
+* line count difference
+* number of different lines
+
+filecompare.pl integrates smoothly with the LPML installation language
+(linux packaging markup language).  filecompare.pl is a tool that can
+be used for safe CVS source-to-target installations.
+
+=head1 README
+
+filecompare.pl integrates smoothly with the LPML installation language
+(linux packaging markup language).  filecompare.pl is a tool that can
+be used for safe CVS source-to-target installations.
+
+The unique identifier is considered to be the file name(s) independent
+of the directory path.
+
+=head1 PREREQUISITES
+
+=head1 COREQUISITES
+
+=head1 OSNAMES
+
+linux
+
+=head1 SCRIPT CATEGORIES
+
+Packaging/Administrative
+
+=cut