--- loncom/auth/lonroles.pm	2003/07/05 10:07:11	1.63
+++ loncom/auth/lonroles.pm	2003/08/12 19:46:04	1.66
@@ -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.66 2003/08/12 19:46:04 www Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -570,7 +570,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 +598,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