--- loncom/interface/lonnavmaps.pm	2003/07/17 18:40:49	1.216
+++ loncom/interface/lonnavmaps.pm	2003/08/07 17:26:44	1.221
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # Navigate Maps Handler
 #
-# $Id: lonnavmaps.pm,v 1.216 2003/07/17 18:40:49 bowersj2 Exp $
+# $Id: lonnavmaps.pm,v 1.221 2003/08/07 17:26:44 bowersj2 Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -129,9 +129,7 @@ sub real_handler {
     $r->send_http_header;
 
     # Create the nav map
-    my $navmap = Apache::lonnavmaps::navmap->new(
-                        $ENV{"request.course.fn"}.".db",
-                        $ENV{"request.course.fn"}."_parms.db", 1, 1);
+    my $navmap = Apache::lonnavmaps::navmap->new();
 
 
     if (!defined($navmap)) {
@@ -161,11 +159,6 @@ sub real_handler {
 
     $r->rflush();
 
-    # Now that we've displayed some stuff to the user, init the navmap
-    $navmap->init();
-
-    $r->rflush();
-
     # Check that it's defined
     if (!($navmap->courseMapDefined())) {
         $r->print('<font size="+2" color="red">Coursemap undefined.</font>' .
@@ -552,7 +545,8 @@ sub timeToHumanString {
 
 =head1 NAME
 
-Apache::lonnavmap - Subroutines to handle and render the navigation maps
+Apache::lonnavmap - Subroutines to handle and render the navigation
+    maps
 
 =head1 SYNOPSIS
 
@@ -562,12 +556,12 @@ other modules.
 
 =head1 OVERVIEW
 
-When a user enters a course, LON-CAPA examines the course structure
-and caches it in what is often referred to as the "big hash". You
-can see it if you are logged into LON-CAPA, in a course, by going
-to /adm/test. (You may need to tweak the /home/httpd/lonTabs/htpasswd
-file to view it.) The content of the hash will be under the heading
-"Big Hash".
+X<lonnavmaps, overview> When a user enters a course, LON-CAPA examines the
+course structure and caches it in what is often referred to as the
+"big hash" X<big hash>. You can see it if you are logged into
+LON-CAPA, in a course, by going to /adm/test. (You may need to
+tweak the /home/httpd/lonTabs/htpasswd file to view it.) The
+content of the hash will be under the heading "Big Hash".
 
 Big Hash contains, among other things, how resources are related
 to each other (next/previous), what resources are maps, which 
@@ -716,9 +710,7 @@ to override vertical and horizontal alig
 
 =head2 Parameters
 
-Most of these parameters are only useful if you are *not* using the
-folder interface (i.e., the default first column), which is probably
-the common case. If you are using this interface, then you should be
+Minimally, you should be
 able to get away with just using 'cols' (to specify the columns
 shown), 'url' (necessary for the folders to link to the current screen
 correctly), and possibly 'queryString' if your app calls for it. In
@@ -1173,12 +1165,9 @@ sub render {
     if (!$ENV{'form.folderManip'} && !defined($args->{'iterator'})) {
         # Step 1: Check to see if we have a navmap
         if (!defined($navmap)) {
-            $navmap = Apache::lonnavmaps::navmap->new(
-                        $ENV{"request.course.fn"}.".db",
-                        $ENV{"request.course.fn"}."_parms.db", 1, 1);
+            $navmap = Apache::lonnavmaps::navmap->new();
             $mustCloseNavMap = 1;
         }
-        $navmap->init();
 
         # Step two: Locate what kind of here marker is necessary
         # Determine where the "here" marker is and where the screen jumps to.
@@ -1239,13 +1228,9 @@ sub render {
         
         # Step 1: Check to see if we have a navmap
         if (!defined($navmap)) {
-            $navmap = Apache::lonnavmaps::navmap->new($r, 
-                        $ENV{"request.course.fn"}.".db",
-                        $ENV{"request.course.fn"}."_parms.db", 1, 1);
+            $navmap = Apache::lonnavmaps::navmap->new();
             $mustCloseNavMap = 1;
         }
-        # Paranoia: Make sure it's ready
-        $navmap->init();
 
         # See if we're being passed a specific map
         if ($args->{'iterator_map'}) {
@@ -1605,29 +1590,59 @@ package Apache::lonnavmaps::navmap;
 
 =head1 Object: Apache::lonnavmaps::navmap
 
-You must obtain resource objects through the navmap object.
+=head2 Overview
+
+The navmap object's job is to provide access to the resources
+in the course as Apache::lonnavmaps::resource objects, and to
+query and manage the relationship between those resource objects.
+
+Generally, you'll use the navmap object in one of three basic ways.
+In order of increasing complexity and power:
+
+=over 4
+
+=item * C<$navmap-E<gt>getByX>, where X is B<Id>, B<Symb>, B<Url> or B<MapPc>. This provides
+    various ways to obtain resource objects, based on various identifiers.
+    Use this when you want to request information about one object or 
+    a handful of resources you already know the identities of, from some
+    other source. For more about Ids, Symbs, and MapPcs, see the
+    Resource documentation. Note that Url should be a B<last resort>,
+    not your first choice; it only works when there is only one
+    instance of the resource in the course, which only applies to
+    maps, and even that may change in the future.
+
+=item * C<my @resources = $navmap-E<gt>retrieveResources(args)>. This
+    retrieves resources matching some criterion and returns them
+    in a flat array, with no structure information. Use this when
+    you are manipulating a series of resources, based on what map
+    the are in, but do not care about branching, or exactly how
+    the maps and resources are related. This is the most common case.
+
+=item * C<$it = $navmap-E<gt>getIterator(args)>. This allows you traverse
+    the course's navmap in various ways without writing the traversal
+    code yourself. See iterator documentation below. Use this when
+    you need to know absolutely everything about the course, including
+    branches and the precise relationship between maps and resources.
+
+=back
+
+=head2 Creation And Destruction
 
-=head2 Creation
+To create a navmap object, use the following function:
 
 =over 4
 
-=item * B<new>(navHashFile, parmHashFile, genCourseAndUserOptions,
-  genMailDiscussStatus, getUserData):
+=item * B<Apache::lonnavmaps::navmap-E<gt>new>():
 
-Binds a new navmap object to the compiled nav map hash and parm hash
-given as filenames. genCourseAndUserOptions is a flag saying whether
-the course options and user options hash should be generated. This is
-for when you are using the parameters of the resources that require
-them; see documentation in resource object
-documentation. genMailDiscussStatus causes the nav map to retreive
-information about the email and discussion status of
-resources. Returns the navmap object if this is successful, or
-B<undef> if not. You must check for undef; errors will occur when you
-try to use the other methods otherwise. getUserData, if true, will 
-retreive the user's performance data for various problems.
+Creates a new navmap object. Returns the navmap object if this is
+successful, or B<undef> if not.
 
 =back
 
+When you are done with the $navmap object, you I<must> call 
+$navmap->untieHashes(), or you'll prevent the current user from using that 
+course until the web server is restarted. (!)
+
 =head2 Methods
 
 =over 4
@@ -1647,12 +1662,6 @@ sub new {
     my $class = ref($proto) || $proto;
     my $self = {};
 
-    $self->{NAV_HASH_FILE} = shift;
-    $self->{PARM_HASH_FILE} = shift;
-    $self->{GENERATE_COURSE_USER_OPT} = shift;
-    $self->{GENERATE_EMAIL_DISCUSS_STATUS} = shift;
-    $self->{GET_USER_DATA} = shift;
-
     # Resource cache stores navmap resources as we reference them. We generate
     # them on-demand so we don't pay for creating resources unless we use them.
     $self->{RESOURCE_CACHE} = {};
@@ -1665,12 +1674,13 @@ sub new {
 
     my %navmaphash;
     my %parmhash;
-    if (!(tie(%navmaphash, 'GDBM_File', $self->{NAV_HASH_FILE},
+    my $courseFn = $ENV{"request.course.fn"};
+    if (!(tie(%navmaphash, 'GDBM_File', "${courseFn}.db",
               &GDBM_READER(), 0640))) {
         return undef;
     }
     
-    if (!(tie(%parmhash, 'GDBM_File', $self->{PARM_HASH_FILE},
+    if (!(tie(%parmhash, 'GDBM_File', "${courseFn}_parms.db",
               &GDBM_READER(), 0640)))
     {
         untie %{$self->{PARM_HASH}};
@@ -1679,128 +1689,134 @@ sub new {
 
     $self->{NAV_HASH} = \%navmaphash;
     $self->{PARM_HASH} = \%parmhash;
-    $self->{INITED} = 0;
+    $self->{PARM_CACHE} = {};
 
     bless($self);
         
     return $self;
 }
 
-sub init {
+sub generate_course_user_opt {
     my $self = shift;
-    if ($self->{INITED}) { return; }
+    if ($self->{COURSE_USER_OPT_GENERATED}) { return; }
 
-    # If the course opt hash and the user opt hash should be generated,
-    # generate them
-    if ($self->{GENERATE_COURSE_USER_OPT}) {
-        my $uname=$ENV{'user.name'};
-        my $udom=$ENV{'user.domain'};
-        my $uhome=$ENV{'user.home'};
-        my $cid=$ENV{'request.course.id'};
-        my $chome=$ENV{'course.'.$cid.'.home'};
-        my ($cdom,$cnum)=split(/\_/,$cid);
-        
-        my $userprefix=$uname.'_'.$udom.'_';
-        
-        my %courserdatas; my %useropt; my %courseopt; my %userrdatas;
-        unless ($uhome eq 'no_host') { 
+    my $uname=$ENV{'user.name'};
+    my $udom=$ENV{'user.domain'};
+    my $uhome=$ENV{'user.home'};
+    my $cid=$ENV{'request.course.id'};
+    my $chome=$ENV{'course.'.$cid.'.home'};
+    my ($cdom,$cnum)=split(/\_/,$cid);
+    
+    my $userprefix=$uname.'_'.$udom.'_';
+    
+    my %courserdatas; my %useropt; my %courseopt; my %userrdatas;
+    unless ($uhome eq 'no_host') { 
 # ------------------------------------------------- Get coursedata (if present)
-            unless ((time-$courserdatas{$cid.'.last_cache'})<240) {
-                my $reply=&Apache::lonnet::reply('dump:'.$cdom.':'.$cnum.
-                                                 ':resourcedata',$chome);
-                # Check for network failure
-                if ( $reply =~ /no.such.host/i || $reply =~ /con_lost/i) {
-                    $self->{NETWORK_FAILURE} = 1;
-                } elsif ($reply!~/^error\:/) {
-                    $courserdatas{$cid}=$reply;
-                    $courserdatas{$cid.'.last_cache'}=time;
-                }
-            }
-            foreach (split(/\&/,$courserdatas{$cid})) {
-                my ($name,$value)=split(/\=/,$_);
-                $courseopt{$userprefix.&Apache::lonnet::unescape($name)}=
-                    &Apache::lonnet::unescape($value);
-            }
+	unless ((time-$courserdatas{$cid.'.last_cache'})<240) {
+	    my $reply=&Apache::lonnet::reply('dump:'.$cdom.':'.$cnum.
+					     ':resourcedata',$chome);
+	    # Check for network failure
+	    if ( $reply =~ /no.such.host/i || $reply =~ /con_lost/i) {
+		$self->{NETWORK_FAILURE} = 1;
+	    } elsif ($reply!~/^error\:/) {
+		$courserdatas{$cid}=$reply;
+		$courserdatas{$cid.'.last_cache'}=time;
+	    }
+	}
+	foreach (split(/\&/,$courserdatas{$cid})) {
+	    my ($name,$value)=split(/\=/,$_);
+	    $courseopt{$userprefix.&Apache::lonnet::unescape($name)}=
+		&Apache::lonnet::unescape($value);
+	}
 # --------------------------------------------------- Get userdata (if present)
-            unless ((time-$userrdatas{$uname.'___'.$udom.'.last_cache'})<240) {
-                my $reply=&Apache::lonnet::reply('dump:'.$udom.':'.$uname.':resourcedata',$uhome);
-                if ($reply!~/^error\:/) {
-                    $userrdatas{$uname.'___'.$udom}=$reply;
-                    $userrdatas{$uname.'___'.$udom.'.last_cache'}=time;
-                }
-                # check to see if network failed
-                elsif ( $reply=~/no.such.host/i || $reply=~/con.*lost/i )
-                {
-                    $self->{NETWORK_FAILURE} = 1;
-                }
-            }
-            foreach (split(/\&/,$userrdatas{$uname.'___'.$udom})) {
-                my ($name,$value)=split(/\=/,$_);
-                $useropt{$userprefix.&Apache::lonnet::unescape($name)}=
-                    &Apache::lonnet::unescape($value);
-            }
-            $self->{COURSE_OPT} = \%courseopt;
-            $self->{USER_OPT} = \%useropt;
-        }
-    }   
-
-    if ($self->{GENERATE_EMAIL_DISCUSS_STATUS}) {
-        my $cid=$ENV{'request.course.id'};
-        my ($cdom,$cnum)=split(/\_/,$cid);
-        
-        my %emailstatus = &Apache::lonnet::dump('email_status');
-        my $logoutTime = $emailstatus{'logout'};
-        my $courseLeaveTime = $emailstatus{'logout_'.$ENV{'request.course.id'}};
-        $self->{LAST_CHECK} = (($courseLeaveTime > $logoutTime) ?
-                               $courseLeaveTime : $logoutTime);
-        my %discussiontime = &Apache::lonnet::dump('discussiontimes', 
-                                                   $cdom, $cnum);
-        my %feedback=();
-        my %error=();
-        my $keys = &Apache::lonnet::reply('keys:'.
-                                          $ENV{'user.domain'}.':'.
-                                          $ENV{'user.name'}.':nohist_email',
-                                          $ENV{'user.home'});
-
-        foreach my $msgid (split(/\&/, $keys)) {
-            $msgid=&Apache::lonnet::unescape($msgid);
-            my $plain=&Apache::lonnet::unescape(&Apache::lonnet::unescape($msgid));
-            if ($plain=~/(Error|Feedback) \[([^\]]+)\]/) {
-                my ($what,$url)=($1,$2);
-                my %status=
-                    &Apache::lonnet::get('email_status',[$msgid]);
-                if ($status{$msgid}=~/^error\:/) { 
-                    $status{$msgid}=''; 
-                }
-                
-                if (($status{$msgid} eq 'new') || 
-                    (!$status{$msgid})) { 
-                    if ($what eq 'Error') {
-                        $error{$url}.=','.$msgid; 
-                    } else {
-                        $feedback{$url}.=','.$msgid;
-                    }
-                }
-            }
-        }
-        
-        $self->{FEEDBACK} = \%feedback;
-        $self->{ERROR_MSG} = \%error; # what is this? JB
-        $self->{DISCUSSION_TIME} = \%discussiontime;
-        $self->{EMAIL_STATUS} = \%emailstatus;
-        
+	unless ((time-$userrdatas{$uname.'___'.$udom.'.last_cache'})<240) {
+	    my $reply=&Apache::lonnet::reply('dump:'.$udom.':'.$uname.':resourcedata',$uhome);
+	    if ($reply!~/^error\:/) {
+		$userrdatas{$uname.'___'.$udom}=$reply;
+		$userrdatas{$uname.'___'.$udom.'.last_cache'}=time;
+	    }
+	    # check to see if network failed
+	    elsif ( $reply=~/no.such.host/i || $reply=~/con.*lost/i )
+	    {
+		$self->{NETWORK_FAILURE} = 1;
+	    }
+	}
+	foreach (split(/\&/,$userrdatas{$uname.'___'.$udom})) {
+	    my ($name,$value)=split(/\=/,$_);
+	    $useropt{$userprefix.&Apache::lonnet::unescape($name)}=
+		&Apache::lonnet::unescape($value);
+	}
+	$self->{COURSE_OPT} = \%courseopt;
+	$self->{USER_OPT} = \%useropt;
     }
 
-    if ($self->{GET_USER_DATA}) {
-	# Retreive performance data on problems
-	my %student_data = Apache::lonnet::currentdump($ENV{'request.course.id'},
-						       $ENV{'user.domain'},
-						       $ENV{'user.name'});
-	$self->{STUDENT_DATA} = \%student_data;
+    $self->{COURSE_USER_OPT_GENERATED} = 1;
+    
+    return;
+}
+
+sub generate_email_discuss_status {
+    my $self = shift;
+    if ($self->{EMAIL_DISCUSS_GENERATED}) { return; }
+
+    my $cid=$ENV{'request.course.id'};
+    my ($cdom,$cnum)=split(/\_/,$cid);
+    
+    my %emailstatus = &Apache::lonnet::dump('email_status');
+    my $logoutTime = $emailstatus{'logout'};
+    my $courseLeaveTime = $emailstatus{'logout_'.$ENV{'request.course.id'}};
+    $self->{LAST_CHECK} = (($courseLeaveTime > $logoutTime) ?
+			   $courseLeaveTime : $logoutTime);
+    my %discussiontime = &Apache::lonnet::dump('discussiontimes', 
+					       $cdom, $cnum);
+    my %feedback=();
+    my %error=();
+    my $keys = &Apache::lonnet::reply('keys:'.
+				      $ENV{'user.domain'}.':'.
+				      $ENV{'user.name'}.':nohist_email',
+				      $ENV{'user.home'});
+    
+    foreach my $msgid (split(/\&/, $keys)) {
+	$msgid=&Apache::lonnet::unescape($msgid);
+	my $plain=&Apache::lonnet::unescape(&Apache::lonnet::unescape($msgid));
+	if ($plain=~/(Error|Feedback) \[([^\]]+)\]/) {
+	    my ($what,$url)=($1,$2);
+	    my %status=
+		&Apache::lonnet::get('email_status',[$msgid]);
+	    if ($status{$msgid}=~/^error\:/) { 
+		$status{$msgid}=''; 
+	    }
+	    
+	    if (($status{$msgid} eq 'new') || 
+		(!$status{$msgid})) { 
+		if ($what eq 'Error') {
+		    $error{$url}.=','.$msgid; 
+		} else {
+		    $feedback{$url}.=','.$msgid;
+		}
+	    }
+	}
     }
+    
+    $self->{FEEDBACK} = \%feedback;
+    $self->{ERROR_MSG} = \%error; # what is this? JB
+    $self->{DISCUSSION_TIME} = \%discussiontime;
+    $self->{EMAIL_STATUS} = \%emailstatus;
+    
+    $self->{EMAIL_DISCUSS_GENERATED} = 1;
+}
 
-    $self->{PARM_CACHE} = {};
-    $self->{INITED} = 1;
+sub get_user_data {
+    my $self = shift;
+    if ($self->{RETRIEVED_USER_DATA}) { return; }
+
+    # Retrieve performance data on problems
+    my %student_data = Apache::lonnet::currentdump($ENV{'request.course.id'},
+						   $ENV{'user.domain'},
+						   $ENV{'user.name'});
+    $self->{STUDENT_DATA} = \%student_data;
+
+    $self->{RETRIEVED_USER_DATA} = 1;
 }
 
 # Internal function: Takes a key to look up in the nav hash and implements internal
@@ -1810,6 +1826,15 @@ sub navhash {
     return $self->{NAV_HASH}->{$key};
 }
 
+=pod
+
+=item * B<courseMapDefined>(): Returns true if the course map is defined, 
+    false otherwise. Undefined course maps indicate an error somewhere in
+    LON-CAPA, and you will not be able to proceed with using the navmap.
+    See the B<NAV> screen for an example of using this.
+
+=cut
+
 # Checks to see if coursemap is defined, matching test in old lonnavmaps
 sub courseMapDefined {
     my $self = shift;
@@ -1839,6 +1864,9 @@ sub untieHashes {
 sub hasDiscussion {
     my $self = shift;
     my $symb = shift;
+    
+    $self->generate_email_discuss_status();
+
     if (!defined($self->{DISCUSSION_TIME})) { return 0; }
 
     #return defined($self->{DISCUSSION_TIME}->{$symb});
@@ -1853,6 +1881,8 @@ sub getFeedback {
     my $self = shift;
     my $symb = shift;
 
+    $self->generate_email_discuss_status();
+
     if (!defined($self->{FEEDBACK})) { return ""; }
     
     return $self->{FEEDBACK}->{$symb};
@@ -1862,7 +1892,9 @@ sub getFeedback {
 sub getErrors { 
     my $self = shift;
     my $src = shift;
-    
+
+    $self->generate_email_discuss_status();
+
     if (!defined($self->{ERROR_MSG})) { return ""; }
     return $self->{ERROR_MSG}->{$src};
 }
@@ -1891,7 +1923,6 @@ the given map. This is one of the proper
 # The strategy here is to cache the resource objects, and only construct them
 # as we use them. The real point is to prevent reading any more from the tied
 # hash then we have to, which should hopefully alleviate speed problems.
-# Caching is just an incidental detail I throw in because it makes sense.
 
 sub getById {
     my $self = shift;
@@ -1974,7 +2005,10 @@ sub parmval {
 
 sub parmval_real {
     my $self = shift;
-    my ($what,$symb) = @_;
+    my ($what,$symb,$recurse) = @_;
+
+    # Make sure the {USER_OPT} and {COURSE_OPT} hashes are populated
+    $self->generate_course_user_opt();
 
     my $cid=$ENV{'request.course.id'};
     my $csec=$ENV{'request.course.sec'};
@@ -2046,9 +2080,12 @@ sub parmval_real {
 	my $id=pop(@parts);
 	my $part=join('_',@parts);
 	if ($part eq '') { $part='0'; }
-	my $partgeneral=$self->parmval($part.".$qualifier",$symb);
+	my $partgeneral=$self->parmval($part.".$qualifier",$symb,1);
 	if (defined($partgeneral)) { return $partgeneral; }
     }
+    if ($recurse) { return undef; }
+    my $pack_def=&Apache::lonnet::packages_tab_default($fn,'resource.'.$what);
+    if (defined($pack_def)) { return $pack_def; }
     return '';
 }
 
@@ -2248,21 +2285,21 @@ new branch. The possible tokens are:
 
 =over 4
 
-=item * BEGIN_MAP:
+=item * B<BEGIN_MAP>:
 
 A new map is being recursed into. This is returned I<after> the map
 resource itself is returned.
 
-=item * END_MAP:
+=item * B<END_MAP>:
 
 The map is now done.
 
-=item * BEGIN_BRANCH:
+=item * B<BEGIN_BRANCH>:
 
 A branch is now starting. The next resource returned will be the first
 in that branch.
 
-=item * END_BRANCH:
+=item * B<END_BRANCH>:
 
 The branch is now done.
 
@@ -2819,8 +2856,9 @@ use Apache::lonnet;
 
 =pod
 
-=head1 Object: resource
+=head1 Object: resource 
 
+X<resource, navmap object>
 A resource object encapsulates a resource in a resource map, allowing
 easy manipulation of the resource, querying the properties of the
 resource (including user properties), and represents a reference that
@@ -2840,24 +2878,52 @@ writing, there is no way to override thi
 parts will never be returned, nor will their response types or ids be
 stored.
 
-=head2 Public Members
-
-resource objects have a hash called DATA ($resourceRef->{DATA}) that
-you can store whatever you want in. This allows you to easily do
-two-pass algorithms without worrying about managing your own
-resource->data hash.
-
-=head2 Methods
-
-=over 4
+=head2 Overview
 
-=item * B<new>($navmapRef, $idString):
-
-The first arg is a reference to the parent navmap object. The second
-is the idString of the resource itself. Very rarely, if ever, called
-directly. Use the nav map->getByID() method.
-
-=back
+A B<Resource> is the most granular type of object in LON-CAPA that can
+be included in a course. It can either be a particular resource, like
+an HTML page, external resource, problem, etc., or it can be a
+container sequence, such as a "page" or a "map".
+
+To see a sequence from the user's point of view, please see the
+B<Creating a Course: Maps and Sequences> chapter of the Author's
+Manual.
+
+A Resource Object, once obtained from a navmap object via a B<getBy*>
+method of the navmap, or from an iterator, allows you to query
+information about that resource.
+
+Generally, you do not ever want to create a resource object yourself,
+so creation has been left undocumented. Always retrieve resources
+from navmap objects.
+
+=head3 Identifying Resources
+
+X<big hash>Every resource is identified by a Resource ID in the big hash that is
+unique to that resource for a given course. X<resource ID, in big hash>
+The Resource ID has the form #.#, where the first number is the same
+for every resource in a map, and the second is unique. For instance,
+for a course laid out like this:
+
+ * Problem 1
+ * Map
+   * Resource 2
+   * Resource 3
+
+C<Problem 1> and C<Map> will share a first number, and C<Resource 2>
+C<Resource 3> will share a first number. The second number may end up
+re-used between the two groups.
+
+The resource ID is only used in the big hash, but can be used in the
+context of a course to identify a resource easily. (For instance, the
+printing system uses it to record which resources from a sequence you 
+wish to print.)
+
+X<symb> X<resource, symb>
+All resources also have B<symb>s, which uniquely identify a resource
+in a course. Many internal LON-CAPA functions expect a symb. A symb
+carries along with it the URL of the resource, and the map it appears
+in. Symbs are much larger then resource IDs.
 
 =cut
 
@@ -2896,14 +2962,21 @@ sub navHash {
 
 =pod
 
-B<Metadata Retreival>
+=head2 Methods
+
+Once you have a resource object, here's what you can do with it:
+
+=head3 Attribute Retrieval
 
-These are methods that help you retrieve metadata about the resource:
-Method names are based on the fields in the compiled course
-representation.
+Every resource has certain attributes that can be retrieved and used:
 
 =over 4
 
+=item * B<ID>: Every resource has an ID that is unique for that
+    resource in the course it is in. The ID is actually in the hash
+    representing the resource, so for a resource object $res, obtain
+    it via C<$res->{ID}).
+
 =item * B<compTitle>:
 
 Returns a "composite title", that is equal to $res->title() if the
@@ -2914,11 +2987,6 @@ resource has a title, and is otherwise t
 
 Returns true if the resource is external.
 
-=item * B<goesto>:
-
-Returns the "goesto" value from the compiled nav map. (It is likely
-you want to use B<getNext> instead.)
-
 =item * B<kind>:
 
 Returns the kind of the resource from the compiled nav map.
@@ -2946,11 +3014,6 @@ Returns the symb for the resource.
 
 Returns the title of the resource.
 
-=item * B<to>:
-
-Returns the "to" value from the compiled nav map. (It is likely you
-want to use B<getNext> instead.)
-
 =back
 
 =cut
@@ -2960,6 +3023,7 @@ want to use B<getNext> instead.)
 sub comesfrom { my $self=shift; return $self->navHash("comesfrom_", 1); }
 sub ext { my $self=shift; return $self->navHash("ext_", 1) eq 'true:'; }
 sub from { my $self=shift; return $self->navHash("from_", 1); }
+# considered private and undocumented
 sub goesto { my $self=shift; return $self->navHash("goesto_", 1); }
 sub kind { my $self=shift; return $self->navHash("kind_", 1); }
 sub randomout { my $self=shift; return $self->navHash("randomout_", 1); }
@@ -2988,6 +3052,7 @@ sub title {
 	return $ENV{'course.'.$ENV{'request.course.id'}.'.description'};
     }
     return $self->navHash("title_", 1); }
+# considered private and undocumented
 sub to { my $self=shift; return $self->navHash("to_", 1); }
 sub compTitle {
     my $self = shift;
@@ -3223,6 +3288,7 @@ sub answerdate {
 }
 sub awarded { 
     my $self = shift; my $part = shift;
+    $self->{NAV_MAP}->get_user_data();
     if (!defined($part)) { $part = '0'; }
     return $self->{NAV_MAP}->{STUDENT_DATA}->{$self->symb()}->{'resource.'.$part.'.awarded'};
 }