--- loncom/auth/lonroles.pm	2003/07/05 10:07:11	1.63
+++ loncom/auth/lonroles.pm	2003/09/11 20:03:28	1.67
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # User Roles Screen
 #
-# $Id: lonroles.pm,v 1.63 2003/07/05 10:07:11 www Exp $
+# $Id: lonroles.pm,v 1.67 2003/09/11 20:03:28 albertel Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -171,7 +171,11 @@ ENDENTERKEY
 			    &Apache::lonuserstate::readmap($cdom.'/'.$cnum);
 			if (($ENV{'form.orgurl'}) && 
 			    ($ENV{'form.orgurl'}!~/^\/adm\/flip/)) {
-			    $r->internal_redirect($ENV{'form.orgurl'});
+			    my $dest=$ENV{'form.orgurl'};
+			    if ( Apache::exists_config_define("MODPERL2") ) {
+				&Apache::lonnet::cleanenv();
+			    }
+			    $r->internal_redirect($dest);
 			    return OK;
 			} else {
 			    unless ($ENV{'request.course.id'}) {
@@ -179,7 +183,7 @@ ENDENTERKEY
 				      "request.course.id"  => $cdom.'_'.$cnum);
 				$furl='/adm/roles?tryagain=1';
 				$msg=
-	 '<h1><font color=red>Could not initialize course at this time.</font></h1><h3>Please try again.</h3>';
+	 '<h1><font color=red>Could not initialize course at this time.</font></h1><h3>Please try again.</h3>'.$ferr;
 			    }
 
 			    # Check to see if the user is a CC entering a course 
@@ -570,7 +574,11 @@ ENDHEADER
 	    }
 	}
     }
-
+    $r->print(&Apache::lonnet::getannounce());
+    if ($advanced) {
+	$r->print('<p><small><i>This is LON-CAPA '.
+		  $r->dir_config('lonVersion').'</i></small></p>');
+    }
     $r->print("</body></html>\n");
     return OK;
 } 
@@ -594,6 +602,36 @@ Invoked by /etc/httpd/conf/srm.conf:
  ErrorDocument	  500 /adm/errorhandler
  </Location>
 
+=head1 OVERVIEW
+
+=head2 Choosing Roles
+
+C<lonroles> is a handler that allows a user to switch roles in
+mid-session. LON-CAPA attempts to work with "No Role Specified", the
+default role that a user has before selecting a role, as widely as
+possible, but certain handlers for example need specification which
+course they should act on, etc. Both in this scenario, and when the
+handler determines via C<lonnet>'s C<&allowed> function that a certain
+action is not allowed, C<lonroles> is used as error handler. This
+allows the user to select another role which may have permission to do
+what they were trying to do. C<lonroles> can also be accessed via the
+B<CRS> button in the Remote Control. 
+
+=begin latex
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=0.45\paperwidth,keepaspectratio]{Sample_Roles_Screen}
+  \caption{\label{Sample_Roles_Screen}Sample Roles Screen} 
+\end{center}
+\end{figure}
+
+=end latex
+
+=head2 Role Initialization
+
+The privileges for a user are established at login time and stored in the session environment. As a consequence, a new role does not become active till the next login. Handlers are able to query for privileges using C<lonnet>'s C<&allowed> function. When a user first logs in, their role is the "common" role, which means that they have the sum of all of their privileges. During a session it might become necessary to choose a particular role, which as a consequence also limits the user to only the privileges in that particular role.
+
 =head1 INTRODUCTION
 
 This module enables a user to select what role he wishes to