--- loncom/interface/lonparmset.pm	2016/03/02 14:14:06	1.556
+++ loncom/interface/lonparmset.pm	2016/08/10 21:05:42	1.566
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # Handler to set parameters for assessments
 #
-# $Id: lonparmset.pm,v 1.556 2016/03/02 14:14:06 raeburn Exp $
+# $Id: lonparmset.pm,v 1.566 2016/08/10 21:05:42 damieng Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -36,7 +36,11 @@ lonparmset - Handler to set parameters f
 
 =head1 SYNOPSIS
 
-lonparmset provides an interface to setting course parameters. 
+lonparmset provides an interface to setting course parameters.
+
+It contains all the code for the "Content and Problem Settings" UI, except
+for the helpers parameter.helper and resettimes.helper, and lonhelper.pm,
+and lonblockingmenu.pm.
 
 =head1 DESCRIPTION
 
@@ -327,6 +331,15 @@ use HTML::Entities;
 use LONCAPA qw(:DEFAULT :match);
 
 
+##################################################
+# CONTENT AND PROBLEM SETTINGS HTML PAGE HEADER/FOOTER
+##################################################
+
+# Page header
+#
+# @param {Apache2::RequestRec} $r - Apache request object
+# @param {string} $mode - selected tab, 'parmset' for course and problem settings, or 'coursepref' for course settings
+# @param {string} $crstype - course type ('Community' for community settings)
 sub startSettingsScreen {
     my ($r,$mode,$crstype)=@_;
 
@@ -345,6 +358,7 @@ sub startSettingsScreen {
     $r->print('<div class="LC_Box" style="clear:both;margin:0;" id="parameditor"><div id="maincoursedoc" style="margin:0 0;padding:0 0;"><div class="LC_ContentBox" id="mainCourseDocuments" style="display: block;">');
 }
 
+# Page footer
 sub endSettingsScreen {
    my ($r)=@_;
    $r->print('</div></div></div>');
@@ -352,18 +366,48 @@ sub endSettingsScreen {
 
 
 
+##################################################
+# (mostly) TABLE MODE
+# (parmval is also used for the log of parameter changes)
+##################################################
+
+# Calls parmval_by_symb, getting the symb from $id with &symbcache.
+#
+# @param {string} $what - part info and parameter name separated by a dot, e.g. '0.weight'
+# @param {string} $id - resource id or map pc
+# @param {string} $def - the resource's default value for this parameter
+# @param {string} $uname - user name
+# @param {string} $udom - user domain
+# @param {string} $csec - section name
+# @param {string} $cgroup - group name
+# @param {hash reference} $courseopt - course parameters hash (result of lonnet::get_courseresdata, dump of course's resourcedata.db)
+# @returns {Array}
 sub parmval {
     my ($what,$id,$def,$uname,$udom,$csec,$cgroup,$courseopt)=@_;
     return &parmval_by_symb($what,&symbcache($id),$def,$uname,$udom,$csec,
                                                            $cgroup,$courseopt);
 }
 
+# Returns an array containing
+# - the most specific level that is defined for that parameter (integer)
+# - an array with the level as index and the parameter value as value (when defined)
+#   (level 1 is the most specific and will have precedence)
+#
+# @param {string} $what - part info and parameter name separated by a dot, e.g. '0.weight'
+# @param {string} $symb - resource symb or map src
+# @param {string} $def - the resource's default value for this parameter
+# @param {string} $uname - user name
+# @param {string} $udom - user domain
+# @param {string} $csec - section name
+# @param {string} $cgroup - group name
+# @param {hash reference} $courseopt - course parameters hash (result of lonnet::get_courseresdata, dump of course's resourcedata.db)
+# @returns {Array}
 sub parmval_by_symb {
     my ($what,$symb,$def,$uname,$udom,$csec,$cgroup,$courseopt)=@_;
 
     my $useropt;
     if ($uname ne '' && $udom ne '') {
-    $useropt = &Apache::lonnet::get_userresdata($uname,$udom);
+        $useropt = &Apache::lonnet::get_userresdata($uname,$udom);
     }
 
     my $result='';
@@ -371,7 +415,10 @@ sub parmval_by_symb {
 # ----------------------------------------------------- Cascading lookup scheme
     my $map=(&Apache::lonnet::decode_symb($symb))[0];
     $map = &Apache::lonnet::deversion($map);
-
+    
+    # NOTE: some of that code looks redondant with code in lonnavmaps::parmval_real,
+    # any change should be reflected there.
+    
     my $symbparm=$symb.'.'.$what;
     my $recurseparm=$map.'___(rec).'.$what; 
     my $mapparm=$map.'___(all).'.$what;
@@ -394,16 +441,19 @@ sub parmval_by_symb {
 
 # --------------------------------------------------------- first, check course
 
+# 18 - General Course
     if (defined($$courseopt{$courselevel})) {
         $outpar[18]=$$courseopt{$courselevel};
         $result=18;
     }
 
+# 17 - Map or Folder level in course (recursive) 
     if (defined($$courseopt{$courseleveli})) {
         $outpar[17]=$$courseopt{$courseleveli};
         $result=17;
     }
 
+# 16 - Map or Folder level in course (non-recursive)
     if (defined($$courseopt{$courselevelm})) {
         $outpar[16]=$$courseopt{$courselevelm};
         $result=16;
@@ -411,14 +461,17 @@ sub parmval_by_symb {
 
 # ------------------------------------------------------- second, check default
 
+# 15 - resource default
     if (defined($def)) { $outpar[15]=$def; $result=15; }
 
 # ------------------------------------------------------ third, check map parms
 
     
+# 14 - map default
     my $thisparm=&parmhash($symbparm);
     if (defined($thisparm)) { $outpar[14]=$thisparm; $result=14; }
 
+# 13 - resource level in course
     if (defined($$courseopt{$courselevelr})) {
         $outpar[13]=$$courseopt{$courselevelr};
         $result=13;
@@ -426,18 +479,22 @@ sub parmval_by_symb {
 
 # ------------------------------------------------------ fourth, back to course
     if ($csec ne '') {
+# 12 - General for section
         if (defined($$courseopt{$seclevel})) {
             $outpar[12]=$$courseopt{$seclevel};
             $result=12;
         }
+# 11 - Map or Folder level for section (recursive)
         if (defined($$courseopt{$secleveli})) {
             $outpar[11]=$$courseopt{$secleveli};
             $result=11;
         }
+# 10 - Map or Folder level for section (non-recursive)
         if (defined($$courseopt{$seclevelm})) {
             $outpar[10]=$$courseopt{$seclevelm};
             $result=10;
         }
+# 9 - resource level in section
         if (defined($$courseopt{$seclevelr})) {
             $outpar[9]=$$courseopt{$seclevelr};
             $result=9;
@@ -445,18 +502,22 @@ sub parmval_by_symb {
     }
 # ------------------------------------------------------ fifth, check course group
     if ($cgroup ne '') {
+# 8 - General for group
         if (defined($$courseopt{$grplevel})) {
             $outpar[8]=$$courseopt{$grplevel};
             $result=8;
         }
+# 7 - Map or Folder level for group (recursive)
         if (defined($$courseopt{$grpleveli})) {
             $outpar[7]=$$courseopt{$grpleveli};
             $result=7;
         }
+# 6 - Map or Folder level for group (non-recursive)
         if (defined($$courseopt{$grplevelm})) {
             $outpar[6]=$$courseopt{$grplevelm};
             $result=6;
         }
+# 5 - resource level in group
         if (defined($$courseopt{$grplevelr})) {
             $outpar[5]=$$courseopt{$grplevelr};
             $result=5;
@@ -466,25 +527,29 @@ sub parmval_by_symb {
 # ---------------------------------------------------------- sixth, check user
 
     if ($uname ne '') {
-    if (defined($$useropt{$courselevel})) {
-        $outpar[4]=$$useropt{$courselevel};
-        $result=4;
-    }
+# 4 - General for specific student
+        if (defined($$useropt{$courselevel})) {
+            $outpar[4]=$$useropt{$courselevel};
+            $result=4;
+        }
 
-    if (defined($$useropt{$courseleveli})) {
-        $outpar[3]=$$useropt{$courseleveli};
-        $result=3;
-    }
+# 3 - Map or Folder level for specific student (recursive)
+        if (defined($$useropt{$courseleveli})) {
+            $outpar[3]=$$useropt{$courseleveli};
+            $result=3;
+        }
 
-    if (defined($$useropt{$courselevelm})) {
-        $outpar[2]=$$useropt{$courselevelm};
-        $result=2;
-    }
+# 2 - Map or Folder level for specific student (non-recursive)
+        if (defined($$useropt{$courselevelm})) {
+            $outpar[2]=$$useropt{$courselevelm};
+            $result=2;
+        }
 
-    if (defined($$useropt{$courselevelr})) {
-        $outpar[1]=$$useropt{$courselevelr};
-        $result=1;
-    }
+# 1 - resource level for specific student
+        if (defined($$useropt{$courselevelr})) {
+            $outpar[1]=$$useropt{$courselevelr};
+            $result=1;
+        }
     }
     return ($result,@outpar);
 }
@@ -494,106 +559,128 @@ sub parmval_by_symb {
 # --- Caches local to lonparmset
 
 
+# Reset lonparmset caches (called at the beginning and end of the handler).
 sub reset_caches {
     &resetparmhash();
     &resetsymbcache();
     &resetrulescache();
 }
 
+# cache for map parameters, stored temporarily in $env{'request.course.fn'}_parms.db
+# (these parameters come from param elements in .sequence files created with the advanced RAT)
 {
-    my $parmhashid;
-    my %parmhash;
+    my $parmhashid; # course identifier, to initialize the cache only once for a course
+    my %parmhash; # the parameter cache
+    # reset map parameter hash
     sub resetparmhash {
-    undef($parmhashid);
-    undef(%parmhash);
+        undef($parmhashid);
+        undef(%parmhash);
     }
 
+    # dump the _parms.db database into %parmhash
     sub cacheparmhash {
-    if ($parmhashid eq  $env{'request.course.fn'}) { return; }
-    my %parmhashfile;
-    if (tie(%parmhashfile,'GDBM_File',
-        $env{'request.course.fn'}.'_parms.db',&GDBM_READER(),0640)) {
-        %parmhash=%parmhashfile;
-        untie(%parmhashfile);
-        $parmhashid=$env{'request.course.fn'};
-    }
+        if ($parmhashid eq  $env{'request.course.fn'}) { return; }
+        my %parmhashfile;
+        if (tie(%parmhashfile,'GDBM_File',
+            $env{'request.course.fn'}.'_parms.db',&GDBM_READER(),0640)) {
+            %parmhash=%parmhashfile;
+            untie(%parmhashfile);
+            $parmhashid=$env{'request.course.fn'};
+        }
     }
 
+    # returns a parameter value for an identifier symb.parts.parameter, using the map parameter cache
     sub parmhash {
-    my ($id) = @_;
-    &cacheparmhash();
-    return $parmhash{$id};
+        my ($id) = @_;
+        &cacheparmhash();
+        return $parmhash{$id};
     }
- }
+}
 
+# cache resource id or map pc -> resource symb or map src, using lonnavmaps to find association
 {
-    my $symbsid;
-    my %symbs;
+    my $symbsid; # course identifier, to initialize the cache only once for a course
+    my %symbs; # hash id->symb
+    # reset the id->symb cache
     sub resetsymbcache {
-    undef($symbsid);
-    undef(%symbs);
+        undef($symbsid);
+        undef(%symbs);
     }
 
+    # returns the resource symb or map src corresponding to a resource id or map pc
+    # (using lonnavmaps and a cache)
     sub symbcache {
-    my $id=shift;
-    if ($symbsid ne $env{'request.course.id'}) {
-        undef(%symbs);
-    }
-    if (!$symbs{$id}) {
-        my $navmap = Apache::lonnavmaps::navmap->new();
-        if ($id=~/\./) {
-        my $resource=$navmap->getById($id);
-        $symbs{$id}=$resource->symb();
-        } else {
-        my $resource=$navmap->getByMapPc($id);
-        $symbs{$id}=&Apache::lonnet::declutter($resource->src());
+        my $id=shift;
+        if ($symbsid ne $env{'request.course.id'}) {
+            undef(%symbs);
+        }
+        if (!$symbs{$id}) {
+            my $navmap = Apache::lonnavmaps::navmap->new();
+            if ($id=~/\./) {
+                my $resource=$navmap->getById($id);
+                $symbs{$id}=$resource->symb();
+            } else {
+                my $resource=$navmap->getByMapPc($id);
+                $symbs{$id}=&Apache::lonnet::declutter($resource->src());
+            }
+            $symbsid=$env{'request.course.id'};
         }
-        $symbsid=$env{'request.course.id'};
+        return $symbs{$id};
     }
-    return $symbs{$id};
-    }
- }
+}
 
+# cache for parameter default actions (stored in parmdefactions.db)
 {
-    my $rulesid;
-    my %rules;
+    my $rulesid; # course identifier, to initialize the cache only once for a course
+    my %rules; # parameter default actions hash
     sub resetrulescache {
-    undef($rulesid);
-    undef(%rules);
+        undef($rulesid);
+        undef(%rules);
     }
 
+    # returns the value for a given key in the parameter default action hash
     sub rulescache {
-    my $id=shift;
-    if ($rulesid ne $env{'request.course.id'}
-        && !defined($rules{$id})) {
-        my $dom = $env{'course.'.$env{'request.course.id'}.'.domain'};
-        my $crs = $env{'course.'.$env{'request.course.id'}.'.num'};
-        %rules=&Apache::lonnet::dump('parmdefactions',$dom,$crs);
-        $rulesid=$env{'request.course.id'};
-    }
-    return $rules{$id};
+        my $id=shift;
+        if ($rulesid ne $env{'request.course.id'}
+            && !defined($rules{$id})) {
+            my $dom = $env{'course.'.$env{'request.course.id'}.'.domain'};
+            my $crs = $env{'course.'.$env{'request.course.id'}.'.num'};
+            %rules=&Apache::lonnet::dump('parmdefactions',$dom,$crs);
+            $rulesid=$env{'request.course.id'};
+        }
+        return $rules{$id};
     }
 }
 
 
-
+# Returns the values of the parameter type default action
+# "default value when manually setting".
+# If none is defined, ('','','','','') is returned.
+#
+# @param {string} $type - parameter type
+# @returns {Array<string>} - (hours, min, sec, value)
 sub preset_defaults {
     my $type=shift;
     if (&rulescache($type.'_action') eq 'default') {
-# yes, there is something
-    return (&rulescache($type.'_hours'),
-        &rulescache($type.'_min'),
-        &rulescache($type.'_sec'),
-        &rulescache($type.'_value'));
+        # yes, there is something
+        return (&rulescache($type.'_hours'),
+            &rulescache($type.'_min'),
+            &rulescache($type.'_sec'),
+            &rulescache($type.'_value'));
     } else {
-# nothing there or something else
-    return ('','','','','');
+        # nothing there or something else
+        return ('','','','','');
     }
 }
 
 
-
-
+# Checks that a date is after enrollment start date and before
+# enrollment end date.
+# Returns HTML with a warning if it is not, or the empty string otherwise.
+# This is used by both overview and table modes.
+#
+# @param {integer} $checkdate - the date to check.
+# @returns {string} - HTML possibly containing a localized warning message.
 sub date_sanity_info {
    my $checkdate=shift;
    unless ($checkdate) { return ''; }
@@ -628,81 +715,109 @@ sub date_sanity_info {
 #      }
    return $result;
 }
-##################################################
-##################################################
-#
-# Store a parameter by ID
-#
-# Takes
-# - resource id
-# - name of parameter
-# - level
-# - new value
-# - new type
-# - username
-# - userdomain
 
+
+# Store a parameter value and type by ID, also triggering more parameter changes based on parameter default actions.
+#
+# @param {string} $sresid - resource id or map pc
+# @param {string} $spnam - part info and parameter name separated by a dot or underscore, e.g. '0.weight'
+# @param {integer} $snum - level
+# @param {string} $nval - new value
+# @param {string} $ntype - new type
+# @param {string} $uname - username
+# @param {string} $udom - userdomain
+# @param {string} $csec - section name
+# @param {string} $cgroup - group name
 sub storeparm {
     my ($sresid,$spnam,$snum,$nval,$ntype,$uname,$udom,$csec,$cgroup)=@_;
     &storeparm_by_symb(&symbcache($sresid),$spnam,$snum,$nval,$ntype,$uname,$udom,$csec,'',$cgroup);
 }
 
-my %recstack;
+my %recstack; # hash parameter name -> 1 when a parameter was used before in a recursive call to storeparm_by_symb
+
+# Store a parameter value and type by symb, also triggering more parameter changes based on parameter default actions.
+# Uses storeparm_by_symb_inner to actually store the parameter, ignoring any returned error.
+#
+# @param {string} $symb - resource symb or map src
+# @param {string} $spnam - part info and parameter name separated by a dot or underscore, e.g. '0.weight'
+# @param {integer} $snum - level
+# @param {string} $nval - new value
+# @param {string} $ntype - new type
+# @param {string} $uname - username
+# @param {string} $udom - userdomain
+# @param {string} $csec - section name
+# @param {boolean} $recflag - should be true for recursive calls to storeparm_by_symb, false otherwise
+# @param {string} $cgroup - group name
 sub storeparm_by_symb {
     my ($symb,$spnam,$snum,$nval,$ntype,$uname,$udom,$csec,$recflag,$cgroup)=@_;
     unless ($recflag) {
-# first time call
-    %recstack=();
-    $recflag=1;
+        # first time call
+        %recstack=();
+        $recflag=1;
     }
-# store parameter
+    # store parameter
     &storeparm_by_symb_inner
     ($symb,$spnam,$snum,$nval,$ntype,$uname,$udom,$csec,$cgroup);
-# don't do anything if parameter was reset
+    # don't do anything if parameter was reset
     unless ($nval) { return; }
     my ($prefix,$parm)=($spnam=~/^(.*[\_\.])([^\_\.]+)$/);
-# remember that this was set
+    # remember that this was set
     $recstack{$parm}=1;
-# what does this trigger?
+    # what does this trigger?
     foreach my $triggered (split(/\:/,&rulescache($parm.'_triggers'))) {
-# don't backfire
-       unless ((!$triggered) || ($recstack{$triggered})) {
-       my $action=&rulescache($triggered.'_action');
-       my ($whichaction,$whichparm)=($action=~/^(.*\_)([^\_]+)$/);
-# set triggered parameter on same level
-       my $newspnam=$prefix.$triggered;
-       my $newvalue='';
-       my $active=1;
-       if ($action=~/^when\_setting/) {
-# are there restrictions?
-           if (&rulescache($triggered.'_triggervalue')=~/\w/) {
-           $active=0;
-           foreach my $possiblevalue (split(/\s*\,\s*/,&rulescache($triggered.'_triggervalue'))) {
-               if (lc($possiblevalue) eq lc($nval)) { $active=1; }
-           }
-           }
-           $newvalue=&rulescache($triggered.'_value');
-       } else {
-           my $totalsecs=((&rulescache($triggered.'_days')*24+&rulescache($triggered.'_hours'))*60+&rulescache($triggered.'_min'))*60+&rulescache($triggered.'_sec');
-           if ($action=~/^later\_than/) {
-           $newvalue=$nval+$totalsecs;
-           } else {
-           $newvalue=$nval-$totalsecs;
-           }
-       }
-       if ($active) {
-           &storeparm_by_symb($symb,$newspnam,$snum,$newvalue,&rulescache($triggered.'_type'),
-                   $uname,$udom,$csec,$recflag,$cgroup);
-       }
-       }
+        # don't backfire
+        unless ((!$triggered) || ($recstack{$triggered})) {
+            my $action=&rulescache($triggered.'_action');
+            my ($whichaction,$whichparm)=($action=~/^(.*\_)([^\_]+)$/);
+            # set triggered parameter on same level
+            my $newspnam=$prefix.$triggered;
+            my $newvalue='';
+            my $active=1;
+            if ($action=~/^when\_setting/) {
+            # are there restrictions?
+                if (&rulescache($triggered.'_triggervalue')=~/\w/) {
+                    $active=0;
+                    foreach my $possiblevalue (split(/\s*\,\s*/,&rulescache($triggered.'_triggervalue'))) {
+                        if (lc($possiblevalue) eq lc($nval)) { $active=1; }
+                    }
+                }
+                $newvalue=&rulescache($triggered.'_value');
+            } else {
+                my $totalsecs=((&rulescache($triggered.'_days')*24+&rulescache($triggered.'_hours'))*60+&rulescache($triggered.'_min'))*60+&rulescache($triggered.'_sec');
+                if ($action=~/^later\_than/) {
+                    $newvalue=$nval+$totalsecs;
+                } else {
+                    $newvalue=$nval-$totalsecs;
+                }
+            }
+            if ($active) {
+                &storeparm_by_symb($symb,$newspnam,$snum,$newvalue,&rulescache($triggered.'_type'),
+                        $uname,$udom,$csec,$recflag,$cgroup);
+            }
+        }
     }
     return '';
 }
 
+# Adds all given arguments to the course parameter log.
+# @returns {string} - the answer to the lonnet query.
 sub log_parmset {
     return &Apache::lonnet::write_log('course','parameterlog',@_);
 }
 
+# Store a parameter value and type by symb, without using the parameter default actions.
+# Expire related sheets.
+#
+# @param {string} $symb - resource symb or map src
+# @param {string} $spnam - part info and parameter name separated by a dot, e.g. '0.weight'
+# @param {integer} $snum - level
+# @param {string} $nval - new value
+# @param {string} $ntype - new type
+# @param {string} $uname - username
+# @param {string} $udom - userdomain
+# @param {string} $csec - section name
+# @param {string} $cgroup - group name
+# @returns {string} - HTML code with an error message if the parameter could not be stored.
 sub storeparm_by_symb_inner {
 # ---------------------------------------------------------- Get symb, map, etc
     my ($symb,$spnam,$snum,$nval,$ntype,$uname,$udom,$csec,$cgroup)=@_;
@@ -750,66 +865,76 @@ sub storeparm_by_symb_inner {
     my %storecontent = ($storeunder         => $nval,
             $storeunder.'.type' => $ntype);
     my $reply='';
+    
     if ($snum>4) {
 # ---------------------------------------------------------------- Store Course
 #
-    my $cnum = $env{'course.'.$env{'request.course.id'}.'.num'};
-    my $cdom = $env{'course.'.$env{'request.course.id'}.'.domain'};
-# Expire sheets
-    &Apache::lonnet::expirespread('','','studentcalc');
-    if (($snum==13) || ($snum==9) || ($snum==5)) {
-        &Apache::lonnet::expirespread('','','assesscalc',$symb);
-#FIXME
-    } elsif (($snum==14) || ($snum==10) || ($snum==6)) {
-        &Apache::lonnet::expirespread('','','assesscalc',$map);
-    } else {
-        &Apache::lonnet::expirespread('','','assesscalc');
-    }
-# Store parameter
-    if ($delete) {
-        $reply=&Apache::lonnet::del
-        ('resourcedata',[keys(%storecontent)],$cdom,$cnum);
-            &log_parmset(\%storecontent,1);
-    } else {
-        $reply=&Apache::lonnet::cput
-        ('resourcedata',\%storecontent,$cdom,$cnum);
-        &log_parmset(\%storecontent);
-    }
-    &Apache::lonnet::devalidatecourseresdata($cnum,$cdom);
+        my $cnum = $env{'course.'.$env{'request.course.id'}.'.num'};
+        my $cdom = $env{'course.'.$env{'request.course.id'}.'.domain'};
+        # Expire sheets
+        &Apache::lonnet::expirespread('','','studentcalc');
+        if (($snum==13) || ($snum==9) || ($snum==5)) {
+            &Apache::lonnet::expirespread('','','assesscalc',$symb);
+        } elsif (($snum==14) || ($snum==10) || ($snum==6)) {
+            &Apache::lonnet::expirespread('','','assesscalc',$map);
+        } else {
+            &Apache::lonnet::expirespread('','','assesscalc');
+        }
+        # Store parameter
+        if ($delete) {
+            $reply=&Apache::lonnet::del
+            ('resourcedata',[keys(%storecontent)],$cdom,$cnum);
+                &log_parmset(\%storecontent,1);
+        } else {
+            $reply=&Apache::lonnet::cput
+            ('resourcedata',\%storecontent,$cdom,$cnum);
+            &log_parmset(\%storecontent);
+        }
+        &Apache::lonnet::devalidatecourseresdata($cnum,$cdom);
     } else {
 # ------------------------------------------------------------------ Store User
 #
-# Expire sheets
-    &Apache::lonnet::expirespread($uname,$udom,'studentcalc');
-    if ($snum==1) {
-        &Apache::lonnet::expirespread
-        ($uname,$udom,'assesscalc',$symb);
-    } elsif ($snum==2) {
-        &Apache::lonnet::expirespread
-        ($uname,$udom,'assesscalc',$map);
-    } else {
-        &Apache::lonnet::expirespread($uname,$udom,'assesscalc');
-    }
-# Store parameter
-    if ($delete) {
-        $reply=&Apache::lonnet::del
-        ('resourcedata',[keys(%storecontent)],$udom,$uname);
-        &log_parmset(\%storecontent,1,$uname,$udom);
-    } else {
-        $reply=&Apache::lonnet::cput
-        ('resourcedata',\%storecontent,$udom,$uname);
-        &log_parmset(\%storecontent,0,$uname,$udom);
-    }
-    &Apache::lonnet::devalidateuserresdata($uname,$udom);
+        # Expire sheets
+        &Apache::lonnet::expirespread($uname,$udom,'studentcalc');
+        if ($snum==1) {
+            &Apache::lonnet::expirespread
+            ($uname,$udom,'assesscalc',$symb);
+        } elsif ($snum==2) {
+            &Apache::lonnet::expirespread
+            ($uname,$udom,'assesscalc',$map);
+        } else {
+            &Apache::lonnet::expirespread($uname,$udom,'assesscalc');
+        }
+        # Store parameter
+        if ($delete) {
+            $reply=&Apache::lonnet::del
+            ('resourcedata',[keys(%storecontent)],$udom,$uname);
+            &log_parmset(\%storecontent,1,$uname,$udom);
+        } else {
+            $reply=&Apache::lonnet::cput
+            ('resourcedata',\%storecontent,$udom,$uname);
+            &log_parmset(\%storecontent,0,$uname,$udom);
+        }
+        &Apache::lonnet::devalidateuserresdata($uname,$udom);
     }
 
     if ($reply=~/^error\:(.*)/) {
-    return "<span class=\"LC_error\">Write Error: $1</span>";
+        return "<span class=\"LC_error\">Write Error: $1</span>";
     }
     return '';
 }
 
 
+# Returns HTML with the value of the given parameter,
+# using a readable format for dates, and
+# a warning if there is a problem with a date.
+# Used by table mode.
+# Returns HTML for the editmap.png image if no value is defined and $editable is true.
+#
+# @param {string} $value - the parameter value
+# @param {string} $type - the parameter type
+# @param {string} $name - the parameter name (unused)
+# @param {boolean} $editable - Set to true to get an icon when no value is defined.
 sub valout {
     my ($value,$type,$name,$editable)=@_;
     my $result = '';
@@ -825,7 +950,16 @@ sub valout {
         }
     } else {
         if ($type eq 'date_interval') {
-            my ($totalsecs,$donebutton) = split(/_/,$value);
+            my ($totalsecs,$donesuffix) = split(/_/,$value,2);
+            my ($usesdone,$donebuttontext,$proctor,$secretkey);
+            if ($donesuffix =~ /^done\:([^\:]+)\:(.*)$/) {
+                $donebuttontext = $1;
+                (undef,$proctor,$secretkey) = split(/_/,$2);
+                $usesdone = 'done';
+            } elsif ($donesuffix =~ /^done(|_.+)$/) {
+                $donebuttontext = &mt('Done');
+                ($usesdone,$proctor,$secretkey) = split(/_/,$donesuffix);
+            }
             my ($sec,$min,$hour,$mday,$mon,$year)=gmtime($totalsecs);
             my @timer;
             $year=$year-70;
@@ -859,27 +993,40 @@ sub valout {
                 push(@timer,&mt('[quant,_1,sec]',0));
             }
             $result.=join(", ",@timer);
-            if ($donebutton eq 'done') {
-                $result .= ' '.&mt('+ "done"');
+            if ($usesdone eq 'done') {
+                if ($secretkey) {
+                    $result .= ' '.&mt('+ "[_1]" with proctor key: [_2]',$donebuttontext,$secretkey);  
+                } else {
+                    $result .= ' + "'.$donebuttontext.'"';
+                }
             }
         } elsif (&isdateparm($type)) {
             $result = &Apache::lonlocal::locallocaltime($value).
-        &date_sanity_info($value);
+                &date_sanity_info($value);
         } else {
             $result = $value;
             $result=~s/\,/\, /gs;
-        $result = &HTML::Entities::encode($result,'"<>&');
+            $result = &HTML::Entities::encode($result,'"<>&');
         }
     }
     return $result;
 }
 
 
+# Returns HTML containing a link on a parameter value, for table mode.
+# The link uses the javascript function 'pjump'.
+#
+# @param {string} $type - parameter type
+# @param {string} $dis - dialog title for editing the parameter value and type
+# @param {string} $value - parameter value
+# @param {string} $marker - identifier for the parameter, "resource id&part_parameter name&level", will be passed as pres_marker when the user submits a change.
+# @param {string} $return - prefix for the name of the form and field names that will be used to submit the form ('parmform.pres')
+# @param {string} $call - javascript function to call to submit the form ('psub')
 sub plink {
     my ($type,$dis,$value,$marker,$return,$call)=@_;
     my $winvalue=$value;
     unless ($winvalue) {
-    if (&isdateparm($type)) {
+        if (&isdateparm($type)) {
             $winvalue=$env{'form.recent_'.$type};
         } else {
             $winvalue=$env{'form.recent_'.(split(/\_/,$type))[0]};
@@ -892,8 +1039,8 @@ sub plink {
     my $unencmarker = $marker;
     foreach my $item (\$type, \$dis, \$winvalue, \$marker, \$return, \$call,
               \$hour, \$min, \$sec) {
-    $$item = &HTML::Entities::encode($$item,'"<>&');
-    $$item =~ s/\'/\\\'/g;
+        $$item = &HTML::Entities::encode($$item,'"<>&');
+        $$item =~ s/\'/\\\'/g;
     }
     return '<table width="100%"><tr valign="top" align="right"><td><a name="'.$unencmarker.'" /></td></tr><tr><td align="center">'.
     '<a href="javascript:pjump('."'".$type."','".$dis."','".$winvalue."','"
@@ -901,6 +1048,7 @@ sub plink {
         $valout.'</a></td></tr></table>';
 }
 
+# Javascript for table mode.
 sub page_js {
 
     my $selscript=&Apache::loncommon::studentbrowser_javascript();
@@ -917,16 +1065,16 @@ sub page_js {
             document.parmform.action+='#'+document.parmform.pres_marker.value;
             var typedef=new Array();
             typedef=document.parmform.pres_type.value.split('_');
-           if (document.parmform.pres_type.value!='') {
-            if (typedef[0]=='date') {
-                eval('document.parmform.recent_'+
-                     document.parmform.pres_type.value+
-             '.value=document.parmform.pres_value.value;');
-            } else {
-                eval('document.parmform.recent_'+typedef[0]+
-             '.value=document.parmform.pres_value.value;');
+            if (document.parmform.pres_type.value!='') {
+                if (typedef[0]=='date') {
+                    eval('document.parmform.recent_'+
+                        document.parmform.pres_type.value+
+                        '.value=document.parmform.pres_value.value;');
+                } else {
+                    eval('document.parmform.recent_'+typedef[0]+
+                        '.value=document.parmform.pres_value.value;');
+                }
             }
-       }
             document.parmform.submit();
         } else {
             document.parmform.pres_value.value='';
@@ -950,6 +1098,8 @@ ENDJS
 
 }
 
+# Javascript to show or hide the map selection (function showHide_courseContent),
+# for table and overview modes.
 sub showhide_js {
     return <<"COURSECONTENTSCRIPT";
 
@@ -970,6 +1120,7 @@ function showHide_courseContent() {
 COURSECONTENTSCRIPT
 }
 
+# Javascript functions showHideLenient and toggleParmTextbox, for overview mode
 sub toggleparmtextbox_js {
     return <<"ENDSCRIPT";
 
@@ -1029,6 +1180,7 @@ function toggleParmTextbox(form,key) {
 ENDSCRIPT
 }
 
+# Javascript function validateParms, for overview mode
 sub validateparms_js {
     return <<'ENDSCRIPT';
 
@@ -1102,6 +1254,7 @@ function validateParms() {
 ENDSCRIPT
 }
 
+# Javascript initialization, for overview mode
 sub ipacc_boxes_js  {
     my $remove = &mt('Remove');
     return <<"END";
@@ -1126,6 +1279,36 @@ sub ipacc_boxes_js  {
 END
 }
 
+# Javascript function toggleSecret, for overview mode.
+sub done_proctor_js {
+    return <<"END";
+function toggleSecret(form,radio,key) {
+    var radios = form[radio+key];
+    if (radios.length) {
+        for (var i=0; i<radios.length; i++) {
+            if (radios[i].checked) {
+                if (radios[i].value == '_done_proctor') {
+                    if (document.getElementById('done_'+key+'_proctorkey')) {
+                        document.getElementById('done_'+key+'_proctorkey').type='text';
+                    }
+                } else {
+                    if (document.getElementById('done_'+key+'_proctorkey')) {
+                        document.getElementById('done_'+key+'_proctorkey').type='hidden';
+                        document.getElementById('done_'+key+'_proctorkey').value='';
+                    }
+                }
+            }
+        }
+    }
+}
+END
+
+}
+
+# Prints HTML page start for table mode.
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {string} $psymb - resource symb
+# @param {string} $crstype - course type (Community / Course / Placement Test)
 sub startpage {
     my ($r,$psymb,$crstype) = @_;
 
@@ -1136,14 +1319,14 @@ sub startpage {
         $loaditems{'onload'} = "showHide_courseContent(); group_or_section('cgroup'); resize_scrollbox('mapmenuscroll','1','1');";
     }
 
-    if ((($env{'form.command'} eq 'set') && ($env{'form.url'})
-         && (!$env{'form.dis'})) || ($env{'form.symb'})) {
-    &Apache::lonhtmlcommon::add_breadcrumb({help=>'Problem_Parameters',
-        text=>"Problem Parameters"});
+    if ((($env{'form.command'} eq 'set') && ($env{'form.url'}) &&
+            (!$env{'form.dis'})) || ($env{'form.symb'})) {
+        &Apache::lonhtmlcommon::add_breadcrumb({help=>'Problem_Parameters',
+            text=>"Problem Parameters"});
     } else {
-    &Apache::lonhtmlcommon::add_breadcrumb({href=>'/adm/parmset?action=settable',
-       text=>"Table Mode",
-       help => 'Course_Setting_Parameters'});
+        &Apache::lonhtmlcommon::add_breadcrumb({href=>'/adm/parmset?action=settable',
+            text=>"Table Mode",
+            help => 'Course_Setting_Parameters'});
     }
     my $js = &page_js().'
 <script type="text/javascript">
@@ -1174,6 +1357,29 @@ ENDHEAD
 }
 
 
+# Prints a row for table mode (except for the tr start).
+# Every time a hash reference is passed, a single entry is used, so print_row
+# could just use these values, but why make it simple when it can be complicated ?
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {string} $which - parameter key ('parameter_'.part.'_'.name)
+# @param {hash reference} $part - parameter key -> parameter part (can be problem part.'_'.response id for response parameters)
+# @param {hash reference} $name - parameter key -> parameter name
+# @param {hash reference} $symbp - map pc or resource/map id -> map src.'___(all)' or resource symb
+# @param {string} $rid - resource id
+# @param {hash reference} $default - parameter key -> resource parameter default value
+# @param {hash reference} $defaulttype - parameter key -> resource parameter default type
+# @param {hash reference} $display - parameter key -> full title for the parameter
+# @param {string} $defbgone - user level and other levels background color
+# @param {string} $defbgtwo - section level background color, also used for part number
+# @param {string} $defbgthree - group level background color
+# @param {string} $parmlev - parameter level (Resource:'full', Map:'map', Course:'general')
+# @param {string} $uname - user name
+# @param {string} $udom - user domain
+# @param {string} $csec - section name
+# @param {string} $cgroup - group name
+# @param {array reference} $usersgroups - list of groups the user belongs to, if any
+# @param {boolean} $noeditgrp - true if no edit is allowed for group level parameters
 sub print_row {
     my ($r,$which,$part,$name,$symbp,$rid,$default,$defaulttype,$display,$defbgone,
     $defbgtwo,$defbgthree,$parmlev,$uname,$udom,$csec,$cgroup,$usersgroups,$noeditgrp)=@_;
@@ -1181,21 +1387,21 @@ sub print_row {
     my $cdom = $env{'course.'.$env{'request.course.id'}.'.domain'};
     my $courseopt=&Apache::lonnet::get_courseresdata($cnum,$cdom);
 
-# get the values for the parameter in cascading order
-# empty levels will remain empty
+    # get the values for the parameter in cascading order
+    # empty levels will remain empty
     my ($result,@outpar)=&parmval($$part{$which}.'.'.$$name{$which},
       $rid,$$default{$which},$uname,$udom,$csec,$cgroup,$courseopt);
-# get the type for the parameters
-# problem: these may not be set for all levels
+    # get the type for the parameters
+    # problem: these may not be set for all levels
     my ($typeresult,@typeoutpar)=&parmval($$part{$which}.'.'.
                                           $$name{$which}.'.type',$rid,
          $$defaulttype{$which},$uname,$udom,$csec,$cgroup,$courseopt);
-# cascade down manually
+    # cascade down manually
     my $cascadetype=$$defaulttype{$which};
     for (my $i=18;$i>0;$i--) {
-     if ($typeoutpar[$i]) {
+        if ($typeoutpar[$i]) {
             $cascadetype=$typeoutpar[$i];
-    } else {
+        } else {
             $typeoutpar[$i]=$cascadetype;
         }
     }
@@ -1209,7 +1415,7 @@ sub print_row {
     }
     my $automatic=&rulescache(($which=~/\_([^\_]+)$/)[0].'_triggers');
     if ($automatic) {
-    $parm.='<span class="LC_warning"><br />'.&mt('Automatically sets').' '.join(', ',split(/\:/,$automatic)).'</span>';
+        $parm.='<span class="LC_warning"><br />'.&mt('Automatically sets').' '.join(', ',split(/\:/,$automatic)).'</span>';
     }
     $r->print('<td>'.$parm.'</td>');
 
@@ -1299,7 +1505,9 @@ sub print_row {
         my $sessionval=&Apache::lonnet::EXT('resource.'.$$part{$which}.
                                         '.'.$$name{$which},$$symbp{$rid});
         my $sessionvaltype=$typeoutpar[$result];
-        if (!defined($sessionvaltype)) { $sessionvaltype=$$defaulttype{$which}; }
+        if (!defined($sessionvaltype)) {
+            $sessionvaltype=$$defaulttype{$which};
+        }
         $r->print('<td style="background-color:#999999;" align="center"><font color="#FFFFFF">'.
                   &valout($sessionval,$sessionvaltype,$$name{$which}).'&nbsp;'.
                   '</font></td>');
@@ -1308,6 +1516,22 @@ sub print_row {
     $r->print("\n");
 }
 
+# Prints a cell for table mode.
+#
+# FIXME: some of these parameter names are uninspired ($which and $value)
+# Also, it would make more sense to pass the display for this cell rather
+# than the full display hash and the key to use.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {integer} $which - level
+# @param {string} $defbg - cell background color
+# @param {integer} $result - the most specific level that is defined for that parameter
+# @param {array reference} $outpar - array level -> parameter value (when defined)
+# @param {string} $mprefix - resource id.'&'.part.'_'.parameter name.'&'
+# @param {string} $value - parameter key ('parameter_'.part.'_'.name)
+# @param {array reference} $typeoutpar - array level -> parameter type (when defined)
+# @param {hash reference} $display - parameter key -> full title for the parameter
+# @param {boolean} $noeditgrp - true if no edit is allowed for group level parameters
 sub print_td {
     my ($r,$which,$defbg,$result,$outpar,$mprefix,$value,$typeoutpar,$display,$noeditgrp)=@_;
     $r->print('<td style="background-color:'.(($result==$which)?'#AAFFAA':$defbg).
@@ -1332,6 +1556,7 @@ sub print_td {
     }
     if ($nolink) {
         $r->print(&valout($$outpar[$which],$$typeoutpar[$which],$mprefix));
+# FIXME: probably a good thing that mprefix is not used in valout, because it does not look like a parameter name !
     } else {
         $r->print(&plink($$typeoutpar[$which],
                          $$display{$value},$$outpar[$which],
@@ -1340,6 +1565,19 @@ sub print_td {
     $r->print('</td>'."\n");
 }
 
+# FIXME: Despite the name, this does not print anything, the $r parameter is unused.
+# Returns HTML and other info for the cell added when a user is selected
+# and that user is in several groups. This is the cell with the title "Control by other group".
+#
+# @param {Apache2::RequestRec} $r - the Apache request (unused)
+# @param {string} $what - parameter part.'.'.parameter name
+# @param {string} $rid - resource id
+# @param {string} $cgroup - group name
+# @param {string} $defbg - cell background color
+# @param {array reference} $usersgroups - list of groups the user belongs to, if any
+# @param {integer} $result - level
+# @param {hash reference} $courseopt - course parameters hash (result of lonnet::get_courseresdata, dump of course's resourcedata.db)
+# @returns {Array} - array (parameter value for the other group, HTML for the cell, HTML with the value, name of the other group)
 sub print_usergroups {
     my ($r,$what,$rid,$cgroup,$defbg,$usersgroups,$result,$courseopt) = @_;
     my $courseid = $env{'request.course.id'};
@@ -1373,6 +1611,17 @@ sub print_usergroups {
     return ($coursereply,$output,$grp_parm,$resultgroup);
 }
 
+# Looks for a group with a defined parameter for given user and parameter.
+# Used by print_usergroups.
+#
+# @param {string} $courseid - the course id
+# @param {array reference} $usersgroups - list of groups the user belongs to, if any
+# @param {string} $symbparm - end of the course parameter hash key for the group resource level
+# @param {string} $mapparm - end of the course parameter hash key for the group map/folder level
+# @param {string} $recurseparm - end of the course parameter hash key for the group recursive level
+# @param {string} $what - parameter part.'.'.parameter name
+# @param {hash reference} $courseopt - course parameters hash
+# @returns {Array} - (parameter value for the group, course parameter hash key for the parameter, name of the group, level name, parameter type)
 sub parm_control_group {
     my ($courseid,$usersgroups,$symbparm,$mapparm,$recurseparm,$what,$courseopt) = @_;
     my ($coursereply,$resultitem,$resultgroup,$resultlevel,$resulttype);
@@ -1399,6 +1648,21 @@ sub parm_control_group {
 
 
 
+# Extracts lots of information about all of the the course's resources into a variety of hashes, using lonnavmaps and lonnet::metadata.
+# All the parameters are references and are filled by the sub.
+#
+# @param {array reference} $ids - resource and map ids
+# @param {hash reference} $typep - hash resource/map id -> resource type (file extension)
+# @param {hash reference} $keyp - hash resource/map id -> comma-separated list of parameter keys from lonnet::metadata
+# @param {hash reference} $allparms - hash parameter name -> parameter title
+# @param {hash reference} $allparts - hash parameter part -> part title (a parameter part can be problem part.'_'.response id for response parameters)
+# @param {hash reference} $allmaps - hash map pc -> map src
+# @param {hash reference} $mapp - hash map pc or resource/map id -> enclosing map src
+# @param {hash reference} $symbp - hash map pc or resource/map id -> map src.'___(all)' for a map or resource symb for a resource
+# @param {hash reference} $maptitles - hash map pc or src -> map title (this should really be two separate hashes)
+# @param {hash reference} $uris - hash resource/map id -> resource src
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank for this parameter when looking through every resource and every parameter, starting at 100 (integer)
+# @param {hash reference} $defkeytype - hash parameter name -> parameter type
 sub extractResourceInformation {
     my $ids = shift;
     my $typep = shift;
@@ -1499,17 +1763,22 @@ sub extractResourceInformation {
 }
 
 
-
+# Tells if a parameter type is a date.
+#
+# @param {string} type - parameter type
+# @returns{boolean} - true if it is a date
 sub isdateparm {
     my $type=shift;
     return (($type=~/^date/) && (!($type eq 'date_interval')));
 }
 
+# Prints the HTML and Javascript to select parameters, with various shortcuts.
+# FIXME: remove unused parameters
 #
-# parmmenu displays a list of the selected parameters.
-# It also offers a link to show/hide the complete parameter list
-# from which you can select all desired parameters.
-#
+# @param {Apache2::RequestRec} $r - the Apache request (unused)
+# @param {hash reference} $allparms - hash parameter name -> parameter title
+# @param {array reference} $pscat - list of selected parameter names (unused)
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank (unused)
 sub parmmenu {
     my ($r,$allparms,$pscat,$keyorder)=@_;
     my $tempkey;
@@ -1525,7 +1794,7 @@ sub parmmenu {
             displayOverview = "none"
         }
 
-    for (i=0; i<document.forms.parmform.elements.length; i++) {
+        for (i=0; i<document.forms.parmform.elements.length; i++) {
             ele = document.forms.parmform.elements[i];
             if (ele.name == checkName) {
                 document.forms.parmform.elements[i].checked=value;
@@ -1534,56 +1803,54 @@ sub parmmenu {
     }
 
     function checkthis(thisvalue, checkName) {
-
-
-    for (i=0; i<document.forms.parmform.elements.length; i++) {
+        for (i=0; i<document.forms.parmform.elements.length; i++) {
             ele = document.forms.parmform.elements[i];
             if (ele.name == checkName) {
-        if (ele.value == thisvalue) {
-            document.forms.parmform.elements[i].checked=true;
-        }
+                if (ele.value == thisvalue) {
+                    document.forms.parmform.elements[i].checked=true;
+                }
             }
         }
     }
 
     function checkdates() {
-    checkthis('duedate','pscat');
-     checkthis('opendate','pscat');
-    checkthis('answerdate','pscat');
+        checkthis('duedate','pscat');
+        checkthis('opendate','pscat');
+        checkthis('answerdate','pscat');
     }
 
     function checkdisset() {
-     checkthis('discussend','pscat');
-     checkthis('discusshide','pscat');
-     checkthis('discussvote','pscat');
+        checkthis('discussend','pscat');
+        checkthis('discusshide','pscat');
+        checkthis('discussvote','pscat');
     }
 
     function checkcontdates() {
-    checkthis('contentopen','pscat');
-     checkthis('contentclose','pscat');
+        checkthis('contentopen','pscat');
+        checkthis('contentclose','pscat');
     }
 
     function checkvisi() {
-    checkthis('hiddenresource','pscat');
-     checkthis('encrypturl','pscat');
-    checkthis('problemstatus','pscat');
-    checkthis('contentopen','pscat');
-    checkthis('opendate','pscat');
+        checkthis('hiddenresource','pscat');
+        checkthis('encrypturl','pscat');
+        checkthis('problemstatus','pscat');
+        checkthis('contentopen','pscat');
+        checkthis('opendate','pscat');
     }
 
     function checkparts() {
-    checkthis('hiddenparts','pscat');
-    checkthis('display','pscat');
-    checkthis('ordered','pscat');
+        checkthis('hiddenparts','pscat');
+        checkthis('display','pscat');
+        checkthis('ordered','pscat');
     }
 
     function checkstandard() {
         checkall(false,'pscat');
-    checkdates();
-    checkthis('weight','pscat');
-    checkthis('maxtries','pscat');
-    checkthis('type','pscat');
-    checkthis('problemstatus','pscat');
+        checkdates();
+        checkthis('weight','pscat');
+        checkthis('maxtries','pscat');
+        checkthis('type','pscat');
+        checkthis('problemstatus','pscat');
     }
 
 // ]]>
@@ -1594,7 +1861,10 @@ ENDSCRIPT
     &shortCuts($r,$allparms,$pscat,$keyorder);
     $r->print('<hr />');
 }
-# return a hash
+
+# Returns parameter categories.
+#
+# @returns {hash} - category name -> title in English
 sub categories {
     return ('time_settings' => 'Time Settings',
     'grading' => 'Grading',
@@ -1608,7 +1878,9 @@ sub categories {
     'misc' => 'Miscellaneous' ); 
 }
 
-# return a hash. Like a look-up table
+# Returns the category for each parameter.
+#
+# @returns {hash} - parameter name -> category name
 sub lookUpTableParameter {
  
     return ( 
@@ -1619,8 +1891,8 @@ sub lookUpTableParameter {
         'contentopen' => 'time_settings',
         'contentclose' => 'time_settings',
         'discussend' => 'time_settings',
-	'printstartdate' => 'time_settings',
-	'printenddate' => 'time_settings',
+        'printstartdate' => 'time_settings',
+        'printenddate' => 'time_settings',
         'weight' => 'grading',
         'handgrade' => 'grading',
         'maxtries' => 'tries',
@@ -1659,6 +1931,10 @@ sub lookUpTableParameter {
     );    
 }
 
+# Adds the given parameter name to an array of arrays listing all parameters for each category.
+#
+# @param {string} $name - parameter name
+# @param {array reference} $catList - array reference category name -> array reference of parameter names
 sub whatIsMyCategory {
     my $name = shift;
     my $catList = shift;
@@ -1682,6 +1958,11 @@ sub whatIsMyCategory {
     }        
 }
 
+# Sorts parameter names based on appearance order.
+#
+# @param {array reference} name - array reference of parameter names
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank
+# @returns {Array} - array of parameter names
 sub keysindisplayorderCategory {
     my ($name,$keyorder)=@_;
     return sort {
@@ -1689,6 +1970,9 @@ sub keysindisplayorderCategory {
     } ( @{$name});
 }
 
+# Returns a hash category name -> order, starting at 1 (integer)
+#
+# @returns {hash}
 sub category_order {
     return (
         'time_settings' => 1,
@@ -1705,6 +1989,12 @@ sub category_order {
 
 }
 
+# Prints HTML to let the user select parameters, from a list of all parameters organized by category.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {hash reference} $allparms - hash parameter name -> parameter title
+# @param {array reference} $pscat - list of selected parameter names
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank
 sub parmboxes {
     my ($r,$allparms,$pscat,$keyorder)=@_;
     my %categories = &categories();
@@ -1746,9 +2036,14 @@ sub parmboxes {
     }
     $r->print("\n");
 }
+
+# Prints HTML with shortcuts to select groups of parameters in one click, or deselect all.
+# FIXME: remove unused parameters
 #
-# This function offers some links on the parameter section to get with one click a group a parameters
-#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {hash reference} $allparms - hash parameter name -> parameter title (unused)
+# @param {array reference} $pscat - list of selected parameter names (unused)
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank (unused)
 sub shortCuts {
     my ($r,$allparms,$pscat,$keyorder)=@_;
 
@@ -1781,6 +2076,12 @@ sub shortCuts {
     );
 }
 
+# Prints HTML to select parts to view (except for the title).
+# Used by table and overview modes.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {hash reference} $allparts - hash parameter part -> part title
+# @param {array reference} $psprt - list of selected parameter parts
 sub partmenu {
     my ($r,$allparts,$psprt)=@_;
     my $selsize = 1+scalar(keys(%{$allparts}));
@@ -1790,24 +2091,36 @@ sub partmenu {
 
     $r->print('<select multiple="multiple" name="psprt" size="'.$selsize.'">');
     $r->print('<option value="all"');
-    $r->print(' selected="selected"') unless (@{$psprt});
+    $r->print(' selected="selected"') unless (@{$psprt}); # useless, the array is never empty
     $r->print('>'.&mt('All Parts').'</option>');
     my %temphash=();
     foreach (@{$psprt}) { $temphash{$_}=1; }
     foreach my $tempkey (sort {
-    if ($a==$b) { return ($a cmp $b) } else { return ($a <=> $b); }
-    } keys(%{$allparts})) {
-    unless ($tempkey =~ /\./) {
-        $r->print('<option value="'.$tempkey.'"');
-        if ($$psprt[0] eq "all" ||  $temphash{$tempkey}) {
-        $r->print(' selected="selected"');
+                if ($a==$b) { return ($a cmp $b) } else { return ($a <=> $b); }
+            } keys(%{$allparts})) {
+        unless ($tempkey =~ /\./) {
+            $r->print('<option value="'.$tempkey.'"');
+            if ($$psprt[0] eq "all" ||  $temphash{$tempkey}) {
+                $r->print(' selected="selected"');
+            }
+            $r->print('>'.$$allparts{$tempkey}.'</option>');
         }
-        $r->print('>'.$$allparts{$tempkey}.'</option>');
-    }
     }
     $r->print('</select>');
 }
 
+# Prints HTML to select a user and/or a group.
+# Used by table mode.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {string} $uname - selected user name
+# @param {string} $id - selected Student/Employee ID
+# @param {string} $udom - selected user domain
+# @param {string} $csec - selected section name
+# @param {string} $cgroup - selected group name
+# @param {string} $parmlev - parameter level (Resource:'full', Map:'map', Course:'general')
+# @param {array reference} $usersgroups - list of groups the user belongs to, if any
+# @param {string} $pssymb - resource symb (when a single resource is selected)
 sub usermenu {
     my ($r,$uname,$id,$udom,$csec,$cgroup,$parmlev,$usersgroups,$pssymb)=@_;
     my $chooseopt=&Apache::loncommon::select_dom_form($udom,'udom').' '.
@@ -1918,16 +2231,23 @@ function group_or_section(caller) {
                  ,$chooseopt));
 }
 
+# Prints HTML to select parameters from a list of all parameters.
+# Uses parmmenu and parmboxes.
+# Used by table and overview modes.
 #
-# This function shows on table Mode the available Parameters for the selected Resources
-#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {hash reference} $allparms - hash parameter name -> parameter title
+# @param {array reference} $pscat - list of selected parameter names
+# @param {array reference} $psprt - list of selected parameter parts (unused)
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank
+# @param {string} [$divid] - name used to give an id to the HTML element for the scroll box
 sub displaymenu {
     my ($r,$allparms,$pscat,$psprt,$keyorder,$divid)=@_;
 
     $r->print(&Apache::lonhtmlcommon::start_pick_box());
     $r->print(&Apache::lonhtmlcommon::row_title(&mt('Select Parameters to View')));
 
-    &parmmenu($r,$allparms,$pscat,$keyorder);
+    &parmmenu($r,$allparms,$pscat,$keyorder); # only $allparms is used by parmmenu
     $r->print(&Apache::loncommon::start_scrollbox('480px','440px','200px',$divid));
     &parmboxes($r,$allparms,$pscat,$keyorder);
     $r->print(&Apache::loncommon::end_scrollbox());
@@ -1937,6 +2257,14 @@ sub displaymenu {
  
 }
 
+# Prints HTML to select a map.
+# Used by table mode and overview mode.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {hash reference} $allmaps - hash map pc -> map src
+# @param {string} $pschp - selected map pc, or 'all'
+# @param {hash reference} $maptitles - hash map id or src -> map title
+# @param {hash reference} $symbp - hash map pc or resource/map id -> map src.'___(all)' or resource symb
 sub mapmenu {
     my ($r,$allmaps,$pschp,$maptitles,$symbp)=@_;
     my %allmaps_inverted = reverse %$allmaps;
@@ -2088,8 +2416,12 @@ sub mapmenu {
     }
 }
 
-# Build up the select Box to choose if your parameter specification should work for the resource, map/folder or the course level
-# The value of default selection in the select box is set by the value that is given by the argument in $parmlev.
+# Prints HTML to select the parameter level (resource, map/folder or course).
+# Used by table and overview modes.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {hash reference} $alllevs - all parameter levels, hash English title -> value
+# @param {string} $parmlev - selected level value (full|map|general), or ''
 sub levelmenu {
     my ($r,$alllevs,$parmlev)=@_;
 
@@ -2107,6 +2439,11 @@ sub levelmenu {
 }
 
 
+# Returns HTML to select a section (with a select HTML element).
+# Used by overview mode.
+#
+# @param {array reference} $selectedsections - list of selected section ids
+# @returns {string}
 sub sectionmenu {
     my ($selectedsections)=@_;
     my %sectionhash = &Apache::loncommon::get_sections();
@@ -2132,6 +2469,11 @@ sub sectionmenu {
     return $output;
 }
 
+# Returns HTML to select a group (with a select HTML element).
+# Used by overview mode.
+#
+# @param {array reference} $selectedgroups - list of selected group names
+# @returns {string}
 sub groupmenu {
     my ($selectedgroups)=@_;
     my %grouphash;
@@ -2154,37 +2496,66 @@ sub groupmenu {
     return $output;
 }
 
+# Returns an array with the given parameter split by comma.
+# Used by assessparms (table mode).
+#
+# @param {string} $keyp - the string to split
+# @returns {Array<string>}
 sub keysplit {
     my $keyp=shift;
     return (split(/\,/,$keyp));
 }
 
+# Returns the keys in $name, sorted using $keyorder.
+# Parameters are sorted by key, which means they are sorted by part first, then by name.
+# Used by assessparms (table mode) for resource level.
+#
+# @param {hash reference} $name - parameter key -> parameter name
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank
+# @returns {Array<string>}
 sub keysinorder {
     my ($name,$keyorder)=@_;
     return sort {
-    $$keyorder{$a} <=> $$keyorder{$b};
+        $$keyorder{$a} <=> $$keyorder{$b};
     } (keys(%{$name}));
 }
 
+# Returns the keys in $name, sorted using $keyorder to sort parameters by name first, then by part.
+# Used by assessparms (table mode) for map and general levels.
+#
+# @param {hash reference} $name - parameter key -> parameter name
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank
+# @returns {Array<string>}
 sub keysinorder_bytype {
     my ($name,$keyorder)=@_;
     return sort {
-    my $ta=(split('_',$a))[-1];
-    my $tb=(split('_',$b))[-1];
-    if ($$keyorder{'parameter_0_'.$ta} == $$keyorder{'parameter_0_'.$tb}) {
-        return ($a cmp $b);
-    }
-    $$keyorder{'parameter_0_'.$ta} <=> $$keyorder{'parameter_0_'.$tb};
+        my $ta=(split('_',$a))[-1]; # parameter name
+        my $tb=(split('_',$b))[-1];
+        if ($$keyorder{'parameter_0_'.$ta} == $$keyorder{'parameter_0_'.$tb}) {
+            return ($a cmp $b);
+        }
+        $$keyorder{'parameter_0_'.$ta} <=> $$keyorder{'parameter_0_'.$tb};
     } (keys(%{$name}));
 }
 
+# Returns the keys in $name, sorted using $keyorder to sort parameters by name.
+# Used by defaultsetter (parameter settings default actions).
+#
+# @param {hash reference} $name - hash parameter name -> parameter title
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank
+# @returns {Array<string>}
 sub keysindisplayorder {
     my ($name,$keyorder)=@_;
     return sort {
-    $$keyorder{'parameter_0_'.$a} <=> $$keyorder{'parameter_0_'.$b};
+        $$keyorder{'parameter_0_'.$a} <=> $$keyorder{'parameter_0_'.$b};
     } (keys(%{$name}));
 }
 
+# Prints HTML with a choice to sort results by realm or student first.
+# Used by overview mode.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {string} $sortorder - realmstudent|studentrealm
 sub sortmenu {
     my ($r,$sortorder)=@_;
     $r->print('<br /><label><input type="radio" name="sortorder" value="realmstudent"');
@@ -2200,6 +2571,9 @@ sub sortmenu {
           '</label>');
 }
 
+# Returns a hash parameter key -> order (integer) giving the order for some parameters.
+#
+# @returns {hash}
 sub standardkeyorder {
     return ('parameter_0_opendate' => 1,
         'parameter_0_duedate' => 2,
@@ -2222,34 +2596,62 @@ sub standardkeyorder {
         'parameter_0_discussend' => 19,
         'parameter_0_discusshide' => 20,
         'parameter_0_discussvote' => 21,
-	'parameter_0_printstartdate'  =>  22,
-	'parameter_0_printenddate' =>  23);
+        'parameter_0_printstartdate'  =>  22,
+        'parameter_0_printenddate' =>  23);
 }
 
 
+# Table mode UI.
+# If nothing is selected, prints HTML forms to select resources, parts, parameters, user, group and section.
+# Otherwise, prints the parameter table, with a link to change the selection unless a single resource is selected.
+#
+# Parameters used from the request:
+# action - handler action (see handler), usermenu is checking for value 'settable'
+# cgroup - selected group
+# command - 'set': direct access to table mode for a resource
+# csec - selected section
+# dis - set when the "Update Display" button was used, used only to discard command 'set'
+# hideparmsel - can be 'hidden' to hide the parameter selection div initially and display the "Change Parameter Selection" link instead (which displays the div)
+# id - student/employee ID
+# parmlev - selected level (full|map|general)
+# part - selected part (unused ?)
+# pres_marker - &&&-separated parameter identifiers, "resource id&part_parameter name&level"
+# pres_type - &&&-separated parameter types
+# pres_value - &&&-separated parameter values
+# prevvisit - '1' if the user has submitted the form before
+# pscat (multiple values) - selected parameter names
+# pschp - selected map pc, or 'all'
+# psprt (multiple values) - list of selected parameter parts
+# filter - part of or whole parameter name, to be filtered out when parameters are displayed (unused ?)
+# recent_* (* = parameter type) - recent values entered by the user for parameter types
+# symb - resource symb (when a single resource is selected)
+# udom - selected user domain
+# uname - selected user name
+# url - used only with command 'set', the resource url
+#
+# @param {Apache2::RequestRec} $r - the Apache request
 sub assessparms {
 
     my $r=shift;
 
 
-
 # -------------------------------------------------------- Variable declaration
-    my @ids=();
-    my %symbp=();
-    my %mapp=();
-    my %typep=();
-    my %keyp=();
-    my %uris=();
-    my %maptitles=();
-    my %allmaps=();
-    my %alllevs=();
-
-    my $uname;
-    my $udom;
-    my $uhome;
-    my $csec;
-    my $cgroup;
-    my @usersgroups = ();
+    my @ids=(); # resource and map ids
+    my %symbp=(); # hash map pc or resource/map id -> map src.'___(all)' or resource symb
+    my %mapp=(); # hash map pc or resource/map id -> enclosing map src
+    my %typep=(); # hash resource/map id -> resource type (file extension)
+    my %keyp=(); # hash resource/map id -> comma-separated list of parameter keys
+    my %uris=(); # hash resource/map id -> resource src
+    my %maptitles=(); # hash map pc or src -> map title
+    my %allmaps=(); # hash map pc -> map src
+    my %alllevs=(); # hash English level title -> value
+
+    my $uname; # selected user name
+    my $udom; # selected user domain
+    my $uhome; # server with the user's files, or 'no_host'
+    my $csec; # selected section name
+    my $cgroup; # selected group name
+    my @usersgroups = (); # list of the user groups
 
     my $coursename=$env{'course.'.$env{'request.course.id'}.'.description'};
 
@@ -2257,8 +2659,8 @@ sub assessparms {
     $alllevs{'Map/Folder Level'}='map';
     $alllevs{'Course Level'}='general';
 
-    my %allparms;
-    my %allparts;
+    my %allparms; # hash parameter name -> parameter title
+    my %allparts; # hash parameter part -> part title
 # ------------------------------------------------------------------------------
 
 #
@@ -2316,8 +2718,8 @@ sub assessparms {
 
 # ----------------------------------------------- Was this started from grades?
 
-    if (($env{'form.command'} eq 'set') && ($env{'form.url'})
-    && (!$env{'form.dis'})) {
+    if (($env{'form.command'} eq 'set') && ($env{'form.url'}) &&
+            (!$env{'form.dis'})) {
         my $url=$env{'form.url'};
         $url=~s-^http://($ENV{'SERVER_NAME'}|$ENV{'HTTP_HOST'})--;
         $pssymb=&Apache::lonnet::symbread($url);
@@ -2412,13 +2814,16 @@ sub assessparms {
         my $totalstored = 0;
         my $now = time;
         for (my $i=0;$i<=$#markers;$i++) {
-            my ($needsrelease,$needsnewer,$name);
+            my ($needsrelease,$needsnewer,$name,$namematch);
             if (($env{'request.course.sec'} ne '') && ($markers[$i] =~ /\&(9|10|11|12)$/)) {
                 next if ($csec ne $env{'request.course.sec'});
             }
             if ($markers[$i] =~ /\&(8|7|6|5)$/) {
                 next if ($noeditgrp);
-            } 
+            }
+            if ($markers[$i] =~ /\&(17|11|7|3)$/) {
+                $namematch = 'maplevelrecurse';
+            }
             if ($markers[$i] =~ /^[\d.]+\&0_availablestudent\&(1|2|3|4)$/) {
                 my (@ok_slots,@fail_slots,@del_slots);
                 my $courseopt=&Apache::lonnet::get_courseresdata($cnum,$cdom);
@@ -2505,19 +2910,42 @@ sub assessparms {
                     }
                 }
                 $needsrelease =
-                    $Apache::lonnet::needsrelease{"parameter:$name:$val:$valmatch"};
+                    $Apache::lonnet::needsrelease{"parameter:$name:$val:$valmatch:"};
                 if ($needsrelease) {
                     unless ($got_chostname) {
                         ($chostname,$cmajor,$cminor) = &parameter_release_vars();
                         $got_chostname = 1;
                     } 
-                    $needsnewer = &parameter_releasecheck($name,$val,$valmatch,
+                    $needsnewer = &parameter_releasecheck($name,$val,$valmatch,undef,
                                                           $needsrelease,
                                                           $cmajor,$cminor);
                 }
             }
             if ($needsnewer) {
-                $message .= &oldversion_warning($name,$values[$i],$chostname,$cmajor,
+                undef($namematch);
+            } else {
+                my $currneeded;
+                if ($needsrelease) {
+                    $currneeded = $needsrelease;
+                }
+                if ($namematch) {
+                    $needsrelease =
+                        $Apache::lonnet::needsrelease{"parameter::::$namematch"};
+                    if (($needsrelease) && (($currneeded eq '') || ($needsrelease < $currneeded))) {
+                        unless ($got_chostname) {
+                            ($chostname,$cmajor,$cminor) = &parameter_release_vars();
+                            $got_chostname = 1;
+                        }
+                        $needsnewer = &parameter_releasecheck(undef,undef,undef,$namematch,
+                                                              $needsrelease,
+                                                              $cmajor,$cminor);
+                    } else {
+                        undef($namematch);
+                    }
+                }
+            }
+            if ($needsnewer) {
+                $message .= &oldversion_warning($name,$namematch,$values[$i],$chostname,$cmajor,
                                                 $cminor,$needsrelease);
             } else {
                 $message.=&storeparm(split(/\&/,$markers[$i]),
@@ -2536,19 +2964,25 @@ sub assessparms {
         }
     }
 #----------------------------------------------- if all selected, fill in array
-    if ($pscat[0] eq "all") {@pscat = (keys(%allparms));}
-    if (!@pscat) { @pscat=('duedate','opendate','answerdate','weight','maxtries','type','problemstatus') };
-    if ($psprt[0] eq "all" || !@psprt) {@psprt = (keys(%allparts));}
+    if ($pscat[0] eq "all") {
+        @pscat = (keys(%allparms));
+    }
+    if (!@pscat) {
+        @pscat=('duedate','opendate','answerdate','weight','maxtries','type','problemstatus')
+    };
+    if ($psprt[0] eq "all" || !@psprt) {
+        @psprt = (keys(%allparts));
+    }
 # ------------------------------------------------------------------ Start page
 
     my $crstype = &Apache::loncommon::course_type();
     &startpage($r,$pssymb,$crstype);
 
     foreach my $item ('tolerance','date_default','date_start','date_end',
-        'date_interval','int','float','string') {
+            'date_interval','int','float','string') {
         $r->print('<input type="hidden" value="'.
-          &HTML::Entities::encode($env{'form.recent_'.$item},'"&<>').
-          '" name="recent_'.$item.'" />');
+            &HTML::Entities::encode($env{'form.recent_'.$item},'"&<>').
+            '" name="recent_'.$item.'" />');
     }
 
     # ----- Start Parameter Selection
@@ -2558,14 +2992,15 @@ sub assessparms {
 <script type="text/javascript">
 // <![CDATA[
 function parmsel_show() {
-  document.getElementById('parmsel').style.display = "";
-  document.getElementById('parmsellink').style.display = "none";
+    document.getElementById('parmsel').style.display = "";
+    document.getElementById('parmsellink').style.display = "none";
 }
 // ]]>
 </script>
 ENDPARMSELSCRIPT
     
     if (!$pssymb) {
+        # No single resource selected, print forms to select things (hidden after first selection)
         my $parmselhiddenstyle=' style="display:none"';
         if($env{'form.hideparmsel'} eq 'hidden') {
            $r->print('<div id="parmsel"'.$parmselhiddenstyle.'>');
@@ -2666,26 +3101,26 @@ ENDPARMSELSCRIPT
 #
 # This produces the cascading table output of parameters
 #
-               my $coursespan=$csec?10:6;
-               my $userspan=4;
-               if ($cgroup ne '') {
-                  $coursespan += 4;
-               }
-
-               $r->print(&Apache::loncommon::start_data_table());
-#
-# This produces the headers
-#
-               $r->print('<tr><td colspan="5"></td>');
-               $r->print('<th colspan="'.($coursespan).'">'.&mt('Any User').'</th>');
-               if ($uname) {
+            my $coursespan=$csec?10:6;
+            my $userspan=4;
+            if ($cgroup ne '') {
+                $coursespan += 4;
+            }
+
+            $r->print(&Apache::loncommon::start_data_table());
+            #
+            # This produces the headers
+            #
+            $r->print('<tr><td colspan="5"></td>');
+            $r->print('<th colspan="'.($coursespan).'">'.&mt('Any User').'</th>');
+            if ($uname) {
                 if (@usersgroups > 1) {
-                       $userspan ++;
-                   }
-                   $r->print('<th colspan="'.$userspan.'" rowspan="2">');
-                   $r->print(&mt('User [_1] at Domain [_2]',"'".$uname."'","'".$udom."'").'</th>');
-               }
-               my %lt=&Apache::lonlocal::texthash(
+                    $userspan ++;
+                }
+                $r->print('<th colspan="'.$userspan.'" rowspan="2">');
+                $r->print(&mt('User [_1] at Domain [_2]',"'".$uname."'","'".$udom."'").'</th>');
+            }
+            my %lt=&Apache::lonlocal::texthash(
                 'pie'    => "Parameter in Effect",
                 'csv'    => "Current Session Value",
                 'rl'     => "Resource Level",
@@ -2702,59 +3137,59 @@ ENDPARMSELSCRIPT
                 'formfr' => 'for Map or Folder (recursive)',
                 'fr'     => 'for Resource'
             );
-               $r->print(<<ENDTABLETWO);
+            $r->print(<<ENDTABLETWO);
 <th rowspan="3">$lt{'pie'}</th>
 <th rowspan="3">$lt{'csv'}<br />($csuname:$csudom)</th>
 </tr><tr><td colspan="5"></td><th colspan="3">$lt{'ic'}</th><th colspan="2">$lt{'rl'}</th>
 <th colspan="1">$lt{'ic'}</th>
 
 ENDTABLETWO
-               if ($csec) {
-                   $r->print('<th colspan="4">'.
-                  &mt("in Section")." $csec</th>");
-               }
-               if ($cgroup) {
+            if ($csec) {
+                $r->print('<th colspan="4">'.
+                &mt("in Section")." $csec</th>");
+            }
+            if ($cgroup) {
                 $r->print('<th colspan="4">'.
                 &mt("in Group")." $cgroup</th>");
-               }
-               $r->print(<<ENDTABLEHEADFOUR);
+            }
+            $r->print(<<ENDTABLEHEADFOUR);
 </tr><tr><th>$lt{'aut'}</th><th>$lt{'type'}</th>
 <th>$lt{'emof'}</th><th>$lt{'part'}</th><th>$lt{'pn'}</th>
 <th>$lt{'gen'}</th><th>$lt{'formfr'}</th><th>$lt{'foremf'}</th>
 <th>$lt{'def'}</th><th>$lt{'femof'}</th><th>$lt{'fr'}</th>
 ENDTABLEHEADFOUR
 
-               if ($csec) {
-                   $r->print('<th>'.$lt{'gen'}.'</th><th>'.$lt{'formfr'}.'</th><th>'.$lt{'foremf'}.'</th><th>'.$lt{'fr'}.'</th>');
-               }
-
-               if ($cgroup) {
-                   $r->print('<th>'.$lt{'gen'}.'</th><th>'.$lt{'formfr'}.'</th><th>'.&mt('foremf').'</th><th>'.$lt{'fr'}.'</th>');
-               }
-
-               if ($uname) {
-                    if (@usersgroups > 1) {
-                        $r->print('<th>'.&mt('Control by other group?').'</th>');
-                   }
-                   $r->print('<th>'.$lt{'gen'}.'</th><th>'.$lt{'formfr'}.'</th><th>'.$lt{'foremf'}.'</th><th>'.$lt{'fr'}.'</th>');
-               }
+            if ($csec) {
+                $r->print('<th>'.$lt{'gen'}.'</th><th>'.$lt{'formfr'}.'</th><th>'.$lt{'foremf'}.'</th><th>'.$lt{'fr'}.'</th>');
+            }
+
+            if ($cgroup) {
+                $r->print('<th>'.$lt{'gen'}.'</th><th>'.$lt{'formfr'}.'</th><th>'.&mt('foremf').'</th><th>'.$lt{'fr'}.'</th>');
+            }
+
+            if ($uname) {
+                if (@usersgroups > 1) {
+                    $r->print('<th>'.&mt('Control by other group?').'</th>');
+                }
+                $r->print('<th>'.$lt{'gen'}.'</th><th>'.$lt{'formfr'}.'</th><th>'.$lt{'foremf'}.'</th><th>'.$lt{'fr'}.'</th>');
+            }
 
-               $r->print('</tr>');
+            $r->print('</tr>');
 #
 # Done with the headers
 # 
-               my $defbgone='';
-               my $defbgtwo='';
-               my $defbgthree = '';
+            my $defbgone='';
+            my $defbgtwo='';
+            my $defbgthree = '';
 
-               foreach my $rid (@ids) {
+            foreach my $rid (@ids) {
 
                 my ($inmapid)=($rid=~/\.(\d+)$/);
 
                 if ((!$pssymb &&
-                 (($pschp eq 'all') || ($allmaps{$pschp} eq $mapp{$rid})))
-                ||
-                ($pssymb && $pssymb eq $symbp{$rid})) {
+                        (($pschp eq 'all') || ($allmaps{$pschp} eq $mapp{$rid})))
+                        ||
+                        ($pssymb && $pssymb eq $symbp{$rid})) {
 # ------------------------------------------------------ Entry for one resource
                     if ($defbgone eq '#E0E099') {
                         $defbgone='#E0E0DD';
@@ -2784,34 +3219,34 @@ ENDTABLEHEADFOUR
                     my $filter=$env{'form.filter'};
                     foreach my $tempkeyp (&keysplit($keyp{$rid})) {
                         if (grep $_ eq $tempkeyp, @catmarker) {
-                          my $parmname=&Apache::lonnet::metadata($uri,$tempkeyp.'.name');
-# We may only want certain parameters listed
-                          if ($filter) {
-                             unless ($filter=~/\Q$parmname\E/) { next; }
-                          }
-                          $name{$tempkeyp}=$parmname;
-                          $part{$tempkeyp}=&Apache::lonnet::metadata($uri,$tempkeyp.'.part');
-
-                          my $parmdis=&Apache::lonnet::metadata($uri,$tempkeyp.'.display');
-                          if ($allparms{$name{$tempkeyp}} ne '') {
-                              my $identifier;
-                              if ($parmdis =~ /(\s*\[Part.*)$/) {
-                                  $identifier = $1;
-                              }
-                              $display{$tempkeyp} = $allparms{$name{$tempkeyp}}.$identifier;
-                          } else {
-                              $display{$tempkeyp} = $parmdis;
-                          }
-                          unless ($display{$tempkeyp}) { $display{$tempkeyp}=''; }
-                          $display{$tempkeyp}.=' ('.$name{$tempkeyp}.')';
-                          $default{$tempkeyp}=&Apache::lonnet::metadata($uri,$tempkeyp);
-                          $type{$tempkeyp}=&Apache::lonnet::metadata($uri,$tempkeyp.'.type');
-                          $thistitle=&Apache::lonnet::metadata($uri,$tempkeyp.'.title');
+                            my $parmname=&Apache::lonnet::metadata($uri,$tempkeyp.'.name');
+    # We may only want certain parameters listed
+                            if ($filter) {
+                                unless ($filter=~/\Q$parmname\E/) { next; }
+                            }
+                            $name{$tempkeyp}=$parmname;
+                            $part{$tempkeyp}=&Apache::lonnet::metadata($uri,$tempkeyp.'.part');
+
+                            my $parmdis=&Apache::lonnet::metadata($uri,$tempkeyp.'.display');
+                            if ($allparms{$name{$tempkeyp}} ne '') {
+                                my $identifier;
+                                if ($parmdis =~ /(\s*\[Part.*)$/) {
+                                    $identifier = $1;
+                                }
+                                $display{$tempkeyp} = $allparms{$name{$tempkeyp}}.$identifier;
+                            } else {
+                                $display{$tempkeyp} = $parmdis;
+                            }
+                            unless ($display{$tempkeyp}) { $display{$tempkeyp}=''; }
+                            $display{$tempkeyp}.=' ('.$name{$tempkeyp}.')';
+                            $default{$tempkeyp}=&Apache::lonnet::metadata($uri,$tempkeyp);
+                            $type{$tempkeyp}=&Apache::lonnet::metadata($uri,$tempkeyp.'.type');
+                            $thistitle=&Apache::lonnet::metadata($uri,$tempkeyp.'.title');
                         }
                     }
                     my $totalparms=scalar(keys(%name));
                     if ($totalparms>0) {
-                           my $firstrow=1;
+                        my $firstrow=1;
                         my $title=&Apache::lonnet::gettitle($symbp{$rid});
                         $r->print('<tr><td style="background-color:'.$defbgone.';"'.
                              ' rowspan='.$totalparms.
@@ -2868,7 +3303,7 @@ ENDTABLEHEADFOUR
 
 #-------------------------------------------- for each map, gather information
             my $mapid;
-               foreach $mapid (sort {$maplist{$a} cmp $maplist{$b}} keys(%maplist)) {
+            foreach $mapid (sort {$maplist{$a} cmp $maplist{$b}} keys(%maplist)) {
                 my $maptitle = $maplist{$mapid};
 
 #-----------------------  loop through ids and get all parameter types for map
@@ -2888,7 +3323,7 @@ ENDTABLEHEADFOUR
 
 #                  $r->print("$mapid:$map:   $rid <br /> \n");
 
-                     if ($map eq $mapid) {
+                    if ($map eq $mapid) {
                         my $uri=&Apache::lonnet::declutter($uris{$rid});
 #                    $r->print("Keys: $keyp{$rid} <br />\n");
 
@@ -2923,7 +3358,7 @@ ENDTABLEHEADFOUR
                                 $type{$tempkeyp}=&Apache::lonnet::metadata($uri,$fullkeyp.'.type');
                               }
                         } # end loop through keys
-                      }
+                    }
                 } # end loop through ids
 
 #---------------------------------------------------- print header information
@@ -3023,7 +3458,7 @@ ENDTABLEHEADFOUR
                         $display{$tempkeyp} =~ s/_\w+_/_0_/;
                         $default{$tempkeyp}=&Apache::lonnet::metadata($uri,$fullkeyp);
                         $type{$tempkeyp}=&Apache::lonnet::metadata($uri,$fullkeyp.'.type');
-                      }
+                    }
                 } # end loop through keys
             } # end loop through ids
 
@@ -3070,11 +3505,17 @@ ENDMAPONE
     $r->print(&Apache::loncommon::end_page());
 } # end sub assessparms
 
+
+
 ##################################################
-# Overview mode
+# OVERVIEW MODE
 ##################################################
-my $tableopen;
 
+my $tableopen; # boolean, true if HTML table is already opened
+
+# Returns HTML with the HTML table start tag and header, unless the table is already opened.
+# @param {boolean} $readonly - true if values cannot be edited (otherwise more columns are added)
+# @returns {string}
 sub tablestart {
     my ($readonly) = @_;
     if ($tableopen) {
@@ -3092,15 +3533,24 @@ sub tablestart {
     }
 }
 
+# Returns HTML with the HTML table end tag, unless the table is not opened.
+# @returns {string}
 sub tableend {
     if ($tableopen) {
-    $tableopen=0;
-    return &Apache::loncommon::end_data_table();
+        $tableopen=0;
+        return &Apache::loncommon::end_data_table();
     } else {
-    return'';
+        return'';
     }
 }
 
+# Reads course and user information.
+# If the context is looking for a scalar, returns the course parameters hash (result of lonnet::get_courseresdata, dump of course's resourcedata.db) with added student data from lonnet::get_userresdata (which reads the user's resourcedata.db).
+# The key for student data is modified with '[useropt:'.username.':'.userdomain.'].'.
+# If the context is looking for a list, returns a list with the scalar data and the class list.
+# @param {string} $crs - course number
+# @param {string} $dom - course domain
+# @returns {hash reference|Array}
 sub readdata {
     my ($crs,$dom)=@_;
 # Read coursedata
@@ -3129,8 +3579,24 @@ sub readdata {
 }
 
 
-# Setting
-
+# Stores parameter data, using form parameters directly.
+#
+# Uses the following form parameters. The variable part in the names is a resourcedata key (except for a modification for user data).
+# set_* (except settext, setipallow, setipdeny) - set a parameter value
+# del_* - remove a parameter
+# datepointer_* - set a date parameter (value is key_* refering to a set of other form parameters)
+# dateinterval_* - set a date interval parameter (value refers to more form parameters)
+# key_* - date values
+# days_* - for date intervals
+# hours_* - for date intervals
+# minutes_* - for date intervals
+# seconds_* - for date intervals
+# done_* - for date intervals
+# typeof_* - parameter type
+# 
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {string} $crs - course number
+# @param {string} $dom - course domain
 sub storedata {
     my ($r,$crs,$dom)=@_;
 # Set userlevel immediately
@@ -3142,183 +3608,220 @@ sub storedata {
     undef @deldata;
     my ($got_chostname,$chostname,$cmajor,$cminor);
     my $now = time;
-    foreach my $key (keys(%env)) { 
-    if ($key =~ /^form\.([a-z]+)\_(.+)$/) {
-        my $cmd=$1;
-        my $thiskey=$2;
-        next if ($cmd eq 'settext' || $cmd eq 'setipallow' || $cmd eq 'setipdeny');
-        my ($tuname,$tudom)=&extractuser($thiskey);
-        my $tkey=$thiskey;
+    foreach my $key (keys(%env)) {
+        if ($key =~ /^form\.([a-z]+)\_(.+)$/) {
+            my $cmd=$1;
+            my $thiskey=$2;
+            next if ($cmd eq 'settext' || $cmd eq 'setipallow' || $cmd eq 'setipdeny');
+            my ($tuname,$tudom)=&extractuser($thiskey);
+            my $tkey=$thiskey;
             if ($tuname) {
-        $tkey=~s/\.\[useropt\:$tuname\:$tudom\]\./\./;
-        }
-        if ($cmd eq 'set' || $cmd eq 'datepointer' || $cmd eq 'dateinterval') {
-        my ($data, $typeof, $text, $name, $valchk, $valmatch);
-        if ($cmd eq 'set') {
-            $data=$env{$key};
-            $valmatch = '';
-            $valchk = $data;
-            $typeof=$env{'form.typeof_'.$thiskey};
-            $text = &mt('Saved modified parameter for');
-            if ($typeof eq 'string_questiontype') {
-                $name = 'type';
-            } elsif ($typeof eq 'string_lenient') {
-                $name = 'lenient';
-                my $stringmatch = &standard_string_matches($typeof);
-                if (ref($stringmatch) eq 'ARRAY') {
-                    foreach my $item (@{$stringmatch}) {
-                        if (ref($item) eq 'ARRAY') {
-                            my ($regexpname,$pattern) = @{$item};
-                            if ($pattern ne '') {
-                                if ($data =~ /$pattern/) {
-                                    $valmatch = $regexpname;
-                                    $valchk = '';
-                                    last;
+                $tkey=~s/\.\[useropt\:$tuname\:$tudom\]\./\./;
+            }
+            if ($cmd eq 'set' || $cmd eq 'datepointer' || $cmd eq 'dateinterval') {
+                my ($data, $typeof, $text, $name, $valchk, $valmatch, $namematch);
+                if ($cmd eq 'set') {
+                    $data=$env{$key};
+                    $valmatch = '';
+                    $valchk = $data;
+                    $typeof=$env{'form.typeof_'.$thiskey};
+                    $text = &mt('Saved modified parameter for');
+                    if ($typeof eq 'string_questiontype') {
+                        $name = 'type';
+                    } elsif ($typeof eq 'string_lenient') {
+                        $name = 'lenient';
+                        my $stringmatch = &standard_string_matches($typeof);
+                        if (ref($stringmatch) eq 'ARRAY') {
+                            foreach my $item (@{$stringmatch}) {
+                                if (ref($item) eq 'ARRAY') {
+                                    my ($regexpname,$pattern) = @{$item};
+                                    if ($pattern ne '') {
+                                        if ($data =~ /$pattern/) {
+                                            $valmatch = $regexpname;
+                                            $valchk = '';
+                                            last;
+                                        }
+                                    }
                                 }
                             }
                         }
+                    } elsif ($typeof eq 'string_discussvote') {
+                        $name = 'discussvote';
+                    } elsif ($typeof eq 'string_examcode') {
+                        $name = 'examcode';
+                        if (&Apache::lonnet::validCODE($data)) {
+                            $valchk = 'valid';
+                        }
+                    } elsif ($typeof eq 'string_yesno') {
+                        if ($thiskey =~ /\.retrypartial$/) {
+                            $name = 'retrypartial';
+                        }
                     }
-                }
-            } elsif ($typeof eq 'string_discussvote') {
-                $name = 'discussvote';
-            } elsif ($typeof eq 'string_examcode') {
-                $name = 'examcode';
-                if (&Apache::lonnet::validCODE($data)) {
-                    $valchk = 'valid';
-                }
-            } elsif ($typeof eq 'string_yesno') {
-                if ($thiskey =~ /\.retrypartial$/) {
-                    $name = 'retrypartial';
-                }
-            }
-        } elsif ($cmd eq 'datepointer') {
-            $data=&Apache::lonhtmlcommon::get_date_from_form($env{$key});
-            $typeof=$env{'form.typeof_'.$thiskey};
-            $text = &mt('Saved modified date for');
-            if ($typeof eq 'date_start') {
-                if ($thiskey =~ /\.printstartdate$/) {
-                    $name = 'printstartdate';
-                    if (($data) && ($data > $now)) {
-                        $valchk = 'future';
-                    }
-                }
-            } elsif ($typeof eq 'date_end') {
-                if ($thiskey =~ /\.printenddate$/) {
-                    $name = 'printenddate';
-                    if (($data) && ($data < $now)) {
-                        $valchk = 'past';
+                } elsif ($cmd eq 'datepointer') {
+                    $data=&Apache::lonhtmlcommon::get_date_from_form($env{$key});
+                    $typeof=$env{'form.typeof_'.$thiskey};
+                    $text = &mt('Saved modified date for');
+                    if ($typeof eq 'date_start') {
+                        if ($thiskey =~ /\.printstartdate$/) {
+                            $name = 'printstartdate';
+                            if (($data) && ($data > $now)) {
+                                $valchk = 'future';
+                            }
+                        }
+                    } elsif ($typeof eq 'date_end') {
+                        if ($thiskey =~ /\.printenddate$/) {
+                            $name = 'printenddate';
+                            if (($data) && ($data < $now)) {
+                                $valchk = 'past';
+                            }
+                        }
                     }
+                } elsif ($cmd eq 'dateinterval') {
+                    $data=&get_date_interval_from_form($thiskey);
+                    if ($thiskey =~ /\.interval$/) {
+                        $name = 'interval';
+                        my $intervaltype = &get_intervaltype($name);
+                        my $intervalmatch = &standard_interval_matches($intervaltype);
+                        if (ref($intervalmatch) eq 'ARRAY') {
+                            foreach my $item (@{$intervalmatch}) {
+                                if (ref($item) eq 'ARRAY') {
+                                    my ($regexpname,$pattern) = @{$item};
+                                    if ($pattern ne '') {
+                                        if ($data =~ /$pattern/) {
+                                            $valmatch = $regexpname;
+                                            $valchk = '';
+                                            last;
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    $typeof=$env{'form.typeof_'.$thiskey};
+                    $text = &mt('Saved modified date for');
                 }
-            }
-        } elsif ($cmd eq 'dateinterval') {
-            $data=&get_date_interval_from_form($thiskey);
-            if ($thiskey =~ /\.interval$/) {
-                $name = 'interval';
-                my $intervaltype = &get_intervaltype($name);
-                my $intervalmatch = &standard_interval_matches($intervaltype);
-                if (ref($intervalmatch) eq 'ARRAY') {
-                    foreach my $item (@{$intervalmatch}) {
-                        if (ref($item) eq 'ARRAY') {
-                            my ($regexpname,$pattern) = @{$item};
-                            if ($pattern ne '') {
-                                if ($data =~ /$pattern/) {
-                                    $valmatch = $regexpname;
-                                    $valchk = '';
-                                    last;
+                if ($thiskey =~ m{\.(?:sequence|page)___\(rec\)}) {
+                    $namematch = 'maplevelrecurse';
+                }
+                if (($name ne '') || ($namematch ne '')) {
+                    my ($needsrelease,$needsnewer);
+                    if ($name ne '') {
+                        $needsrelease = $Apache::lonnet::needsrelease{"parameter:$name:$valchk:$valmatch:"};
+                        if ($needsrelease) {
+                            unless ($got_chostname) {
+                                ($chostname,$cmajor,$cminor)=&parameter_release_vars();
+                                $got_chostname = 1;
+                            }
+                            $needsnewer = &parameter_releasecheck($name,$valchk,$valmatch,undef,
+                                                                $needsrelease,
+                                                                $cmajor,$cminor);
+                        }
+                    }
+                    if ($namematch ne '') {
+                        if ($needsnewer) {
+                            undef($namematch);
+                        } else {
+                            my $currneeded;
+                            if ($needsrelease) {
+                                $currneeded = $needsrelease;
+                            }
+                            $needsrelease =
+                                $Apache::lonnet::needsrelease{"parameter::::$namematch"};
+                            if (($needsrelease) &&
+                                    (($currneeded eq '') || ($needsrelease < $currneeded))) {
+                                unless ($got_chostname) {
+                                    ($chostname,$cmajor,$cminor) = &parameter_release_vars();
+                                    $got_chostname = 1;
                                 }
+                                $needsnewer = &parameter_releasecheck(undef,$valchk,$valmatch,
+                                    $namematch, $needsrelease,$cmajor,$cminor);
+                            } else {
+                                undef($namematch);
                             }
                         }
                     }
+                    if ($needsnewer) {
+                        $r->print('<br />'.&oldversion_warning($name,$namematch,$data,
+                                                            $chostname,$cmajor,
+                                                            $cminor,$needsrelease));
+                        next;
+                    }
                 }
-            }
-            $typeof=$env{'form.typeof_'.$thiskey};
-            $text = &mt('Saved modified date for');
-        }
-        if ($name ne '') {
-            my ($needsrelease,$needsnewer);
-            $needsrelease = $Apache::lonnet::needsrelease{"parameter:$name:$valchk:$valmatch"};
-            if ($needsrelease) {
-                unless ($got_chostname) {
-                    ($chostname,$cmajor,$cminor)=&parameter_release_vars();
-                    $got_chostname = 1;
+                if (defined($data) and $$olddata{$thiskey} ne $data) {
+                    if ($tuname) {
+                        if (&Apache::lonnet::put('resourcedata',{$tkey=>$data,
+                                            $tkey.'.type' => $typeof},
+                                    $tudom,$tuname) eq 'ok') {
+                            &log_parmset({$tkey=>$data,$tkey.'.type' => $typeof},0,$tuname,$tudom);
+                            $r->print('<br />'.$text.' '.
+                                &Apache::loncommon::plainname($tuname,$tudom));
+                        } else {
+                            $r->print('<div class="LC_error">'.
+                                &mt('Error saving parameters').'</div>');
+                        }
+                        &Apache::lonnet::devalidateuserresdata($tuname,$tudom);
+                    } else {
+                        $newdata{$thiskey}=$data;
+                        $newdata{$thiskey.'.type'}=$typeof;
+                    }
                 }
-                $needsnewer = &parameter_releasecheck($name,$valchk,$valmatch,
-                                                      $needsrelease,
-                                                      $cmajor,$cminor);
-                if ($needsnewer) {
-                    $r->print('<br />'.&oldversion_warning($name,$data,
-                                                           $chostname,$cmajor,
-                                                           $cminor,$needsrelease));
-                    next;
+            } elsif ($cmd eq 'del') {
+                if ($tuname) {
+                    if (&Apache::lonnet::del('resourcedata',[$tkey],$tudom,$tuname) eq 'ok') {
+                            &log_parmset({$tkey=>''},1,$tuname,$tudom);
+                        $r->print('<br />'.&mt('Deleted parameter for').' '.&Apache::loncommon::plainname($tuname,$tudom));
+                    } else {
+                        $r->print('<div class="LC_error">'.
+                            &mt('Error deleting parameters').'</div>');
+                    }
+                    &Apache::lonnet::devalidateuserresdata($tuname,$tudom);
+                } else {
+                    push (@deldata,$thiskey,$thiskey.'.type');
                 }
             }
         }
-        if (defined($data) and $$olddata{$thiskey} ne $data) {
-            if ($tuname) {
-            if (&Apache::lonnet::put('resourcedata',{$tkey=>$data,
-                                 $tkey.'.type' => $typeof},
-                         $tudom,$tuname) eq 'ok') {
-                &log_parmset({$tkey=>$data,$tkey.'.type' => $typeof},0,$tuname,$tudom);
-                $r->print('<br />'.$text.' '.
-                      &Apache::loncommon::plainname($tuname,$tudom));
-            } else {
-                $r->print('<div class="LC_error">'.
-                      &mt('Error saving parameters').'</div>');
-            }
-            &Apache::lonnet::devalidateuserresdata($tuname,$tudom);
-            } else {
-            $newdata{$thiskey}=$data;
-             $newdata{$thiskey.'.type'}=$typeof;
-                   }
-        }
-        } elsif ($cmd eq 'del') {
-        if ($tuname) {
-            if (&Apache::lonnet::del('resourcedata',[$tkey],$tudom,$tuname) eq 'ok') {
-                &log_parmset({$tkey=>''},1,$tuname,$tudom);
-            $r->print('<br />'.&mt('Deleted parameter for').' '.&Apache::loncommon::plainname($tuname,$tudom));
-            } else {
-            $r->print('<div class="LC_error">'.
-                  &mt('Error deleting parameters').'</div>');
-            }
-            &Apache::lonnet::devalidateuserresdata($tuname,$tudom);
-        } else {
-            push (@deldata,$thiskey,$thiskey.'.type');
-        }
-        }
-    }
     }
 # Store all course level
     my $delentries=$#deldata+1;
     my @newdatakeys=keys(%newdata);
     my $putentries=$#newdatakeys+1;
     if ($delentries) {
-    if (&Apache::lonnet::del('resourcedata',\@deldata,$dom,$crs) eq 'ok') {
-        my %loghash=map { $_ => '' } @deldata;
-        &log_parmset(\%loghash,1);
-        $r->print('<h2>'.&mt('Deleted [quant,_1,parameter]',$delentries/2).'</h2>');
-    } else {
-        $r->print('<div class="LC_error">'.
-              &mt('Error deleting parameters').'</div>');
-    }
-    &Apache::lonnet::devalidatecourseresdata($crs,$dom);
+        if (&Apache::lonnet::del('resourcedata',\@deldata,$dom,$crs) eq 'ok') {
+            my %loghash=map { $_ => '' } @deldata;
+            &log_parmset(\%loghash,1);
+            $r->print('<h2>'.&mt('Deleted [quant,_1,parameter]',$delentries/2).'</h2>');
+        } else {
+            $r->print('<div class="LC_error">'.
+                &mt('Error deleting parameters').'</div>');
+        }
+        &Apache::lonnet::devalidatecourseresdata($crs,$dom);
     }
     if ($putentries) {
-    if (&Apache::lonnet::put('resourcedata',\%newdata,$dom,$crs) eq 'ok') {
-                &log_parmset(\%newdata,0);
-        $r->print('<h3>'.&mt('Saved [quant,_1,parameter]',$putentries/2).'</h3>');
-    } else {
-        $r->print('<div class="LC_error">'.
-              &mt('Error saving parameters').'</div>');
-    }
-    &Apache::lonnet::devalidatecourseresdata($crs,$dom);
+        if (&Apache::lonnet::put('resourcedata',\%newdata,$dom,$crs) eq 'ok') {
+                    &log_parmset(\%newdata,0);
+            $r->print('<h3>'.&mt('Saved [quant,_1,parameter]',$putentries/2).'</h3>');
+        } else {
+            $r->print('<div class="LC_error">'.
+                &mt('Error saving parameters').'</div>');
+        }
+        &Apache::lonnet::devalidatecourseresdata($crs,$dom);
     }
 }
 
+# Returns the username and domain from a key created in readdata from a resourcedata key.
+#
+# @param {string} $key - the key
+# @returns {Array}
 sub extractuser {
     my $key=shift;
     return ($key=~/^$env{'request.course.id'}.\[useropt\:($match_username)\:($match_domain)\]\./);
 }
 
+# Parses a parameter key and returns the components.
+#
+# @param {string} $key - 
+# @param {hash reference} $listdata - 
+# @return {Array} - (student, resource, part, parameter)
 sub parse_listdata_key {
     my ($key,$listdata) = @_;
     # split into student/section affected, and
@@ -3327,11 +3830,11 @@ sub parse_listdata_key {
     ($key=~/^\Q$env{'request.course.id'}\E\.\[([^\.]+)\]\.(.+)$/);
     # if course wide student would be undefined
     if (!defined($student)) {
-    ($realm)=($key=~/^\Q$env{'request.course.id'}\E\.(.+)$/);
+        ($realm)=($key=~/^\Q$env{'request.course.id'}\E\.(.+)$/);
     }
     # strip off the .type if it's not the Question type parameter
     if ($realm=~/\.type$/ && !exists($listdata->{$key.'.type'})) {
-    $realm=~s/\.type//;
+        $realm=~s/\.type//;
     }
     # split into resource+part and parameter name
     my ($res,    $parm) = ($realm=~/^(.*)\.(.*)$/);
@@ -3339,6 +3842,15 @@ sub parse_listdata_key {
     return ($student,$res,$part,$parm);
 }
 
+# Prints HTML with forms for the given parameter data in overview mode (newoverview or overview).
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {hash reference} $resourcedata - parameter data returned by readdata
+# @param {hash reference} $listdata - data created in secgroup_lister, course id.[section id].part.name -> 1 or course id.[section id].part.name.type -> parameter type
+# @param {string} $sortorder - realmstudent|studentrealm
+# @param {string} $caller - name of the calling sub (overview|newoverview)
+# @param {hash reference} $classlist - from loncoursedata::get_classlist
+# @returns{integer} - number of $listdata parameters processed
 sub listdata {
     my ($r,$resourcedata,$listdata,$sortorder,$caller,$classlist)=@_;
     
@@ -3363,180 +3875,190 @@ sub listdata {
     }
 
     foreach my $thiskey (sort {
-    my ($astudent,$ares,$apart,$aparm) = &parse_listdata_key($a,$listdata);
-    my ($bstudent,$bres,$bpart,$bparm) = &parse_listdata_key($b,$listdata);
+        my ($astudent,$ares,$apart,$aparm) = &parse_listdata_key($a,$listdata);
+        my ($bstudent,$bres,$bpart,$bparm) = &parse_listdata_key($b,$listdata);
 
-    # get the numerical order for the param
-    $aparm=$keyorder{'parameter_0_'.$aparm};
-    $bparm=$keyorder{'parameter_0_'.$bparm};
+        # get the numerical order for the param
+        $aparm=$keyorder{'parameter_0_'.$aparm};
+        $bparm=$keyorder{'parameter_0_'.$bparm};
 
-    my $result=0;
+        my $result=0;
 
-    if ($sortorder eq 'realmstudent') {
+        if ($sortorder eq 'realmstudent') {
             if ($ares     ne $bres    ) {
-        $result = ($ares     cmp $bres);
+                $result = ($ares     cmp $bres);
             } elsif ($astudent ne $bstudent) {
-        $result = ($astudent cmp $bstudent);
-        } elsif ($apart    ne $bpart   ) {
-        $result = ($apart    cmp $bpart);
-        }
-    } else {
-        if      ($astudent ne $bstudent) {
-        $result = ($astudent cmp $bstudent);
-        } elsif ($ares     ne $bres    ) {
-        $result = ($ares     cmp $bres);
-        } elsif ($apart    ne $bpart   ) {
-        $result = ($apart    cmp $bpart);
+                $result = ($astudent cmp $bstudent);
+            } elsif ($apart    ne $bpart   ) {
+                $result = ($apart    cmp $bpart);
+            }
+        } else {
+            if      ($astudent ne $bstudent) {
+                $result = ($astudent cmp $bstudent);
+            } elsif ($ares     ne $bres    ) {
+                $result = ($ares     cmp $bres);
+            } elsif ($apart    ne $bpart   ) {
+                $result = ($apart    cmp $bpart);
+            }
         }
-    }
 
-    if (!$result) {
+        if (!$result) {
             if (defined($aparm) && defined($bparm)) {
-        $result = ($aparm <=> $bparm);
+                $result = ($aparm <=> $bparm);
             } elsif (defined($aparm)) {
-        $result = -1;
+                $result = -1;
             } elsif (defined($bparm)) {
-        $result = 1;
+                $result = 1;
+            }
         }
-    }
 
-    $result;
-    } keys(%{$listdata})) {
+        $result;
+        
+    } keys(%{$listdata})) { # foreach my $thiskey
 
-    my $readonly;
-    if ($$listdata{$thiskey.'.type'}) {
-        my $thistype=$$listdata{$thiskey.'.type'};
-        if ($$resourcedata{$thiskey.'.type'}) {
-            $thistype=$$resourcedata{$thiskey.'.type'};
-        }
-        my ($middle,$part,$name)=
-        ($thiskey=~/^$env{'request.course.id'}\.(?:(.+)\.)*([\w\s]+)\.(\w+)$/);
-        my $section=&mt('All Students');
-        if ($middle=~/^\[(.*)\]/) {
-            my $issection=$1;
-            if ($issection=~/^useropt\:($match_username)\:($match_domain)/) {
-                my ($stuname,$studom) = ($1,$2);
-                if (($env{'request.course.sec'} ne '') && ($caller eq 'overview')) {
-                    if (ref($classlist) eq 'HASH') {
-                        if (ref($classlist->{$stuname.':'.$studom}) eq 'ARRAY') {
-                            next unless ($classlist->{$stuname.':'.$studom}->[$secidx] eq $env{'request.course.sec'}); 
+        my $readonly;
+        if ($$listdata{$thiskey.'.type'}) {
+            my $thistype=$$listdata{$thiskey.'.type'};
+            if ($$resourcedata{$thiskey.'.type'}) {
+                $thistype=$$resourcedata{$thiskey.'.type'};
+            }
+            my ($middle,$part,$name)=
+                ($thiskey=~/^$env{'request.course.id'}\.(?:(.+)\.)*([\w\s]+)\.(\w+)$/);
+            my $section=&mt('All Students');
+            if ($middle=~/^\[(.*)\]/) {
+                my $issection=$1;
+                if ($issection=~/^useropt\:($match_username)\:($match_domain)/) {
+                    my ($stuname,$studom) = ($1,$2);
+                    if (($env{'request.course.sec'} ne '') && ($caller eq 'overview')) {
+                        if (ref($classlist) eq 'HASH') {
+                            if (ref($classlist->{$stuname.':'.$studom}) eq 'ARRAY') {
+                                next unless ($classlist->{$stuname.':'.$studom}->[$secidx] eq $env{'request.course.sec'}); 
+                            }
                         }
                     }
-                }
-                $section=&mt('User').": ".&Apache::loncommon::plainname($stuname,$studom);
-            } else {
-                if (($env{'request.course.sec'} ne '') && ($caller eq 'overview')) {
-                    if (exists($grouphash{$issection})) {
-                        $section=&mt('Group').': '.$issection;
-                    } elsif ($issection eq $env{'request.course.sec'}) {
-                        $section = &mt('Section').': '.$issection;
+                    $section=&mt('User').": ".&Apache::loncommon::plainname($stuname,$studom);
+                } else {
+                    if (($env{'request.course.sec'} ne '') && ($caller eq 'overview')) {
+                        if (exists($grouphash{$issection})) {
+                            $section=&mt('Group').': '.$issection;
+                        } elsif ($issection eq $env{'request.course.sec'}) {
+                            $section = &mt('Section').': '.$issection;
+                        } else {
+                            next; 
+                        }
                     } else {
-                        next; 
+                        $section=&mt('Group/Section').': '.$issection;
                     }
-                } else {
-                    $section=&mt('Group/Section').': '.$issection;
+                }
+                $middle=~s/^\[(.*)\]//;
+            } elsif (($env{'request.course.sec'} ne '') && ($caller eq 'overview')) {
+                $readonly = 1;
+            }
+            $middle=~s/\.+$//;
+            $middle=~s/^\.+//;
+            my $realm='<span class="LC_parm_scope_all">'.&mt('All Resources').'</span>';
+            if ($middle=~/^(.+)\_\_\_\((all|rec)\)$/) {
+                my $mapurl = $1;
+                my $maplevel = $2;
+                my $leveltitle = &mt('Folder/Map');
+                if ($maplevel eq 'rec') {
+                    $leveltitle = &mt('Recursive');
+                }
+                $realm='<span class="LC_parm_scope_folder">'.$leveltitle.': '.&Apache::lonnet::gettitle($mapurl).' <br /><span class="LC_parm_folder">('.$mapurl.')</span></span>';
+            } elsif ($middle) {
+                my ($map,$id,$url)=&Apache::lonnet::decode_symb($middle);
+                $realm='<span class="LC_parm_scope_resource">'.&mt('Resource').
+                    ': '.&Apache::lonnet::gettitle($middle).
+                    ' <br /><span class="LC_parm_symb">('.$url.' in '.$map.' id: '.
+                    $id.')</span></span>';
+            }
+            if ($sortorder eq 'realmstudent') {
+                if ($realm ne $oldrealm) {
+                    $r->print(&tableend()."\n<hr /><h1>$realm</h1>");
+                    $oldrealm=$realm;
+                    $oldsection='';
+                }
+                if ($section ne $oldsection) {
+                    $r->print(&tableend()."\n<h2>$section</h2>");
+                    $oldsection=$section;
+                    $oldpart='';
+                }
+            } else {
+                if ($section ne $oldsection) {
+                    $r->print(&tableend()."\n<hr /><h1>$section</h1>");
+                    $oldsection=$section;
+                    $oldrealm='';
+                }
+                if ($realm ne $oldrealm) {
+                    $r->print(&tableend()."\n<h2>$realm</h2>");
+                    $oldrealm=$realm;
+                    $oldpart='';
                 }
             }
-            $middle=~s/^\[(.*)\]//;
-        } elsif (($env{'request.course.sec'} ne '') && ($caller eq 'overview')) {
-            $readonly = 1;
-        }
-        $middle=~s/\.+$//;
-        $middle=~s/^\.+//;
-        my $realm='<span class="LC_parm_scope_all">'.&mt('All Resources').'</span>';
-        if ($middle=~/^(.+)\_\_\_\((all|rec)\)$/) {
-            my $mapurl = $1;
-            my $maplevel = $2;
-            my $leveltitle = &mt('Folder/Map');
-            if ($maplevel eq 'rec') {
-                $leveltitle = &mt('Recursive');
+            if ($part ne $oldpart) {
+                $r->print(&tableend().
+                    "\n".'<span class="LC_parm_part">'.&mt('Part').": $part</span>");
+                $oldpart=$part;
             }
-            $realm='<span class="LC_parm_scope_folder">'.$leveltitle.': '.&Apache::lonnet::gettitle($mapurl).' <br /><span class="LC_parm_folder">('.$mapurl.')</span></span>';
-        } elsif ($middle) {
-        my ($map,$id,$url)=&Apache::lonnet::decode_symb($middle);
-        $realm='<span class="LC_parm_scope_resource">'.&mt('Resource').': '.&Apache::lonnet::gettitle($middle).' <br /><span class="LC_parm_symb">('.$url.' in '.$map.' id: '.$id.')</span></span>';
-        }
-        if ($sortorder eq 'realmstudent') {
-        if ($realm ne $oldrealm) {
-            $r->print(&tableend()."\n<hr /><h1>$realm</h1>");
-            $oldrealm=$realm;
-            $oldsection='';
-        }
-        if ($section ne $oldsection) {
-            $r->print(&tableend()."\n<h2>$section</h2>");
-            $oldsection=$section;
-            $oldpart='';
-        }
-        } else {
-        if ($section ne $oldsection) {
-            $r->print(&tableend()."\n<hr /><h1>$section</h1>");
-            $oldsection=$section;
-            $oldrealm='';
-        }
-        if ($realm ne $oldrealm) {
-            $r->print(&tableend()."\n<h2>$realm</h2>");
-            $oldrealm=$realm;
-            $oldpart='';
-        }
-        }
-        if ($part ne $oldpart) {
-        $r->print(&tableend().
-              "\n".'<span class="LC_parm_part">'.&mt('Part').": $part</span>");
-        $oldpart=$part;
-        }
-#
-# Ready to print
-#
+    #
+    # Ready to print
+    #
             my $parmitem = &standard_parameter_names($name);
-        $r->print(&tablestart($readonly).
-              &Apache::loncommon::start_data_table_row().
-              '<td><b>'.&mt($parmitem).
-              '</b></td>');
-        unless ($readonly) {
-            $r->print('<td><input type="checkbox" name="del_'.
-                      $thiskey.'" /></td>');
-        }
-        $r->print('<td>');
-        $foundkeys++;
-        if (&isdateparm($thistype)) {
-            my $jskey='key_'.$pointer;
-            my $state;
-            $pointer++;
-            if ($readonly) {
-                $state = 'disabled';
-            }
-            $r->print(
-                &Apache::lonhtmlcommon::date_setter('parmform',
-                                                    $jskey,
-                                                    $$resourcedata{$thiskey},
-                                                    '',1,$state));
-            unless  ($readonly) {
+            $r->print(&tablestart($readonly).
+                &Apache::loncommon::start_data_table_row().
+                '<td><b>'.&mt($parmitem).
+                '</b></td>');
+            unless ($readonly) {
+                $r->print('<td><input type="checkbox" name="del_'.
+                        $thiskey.'" /></td>');
+            }
+            $r->print('<td>');
+            $foundkeys++;
+            if (&isdateparm($thistype)) {
+                my $jskey='key_'.$pointer;
+                my $state;
+                $pointer++;
+                if ($readonly) {
+                    $state = 'disabled';
+                }
                 $r->print(
-'<input type="hidden" name="datepointer_'.$thiskey.'" value="'.$jskey.'" />'.
-(($$resourcedata{$thiskey}!=0)?'<span class="LC_nobreak"><a href="/adm/parmset?&action=dateshift1&timebase='.$$resourcedata{$thiskey}.'">'.
-&mt('Shift all dates based on this date').'</a></span>':'').
-&date_sanity_info($$resourcedata{$thiskey})
-                );
+                    &Apache::lonhtmlcommon::date_setter('parmform',
+                                                        $jskey,
+                                                        $$resourcedata{$thiskey},
+                                                        '',1,$state));
+                unless  ($readonly) {
+                    $r->print(
+    '<input type="hidden" name="datepointer_'.$thiskey.'" value="'.$jskey.'" />'.
+    (($$resourcedata{$thiskey}!=0)?'<span class="LC_nobreak"><a href="/adm/parmset?&action=dateshift1&timebase='.$$resourcedata{$thiskey}.'">'.
+    &mt('Shift all dates based on this date').'</a></span>':'').
+    &date_sanity_info($$resourcedata{$thiskey})
+                    );
+                }
+            } elsif ($thistype eq 'date_interval') {
+                $r->print(&date_interval_selector($thiskey,$name,
+                        $$resourcedata{$thiskey},$readonly));
+            } elsif ($thistype =~ m/^string/) {
+                $r->print(&string_selector($thistype,$thiskey,
+                        $$resourcedata{$thiskey},$name,$readonly));
+            } else {
+                $r->print(&default_selector($thiskey,$$resourcedata{$thiskey},$readonly));
             }
-        } elsif ($thistype eq 'date_interval') {
-            $r->print(&date_interval_selector($thiskey,$name,
-                      $$resourcedata{$thiskey},$readonly));
-        } elsif ($thistype =~ m/^string/) {
-            $r->print(&string_selector($thistype,$thiskey,
-                      $$resourcedata{$thiskey},$name,$readonly));
-        } else {
-            $r->print(&default_selector($thiskey,$$resourcedata{$thiskey},$readonly));
-        }
-        unless ($readonly) {
-            $r->print('<input type="hidden" name="typeof_'.$thiskey.'" value="'.
-                      $thistype.'" />');
+            unless ($readonly) {
+                $r->print('<input type="hidden" name="typeof_'.$thiskey.'" value="'.
+                        $thistype.'" />');
+            }
+            $r->print('</td>'.&Apache::loncommon::end_data_table_row());
         }
-        $r->print('</td>'.&Apache::loncommon::end_data_table_row());
-    }
     }
     return $foundkeys;
 }
 
+# Returns a string representing the interval, directly using form data matching the given key.
+# The returned string may also include information related to proctored exams.
+# Format: seconds['_done'[':'done button title':']['_proctor'['_'proctor key]]]
+#
+# @param {string} $key - suffix for form fields related to the interval
+# @returns {string}
 sub get_date_interval_from_form {
     my ($key) = @_;
     my $seconds = 0;
@@ -3544,18 +4066,37 @@ sub get_date_interval_from_form {
                ['hours', 3600],
                ['minutes', 60],
                ['seconds',  1]) {
-    my ($name, $factor) = @{ $which };
-    if (defined($env{'form.'.$name.'_'.$key})) {
-        $seconds += $env{'form.'.$name.'_'.$key} * $factor;
-    }
+        my ($name, $factor) = @{ $which };
+        if (defined($env{'form.'.$name.'_'.$key})) {
+            $seconds += $env{'form.'.$name.'_'.$key} * $factor;
+        }
     }
-    if (($key =~ /\.interval$/) && ($env{'form.done_'.$key} eq '_done')) {
-        $seconds .= $env{'form.done_'.$key};
+    if (($key =~ /\.interval$/) &&
+            (($env{'form.done_'.$key} eq '_done') || ($env{'form.done_'.$key} eq '_done_proctor'))) {
+        if ($env{'form.done_'.$key.'_buttontext'}) {
+            $env{'form.done_'.$key.'_buttontext'} =~ s/\://g;
+            $seconds .= '_done:'.$env{'form.done_'.$key.'_buttontext'}.':';
+            if ($env{'form.done_'.$key} eq '_done_proctor') {
+                $seconds .= '_proctor';
+            }
+        } else {
+            $seconds .= $env{'form.done_'.$key}; 
+        }
+        if (($env{'form.done_'.$key} eq '_done_proctor') && 
+                ($env{'form.done_'.$key.'_proctorkey'})) {
+            $seconds .= '_'.$env{'form.done_'.$key.'_proctorkey'};
+        }
     }
     return $seconds;
 }
 
 
+# Returns HTML to enter a text value for a parameter.
+#
+# @param {string} $thiskey - parameter key
+# @param {string} $showval - the current value
+# @param {boolean} $readonly - true if the field should not be made editable
+# @returns {string}
 sub default_selector {
     my ($thiskey, $showval, $readonly) = @_;
     my $disabled;
@@ -3565,6 +4106,12 @@ sub default_selector {
     return '<input type="text" name="set_'.$thiskey.'" value="'.$showval.'"'.$disabled.' />';
 }
 
+# Returns HTML to enter allow/deny rules related to IP addresses.
+#
+# @param {string} $thiskey - parameter key
+# @param {string} $showval - the current value
+# @param {boolean} $readonly - true if the fields should not be made editable
+# @returns {string}
 sub string_ip_selector {
     my ($thiskey, $showval, $readonly) = @_;
     my %access = (
@@ -3625,12 +4172,14 @@ sub string_ip_selector {
     return $output;
 }
 
-{
+
+{ # block using some constants related to parameter types (overview mode)
+
 my %strings =
     (
      'string_yesno'
              => [[ 'yes', 'Yes' ],
-         [ 'no', 'No' ]],
+                 [ 'no', 'No' ]],
      'string_problemstatus'
              => [[ 'yes', 'Yes' ],
          [ 'answer', 'Yes, and show correct answer if they exceed the maximum number of tries.' ],
@@ -3676,6 +4225,11 @@ my %stringtypes = (
                     acc          => 'string_ip',
                   );
 
+# Returns the possible values and titles for a given string type, or undef if there are none.
+# Used by courseprefs.
+#
+# @param {string} $string_type - a parameter type for strings
+# @returns {array reference} - 2D array, containing values and English titles
 sub standard_string_options {
     my ($string_type) = @_;
     if (ref($strings{$string_type}) eq 'ARRAY') {
@@ -3684,6 +4238,10 @@ sub standard_string_options {
     return;
 }
 
+# Returns regular expressions to match kinds of string types, or undef if there are none.
+#
+# @param {string} $string_type - a parameter type for strings
+# @returns {array reference}  - 2D array, containing regular expression names and regular expressions
 sub standard_string_matches {
     my ($string_type) = @_;
     if (ref($stringmatches{$string_type}) eq 'ARRAY') {
@@ -3692,6 +4250,10 @@ sub standard_string_matches {
     return;
 }
 
+# Returns a parameter type for a given parameter with a string type, or undef if not known.
+#
+# @param {string} $name - parameter name
+# @returns {string}
 sub get_stringtype {
     my ($name) = @_;
     if (exists($stringtypes{$name})) {
@@ -3700,6 +4262,14 @@ sub get_stringtype {
     return;
 }
 
+# Returns HTML to edit a string parameter.
+#
+# @param {string} $thistype - parameter type
+# @param {string} $thiskey - parameter key
+# @param {string} $showval - parameter current value
+# @param {string} $name - parameter name
+# @param {boolean} $readonly - true if the values should not be made editable
+# @returns {string}
 sub string_selector {
     my ($thistype, $thiskey, $showval, $name, $readonly) = @_;
 
@@ -3709,10 +4279,10 @@ sub string_selector {
 
     my %skiptype;
     if (($thistype eq 'string_questiontype') || 
-        ($thistype eq 'string_lenient') ||
-        ($thistype eq 'string_discussvote') ||
-        ($thistype eq 'string_ip') ||
-        ($name eq 'retrypartial')) {
+            ($thistype eq 'string_lenient') ||
+            ($thistype eq 'string_discussvote') ||
+            ($thistype eq 'string_ip') ||
+            ($name eq 'retrypartial')) {
         my ($got_chostname,$chostname,$cmajor,$cminor); 
         foreach my $possibilities (@{ $strings{$thistype} }) {
             next unless (ref($possibilities) eq 'ARRAY');
@@ -3735,7 +4305,7 @@ sub string_selector {
                     ($chostname,$cmajor,$cminor)=&parameter_release_vars();
                     $got_chostname = 1;
                 }
-                my $needsnewer=&parameter_releasecheck($name,$parmval,$parmmatch,
+                my $needsnewer=&parameter_releasecheck($name,$parmval,$parmmatch,undef,
                                                        $needsrelease,$cmajor,$cminor);
                 if ($needsnewer) {
                     if ($parmmatch ne '') {
@@ -3851,18 +4421,24 @@ my %intervals =
     (
      'date_interval'
              => [[ 'done', 'Yes' ],
+                 [ 'done_proctor', 'Yes, with proctor key'],                  
                  [ '', 'No' ]],
     );
 
 my %intervalmatches = (
          'date_interval'
-              => [['done','\d+_done$'],],
+              => [['done','\d+_done(|\:[^\:]+\:)$'],
+                  ['done_proctor','\d+_done(|\:[^\:]+\:)_proctor_']],
     );
 
 my %intervaltypes = (
                       interval => 'date_interval',
     );
 
+# Returns regular expressions to match kinds of interval type, or undef if there are none.
+#
+# @param {string} $interval_type - a parameter type for intervals
+# @returns {array reference}  - 2D array, containing regular expression names and regular expressions
 sub standard_interval_matches {
     my ($interval_type) = @_;
     if (ref($intervalmatches{$interval_type}) eq 'ARRAY') {
@@ -3871,6 +4447,10 @@ sub standard_interval_matches {
     return;
 }
 
+# Returns a parameter type for a given parameter with an interval type, or undef if not known.
+#
+# @param {string} $name - parameter name
+# @returns {string}
 sub get_intervaltype {
     my ($name) = @_;
     if (exists($intervaltypes{$name})) {
@@ -3879,6 +4459,11 @@ sub get_intervaltype {
     return;
 }
 
+# Returns the possible values and titles for a given interval type, or undef if there are none.
+# Used by courseprefs.
+#
+# @param {string} $interval_type - a parameter type for intervals
+# @returns {array reference} - 2D array, containing values and English titles
 sub standard_interval_options {
     my ($interval_type) = @_;
     if (ref($intervals{$interval_type}) eq 'ARRAY') {
@@ -3887,6 +4472,13 @@ sub standard_interval_options {
     return;
 }
 
+# Returns HTML to edit a date interval parameter.
+#
+# @param {string} $thiskey - parameter key
+# @param {string} $name - parameter name
+# @param {string} $showval - parameter current value
+# @param {boolean} $readonly - true if the values should not be made editable
+# @returns {string}
 sub date_interval_selector {
     my ($thiskey, $name, $showval, $readonly) = @_;
     my ($result,%skipval);
@@ -3914,7 +4506,7 @@ sub date_interval_selector {
                     ($chostname,$cmajor,$cminor)=&parameter_release_vars();
                     $got_chostname = 1;
                 }
-                my $needsnewer=&parameter_releasecheck($name,$parmval,$parmmatch,
+                my $needsnewer=&parameter_releasecheck($name,$parmval,$parmmatch,undef,
                                                        $needsrelease,$cmajor,$cminor);
                 if ($needsnewer) {
                     if ($parmmatch ne '') {
@@ -3932,28 +4524,54 @@ sub date_interval_selector {
                ['hours', 3600, 23],
                ['minutes', 60, 59],
                ['seconds',  1, 59]) {
-    my ($name, $factor, $max) = @{ $which };
-    my $amount = int($showval/$factor);
-    $showval  %= $factor;
-    my %select = ((map {$_ => $_} (0..$max)),
-              'select_form_order' => [0..$max]);
-    $result .= &Apache::loncommon::select_form($amount,$name.'_'.$thiskey,
-                           \%select,'',$readonly);
-    $result .= ' '.&mt($name);
+        my ($name, $factor, $max) = @{ $which };
+        my $amount = int($showval/$factor);
+        $showval  %= $factor;
+        my %select = ((map {$_ => $_} (0..$max)),
+                'select_form_order' => [0..$max]);
+        $result .= &Apache::loncommon::select_form($amount,$name.'_'.$thiskey,
+                            \%select,'',$readonly);
+        $result .= ' '.&mt($name);
     }
     if ($name eq 'interval') {
         unless ($skipval{'done'}) {
             my $checkedon = '';
+            my $checkedproc = '';
+            my $currproctorkey = '';
+            my $currprocdisplay = 'hidden';
+            my $currdonetext = &mt('Done');
             my $checkedoff = ' checked="checked"';
-            if ($currval =~ /^(\d+)_done$/) {
+            if ($currval =~ /^(?:\d+)_done$/) {
                 $checkedon = ' checked="checked"';
                 $checkedoff = '';
+            } elsif ($currval =~ /^(?:\d+)_done\:([^\:]+)\:$/) {
+                $currdonetext = $1;
+                $checkedon = ' checked="checked"';
+                $checkedoff = '';
+            } elsif ($currval =~ /^(?:\d+)_done_proctor_(.+)$/) {
+                $currproctorkey = $1;
+                $checkedproc = ' checked="checked"';
+                $checkedoff = '';
+                $currprocdisplay = 'text';
+            } elsif ($currval =~ /^(?:\d+)_done\:([^\:]+)\:_proctor_(.+)$/) {
+                $currdonetext = $1;
+                $currproctorkey = $2;
+                $checkedproc = ' checked="checked"';
+                $checkedoff = '';
+                $currprocdisplay = 'text';
             }
-            $result .= '<span class="LC_nobreak">'.('&nbsp;' x 3).'('.&mt('Include "done" button').
-                       '<label><input type="radio" value="_done" name="done_'.$thiskey.'"'.$checkedon.' />'.
-                       &mt('Yes').'</label>'.
-                       '<label><input type="radio" value="" name="done_'.$thiskey.'"'.$checkedoff.' />'.
-                       &mt('No').'</label>)</span>';
+            my $onclick = ' onclick="toggleSecret(this.form,'."'done_','$thiskey'".');"';
+            $result .= '<br /><span class="LC_nobreak">'.&mt('Include "done" button').
+                       '<label><input type="radio" value="" name="done_'.$thiskey.'"'.$checkedoff.$onclick.' />'.
+                       &mt('No').'</label>'.('&nbsp;'x2).
+                       '<label><input type="radio" value="_done" name="done_'.$thiskey.'"'.$checkedon.$onclick.' />'.
+                       &mt('Yes').'</label>'.('&nbsp;'x2).
+                       '<label><input type="radio" value="_done_proctor" name="done_'.$thiskey.'"'.$checkedproc.$onclick.' />'.
+                       &mt('Yes, with proctor key').'</label>'.
+                       '<input type="'.$currprocdisplay.'" id="done_'.$thiskey.'_proctorkey" '.
+                       'name="done_'.$thiskey.'_proctorkey" value="'.&HTML::Entities::encode($currproctorkey,'"<>&').'" /></span><br />'.
+                       '<span class="LC_nobreak">'.&mt('Button text').': '.
+                       '<input type="text" name="done_'.$thiskey.'_buttontext" value="'.&HTML::Entities::encode($currdonetext,'"<>&').'" /></span>';
         }
     }
     unless ($readonly) {
@@ -3962,8 +4580,35 @@ sub date_interval_selector {
     return $result;
 }
 
+# Returns HTML with a warning if a parameter requires a more recent version of LON-CAPA.
+#
+# @param {string} $name - parameter name
+# @param {string} $namematch - parameter level name (recognized: resourcelevel|maplevel|maplevelrecurse|courselevel)
+# @param {string} $value - parameter value
+# @param {string} $chostname - course server name
+# @param {integer} $cmajor - major version number
+# @param {integer} $cminor - minor version number
+# @param {string} $needsrelease - release version needed (major.minor)
+# @returns {string}
 sub oldversion_warning {
-    my ($name,$value,$chostname,$cmajor,$cminor,$needsrelease) = @_;
+    my ($name,$namematch,$value,$chostname,$cmajor,$cminor,$needsrelease) = @_;
+    my $standard_name = &standard_parameter_names($name);
+    if ($namematch) {
+        my $level = &standard_parameter_levels($namematch);
+        my $msg = '';
+        if ($level) {
+            $msg = &mt('[_1] was [_2]not[_3] set at the level of: [_4].',
+                       $standard_name,'<b>','</b>','"'.$level.'"');
+        } else {
+            $msg = &mt('[_1] was [_2]not[_3] set.',
+                      $standard_name,'<b>','</b>');
+        }
+        return '<p class="LC_warning">'.$msg.'<br />'.
+               &mt('LON-CAPA version ([_1]) installed on home server ([_2]) does not meet version requirements ([_3] or newer).',
+                   $cmajor.'.'.$cminor,$chostname,
+                   $needsrelease).
+                   '</p>';
+    }
     my $desc;
     my $stringtype = &get_stringtype($name);
     if ($stringtype ne '') {
@@ -4008,22 +4653,23 @@ sub oldversion_warning {
             }
         }
     }
-    my $standard_name = &standard_parameter_names($name);
     return '<p class="LC_warning">'.
-           &mt('[_1] was [_2]not[_3] set to [_4].',
-               $standard_name,'<b>','</b>','"'.$desc.'"').'<br />'.
-           &mt('LON-CAPA version ([_1]) installed on home server ([_2]) does not meet version requirements ([_3] or newer).',
-           $cmajor.'.'.$cminor,$chostname,
-           $needsrelease).
-           '</p>';
+       &mt('[_1] was [_2]not[_3] set to [_4].',
+           $standard_name,'<b>','</b>','"'.$desc.'"').'<br />'.
+       &mt('LON-CAPA version ([_1]) installed on home server ([_2]) does not meet version requirements ([_3] or newer).',
+       $cmajor.'.'.$cminor,$chostname,
+       $needsrelease).
+       '</p>';
 }
 
-}
+} # end of block using some constants related to parameter types
+
 
-#
-# Shift all start and end dates by $shift
-#
 
+# Shifts all start and end dates in the current course by $shift.
+#
+# @param {integer} $shift - time to shift, in seconds
+# @returns {string} - error name or 'ok'
 sub dateshift {
     my ($shift)=@_;
     my $dom = $env{'course.'.$env{'request.course.id'}.'.domain'};
@@ -4055,6 +4701,9 @@ sub dateshift {
     return $reply;
 }
 
+# Overview mode UI to edit course parameters.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
 sub newoverview {
     my ($r) = @_;
 
@@ -4076,6 +4725,7 @@ sub newoverview {
             &toggleparmtextbox_js()."\n".
             &validateparms_js()."\n".
             &ipacc_boxes_js()."\n".
+            &done_proctor_js()."\n".
 '// ]]>
 </script>
 ';
@@ -4162,7 +4812,7 @@ ENDOVER
 
     $r->print('<div class="LC_Box">');
     $r->print('<div>');
-    &displaymenu($r,\%allparms,\@pscat,\%keyorder);
+    &displaymenu($r,\%allparms,\@pscat,\%keyorder); # FIXME: wrong parameters, could make keysindisplayorderCategory crash because $keyorder is undefined
     $r->print(&Apache::lonhtmlcommon::start_pick_box());
     $r->print(&Apache::lonhtmlcommon::row_title(&mt('Select Parts to View')));
     my $sectionselector = &sectionmenu(\@selected_sections);
@@ -4227,6 +4877,20 @@ ENDOVER
     $r->print(&Apache::loncommon::end_page());
 }
 
+# Fills $listdata with parameter information.
+# Keys use the format course id.[section id].part.name and course id.[section id].part.name.type.
+# The non-type value is always 1.
+#
+# @param {string} $cat - parameter name
+# @param {string} $pschp - selected map pc, or 'all'
+# @param {string} $parmlev - selected level value (full|map|general), or ''
+# @param {hash reference} $listdata - the parameter data that will be modified
+# @param {array reference} $psprt - selected parts
+# @param {array reference} $selections - selected sections
+# @param {hash reference} $defkeytype - hash parameter name -> parameter type
+# @param {hash reference} $allmaps - hash map pc -> map src
+# @param {array reference} $ids - resource and map ids
+# @param {hash reference} $symbp - hash map pc or resource/map id -> map src.'___(all)' or resource symb
 sub secgroup_lister {
     my ($cat,$pschp,$parmlev,$listdata,$psprt,$selections,$defkeytype,$allmaps,$ids,$symbp) = @_;
     foreach my $item (@{$selections}) {
@@ -4265,6 +4929,10 @@ sub secgroup_lister {
     }
 }
 
+# UI to edit parameter settings starting with a list of all existing parameters.
+# (called by setoverview action)
+#
+# @param {Apache2::RequestRec} $r - the Apache request
 sub overview {
     my ($r) = @_;
     my $dom = $env{'course.'.$env{'request.course.id'}.'.domain'};
@@ -4275,6 +4943,7 @@ sub overview {
              &toggleparmtextbox_js()."\n".
              &validateparms_js()."\n".
              &ipacc_boxes_js()."\n".
+             &done_proctor_js()."\n".
              '// ]]>'."\n".
              '</script>'."\n";
     &Apache::lonhtmlcommon::add_breadcrumb({href=>'/adm/parmset?action=setoverview',
@@ -4310,6 +4979,9 @@ sub overview {
           &Apache::loncommon::end_page());
 }
 
+# Unused sub.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
 sub clean_parameters {
     my ($r) = @_;
     my $dom = $env{'course.'.$env{'request.course.id'}.'.domain'};
@@ -4345,51 +5017,51 @@ ENDOVER
           '<th>'.&mt('Parameter').'</th>'.
           '</tr>');
     foreach my $thiskey (sort(keys(%{$resourcedata}))) {
-    next if (!exists($resourcedata->{$thiskey.'.type'})
-         && $thiskey=~/\.type$/);
-    my %data = &parse_key($thiskey);
-    if (1) { #exists($data{'realm_exists'})
-        #&& !$data{'realm_exists'}) {
-        $r->print(&Apache::loncommon::start_data_table_row().
-              '<tr>'.
-              '<td><input type="checkbox" name="del_'.$thiskey.'" /></td>'              );
-
-        $r->print('<td>');
-        my $display_value = $resourcedata->{$thiskey};
-        if (&isdateparm($resourcedata->{$thiskey.'.type'})) {
-        $display_value =
-            &Apache::lonlocal::locallocaltime($display_value);
-        }
+        next if (!exists($resourcedata->{$thiskey.'.type'})
+            && $thiskey=~/\.type$/);
+        my %data = &parse_key($thiskey);
+        if (1) { #exists($data{'realm_exists'})
+            #&& !$data{'realm_exists'}) {
+            $r->print(&Apache::loncommon::start_data_table_row().
+                '<tr>'.
+                '<td><input type="checkbox" name="del_'.$thiskey.'" /></td>'              );
+
+            $r->print('<td>');
+            my $display_value = $resourcedata->{$thiskey};
+            if (&isdateparm($resourcedata->{$thiskey.'.type'})) {
+            $display_value =
+                &Apache::lonlocal::locallocaltime($display_value);
+            }
             my $parmitem = &standard_parameter_names($data{'parameter_name'});
             $parmitem = &mt($parmitem);
-        $r->print(&mt('Parameter: "[_1]" with value: "[_2]"',
-              $parmitem,$resourcedata->{$thiskey}));
-        $r->print('<br />');
-        if ($data{'scope_type'} eq 'all') {
-        $r->print(&mt('All users'));
-        } elsif ($data{'scope_type'} eq 'user') {
-        $r->print(&mt('User: [_1]',join(':',@{$data{'scope'}})));
-        } elsif ($data{'scope_type'} eq 'section') {
-        $r->print(&mt('Section: [_1]',$data{'scope'}));
-        } elsif ($data{'scope_type'} eq 'group') {
-        $r->print(&mt('Group: [_1]',$data{'scope'}));
-        }
-        $r->print('<br />');
-        if ($data{'realm_type'} eq 'all') {
-        $r->print(&mt('All Resources'));
-        } elsif ($data{'realm_type'} eq 'folder') {
-        $r->print(&mt('Folder: [_1]'),$data{'realm'});
-        } elsif ($data{'realm_type'} eq 'symb') {
-        my ($map,$resid,$url) =
-            &Apache::lonnet::decode_symb($data{'realm'});
-        $r->print(&mt('Resource: [_1]with ID: [_2]in folder [_3]',
-                      $url.' <br />&nbsp;&nbsp;&nbsp;',
-                      $resid.' <br />&nbsp;&nbsp;&nbsp;',$map));
-        }
-        $r->print(' <br />&nbsp;&nbsp;&nbsp;'.&mt('Part: [_1]',$data{'parameter_part'}));
-        $r->print('</td></tr>');
+            $r->print(&mt('Parameter: "[_1]" with value: "[_2]"',
+                $parmitem,$resourcedata->{$thiskey}));
+            $r->print('<br />');
+            if ($data{'scope_type'} eq 'all') {
+                $r->print(&mt('All users'));
+            } elsif ($data{'scope_type'} eq 'user') {
+                $r->print(&mt('User: [_1]',join(':',@{$data{'scope'}})));
+            } elsif ($data{'scope_type'} eq 'section') {
+                $r->print(&mt('Section: [_1]',$data{'scope'}));
+            } elsif ($data{'scope_type'} eq 'group') {
+                $r->print(&mt('Group: [_1]',$data{'scope'}));
+            }
+            $r->print('<br />');
+            if ($data{'realm_type'} eq 'all') {
+                $r->print(&mt('All Resources'));
+            } elsif ($data{'realm_type'} eq 'folder') {
+                $r->print(&mt('Folder: [_1]'),$data{'realm'});
+            } elsif ($data{'realm_type'} eq 'symb') {
+            my ($map,$resid,$url) =
+                &Apache::lonnet::decode_symb($data{'realm'});
+            $r->print(&mt('Resource: [_1]with ID: [_2]in folder [_3]',
+                        $url.' <br />&nbsp;&nbsp;&nbsp;',
+                        $resid.' <br />&nbsp;&nbsp;&nbsp;',$map));
+            }
+            $r->print(' <br />&nbsp;&nbsp;&nbsp;'.&mt('Part: [_1]',$data{'parameter_part'}));
+            $r->print('</td></tr>');
 
-    }
+        }
     }
     $r->print(&Apache::loncommon::end_data_table().'<p>'.
           '<input type="submit" value="'.&mt('Delete Selected').'" />'.
@@ -4398,6 +5070,10 @@ ENDOVER
     $r->print(&Apache::loncommon::end_page());
 }
 
+# UI to shift all dates (called by dateshift1 action).
+# Used by overview mode.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
 sub date_shift_one {
     my ($r) = @_;
     my $dom = $env{'course.'.$env{'request.course.id'}.'.domain'};
@@ -4426,6 +5102,9 @@ sub date_shift_one {
     $r->print(&Apache::loncommon::end_page());
 }
 
+# UI to shift all dates (second form).
+#
+# @param {Apache2::RequestRec} $r - the Apache request
 sub date_shift_two {
     my ($r) = @_;
     my $dom = $env{'course.'.$env{'request.course.id'}.'.domain'};
@@ -4453,6 +5132,13 @@ sub date_shift_two {
     $r->print(&Apache::loncommon::end_page());
 }
 
+# Returns the different components of a resourcedata key.
+# Keys: scope_type, scope, realm_type, realm, realm_title,
+#       realm_exists, parameter_part, parameter_name.
+# Was used by clean_parameters (which is unused).
+#
+# @param {string} $key - the parameter key
+# @returns {hash}
 sub parse_key {
     my ($key) = @_;
     my %data;
@@ -4460,30 +5146,30 @@ sub parse_key {
     ($key=~/^$env{'request.course.id'}\.(?:(.+)\.)*([\w\s]+)\.(\w+)$/);
     $data{'scope_type'} = 'all';
     if ($middle=~/^\[(.*)\]/) {
-           $data{'scope'} = $1;
-    if ($data{'scope'}=~/^useropt\:($match_username)\:($match_domain)/) {
-        $data{'scope_type'} = 'user';
-        $data{'scope'} = [$1,$2];
-    } else {
-        #FIXME check for group scope
-        $data{'scope_type'} = 'section';
-    }
-    $middle=~s/^\[(.*)\]//;
+        $data{'scope'} = $1;
+        if ($data{'scope'}=~/^useropt\:($match_username)\:($match_domain)/) {
+            $data{'scope_type'} = 'user';
+            $data{'scope'} = [$1,$2];
+        } else {
+            #FIXME check for group scope
+            $data{'scope_type'} = 'section';
+        }
+        $middle=~s/^\[(.*)\]//;
     }
     $middle=~s/\.+$//;
     $middle=~s/^\.+//;
     $data{'realm_type'}='all';
     if ($middle=~/^(.+)\_\_\_\(all\)$/) {
-    $data{'realm'} = $1;
-    $data{'realm_type'} = 'folder';
-    $data{'realm_title'} = &Apache::lonnet::gettitle($data{'realm'});
-    ($data{'realm_exists'}) = &Apache::lonnet::is_on_map($data{'realm'});
+        $data{'realm'} = $1;
+        $data{'realm_type'} = 'folder';
+        $data{'realm_title'} = &Apache::lonnet::gettitle($data{'realm'});
+        ($data{'realm_exists'}) = &Apache::lonnet::is_on_map($data{'realm'});
     } elsif ($middle) {
-    $data{'realm'} = $middle;
-    $data{'realm_type'} = 'symb';
-    $data{'realm_title'} = &Apache::lonnet::gettitle($data{'realm'});
-    my ($map,$resid,$url) = &Apache::lonnet::decode_symb($data{'realm'});
-    $data{'realm_exists'} = &Apache::lonnet::symbverify($data{'realm'},$url);
+        $data{'realm'} = $middle;
+        $data{'realm_type'} = 'symb';
+        $data{'realm_title'} = &Apache::lonnet::gettitle($data{'realm'});
+        my ($map,$resid,$url) = &Apache::lonnet::decode_symb($data{'realm'});
+        $data{'realm_exists'} = &Apache::lonnet::symbverify($data{'realm'},$url);
     }
 
     $data{'parameter_part'} = $part;
@@ -4493,12 +5179,21 @@ sub parse_key {
 }
 
 
+# Calls loncommon::start_page with the "Settings" title.
 sub header {
     return &Apache::loncommon::start_page('Settings');
 }
 
 
 
+##################################################
+# MAIN MENU
+##################################################
+
+# Content and problem settings main menu.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {boolean} $parm_permission - true if the user has permission to edit the current course or section
 sub print_main_menu {
     my ($r,$parm_permission)=@_;
     #
@@ -4598,6 +5293,17 @@ ENDMAINFORMHEAD
 
 
 
+##################################################
+# PORTFOLIO METADATA
+##################################################
+
+# Prints HTML to edit an item of portfolio metadata. The HTML contains several td elements (no tr).
+# It looks like field titles are not localized.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {string} $field_name - metadata field name
+# @param {string} $field_text - metadata field title, in English unless manually added
+# @param {boolean} $added_flag - true if the field was manually added
 sub output_row {
     my ($r, $field_name, $field_text, $added_flag) = @_;
     my $output;
@@ -4619,14 +5325,14 @@ sub output_row {
         $output .= '<td><strong>'.$field_text.':</strong></td>';
         $output .= &Apache::loncommon::end_data_table_row();
         foreach my $opt (@options) {
-        my $checked = ($options =~ m/$opt->[0]/) ? ' checked="checked" ' : '' ;
-        $output .= &Apache::loncommon::continue_data_table_row();
-        $output .= '<td>'.('&nbsp;' x 5).'<label>
-                   <input type="checkbox" name="'.
-                   $field_name.'_'.$opt->[0].'" value="yes"'.$checked.' />'.
-                   &mt($opt->[1]).'</label></td>';
-        $output .= &Apache::loncommon::end_data_table_row();
-    }
+            my $checked = ($options =~ m/$opt->[0]/) ? ' checked="checked" ' : '' ;
+            $output .= &Apache::loncommon::continue_data_table_row();
+            $output .= '<td>'.('&nbsp;' x 5).'<label>
+                    <input type="checkbox" name="'.
+                    $field_name.'_'.$opt->[0].'" value="yes"'.$checked.' />'.
+                    &mt($opt->[1]).'</label></td>';
+            $output .= &Apache::loncommon::end_data_table_row();
+        }
         $output .= &Apache::loncommon::continue_data_table_row();
         $output .= '<td>'.('&nbsp;' x 10).'<input name="'.$field_name.'_values" type="text" value="'.$values.'" size="80" /></td>';
         $output .= &Apache::loncommon::end_data_table_row();
@@ -4639,22 +5345,25 @@ sub output_row {
             $multiple_checked = ' checked="checked"';
             $single_checked = '';
         }
-    $output .= &Apache::loncommon::continue_data_table_row();
-    $output .= '<td>'.('&nbsp;' x 10).'
-                <input type="radio" name="'.$field_name.'_onlyone" value="multiple"'.$multiple_checked .' />
-                '.&mt('Student may select multiple choices from list').'</td>';
-    $output .= &Apache::loncommon::end_data_table_row();
-    $output .= &Apache::loncommon::continue_data_table_row();
-    $output .= '<td>'.('&nbsp;' x 10).'
-                <input type="radio" name="'.$field_name.'_onlyone"  value="single"'.$single_checked.' />
-                '.&mt('Student may select only one choice from list').'</td>';
-    $output .= &Apache::loncommon::end_data_table_row();
+        $output .= &Apache::loncommon::continue_data_table_row();
+        $output .= '<td>'.('&nbsp;' x 10).'
+                    <input type="radio" name="'.$field_name.'_onlyone" value="multiple"'.$multiple_checked .' />
+                    '.&mt('Student may select multiple choices from list').'</td>';
+        $output .= &Apache::loncommon::end_data_table_row();
+        $output .= &Apache::loncommon::continue_data_table_row();
+        $output .= '<td>'.('&nbsp;' x 10).'
+                    <input type="radio" name="'.$field_name.'_onlyone"  value="single"'.$single_checked.' />
+                    '.&mt('Student may select only one choice from list').'</td>';
+        $output .= &Apache::loncommon::end_data_table_row();
     }
     return ($output);
 }
 
 
-
+# UI to order portfolio metadata fields.
+# Currently useless because addmetafield does not work.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
 sub order_meta_fields {
     my ($r)=@_;
     my $idx = 1;
@@ -4662,12 +5371,13 @@ sub order_meta_fields {
     my $crs = $env{'course.'.$env{'request.course.id'}.'.num'};
     my $crstype = $env{'course.'.$env{'request.course.id'}.'.type'};;
     $r->print(&Apache::loncommon::start_page('Order Metadata Fields'));
-    &Apache::lonhtmlcommon::add_breadcrumb({href=>'/adm/parmset?action=addmetadata',
+    &Apache::lonhtmlcommon::add_breadcrumb(
+        {href=>'/adm/parmset?action=addmetadata',
         text=>"Add Metadata Field"});
-    &Apache::lonhtmlcommon::add_breadcrumb
-            ({href=>"/adm/parmset?action=setrestrictmeta",
-              text=>"Restrict Metadata"},
-             {text=>"Order Metadata"});
+    &Apache::lonhtmlcommon::add_breadcrumb(
+        {href=>"/adm/parmset?action=setrestrictmeta",
+        text=>"Restrict Metadata"},
+        {text=>"Order Metadata"});
     $r->print(&Apache::lonhtmlcommon::breadcrumbs('Order Metadata'));
     &startSettingsScreen($r,'parmset',$crstype);
     if ($env{'form.storeorder'}) {
@@ -4679,14 +5389,14 @@ sub order_meta_fields {
         if ($newpos > $currentpos) {
         # moving stuff up
             for ($i=0;$i<$currentpos;$i++) {
-            $neworder[$i]=$oldorder[$i];
+                $neworder[$i]=$oldorder[$i];
             }
             for ($i=$currentpos;$i<$newpos;$i++) {
-            $neworder[$i]=$oldorder[$i+1];
+                $neworder[$i]=$oldorder[$i+1];
             }
             $neworder[$newpos]=$oldorder[$currentpos];
             for ($i=$newpos+1;$i<=$#oldorder;$i++) {
-            $neworder[$i]=$oldorder[$i];
+                $neworder[$i]=$oldorder[$i];
             }
         } else {
         # moving stuff down
@@ -4701,10 +5411,10 @@ sub order_meta_fields {
                 $neworder[$i]=$oldorder[$i];
             }
         }
-    my $ordered_fields = join ",", @neworder;
+        my $ordered_fields = join ",", @neworder;
         my $put_result = &Apache::lonnet::put('environment',
-                           {'metadata.addedorder'=>$ordered_fields},$dom,$crs);
-    &Apache::lonnet::appenv({'course.'.$env{'request.course.id'}.'.metadata.addedorder' => $ordered_fields});
+                        {'metadata.addedorder'=>$ordered_fields},$dom,$crs);
+        &Apache::lonnet::appenv({'course.'.$env{'request.course.id'}.'.metadata.addedorder' => $ordered_fields});
     }
     my $fields = &get_added_meta_fieldnames($env{'request.course.id'});
     my $ordered_fields;
@@ -4744,6 +5454,8 @@ sub order_meta_fields {
 }
 
 
+# Returns HTML with a Continue button redirecting to the initial portfolio metadata screen.
+# @returns {string}
 sub continue {
     my $output;
     $output .= '<form action="" method="post">';
@@ -4753,6 +5465,10 @@ sub continue {
 }
 
 
+# UI to add a metadata field.
+# Currenly does not work because of an HTML error (the field is not visible).
+#
+# @param {Apache2::RequestRec} $r - the Apache request
 sub addmetafield {
     my ($r)=@_;
     &Apache::lonhtmlcommon::add_breadcrumb({href=>'/adm/parmset?action=addmetadata',
@@ -4797,7 +5513,7 @@ sub addmetafield {
             $r->print('<input type="submit" name="undelete" value="Undelete" />');
             $r->print('</form>');
         }
-        $r->print('<hr /><strong>Or</strong> you may enter a new metadata field name.<form method="post" action="/adm/parmset?action=addmetadata"');
+        $r->print('<hr /><strong>Or</strong> you may enter a new metadata field name.<form method="post" action="/adm/parmset?action=addmetadata"'); # FIXME: HTML error, input will not be displayed !
         $r->print('<input type="text" name="fieldname" /><br />');
         $r->print('<input type="submit" value="Add Metadata Field" />');
     }
@@ -4807,6 +5523,9 @@ sub addmetafield {
 
 
 
+# Display or save portfolio metadata.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
 sub setrestrictmeta {
     my ($r)=@_;
     my $next_meta;
@@ -4847,10 +5566,10 @@ sub setrestrictmeta {
                         $options.='deleted,';
                     }
                     my $name = $save_field;
-                     $put_result = &Apache::lonnet::put('environment',
-                                                  {'metadata.'.$meta_field.'.options'=>$options,
-                                                   'metadata.'.$meta_field.'.values'=>$env{'form.'.$meta_field.'_values'},
-                                                   },$dom,$crs);
+                    $put_result = &Apache::lonnet::put('environment',
+                        {'metadata.'.$meta_field.'.options'=>$options,
+                        'metadata.'.$meta_field.'.values'=>$env{'form.'.$meta_field.'_values'},
+                        },$dom,$crs);
                 }
             }
         }
@@ -4866,8 +5585,8 @@ sub setrestrictmeta {
     foreach my $field (sort(keys(%metadata_fields))) {
         if ($field ne 'courserestricted') {
             $row_alt = $row_alt ? 0 : 1;
-        $output.= &output_row($r, $field, $metadata_fields{$field});
-    }
+            $output.= &output_row($r, $field, $metadata_fields{$field});
+        }
     }
     my $buttons = (<<ENDButtons);
         <input type="submit" name="restrictmeta" value="Save" />
@@ -4882,7 +5601,7 @@ ENDButtons
     my $added_flag = 1;
     foreach my $field (sort(keys(%$added_metadata_fields))) {
         $row_alt = $row_alt ? 0 : 1;
-        $output.= &output_row($r, $field, $$added_metadata_fields{$field},$added_flag, $row_alt);
+        $output.= &output_row($r, $field, $$added_metadata_fields{$field},$added_flag, $row_alt); # FIXME: wrong parameters
     }
     $output .= &Apache::loncommon::end_data_table();
     $r->print(<<ENDenv);
@@ -4897,7 +5616,10 @@ ENDenv
 }
 
 
-
+# Returns metadata fields that have been manually added.
+#
+# @param {string} $cid - course id
+# @returns {hash reference} - hash field name -> field title (not localized)
 sub get_added_meta_fieldnames {
     my ($cid) = @_;
     my %fields;
@@ -4912,7 +5634,10 @@ sub get_added_meta_fieldnames {
 }
 
 
-
+# Returns metadata fields that have been manually added and deleted.
+#
+# @param {string} $cid - course id
+# @returns {hash reference} - hash field name -> field title (not localized)
 sub get_deleted_meta_fieldnames {
     my ($cid) = @_;
     my %fields;
@@ -4927,6 +5652,15 @@ sub get_deleted_meta_fieldnames {
     }
     return \%fields;
 }
+
+
+##################################################
+# PARAMETER SETTINGS DEFAULT ACTIONS
+##################################################
+
+# UI to change parameter setting default actions
+#
+# @param {Apache2::RequestRec} $r - the Apache request
 sub defaultsetter {
     my ($r) = @_;
 
@@ -4959,45 +5693,45 @@ sub defaultsetter {
                 \%mapp, \%symbp,\%maptitles,\%uris,
                 \%keyorder,\%defkeytype);
     if ($env{'form.storerules'}) {
-    my %newrules=();
-    my @delrules=();
-    my %triggers=();
-    foreach my $key (keys(%env)) {
+        my %newrules=();
+        my @delrules=();
+        my %triggers=();
+        foreach my $key (keys(%env)) {
             if ($key=~/^form\.(\w+)\_action$/) {
-        my $tempkey=$1;
-        my $action=$env{$key};
+                my $tempkey=$1;
+                my $action=$env{$key};
                 if ($action) {
-            $newrules{$tempkey.'_action'}=$action;
-            if ($action ne 'default') {
-            my ($whichaction,$whichparm)=($action=~/^(.*\_)([^\_]+)$/);
-            $triggers{$whichparm}.=$tempkey.':';
-            }
-            $newrules{$tempkey.'_type'}=$defkeytype{$tempkey};
-            if (&isdateparm($defkeytype{$tempkey})) {
-            $newrules{$tempkey.'_days'}=$env{'form.'.$tempkey.'_days'};
-            $newrules{$tempkey.'_hours'}=$env{'form.'.$tempkey.'_hours'};
-            $newrules{$tempkey.'_min'}=$env{'form.'.$tempkey.'_min'};
-            $newrules{$tempkey.'_sec'}=$env{'form.'.$tempkey.'_sec'};
-            } else {
-            $newrules{$tempkey.'_value'}=$env{'form.'.$tempkey.'_value'};
-            $newrules{$tempkey.'_triggervalue'}=$env{'form.'.$tempkey.'_triggervalue'};
+                    $newrules{$tempkey.'_action'}=$action;
+                    if ($action ne 'default') {
+                        my ($whichaction,$whichparm)=($action=~/^(.*\_)([^\_]+)$/);
+                        $triggers{$whichparm}.=$tempkey.':';
+                    }
+                    $newrules{$tempkey.'_type'}=$defkeytype{$tempkey};
+                    if (&isdateparm($defkeytype{$tempkey})) {
+                        $newrules{$tempkey.'_days'}=$env{'form.'.$tempkey.'_days'};
+                        $newrules{$tempkey.'_hours'}=$env{'form.'.$tempkey.'_hours'};
+                        $newrules{$tempkey.'_min'}=$env{'form.'.$tempkey.'_min'};
+                        $newrules{$tempkey.'_sec'}=$env{'form.'.$tempkey.'_sec'};
+                    } else {
+                        $newrules{$tempkey.'_value'}=$env{'form.'.$tempkey.'_value'};
+                        $newrules{$tempkey.'_triggervalue'}=$env{'form.'.$tempkey.'_triggervalue'};
+                    }
+                } else {
+                    push(@delrules,$tempkey.'_action');
+                    push(@delrules,$tempkey.'_type');
+                    push(@delrules,$tempkey.'_hours');
+                    push(@delrules,$tempkey.'_min');
+                    push(@delrules,$tempkey.'_sec');
+                    push(@delrules,$tempkey.'_value');
+                }
             }
-        } else {
-            push(@delrules,$tempkey.'_action');
-            push(@delrules,$tempkey.'_type');
-            push(@delrules,$tempkey.'_hours');
-            push(@delrules,$tempkey.'_min');
-            push(@delrules,$tempkey.'_sec');
-            push(@delrules,$tempkey.'_value');
         }
+        foreach my $key (keys(%allparms)) {
+            $newrules{$key.'_triggers'}=$triggers{$key};
         }
-    }
-    foreach my $key (keys(%allparms)) {
-        $newrules{$key.'_triggers'}=$triggers{$key};
-    }
-    &Apache::lonnet::put('parmdefactions',\%newrules,$cdom,$cnum);
-    &Apache::lonnet::del('parmdefactions',\@delrules,$cdom,$cnum);
-    &resetrulescache();
+        &Apache::lonnet::put('parmdefactions',\%newrules,$cdom,$cnum);
+        &Apache::lonnet::del('parmdefactions',\@delrules,$cdom,$cnum);
+        &resetrulescache();
     }
     my %lt=&Apache::lonlocal::texthash('days' => 'Days',
                        'hours' => 'Hours',
@@ -5010,75 +5744,75 @@ sub defaultsetter {
     my @dateoptions=('','default');
     my @datedisplay=('',&mt('Default value when manually setting'));
     foreach my $tempkey (&keysindisplayorder(\%allparms,\%keyorder)) {
-    unless ($tempkey) { next; }
-    push @standardoptions,'when_setting_'.$tempkey;
-    push @standarddisplay,&mt('Automatically set when setting ').$tempkey;
-    if (&isdateparm($defkeytype{$tempkey})) {
-        push @dateoptions,'later_than_'.$tempkey;
-        push @datedisplay,&mt('Automatically set later than ').$tempkey;
-        push @dateoptions,'earlier_than_'.$tempkey;
-        push @datedisplay,&mt('Automatically set earlier than ').$tempkey;
-    }
+        unless ($tempkey) { next; }
+        push @standardoptions,'when_setting_'.$tempkey;
+        push @standarddisplay,&mt('Automatically set when setting ').$tempkey;
+        if (&isdateparm($defkeytype{$tempkey})) {
+            push @dateoptions,'later_than_'.$tempkey;
+            push @datedisplay,&mt('Automatically set later than ').$tempkey;
+            push @dateoptions,'earlier_than_'.$tempkey;
+            push @datedisplay,&mt('Automatically set earlier than ').$tempkey;
+        }
     }
-$r->print(&mt('Manual setting rules apply to all interfaces.').'<br />'.
-      &mt('Automatic setting rules apply to table mode interfaces only.'));
+    $r->print(&mt('Manual setting rules apply to all interfaces.').'<br />'.
+        &mt('Automatic setting rules apply to table mode interfaces only.'));
     $r->print("\n".&Apache::loncommon::start_data_table().
           &Apache::loncommon::start_data_table_header_row().
           "<th>".&mt('Rule for parameter').'</th><th>'.
           &mt('Action').'</th><th>'.&mt('Value').'</th>'.
           &Apache::loncommon::end_data_table_header_row());
     foreach my $tempkey (&keysindisplayorder(\%allparms,\%keyorder)) {
-    unless ($tempkey) { next; }
-    $r->print("\n".&Apache::loncommon::start_data_table_row().
-          "<td>".$allparms{$tempkey}."\n<br />(".$tempkey.')</td><td>');
-    my $action=&rulescache($tempkey.'_action');
-    $r->print('<select name="'.$tempkey.'_action">');
-    if (&isdateparm($defkeytype{$tempkey})) {
-        for (my $i=0;$i<=$#dateoptions;$i++) {
-        if ($dateoptions[$i]=~/\_$tempkey$/) { next; }
-        $r->print("\n<option value='$dateoptions[$i]'".
-              ($dateoptions[$i] eq $action?' selected="selected"':'').
-              ">$datedisplay[$i]</option>");
+        unless ($tempkey) { next; }
+        $r->print("\n".&Apache::loncommon::start_data_table_row().
+            "<td>".$allparms{$tempkey}."\n<br />(".$tempkey.')</td><td>');
+        my $action=&rulescache($tempkey.'_action');
+        $r->print('<select name="'.$tempkey.'_action">');
+        if (&isdateparm($defkeytype{$tempkey})) {
+            for (my $i=0;$i<=$#dateoptions;$i++) {
+            if ($dateoptions[$i]=~/\_$tempkey$/) { next; }
+            $r->print("\n<option value='$dateoptions[$i]'".
+                ($dateoptions[$i] eq $action?' selected="selected"':'').
+                ">$datedisplay[$i]</option>");
+            }
+        } else {
+            for (my $i=0;$i<=$#standardoptions;$i++) {
+            if ($standardoptions[$i]=~/\_$tempkey$/) { next; }
+            $r->print("\n<option value='$standardoptions[$i]'".
+                ($standardoptions[$i] eq $action?' selected="selected"':'').
+                ">$standarddisplay[$i]</option>");
+            }
         }
-    } else {
-        for (my $i=0;$i<=$#standardoptions;$i++) {
-        if ($standardoptions[$i]=~/\_$tempkey$/) { next; }
-        $r->print("\n<option value='$standardoptions[$i]'".
-              ($standardoptions[$i] eq $action?' selected="selected"':'').
-              ">$standarddisplay[$i]</option>");
+        $r->print('</select>');
+        unless (&isdateparm($defkeytype{$tempkey})) {
+            $r->print("\n<br />".&mt('Triggering value(s) of other parameter (optional, comma-separated):').
+                '<input type="text" size="20" name="'.$tempkey.'_triggervalue" value="'.&rulescache($tempkey.'_triggervalue').'" />');
         }
-    }
-    $r->print('</select>');
-    unless (&isdateparm($defkeytype{$tempkey})) {
-        $r->print("\n<br />".&mt('Triggering value(s) of other parameter (optional, comma-separated):').
-              '<input type="text" size="20" name="'.$tempkey.'_triggervalue" value="'.&rulescache($tempkey.'_triggervalue').'" />');
-    }
-    $r->print("\n</td><td>\n");
+        $r->print("\n</td><td>\n");
 
         if (&isdateparm($defkeytype{$tempkey})) {
-        my $days=&rulescache($tempkey.'_days');
-        my $hours=&rulescache($tempkey.'_hours');
-        my $min=&rulescache($tempkey.'_min');
-        my $sec=&rulescache($tempkey.'_sec');
-        $r->print(<<ENDINPUTDATE);
-<input name="$tempkey\_days" type="text" size="4" value="$days" />$lt{'days'}<br />
-<input name="$tempkey\_hours" type="text" size="4" value="$hours" />$lt{'hours'}<br />
-<input name="$tempkey\_min" type="text" size="4" value="$min" />$lt{'min'}<br />
-<input name="$tempkey\_sec" type="text" size="4" value="$sec" />$lt{'sec'}
+            my $days=&rulescache($tempkey.'_days');
+            my $hours=&rulescache($tempkey.'_hours');
+            my $min=&rulescache($tempkey.'_min');
+            my $sec=&rulescache($tempkey.'_sec');
+            $r->print(<<ENDINPUTDATE);
+    <input name="$tempkey\_days" type="text" size="4" value="$days" />$lt{'days'}<br />
+    <input name="$tempkey\_hours" type="text" size="4" value="$hours" />$lt{'hours'}<br />
+    <input name="$tempkey\_min" type="text" size="4" value="$min" />$lt{'min'}<br />
+    <input name="$tempkey\_sec" type="text" size="4" value="$sec" />$lt{'sec'}
 ENDINPUTDATE
-    } elsif ($defkeytype{$tempkey} eq 'string_yesno') {
-            my $yeschecked='';
-            my $nochecked='';
-            if (&rulescache($tempkey.'_value') eq 'yes') { $yeschecked=' checked="checked"'; }
-            if (&rulescache($tempkey.'_value') eq 'no') { $nochecked=' checked="checked"'; }
-
-        $r->print(<<ENDYESNO);
-<label><input type="radio" name="$tempkey\_value" value="yes"$yeschecked /> $lt{'yes'}</label><br />
-<label><input type="radio" name="$tempkey\_value" value="no"$nochecked /> $lt{'no'}</label>
+        } elsif ($defkeytype{$tempkey} eq 'string_yesno') {
+                my $yeschecked='';
+                my $nochecked='';
+                if (&rulescache($tempkey.'_value') eq 'yes') { $yeschecked=' checked="checked"'; }
+                if (&rulescache($tempkey.'_value') eq 'no') { $nochecked=' checked="checked"'; }
+
+            $r->print(<<ENDYESNO);
+    <label><input type="radio" name="$tempkey\_value" value="yes"$yeschecked /> $lt{'yes'}</label><br />
+    <label><input type="radio" name="$tempkey\_value" value="no"$nochecked /> $lt{'no'}</label>
 ENDYESNO
         } else {
-        $r->print('<input type="text" size="20" name="'.$tempkey.'_value" value="'.&rulescache($tempkey.'_value').'" />');
-    }
+            $r->print('<input type="text" size="20" name="'.$tempkey.'_value" value="'.&rulescache($tempkey.'_value').'" />');
+        }
         $r->print('</td>'.&Apache::loncommon::end_data_table_row());
     }
     $r->print(&Apache::loncommon::end_data_table().
@@ -5089,28 +5823,54 @@ ENDYESNO
     return;
 }
 
+##################################################
+# PARAMETER CHANGES LOG
+##################################################
+
+# Returns some info for a parameter log entry.
+# Returned entries:
+# $realm - HTML title for the parameter level and resource
+# $section - parameter section
+# $name - parameter name
+# $part - parameter part
+# $what - $part.'.'.$name
+# $middle - resource symb ?
+# $uname - user name (same as given)
+# $udom - user domain (same as given)
+# $issection - section or group name
+# $realmdescription - title for the parameter level and resource (without using HTML)
+#
+# FIXME: remove unused fields.
+#
+# @param {string} $key - parameter log key
+# @param {string} $uname - user name
+# @param {string} $udom - user domain
+# @param {string} $exeuser - unused
+# @param {string} $exedomain - unused
+# @param {boolean} $typeflag - .type log entry
+# @returns {Array}
 sub components {
     my ($key,$uname,$udom,$exeuser,$exedomain,$typeflag)=@_;
 
     if ($typeflag) {
-    $key=~s/\.type$//;
+        $key=~s/\.type$//;
     }
 
     my ($middle,$part,$name)=
-    ($key=~/^$env{'request.course.id'}\.(?:(.+)\.)*([\w\s]+)\.(\w+)$/);
+        ($key=~/^$env{'request.course.id'}\.(?:(.+)\.)*([\w\s]+)\.(\w+)$/);
     my $issection;
 
     my $section=&mt('All Students');
     if ($middle=~/^\[(.*)\]/) {
-    $issection=$1;
-    $section=&mt('Group/Section').': '.$issection;
-    $middle=~s/^\[(.*)\]//;
+        $issection=$1;
+        $section=&mt('Group/Section').': '.$issection;
+        $middle=~s/^\[(.*)\]//;
     }
     $middle=~s/\.+$//;
     $middle=~s/^\.+//;
     if ($uname) {
-    $section=&mt('User').": ".&Apache::loncommon::plainname($uname,$udom);
-    $issection='';
+        $section=&mt('User').": ".&Apache::loncommon::plainname($uname,$udom);
+        $issection='';
     }
     my $realm='<span class="LC_parm_scope_all">'.&mt('All Resources').'</span>';
     my $realmdescription=&mt('all resources');
@@ -5121,32 +5881,37 @@ sub components {
         if ($maplevel eq 'rec') {
             $leveltitle = &mt('Recursive');
         }
-    $realm='<span class="LC_parm_scope_folder">'.$leveltitle.': '.&Apache::lonnet::gettitle($mapurl).' <span class="LC_parm_folder"><br />('.$mapurl.')</span></span>';
-     $realmdescription=&mt('folder').' '.&Apache::lonnet::gettitle($mapurl);
-   } elsif ($middle) {
-    my ($map,$id,$url)=&Apache::lonnet::decode_symb($middle);
-    $realm='<span class="LC_parm_scope_resource">'.&mt('Resource').': '.&Apache::lonnet::gettitle($middle).' <br /><span class="LC_parm_symb">('.$url.' in '.$map.' id: '.$id.')</span></span>';
-    $realmdescription=&mt('resource').' '.&Apache::lonnet::gettitle($middle);
+        $realm='<span class="LC_parm_scope_folder">'.$leveltitle.
+            ': '.&Apache::lonnet::gettitle($mapurl).' <span class="LC_parm_folder"><br />('.
+            $mapurl.')</span></span>';
+        $realmdescription=&mt('folder').' '.&Apache::lonnet::gettitle($mapurl);
+    } elsif ($middle) {
+        my ($map,$id,$url)=&Apache::lonnet::decode_symb($middle);
+        $realm='<span class="LC_parm_scope_resource">'.&mt('Resource').
+            ': '.&Apache::lonnet::gettitle($middle).' <br /><span class="LC_parm_symb">('.$url.
+            ' in '.$map.' id: '.$id.')</span></span>';
+        $realmdescription=&mt('resource').' '.&Apache::lonnet::gettitle($middle);
     }
     my $what=$part.'.'.$name;
     return ($realm,$section,$name,$part,
         $what,$middle,$uname,$udom,$issection,$realmdescription);
 }
 
-my %standard_parms;
-my %standard_parms_types;
+my %standard_parms; # hash parameter name -> parameter title (not localized)
+my %standard_parms_types; # hash parameter name -> parameter type
 
+# Reads parameter info from packages.tab into %standard_parms.
 sub load_parameter_names {
     open(my $config,"<$Apache::lonnet::perlvar{'lonTabDir'}/packages.tab");
     while (my $configline=<$config>) {
-    if ($configline !~ /\S/ || $configline=~/^\#/) { next; }
-    chomp($configline);
-    my ($short,$plain)=split(/:/,$configline);
-    my (undef,$name,$type)=split(/\&/,$short,3);
-    if ($type eq 'display') {
-        $standard_parms{$name} = $plain;
+        if ($configline !~ /\S/ || $configline=~/^\#/) { next; }
+        chomp($configline);
+        my ($short,$plain)=split(/:/,$configline);
+        my (undef,$name,$type)=split(/\&/,$short,3);
+        if ($type eq 'display') {
+            $standard_parms{$name} = $plain;
         } elsif ($type eq 'type') {
-            $standard_parms_types{$name} = $plain;
+                $standard_parms_types{$name} = $plain;
         }
     }
     close($config);
@@ -5154,18 +5919,26 @@ sub load_parameter_names {
     $standard_parms{'int_zero_pos'} = 'Positive Integer or Zero';
 }
 
+# Returns a parameter title for standard parameters, the name for others.
+#
+# @param {string} $name - parameter name
+# @returns {string}
 sub standard_parameter_names {
     my ($name)=@_;
     if (!%standard_parms) {
-    &load_parameter_names();
+        &load_parameter_names();
     }
     if ($standard_parms{$name}) {
-    return $standard_parms{$name};
+        return $standard_parms{$name};
     } else {
-    return $name;
+        return $name;
     }
 }
 
+# Returns a parameter type for standard parameters, undef for others.
+#
+# @param {string} $name - parameter name
+# @returns {string}
 sub standard_parameter_types {
     my ($name)=@_;
     if (!%standard_parms_types) {
@@ -5177,6 +5950,27 @@ sub standard_parameter_types {
     return;
 }
 
+# Returns a parameter level title (not localized) from the parameter level name.
+#
+# @param {string} $name - parameter level name (recognized: resourcelevel|maplevel|maplevelrecurse|courselevel)
+# @returns {string}
+sub standard_parameter_levels {
+    my ($name)=@_;
+    my %levels = (
+                    'resourcelevel'   => 'a single resource',
+                    'maplevel'        => 'the enclosing map/folder', 
+                    'maplevelrecurse' => 'the enclosing map/folder (recursive into sub-folders)',
+                    'courselevel'     => 'the general (course) level',
+                 );
+    if ($levels{$name}) {
+        return $levels{$name};
+    }
+    return;
+}
+
+# Display log for parameter changes, blog postings, user notification changes.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
 sub parm_change_log {
     my ($r)=@_;
     my $cdom = $env{'course.'.$env{'request.course.id'}.'.domain'};
@@ -5218,89 +6012,89 @@ sub parm_change_log {
     my $shown=0;
     my $folder='';
     if ($env{'form.displayfilter'} eq 'currentfolder') {
-    my $last='';
-    if (tie(my %hash,'GDBM_File',$env{'request.course.fn'}.'_symb.db',
-        &GDBM_READER(),0640)) {
-        $last=$hash{'last_known'};
-        untie(%hash);
-    }
-    if ($last) { ($folder) = &Apache::lonnet::decode_symb($last); }
-    }
-    foreach my $id (sort
-            {
-            if ($parmlog{$b}{'exe_time'} ne $parmlog{$a}{'exe_time'}) {
-                return $parmlog{$b}{'exe_time'} <=>$parmlog{$a}{'exe_time'}
-            }
-            my $aid = (split('00000',$a))[-1];
-            my $bid = (split('00000',$b))[-1];
-            return $bid<=>$aid;
+        my $last='';
+        if (tie(my %hash,'GDBM_File',$env{'request.course.fn'}.'_symb.db',
+                &GDBM_READER(),0640)) {
+            $last=$hash{'last_known'};
+            untie(%hash);
+        }
+        if ($last) { ($folder) = &Apache::lonnet::decode_symb($last); }
+    }
+    foreach my $id (sort {
+                if ($parmlog{$b}{'exe_time'} ne $parmlog{$a}{'exe_time'}) {
+                    return $parmlog{$b}{'exe_time'} <=>$parmlog{$a}{'exe_time'}
+                }
+                my $aid = (split('00000',$a))[-1];
+                my $bid = (split('00000',$b))[-1];
+                return $bid<=>$aid;
             } (keys(%parmlog))) {
         my @changes=keys(%{$parmlog{$id}{'logentry'}});
-    my $count = 0;
-    my $time =
-        &Apache::lonlocal::locallocaltime($parmlog{$id}{'exe_time'});
-    my $plainname =
-        &Apache::loncommon::plainname($parmlog{$id}{'exe_uname'},
-                      $parmlog{$id}{'exe_udom'});
-    my $about_me_link =
-        &Apache::loncommon::aboutmewrapper($plainname,
-                           $parmlog{$id}{'exe_uname'},
-                           $parmlog{$id}{'exe_udom'});
-    my $send_msg_link='';
-    if ((($parmlog{$id}{'exe_uname'} ne $env{'user.name'})
-         || ($parmlog{$id}{'exe_udom'} ne $env{'user.domain'}))) {
-        $send_msg_link ='<br />'.
-        &Apache::loncommon::messagewrapper(&mt('Send message'),
-                           $parmlog{$id}{'exe_uname'},
-                           $parmlog{$id}{'exe_udom'});
-    }
-    my $row_start=&Apache::loncommon::start_data_table_row();
-    my $makenewrow=0;
-    my %istype=();
-    my $output;
-    foreach my $changed (reverse(sort(@changes))) {
-            my $value=$parmlog{$id}{'logentry'}{$changed};
-        my $typeflag = ($changed =~/\.type$/ &&
-                !exists($parmlog{$id}{'logentry'}{$changed.'.type'}));
+        my $count = 0;
+        my $time =
+            &Apache::lonlocal::locallocaltime($parmlog{$id}{'exe_time'});
+        my $plainname =
+            &Apache::loncommon::plainname($parmlog{$id}{'exe_uname'},
+                        $parmlog{$id}{'exe_udom'});
+        my $about_me_link =
+            &Apache::loncommon::aboutmewrapper($plainname,
+                            $parmlog{$id}{'exe_uname'},
+                            $parmlog{$id}{'exe_udom'});
+        my $send_msg_link='';
+        if ((($parmlog{$id}{'exe_uname'} ne $env{'user.name'})
+            || ($parmlog{$id}{'exe_udom'} ne $env{'user.domain'}))) {
+            $send_msg_link ='<br />'.
+            &Apache::loncommon::messagewrapper(&mt('Send message'),
+                            $parmlog{$id}{'exe_uname'},
+                            $parmlog{$id}{'exe_udom'});
+        }
+        my $row_start=&Apache::loncommon::start_data_table_row();
+        my $makenewrow=0;
+        my %istype=();
+        my $output;
+        foreach my $changed (reverse(sort(@changes))) {
+                my $value=$parmlog{$id}{'logentry'}{$changed};
+            my $typeflag = ($changed =~/\.type$/ &&
+                    !exists($parmlog{$id}{'logentry'}{$changed.'.type'}));
             my ($realm,$section,$parmname,$part,$what,$middle,$uname,$udom,$issection,$realmdescription)=
-        &components($changed,$parmlog{$id}{'uname'},$parmlog{$id}{'udom'},undef,undef,$typeflag);
-        if ($env{'request.course.sec'} ne '') {
-            next if (($issection ne '') && ($issection ne $env{'request.course.sec'}));
-            if ($uname ne '') {
-                my $stusection = &Apache::lonnet::getsection($uname,$udom,$env{'request.course.id'});
-                next if (($stusection ne '-1') && ($stusection ne $env{'request.course.sec'})); 
-            }
-        }
-        if ($env{'form.displayfilter'} eq 'currentfolder') {
-        if ($folder) {
-            if ($middle!~/^\Q$folder\E/) { next; }
-        }
-        }
-        if ($typeflag) {
-        $istype{$parmname}=$value;
-        if (!$env{'form.includetypes'}) { next; }
-        }
-        $count++;
-        if ($makenewrow) {
-        $output .= $row_start;
-        } else {
-        $makenewrow=1;
-        }
+                &components($changed,$parmlog{$id}{'uname'},$parmlog{$id}{'udom'},undef,undef,$typeflag);
+            if ($env{'request.course.sec'} ne '') {
+                next if (($issection ne '') && ($issection ne $env{'request.course.sec'}));
+                if ($uname ne '') {
+                    my $stusection = &Apache::lonnet::getsection($uname,$udom,$env{'request.course.id'});
+                    next if (($stusection ne '-1') && ($stusection ne $env{'request.course.sec'})); 
+                }
+            }
+            if ($env{'form.displayfilter'} eq 'currentfolder') {
+                if ($folder) {
+                    if ($middle!~/^\Q$folder\E/) { next; }
+                }
+            }
+            if ($typeflag) {
+                $istype{$parmname}=$value;
+                if (!$env{'form.includetypes'}) { next; }
+            }
+            $count++;
+            if ($makenewrow) {
+                $output .= $row_start;
+            } else {
+                $makenewrow=1;
+            }
             my $parmitem = &standard_parameter_names($parmname);
-        $output .='<td>'.$realm.'</td><td>'.$section.'</td><td>'.
-              &mt($parmitem).'</td><td>'.
-              ($part?&mt('Part: [_1]',$part):&mt('All Parts')).'</td><td>';
-        my $stillactive=0;
-        if ($parmlog{$id}{'delflag'}) {
-        $output .= &mt('Deleted');
-        } else {
-        if ($typeflag) {
+            $output .='<td>'.$realm.'</td><td>'.$section.'</td><td>'.
+                &mt($parmitem).'</td><td>'.
+                ($part?&mt('Part: [_1]',$part):&mt('All Parts')).'</td><td>';
+            my $stillactive=0;
+            if ($parmlog{$id}{'delflag'}) {
+                $output .= &mt('Deleted');
+            } else {
+                if ($typeflag) {
                     my $parmitem = &standard_parameter_names($value); 
                     $parmitem = &mt($parmitem);
-            $output .= &mt('Type: [_1]',$parmitem);
-        } else {
-            my ($level,@all)=&parmval_by_symb($what,$middle,&Apache::lonnet::metadata($middle,$what),
-                              $uname,$udom,$issection,$issection,$courseopt);
+                    $output .= &mt('Type: [_1]',$parmitem);
+                } else {
+                    my ($level,@all)=&parmval_by_symb($what,$middle,
+                        &Apache::lonnet::metadata($middle,$what),
+                        $uname,$udom,$issection,$issection,$courseopt);
                     my $showvalue = $value;
                     if ($istype{$parmname} eq '') {
                         my $type = &standard_parameter_types($parmname);
@@ -5311,63 +6105,77 @@ sub parm_change_log {
                             }
                         }
                     } else {
-                if (&isdateparm($istype{$parmname})) {
-                $showvalue = 
-                                &Apache::lonlocal::locallocaltime($value);
-                }
+                        if (&isdateparm($istype{$parmname})) {
+                            $showvalue = &Apache::lonlocal::locallocaltime($value);
+                        }
                     }
                     $output .= $showvalue;
-            if ($value ne $all[$level]) {
-            $output .= '<br /><span class="LC_warning">'.&mt('Not active anymore').'</span>';
-            } else {
-            $stillactive=1;
+                    if ($value ne $all[$level]) {
+                        $output .= '<br /><span class="LC_warning">'.&mt('Not active anymore').'</span>';
+                    } else {
+                        $stillactive=1;
+                    }
+                }
             }
-        }
-        }
-        $output .= '</td><td>';
-            
-        if ($stillactive) {
+            $output .= '</td><td>';
+                
+            if ($stillactive) {
                 my $parmitem = &standard_parameter_names($parmname);
                 $parmitem = &mt($parmitem);
-        my $title=&mt('Changed [_1]',$parmitem);
+                my $title=&mt('Changed [_1]',$parmitem);
                 my $description=&mt('Changed [_1] for [_2] to [_3]',
-                                    $parmitem,$realmdescription,
+                    $parmitem,$realmdescription,
                     (&isdateparm($istype{$parmname})?&Apache::lonlocal::locallocaltime($value):$value));
-        if (($uname) && ($udom)) {
-            $output .=
-            &Apache::loncommon::messagewrapper('Notify User',
-                               $uname,$udom,$title,
-                               $description);
-        } else {
-            $output .=
-            &Apache::lonrss::course_blog_link($id,$title,
-                              $description);
-        }
+                if (($uname) && ($udom)) {
+                    $output .=
+                    &Apache::loncommon::messagewrapper('Notify User',
+                                    $uname,$udom,$title,
+                                    $description);
+                } else {
+                    $output .=
+                    &Apache::lonrss::course_blog_link($id,$title,
+                                    $description);
+                }
+            }
+            $output .= '</td>'.&Apache::loncommon::end_data_table_row();
         }
-        $output .= '</td>'.&Apache::loncommon::end_data_table_row();
-    }
         if ($env{'form.displayfilter'} eq 'containing') {
-        my $wholeentry=$about_me_link.':'.
-        $parmlog{$id}{'exe_uname'}.':'.$parmlog{$id}{'exe_udom'}.':'.
-        $output;
-        if ($wholeentry!~/\Q$env{'form.containingphrase'}\E/i) { next; }
-    }
+            my $wholeentry=$about_me_link.':'.
+            $parmlog{$id}{'exe_uname'}.':'.$parmlog{$id}{'exe_udom'}.':'.
+            $output;
+            if ($wholeentry!~/\Q$env{'form.containingphrase'}\E/i) { next; }
+        }
         if ($count) {
-        $r->print($row_start.'<td rowspan="'.$count.'">'.$time.'</td>
-                       <td rowspan="'.$count.'">'.$about_me_link.
-          '<br /><tt>'.$parmlog{$id}{'exe_uname'}.
-                      ':'.$parmlog{$id}{'exe_udom'}.'</tt>'.
-          $send_msg_link.'</td>'.$output);
-        $shown++;
-    }
-    if (!($env{'form.show'} eq &mt('all')
-          || $shown<=$env{'form.show'})) { last; }
+            $r->print($row_start.'<td rowspan="'.$count.'">'.$time.'</td>
+                        <td rowspan="'.$count.'">'.$about_me_link.
+            '<br /><tt>'.$parmlog{$id}{'exe_uname'}.
+                        ':'.$parmlog{$id}{'exe_udom'}.'</tt>'.
+            $send_msg_link.'</td>'.$output);
+            $shown++;
+        }
+        if (!($env{'form.show'} eq &mt('all')
+            || $shown<=$env{'form.show'})) { last; }
     }
     $r->print(&Apache::loncommon::end_data_table());
     &endSettingsScreen($r);
     $r->print(&Apache::loncommon::end_page());
 }
 
+##################################################
+# MISC !
+##################################################
+
+# Stores slot information.
+# Used by table UI
+# FIXME: I don't understand how this can work when the symb is not defined (if only a map was selected)
+#
+# @param {string} $slot_name - slot name
+# @param {string} $cdom - course domain
+# @param {string} $cnum - course number
+# @param {string} $symb - resource symb
+# @param {string} $uname - user name
+# @param {string} $udom - user domain
+# @returns {string} - 'ok' or error name
 sub update_slots {
     my ($slot_name,$cdom,$cnum,$symb,$uname,$udom) = @_;
     my %slot=&Apache::lonnet::get_slot($slot_name);
@@ -5421,6 +6229,17 @@ sub update_slots {
     return $success;
 }
 
+# Deletes a slot reservation.
+# Used by table UI
+# FIXME: I don't understand how this can work when the symb is not defined (if only a map was selected)
+#
+# @param {string} $slot_name - slot name
+# @param {string} $cdom - course domain
+# @param {string} $cnum - course number
+# @param {string} $uname - user name
+# @param {string} $udom - user domain
+# @param {string} $symb - resource symb
+# @returns {string} - 'ok' or error name
 sub delete_slots {
     my ($slot_name,$cdom,$cnum,$uname,$udom,$symb) = @_;
     my $delresult;
@@ -5456,12 +6275,19 @@ sub delete_slots {
     return $delresult;
 }
 
+# Returns true if there is a current course.
+# Used by handler
+#
+# @returns {boolean}
 sub check_for_course_info {
     my $navmap = Apache::lonnavmaps::navmap->new();
     return 1 if ($navmap);
     return 0;
 }
 
+# Returns the current course host and host LON-CAPA version.
+#
+# @returns {Array} - (course hostname, major version number, minor version number)
 sub parameter_release_vars { 
    my $cdom = $env{'course.'.$env{'request.course.id'}.'.domain'};
    my $chome = $env{'course.'.$env{'request.course.id'}.'.home'};
@@ -5471,21 +6297,57 @@ sub parameter_release_vars {
    return ($chostname,$cmajor,$cminor);
 }
 
+# Checks if the course host version can handle a parameter required version,
+# and if it does, stores the release needed for the course.
+#
+# @param {string} $name - parameter name
+# @param {string} $value - parameter value
+# @param {string} $valmatch - name of the test used for checking the value
+# @param {string} $namematch - name of the test used for checking the name
+# @param {string} $needsrelease - version needed by the parameter, major.minor
+# @param {integer} $cmajor - course major version number
+# @param {integer} $cminor - course minor version number
+# @returns {boolean} - true if a newer version is needed
 sub parameter_releasecheck {
-    my ($name,$value,$valmatch,$needsrelease,$cmajor,$cminor) = @_;
+    my ($name,$value,$valmatch,$namematch,$needsrelease,$cmajor,$cminor) = @_;
     my $needsnewer;
     my ($needsmajor,$needsminor) = split(/\./,$needsrelease);
     if (($cmajor < $needsmajor) || 
         ($cmajor == $needsmajor && $cminor < $needsminor)) {
         $needsnewer = 1;
-    } elsif ($valmatch) {
-        &Apache::lonnet::update_released_required($Apache::lonnet::needsrelease{'parameter:'.$name.'::'.$valmatch});
-    } elsif ($value) { 
-        &Apache::lonnet::update_released_required($Apache::lonnet::needsrelease{'parameter:'.$name.':'.$value.':'});
+    } elsif ($name) {
+        if ($valmatch) {
+            &Apache::lonnet::update_released_required($Apache::lonnet::needsrelease{'parameter:'.$name.'::'.$valmatch.':'});
+        } elsif ($value) { 
+            &Apache::lonnet::update_released_required($Apache::lonnet::needsrelease{'parameter:'.$name.':'.$value.'::'});
+        }
+    } elsif ($namematch) {
+        &Apache::lonnet::update_released_required($Apache::lonnet::needsrelease{'parameter::::'.$namematch});
     }
     return $needsnewer;
 }
 
+##################################################
+# HANDLER
+##################################################
+
+# Main handler for lonparmset.
+# Sub called based on request parameters action and command:
+# no command or action: print_main_menu
+# command 'set': assessparms (direct access to table mode for a resource)
+#                (this can also be accessed simply with the symb parameter)
+# action 'setoverview': overview (display all existing parameter settings)
+# action 'addmetadata': addmetafield (called to add a portfolio metadata field)
+# action 'ordermetadata': order_meta_fields (called to order portfolio metadata fields)
+# action 'setrestrictmeta': setrestrictmeta (display or save portfolio metadata)
+# action 'newoverview': newoverview (overview mode)
+# action 'setdefaults': defaultsetter (UI to change parameter setting default actions)
+# action 'settable': assessparms (table mode)
+# action 'parameterchangelog': parm_change_log (display log for parameter changes,
+#                              blog postings, user notification changes)
+# action 'cleanparameters': clean_parameters (unused)
+# action 'dateshift1': date_shift_one (overview mode, shift all dates)
+# action 'dateshift2': date_shift_two (overview mode, shift all dates)
 sub handler {
     my $r=shift;
 
@@ -5526,28 +6388,28 @@ sub handler {
         # Check first if coming from someone else headed directly for
         #  the table mode
         if ((($env{'form.command'} eq 'set') && ($env{'form.url'})
-         && (!$env{'form.dis'})) || ($env{'form.symb'})) {
-        &assessparms($r);
+                && (!$env{'form.dis'})) || ($env{'form.symb'})) {
+            &assessparms($r);
         } elsif (! exists($env{'form.action'})) {
             &print_main_menu($r,$parm_permission);
         } elsif ($env{'form.action'} eq 'setoverview') {
-        &overview($r);
-    } elsif ($env{'form.action'} eq 'addmetadata') {
-        &addmetafield($r);
-    } elsif ($env{'form.action'} eq 'ordermetadata') {
-        &order_meta_fields($r);
+            &overview($r);
+        } elsif ($env{'form.action'} eq 'addmetadata') {
+            &addmetafield($r);
+        } elsif ($env{'form.action'} eq 'ordermetadata') {
+            &order_meta_fields($r);
         } elsif ($env{'form.action'} eq 'setrestrictmeta') {
-        &setrestrictmeta($r);
+            &setrestrictmeta($r);
         } elsif ($env{'form.action'} eq 'newoverview') {
-        &newoverview($r);
+            &newoverview($r);
         } elsif ($env{'form.action'} eq 'setdefaults') {
-        &defaultsetter($r);
-    } elsif ($env{'form.action'} eq 'settable') {
-        &assessparms($r);
+            &defaultsetter($r);
+        } elsif ($env{'form.action'} eq 'settable') {
+            &assessparms($r);
         } elsif ($env{'form.action'} eq 'parameterchangelog') {
-        &parm_change_log($r);
+            &parm_change_log($r);
         } elsif ($env{'form.action'} eq 'cleanparameters') {
-        &clean_parameters($r);
+            &clean_parameters($r);
         } elsif ($env{'form.action'} eq 'dateshift1') {
             &date_shift_one($r);
         } elsif ($env{'form.action'} eq 'dateshift2') {
@@ -5555,14 +6417,14 @@ sub handler {
         }
     } else {
 # ----------------------------- Not in a course, or not allowed to modify parms
-    if ($exists) {
-        $env{'user.error.msg'}=
-        "/adm/parmset:opa:0:0:Cannot modify assessment parameters";
-    } else {
-        $env{'user.error.msg'}=
-        "/adm/parmset::0:1:Course environment gone, reinitialize the course";
-    }
-    return HTTP_NOT_ACCEPTABLE;
+        if ($exists) {
+            $env{'user.error.msg'}=
+            "/adm/parmset:opa:0:0:Cannot modify assessment parameters";
+        } else {
+            $env{'user.error.msg'}=
+            "/adm/parmset::0:1:Course environment gone, reinitialize the course";
+        }
+        return HTTP_NOT_ACCEPTABLE;
     }
     &reset_caches();