--- loncom/auth/lonroles.pm	2003/07/05 10:07:11	1.63
+++ loncom/auth/lonroles.pm	2003/07/25 01:16:29	1.64
@@ -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.64 2003/07/25 01:16:29 bowersj2 Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -594,6 +594,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