--- loncom/interface/loncommon.pm	2002/06/25 16:31:51	1.40
+++ loncom/interface/loncommon.pm	2002/07/12 14:36:16	1.46
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # a pile of common routines
 #
-# $Id: loncommon.pm,v 1.40 2002/06/25 16:31:51 ng Exp $
+# $Id: loncommon.pm,v 1.46 2002/07/12 14:36:16 matthew Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -33,6 +33,7 @@
 # 12/25,12/28 Gerd Kortemeyer
 # YEAR=2002
 # 1/4 Gerd Kortemeyer
+# 6/24,7/2 H. K. Ng
 
 # Makes a table out of the previous attempts
 # Inputs result_from_symbread, user, domain, course_id
@@ -40,6 +41,8 @@
 
 # POD header:
 
+=pod
+
 =head1 NAME
 
 Apache::loncommon - pile of common routines
@@ -65,7 +68,7 @@ Current things done:
 This is part of the LearningOnline Network with CAPA project
 described at http://www.lon-capa.org.
 
-=head2 Subroutines
+=head2 General Subroutines
 
 =over 4
 
@@ -76,39 +79,66 @@ package Apache::loncommon;
 
 use strict;
 use Apache::lonnet();
+use GDBM_File;
 use POSIX qw(strftime);
 use Apache::Constants qw(:common);
 use Apache::lonmsg();
-
 my $readit;
 
+=pod 
+
+=item Global Variables
+
+=over 4
+
+=cut
 # ----------------------------------------------- Filetypes/Languages/Copyright
 my %language;
 my %cprtag;
 my %fe; my %fd;
-my %fc;
+my %category_extensions;
 
-# -------------------------------------------------------------- Thesaurus data
-my @therelated;
-my @theword;
-my @thecount;
-my %theindex;
-my $thetotalcount;
-my $thefuzzy=2;
-my $thethreshold=0.1/$thefuzzy;
-my $theavecount;
+# ---------------------------------------------- Thesaurus variables
+
+=pod
+
+=item %Keywords  
+
+A hash used by &keyword to determine if a word is considered a keyword.
+
+=item $thesaurus_db_file
+
+Scalar containing the full path to the thesaurus database.                 
+
+=cut
+
+my %Keywords;
+my $thesaurus_db_file;
+
+
+=pod
+
+=back
+
+=cut
 
 # ----------------------------------------------------------------------- BEGIN
+
+=pod
+
 =item BEGIN() 
 
 Initialize values from language.tab, copyright.tab, filetypes.tab,
-and filecategories.tab.
+thesaurus.tab, and filecategories.tab.
 
 =cut
+
 # ----------------------------------------------------------------------- BEGIN
 
 BEGIN {
-
+    # Variable initialization
+    $thesaurus_db_file = $Apache::lonnet::perlvar{'lonTabDir'}."/thesaurus.db";
+    #
     unless ($readit) {
 # ------------------------------------------------------------------- languages
     {
@@ -144,8 +174,8 @@ BEGIN {
 	    while (<$fh>) {
 		next if /^\#/;
 		chomp;
-		my ($key,$val)=(split(/\s+/,$_,2));
-		push @{$fc{$key}},$val;
+		my ($extension,$category)=(split(/\s+/,$_,2));
+		push @{$category_extensions{lc($category)}},$extension;
 	    }
 	}
     }
@@ -165,29 +195,99 @@ BEGIN {
 	    }
 	}
     }
-# -------------------------------------------------------------- Thesaurus data
-    {
-	my $fh=Apache::File->new($Apache::lonnet::perlvar{'lonTabDir'}.
-	       '/thesaurus.dat');
-	if ($fh) {
-            while (<$fh>) {
-               my ($tword,$tindex,$tcount,$trelated)=split(/\@/,$_);
-               $theindex{$tword}=$tindex;
-               $theword[$tindex]=$tword;
-               $thecount[$tindex]=$tcount;
-               $thetotalcount+=$tcount;
-               $therelated[$tindex]=$trelated;
-	   }
-        }
-        $theavecount=$thetotalcount/$#thecount;
-    }
     &Apache::lonnet::logthis(
-              "<font color=yellow>INFO: Read file types and thesaurus</font>");
+              "<font color=yellow>INFO: Read file types</font>");
     $readit=1;
-}
+    }  # end of unless($readit) 
     
 }
 # ============================================================= END BEGIN BLOCK
+###############################################################
+##           HTML and Javascript Helper Functions            ##
+###############################################################
+
+=pod 
+
+=item browser_and_searcher_javascript 
+
+Returns scalar containing javascript to open a browser window
+or a searcher window.  Also creates 
+
+=over 4
+
+=item openbrowser(formname,elementname,only,omit) [javascript]
+
+inputs: formname, elementname, only, omit
+
+formname and elementname indicate the name of the html form and name of
+the element that the results of the browsing selection are to be placed in. 
+
+Specifying 'only' will restrict the browser to displaying only files
+with the given extension.  Can be a comma seperated list.
+
+Specifying 'omit' will restrict the browser to NOT displaying files
+with the given extension.  Can be a comma seperated list.
+
+=item opensearcher(formname, elementname) [javascript]
+
+Inputs: formname, elementname
+
+formname and elementname specify the name of the html form and the name
+of the element the selection from the search results will be placed in.
+
+=back
+
+=cut
+
+###############################################################
+sub browser_and_searcher_javascript {
+    return <<END;
+    var editbrowser;
+    function openbrowser(formname,elementname,only,omit) {
+        var url = '/res/?';
+        if (editbrowser == null) {
+            url += 'launch=1&';
+        }
+        url += 'catalogmode=interactive&';
+        url += 'mode=edit&';
+        url += 'form=' + formname + '&';
+        if (only != null) {
+            url += 'only=' + only + '&';
+        } 
+        if (omit != null) {
+            url += 'omit=' + omit + '&';
+        }
+        url += 'element=' + elementname + '';
+        var title = 'Browser';
+        var options = 'scrollbars=1,resizable=1,menubar=0';
+        options += ',width=700,height=600';
+        editbrowser = open(url,title,options,'1');
+        editbrowser.focus();
+    }
+    var editsearcher;
+    function opensearcher(formname,elementname) {
+        var url = '/adm/searchcat?';
+        if (editsearcher == null) {
+            url += 'launch=1&';
+        }
+        url += 'catalogmode=interactive&';
+        url += 'mode=edit&';
+        url += 'form=' + formname + '&';
+        url += 'element=' + elementname + '';
+        var title = 'Search';
+        var options = 'scrollbars=1,resizable=1,menubar=0';
+        options += ',width=700,height=600';
+        editsearcher = open(url,title,options,'1');
+        editsearcher.focus();
+    }
+END
+}
+
+
+
+###############################################################
+
+=pod
 
 =item linked_select_forms(...)
 
@@ -213,14 +313,16 @@ linked_select_forms takes the following
 
 =item $hashref, a reference to a hash containing the data for the menus.
 
+=back 
+
 Below is an example of such a hash.  Only the 'text', 'default', and 
 'select2' keys must appear as stated.  keys(%menu) are the possible 
 values for the first select menu.  The text that coincides with the 
-first menu values is given in $menu{$choice1}->{'text'}.  The values 
+first menu value is given in $menu{$choice1}->{'text'}.  The values 
 and text for the second menu are given in the hash pointed to by 
 $menu{$choice1}->{'select2'}.  
 
- my %menu = ( A1 => { text =>"Choice A1" ,
+my %menu = ( A1 => { text =>"Choice A1" ,
                       default => "B3",
                       select2 => { 
                           B1 => "Choice B1",
@@ -251,8 +353,6 @@ $menu{$choice1}->{'select2'}.
                   }
               );
 
-=back
-
 =cut
 
 # ------------------------------------------------
@@ -337,6 +437,52 @@ END
 
 ###############################################################
 
+=pod
+
+=item help_open_topic($topic, $stayOnPage, $width, $height)
+
+Returns a string corresponding to an HTML link to the given help $topic, where $topic corresponds to the name of a .tex file in /home/httpd/html/adm/help/tex, with underscores replaced by spaces.
+
+$stayOnPage is a value that will be interpreted as a boolean. If true, the link will not open a new window. If false, the link will open a new window using Javascript. (Default is false.)
+
+$width and $height are optional numerical parameters that will override the width and height of the popped up window, which may be useful for certain help topics with big pictures included.
+
+=cut
+
+sub help_open_topic {
+    my ($topic, $stayOnPage, $width, $height) = @_;
+    $stayOnPage = 0 if (not defined $stayOnPage);
+    $width = 350 if (not defined $width);
+    $height = 400 if (not defined $height);
+    my $filename = $topic;
+    $filename =~ s/ /_/g;
+
+    my $template;
+
+    if (!$stayOnPage)
+    {
+        $template = <<"ENDTEMPLATE";
+<a href="javascript:void(open('/adm/help/${filename}.hlp', 'Help for $topic', 'menubar=0,s
+crollbars=1,width=$width,height=$height'))"><image
+  src="/adm/help/gif/smallHelp.gif"
+  border="0" alt="(Help: $topic)"></a>
+ENDTEMPLATE
+    }
+    else
+    {
+        $template = <<"ENDTEMPLATE";
+<a href="/adm/help/${filename}.hlp"><image
+  src="/adm/help/gif/smallHelp.gif"
+  border="0" alt="(Help: $topic)"></a>
+ENDTEMPLATE
+    }
+
+    return $template;
+
+}
+
+=pod
+
 =item csv_translate($text) 
 
 Translate $text to allow it to be output as a 'comma seperated values' 
@@ -352,12 +498,12 @@ sub csv_translate {
 }
 
 ###############################################################
-
-###############################################################
 ##        Home server <option> list generating code          ##
 ###############################################################
 #-------------------------------------------
 
+=pod
+
 =item get_domains()
 
 Returns an array containing each of the domains listed in the hosts.tab
@@ -378,6 +524,8 @@ sub get_domains {
 
 #-------------------------------------------
 
+=pod
+
 =item select_dom_form($defdom,$name)
 
 Returns a string containing a <select name='$name' size='1'> form to 
@@ -402,6 +550,8 @@ sub select_dom_form {
 
 #-------------------------------------------
 
+=pod
+
 =item get_home_servers($domain)
 
 Returns a hash which contains keys like '103l3' and values like 
@@ -424,6 +574,8 @@ sub get_home_servers {
 
 #-------------------------------------------
 
+=pod
+
 =item home_server_option_list($domain)
 
 returns a string which contains an <option> list to be used in a 
@@ -456,6 +608,8 @@ sub home_server_option_list {
 ##    formname = the name given in the <form> tag.
 #-------------------------------------------
 
+=pod
+
 =item authform_xxxxxx
 
 The authform_xxxxxx subroutines provide javascript and html forms which 
@@ -657,66 +811,166 @@ END
 ##   End Authentication changing form generation functions   ##
 ###############################################################
 
+###############################################################
+##                Thesaurus Functions                        ##
+###############################################################
+
+=pod
+
+=item initialize_keywords
+
+Initializes the package variable %Keywords if it is empty.  Uses the
+package variable $thesaurus_db_file.
+
+=cut
+
+###################################################
+
+sub initialize_keywords {
+    return 1 if (scalar keys(%Keywords));
+    # If we are here, %Keywords is empty, so fill it up
+    #   Make sure the file we need exists...
+    if (! -e $thesaurus_db_file) {
+        &Apache::lonnet::logthis("Attempt to access $thesaurus_db_file".
+                                 " failed because it does not exist");
+        return 0;
+    }
+    #   Set up the hash as a database
+    my %thesaurus_db;
+    if (! tie(%thesaurus_db,'GDBM_File',
+              $thesaurus_db_file,&GDBM_READER,0640)){
+        &Apache::lonnet::logthis("Could not tie \%thesaurus_db to ".
+                                 $thesaurus_db_file);
+        return 0;
+    } 
+    #  Get the average number of appearances of a word.
+    my $avecount = $thesaurus_db{'average.count'};
+    #  Put keywords (those that appear > average) into %Keywords
+    while (my ($word,$data)=each (%thesaurus_db)) {
+        my ($count,undef) = split /:/,$data;
+        $Keywords{$word}++ if ($count > $avecount);
+    }
+    untie %thesaurus_db;
+    # Remove special values from %Keywords.
+    foreach ('total.count','average.count') {
+        delete($Keywords{$_}) if (exists($Keywords{$_}));
+    }
+    return 1;
+}
+
+###################################################
+
+=pod
+
+=item keyword($word)
+
+Returns true if $word is a keyword.  A keyword is a word that appears more 
+than the average number of times in the thesaurus database.  Calls 
+&initialize_keywords
 
+=cut
 
-# ---------------------------------------------------------- Is this a keyword?
+###################################################
 
 sub keyword {
-    my $newword=shift;
-    $newword=~s/\W//g;
-    $newword=~tr/A-Z/a-z/;
-    my $tindex=$theindex{$newword};
-    if ($tindex) {
-        if ($thecount[$tindex]>$theavecount) {
-           return 1;
-        }
-    }
-    return 0;
+    return if (!&initialize_keywords());
+    my $word=lc(shift());
+    $word=~s/\W//g;
+    return exists($Keywords{$word});
 }
+
+###################################################
+#         Old code, to be removed soon            #
+###################################################
 # -------------------------------------------------------- Return related words
+#sub related {
+#    my $newword=shift;
+#    $newword=~s/\W//g;
+#    $newword=~tr/A-Z/a-z/;
+#    my $tindex=$theindex{$newword};
+#    if ($tindex) {
+#        my %found=();
+#        foreach (split(/\,/,$therelated[$tindex])) {
+## - Related word found
+#            my ($ridx,$rcount)=split(/\:/,$_);
+## - Direct relation index
+#            my $directrel=$rcount/$thecount[$tindex];
+#            if ($directrel>$thethreshold) {
+#               foreach (split(/\,/,$therelated[$ridx])) {
+#                  my ($rridx,$rrcount)=split(/\:/,$_);
+#                  if ($rridx==$tindex) {
+## - Determine reverse relation index
+#                     my $revrel=$rrcount/$thecount[$ridx];
+## - Calculate full index
+#                     $found{$ridx}=$directrel*$revrel;
+#                     if ($found{$ridx}>$thethreshold) {
+#                        foreach (split(/\,/,$therelated[$ridx])) {
+#                            my ($rrridx,$rrrcount)=split(/\:/,$_);
+#                            unless ($found{$rrridx}) {
+#                               my $revrevrel=$rrrcount/$thecount[$ridx];
+#                               if (
+#                          $directrel*$revrel*$revrevrel>$thethreshold
+#                               ) {
+#                                  $found{$rrridx}=
+#                                       $directrel*$revrel*$revrevrel;
+#                               }
+#                            }
+#                        }
+#                     }
+#                  }
+#               }
+#            }
+#        }
+#    }
+#    return ();
+#}
 
-sub related {
-    my $newword=shift;
-    $newword=~s/\W//g;
-    $newword=~tr/A-Z/a-z/;
-    my $tindex=$theindex{$newword};
-    if ($tindex) {
-        my %found=();
-        foreach (split(/\,/,$therelated[$tindex])) {
-# - Related word found
-            my ($ridx,$rcount)=split(/\:/,$_);
-# - Direct relation index
-            my $directrel=$rcount/$thecount[$tindex];
-            if ($directrel>$thethreshold) {
-               foreach (split(/\,/,$therelated[$ridx])) {
-                  my ($rridx,$rrcount)=split(/\:/,$_);
-                  if ($rridx==$tindex) {
-# - Determine reverse relation index
-                     my $revrel=$rrcount/$thecount[$ridx];
-# - Calculate full index
-                     $found{$ridx}=$directrel*$revrel;
-                     if ($found{$ridx}>$thethreshold) {
-                        foreach (split(/\,/,$therelated[$ridx])) {
-                            my ($rrridx,$rrrcount)=split(/\:/,$_);
-                            unless ($found{$rrridx}) {
-                               my $revrevrel=$rrrcount/$thecount[$ridx];
-                               if (
-                          $directrel*$revrel*$revrevrel>$thethreshold
-                               ) {
-                                  $found{$rrridx}=
-                                       $directrel*$revrel*$revrevrel;
-                               }
-                            }
-                        }
-                     }
-                  }
-               }
-            }
+###############################################################
+
+=pod 
+
+=item get_related_words
+
+Look up a word in the thesaurus.  Takes a scalar arguement and returns
+an array of words.  If the keyword is not in the thesaurus, an empty array
+will be returned.  The order of the words returned is determined by the
+database which holds them.
+
+Uses global $thesaurus_db_file.
+
+=cut
+
+###############################################################
+
+sub get_related_words {
+    my $keyword = shift;
+    my %thesaurus_db;
+    if (! -e $thesaurus_db_file) {
+        &Apache::lonnet::logthis("Attempt to access $thesaurus_db_file ".
+                                 "failed because the file does not exist");
+        return ();
+    }
+    if (! tie(%thesaurus_db,'GDBM_File',
+              $thesaurus_db_file,&GDBM_READER,0640)){
+        return ();
+    } 
+    my @Words=();
+    if (exists($thesaurus_db{$keyword})) {
+        $_ = $thesaurus_db{$keyword};
+        (undef,@Words) = split/:/;  # The first element is the number of times
+                                    # the word appears.  We do not need it now.
+        for (my $i=0;$i<=$#Words;$i++) {
+            ($Words[$i],undef)= split/\,/,$Words[$i];
         }
     }
-    return ();
+    untie %thesaurus_db;
+    return @Words;
 }
 
+###############################################################
+##              End Thesaurus Functions                      ##
+###############################################################
+
 # ---------------------------------------------------------------- Language IDs
 sub languageids {
     return sort(keys(%language));
@@ -739,12 +993,12 @@ sub copyrightdescription {
 
 # ------------------------------------------------------------- File Categories
 sub filecategories {
-    return sort(keys(%fc));
+    return sort(keys(%category_extensions));
 }
 
 # -------------------------------------- File Types within a specified category
 sub filecategorytypes {
-    return @{$fc{lc(shift(@_))}};
+    return @{$category_extensions{lc($_[0])}};
 }
 
 # ------------------------------------------------------------------ File Types
@@ -774,13 +1028,16 @@ sub filedescriptionex {
 # $username,$domain - that of the student
 # $course           - course name
 # $getattempt       - leave blank if want all attempts, else put something.
+# $regexp           - regular expression. If string matches regexp send to
+# $gradesub         - routine that process the string if it matches regexp
 # 
 # output
 # formatted as a table all the attempts, if any.
 #
 sub get_previous_attempt {
-  my ($symb,$username,$domain,$course,$getattempt)=@_;
+  my ($symb,$username,$domain,$course,$getattempt,$regexp,$gradesub)=@_;
   my $prevattempts='';
+  no strict 'refs';
   if ($symb) {
     my (%returnhash)=
       &Apache::lonnet::restore($symb,$course,$domain,$username);
@@ -792,16 +1049,20 @@ sub get_previous_attempt {
 	  $lasthash{$_}=$returnhash{$version.':'.$_};
         }
       }
-      $prevattempts='<table border="0" width="100%"><tr><td bgcolor="#000000">';
+      $prevattempts='<table border="0" width="100%"><tr><td bgcolor="#777777">';
       $prevattempts.='<table border="0" width="100%"><tr bgcolor="#e6ffff"><td>History</td>';
       foreach (sort(keys %lasthash)) {
 	my ($ign,@parts) = split(/\./,$_);
-	if (@parts) {
+	if ($#parts > 0) {
 	  my $data=$parts[-1];
 	  pop(@parts);
 	  $prevattempts.='<td>Part '.join('.',@parts).'<br />'.$data.'&nbsp;</td>';
 	} else {
-	  $prevattempts.='<td>'.$ign.'&nbsp;</td>';
+	  if ($#parts == 0) {
+	    $prevattempts.='<th>'.$parts[0].'</th>';
+	  } else {
+	    $prevattempts.='<th>'.$ign.'</th>';
+	  }
 	}
       }
       if ($getattempt eq '') {
@@ -826,6 +1087,7 @@ sub get_previous_attempt {
 	} else {
 	  $value=$lasthash{$_};
 	}
+	if ($_ =~/$regexp$/) {$value = &$gradesub($value)}
 	$prevattempts.='<td>'.$value.'&nbsp;</td>';
       }
       $prevattempts.='</tr></table></td></tr></table>';
@@ -878,31 +1140,11 @@ sub get_student_answers {
   foreach my $element (@elements) {
     $ENV{'form.grade_'.$element}=$old{$element};
   }
-  $userview=~s/\<body[^\>]*\>//gi;
-  $userview=~s/\<\/body\>//gi;
-  $userview=~s/\<html\>//gi;
-  $userview=~s/\<\/html\>//gi;
-  $userview=~s/\<head\>//gi;
-  $userview=~s/\<\/head\>//gi;
-  $userview=~s/action\s*\=/would_be_action\=/gi;
   return $userview;
 }
 
 ###############################################
 
-=item get_unprocessed_cgi($query,$possible_names)
-
-Modify the %ENV hash to contain unprocessed CGI form parameters held in
-$query.  The parameters listed in $possible_names (an array reference),
-will be set in $ENV{'form.name'} if they do not already exist.
-
-Typically called with $ENV{'QUERY_STRING'} as the first parameter.  
-$possible_names is an ref to an array of form element names.  As an example:
-get_unprocessed_cgi($ENV{'QUERY_STRING'},['uname','udom']);
-will result in $ENV{'form.uname'} and $ENV{'form.udom'} being set.
-
-=cut
-
 ###############################################
 
 sub get_unprocessed_cgi {
@@ -955,11 +1197,21 @@ sub add_to_env {
   }
 }
 
-#---CSV Upload/Handling functions
+=pod
+
+=back 
+
+=head2 CSV Upload/Handling functions
+
+=over 4
+
+=item  upfile_store($r)
+
+Store uploaded file, $r should be the HTTP Request object,
+needs $ENV{'form.upfile'}
+returns $datatoken to be put into hidden field
 
-# ========================================================= Store uploaded file
-# needs $ENV{'form.upfile'}
-# return $datatoken to be put into hidden field
+=cut
 
 sub upfile_store {
     my $r=shift;
@@ -978,9 +1230,13 @@ sub upfile_store {
     return $datatoken;
 }
 
-# ================================================= Load uploaded file from tmp
-# needs $ENV{'form.datatoken'}
-# sets $ENV{'form.upfile'} to the contents of the file
+=item load_tmp_file($r)
+
+Load uploaded file from tmp, $r should be the HTTP Request object,
+needs $ENV{'form.datatoken'},
+sets $ENV{'form.upfile'} to the contents of the file
+
+=cut
 
 sub load_tmp_file {
     my $r=shift;
@@ -995,10 +1251,13 @@ sub load_tmp_file {
     $ENV{'form.upfile'}=join('',@studentdata);
 }
 
-# ========================================= Separate uploaded file into records
-# returns array of records
-# needs $ENV{'form.upfile'}
-# needs $ENV{'form.upfiletype'}
+=item upfile_record_sep()
+
+Separate uploaded file into records
+returns array of records,
+needs $ENV{'form.upfile'} and $ENV{'form.upfiletype'}
+
+=cut
 
 sub upfile_record_sep {
     if ($ENV{'form.upfiletype'} eq 'xml') {
@@ -1007,9 +1266,12 @@ sub upfile_record_sep {
     }
 }
 
-# =============================================== Separate a record into fields
-# needs $ENV{'form.upfiletype'}
-# takes $record as arg
+=item record_sep($record)
+
+Separate a record into fields $record should be an item from the upfile_record_sep(), needs $ENV{'form.upfiletype'}
+
+=cut
+
 sub record_sep {
     my $record=shift;
     my %components=();
@@ -1054,7 +1316,12 @@ sub record_sep {
     return %components;
 }
 
-# =============================== HTML code to select file and specify its type
+=item upfile_select_html()
+
+return HTML code to select file and specify its type
+
+=cut
+
 sub upfile_select_html {
     return (<<'ENDUPFORM');
 <input type="file" name="upfile" size="50">
@@ -1067,9 +1334,14 @@ sub upfile_select_html {
 ENDUPFORM
 }
 
-# ===================Prints a table of sample values from each column uploaded
-# $r is an Apache Request ref
-# $records is an arrayref from &Apache::loncommon::upfile_record_sep
+=item csv_print_samples($r,$records)
+
+Prints a table of sample values from each column uploaded $r is an
+Apache Request ref, $records is an arrayref from
+&Apache::loncommon::upfile_record_sep
+
+=cut
+
 sub csv_print_samples {
     my ($r,$records) = @_;
     my (%sone,%stwo,%sthree);
@@ -1092,10 +1364,15 @@ sub csv_print_samples {
     $r->print('</tr></table><br />'."\n");
 }
 
-# ======Prints a table to create associations between values and table columns
-# $r is an Apache Request ref
-# $records is an arrayref from &Apache::loncommon::upfile_record_sep
-# $d is an array of 2 element arrays (internal name, displayed name)
+=item csv_print_select_table($r,$records,$d)
+
+Prints a table to create associations between values and table columns.
+$r is an Apache Request ref,
+$records is an arrayref from &Apache::loncommon::upfile_record_sep,
+$d is an array of 2 element arrays (internal name, displayed name)
+
+=cut
+
 sub csv_print_select_table {
     my ($r,$records,$d) = @_;
     my $i=0;my %sone;
@@ -1119,11 +1396,16 @@ sub csv_print_select_table {
     return $i;
 }
 
-# ===================Prints a table of sample values from the upload and
-#                      can make associate samples to internal names
-# $r is an Apache Request ref
-# $records is an arrayref from &Apache::loncommon::upfile_record_sep
-# $d is an array of 2 element arrays (internal name, displayed name)
+=item csv_samples_select_table($r,$records,$d)
+
+Prints a table of sample values from the upload and can make associate samples to internal names.
+
+$r is an Apache Request ref,
+$records is an arrayref from &Apache::loncommon::upfile_record_sep,
+$d is an array of 2 element arrays (internal name, displayed name)
+
+=cut
+
 sub csv_samples_select_table {
     my ($r,$records,$d) = @_;
     my %sone; my %stwo; my %sthree;
@@ -1154,6 +1436,14 @@ sub csv_samples_select_table {
 1;
 __END__;
 
+=pod
+
+=back
+
+=head2 Access .tab File Data
+
+=over 4
+
 =item languageids() 
 
 returns list of all language ids
@@ -1192,6 +1482,12 @@ returns description for a specified file
 returns description for a specified file type with
 extra formatting
 
+=back
+
+=head2 Alternate Problem Views
+
+=over 4
+
 =item get_previous_attempt() 
 
 return string with previous attempt on problem
@@ -1204,9 +1500,22 @@ show a snapshot of what student was look
 
 show a snapshot of how student was answering problem
 
-=item get_unprocessed_cgi() 
+=back
+
+=head2 HTTP Helper
 
-get unparsed CGI parameters
+=over 4
+
+=item get_unprocessed_cgi($query,$possible_names)
+
+Modify the %ENV hash to contain unprocessed CGI form parameters held in
+$query.  The parameters listed in $possible_names (an array reference),
+will be set in $ENV{'form.name'} if they do not already exist.
+
+Typically called with $ENV{'QUERY_STRING'} as the first parameter.  
+$possible_names is an ref to an array of form element names.  As an example:
+get_unprocessed_cgi($ENV{'QUERY_STRING'},['uname','udom']);
+will result in $ENV{'form.uname'} and $ENV{'form.udom'} being set.
 
 =item cacheheader()