--- rock-old/scripts/Download	Thu Aug 23 11:28:40 2001
+++ rock-new/scripts/Download	Sun Sep 30 10:27:25 2001
@@ -1,4 +1,15 @@
 #!/bin/sh
+#
+#   Run this command from the ROCK directory as ./scripts/Download [ options ]
+#
+#   It enables you to download source files as described in the package 
+#   definitions (optionally using a mirroring 'cache' server). 
+#
+#   This script also allows for checksum display/validation.
+#
+#   Key to understanding this script is that all file lists get broken
+#   down to a single file download using ./scripts/Download filename.
+
 
 if [ -z "$1" ] ; then
 	echo
@@ -25,7 +36,7 @@
 
 if [ -z "$BASH_VERSION" ] ; then
 	echo
-	echo 'To run this script, /bin/sh must be a bash!'
+	echo 'To run this script, /bin/sh must really be bash!'
 	echo
 	exit 1
 fi
@@ -39,7 +50,10 @@
 	exit 1
 fi
 
-# Handle -mk-cksum mode
+# -mk-cksum mode (display ROCK type package checksum): it
+# displays the checksum ROCK validates against.
+#
+# Currently bz2, tbz2, gz, tgz are unpacked
 #
 if [ "$1" = -mk-cksum ] ; then
     shift 1
@@ -58,40 +72,49 @@
     exit 1
 fi
 
-# Handle Options
+# Handle options passed on the command line
 #
 mirror='' ; checkonly=0
 nocheck=0 ; options=''
-#
+# -nock skips checksum checking (don't use lightly)
 if [ "$1" = -nock ] ; then
 	options="$options -nock"
 	nocheck=1 ; shift 1
 fi
-#
+# -mirror uses a mirror for finding source files
 if [ "$1" = -mirror ] ; then
 	options="$options -mirror $2"
 	mirror=$2 ; shift 2
 fi
-#
+# -check just validates the file using the checksum
 if [ "$1" = -check ] ; then
 	options="$options -check"
 	checkonly=1 ; shift 1
 fi
 
-# Handle Aliases
+# Handle aliases:
+#
+# This part of the script creates a list of all missing source
+# tar balls and creates a subset based on the -all, -base, -ext
+# option. Then it reinvokes the Download script a file at a 
+# time.
 #
 if [ "$1" = -all -o "$1" = -base -o "$1" = -ext ] ; then
 	{
 	  if [ $checkonly = 1 ] ; then
+	    # Create list of archive files
 		./scripts/Download $options -list
 	  else
+	    # Create list of missing archive files
 		./scripts/Download $options -list-missing
 	  fi
 	} | {
+	  # Create subset based on option
 	  if   [ "$1" = -all  ] ; then cat
 	  elif [ "$1" = -ext  ] ; then egrep '^ext-(archive|config)/'
 	  elif [ "$1" = -base ] ; then egrep '^(pkg|opt)-archive/' ; fi
 	} | {
+	  # For each file verify or download
 	  while read fn ; do
 		[ $checkonly = 1 ] || echo "Downloading $fn ..."
 		./scripts/Download $options $fn
@@ -102,6 +125,9 @@
 
 # cksum_chk filename cksum origfile
 #
+# This function verifies the checksum. If it fails it renames the file
+# to file.chksum-err and returns failure.
+#
 # It seams like the [ ] command has problems with comparing high numbers.
 # That's why I'm using 'bc' to calculate the difference betwen the numbers.
 #
@@ -109,6 +135,7 @@
 	[ $nocheck = 1 -o $2 -eq 0 ] && return 0
 	x="`cksum "$1" | cut -f1 -d' '`" ; y="`echo $x - $2 | bc`"
 	if [ $y -ne 0 ] ; then
+	    # Add .cksum-err extension to filename:
 		echo "Cksum ERROR: $3.cksum-err ($x)"
 		mv "$3" "$3.cksum-err" ; return 1
 	fi
@@ -117,12 +144,18 @@
 
 # download_file local-filename download-location cksum
 #
+# This function executes the actual download using wget.
+#
 download_file() {
 
 	# Init
 	#
-	gzfile="$1" ; location="$2" ; cksum="$3" ; mkdir -p src/
+	gzfile="$1" ; location="$2" ; cksum="$3" 
+	# Make src directory for creating tar balls
+	mkdir -p src/
+	# Tar ball file name:
 	bzfile="`echo "$gzfile" | sed 's,.\(\t\?\)gz$,.\1bz2,'`"
+	# Lock file name:
 	lkfile="src/down.lockfile.`echo $bzfile | tr / -`"
 
 	# Check if we only like to test the cksum(s)
@@ -139,6 +172,8 @@
 
 		# Is it a local symlink ?
 		#
+		# @@ COMMENT?
+		#
 		if [[ $location == intern://* ]] ; then
 			x="`echo $location | sed s,intern://,../../misc/ext-intern/,`"
 			y="`echo $bzfile | sed 's,.*/,,'`"
@@ -146,7 +181,7 @@
 			else rm -f "$bzfile" ; ln -sf "$x$y" "$bzfile" ; fi
 			return 0
 		fi
-		#
+		# @@ COMMENT?
 		if [[ $location == \!intern://* ]] ; then
 			x="`echo $location | sed s,!intern://,../misc/ext-intern/,`"
 			if [ ! -e "$bzfile" ] ; then ln -svf "$x" "$bzfile"
@@ -180,6 +215,7 @@
 		# Download
 		#
 		if [ -s "$gzfile.cksum-err" ] ; then
+		    # cksum-err file alread exists:
 			echo "Found $gzfile.cksum-err -> skip download."
 			rm -f "$lkfile" ; return 1
 		elif [ ! -s "$gzfile" ] ; then
@@ -194,7 +230,7 @@
 
 	fi  # checkonly
 
-	# Convert a .gz to .bz2 and make cksum testing
+	# Convert a .gz to .bz2 and test checksum
 	#
 	if [ "$gzfile" != "$bzfile" ] ; then
 		echo "gzip->bzip2 + cksum-test: $gzfile"
@@ -204,7 +240,7 @@
 		fi
 		rm -f src/temp.$$.dat
 	#
-	# Make a cksum test on a bzip2 file
+	# Execute a cksum test on a bzip2 file
 	#
 	elif [[ "$gzfile" == *.bz2 ]] || [[ "$gzfile" == *.tbz2 ]] ; then
 		echo "cksum-test (bzip2): $bzfile"
@@ -214,7 +250,7 @@
 		fi
 		rm -f src/temp.$$.dat
 	#
-	# Make a cksum test on a raw data file
+	# Execute a cksum test on a raw data file
 	#
 	else
 		echo "cksum-test (raw): $gzfile"
@@ -228,6 +264,12 @@
 	return 0
 }
 
+# handle_file filename
+#
+# This function fetches the checksum and download information 
+# from cksum.cache or the ext-config file and calls the 
+# download_file function.
+#
 handle_file() {
 
 	# Files in pkg-archive/ and opt-archive/
--- rock-old/scripts/help.txt	Sun Mar  4 22:57:55 2001
+++ rock-new/scripts/help.txt	Sun Sep 30 09:37:24 2001
@@ -15,7 +15,7 @@
 
 
 Please also read the file BUILD which can be found in the Documentation/
-directory.
+directory and if you are new to ROCK read the ROCK Linux Guide.
 
 
 ## Download ##
@@ -101,7 +101,8 @@
 When the script finds a file with a wrong checksum it automatically renames
 it to '<old-filename>.cksum-err'.
 
-When downloading a file, it is automatically checked, unless the -nock option
+When downloading a file, it is automatically checked (using checksums 
+which can be generated with the -mk-cksum option), unless the -nock option
 is used.
 
  The checksums for the base packages are stored in scripts/cksum.cache, the