[LON-CAPA-cvs] cvs: loncom /html/adm/help/tex Latex_Header.tex /interface loncreateuser.pm lonmsg.pm lonnavmaps.pm /lonnet/perl lonnet.pm
bowersj2
lon-capa-cvs@mail.lon-capa.org
Fri, 25 Jul 2003 01:18:04 -0000
This is a MIME encoded message
--bowersj21059095884
Content-Type: text/plain
bowersj2 Thu Jul 24 21:18:04 2003 EDT
Modified files:
/loncom/html/adm/help/tex Latex_Header.tex
/loncom/interface loncreateuser.pm lonmsg.pm lonnavmaps.pm
/loncom/lonnet/perl lonnet.pm
Log:
Documentation updates
--bowersj21059095884
Content-Type: text/plain
Content-Disposition: attachment; filename="bowersj2-20030724211804.txt"
Index: loncom/html/adm/help/tex/Latex_Header.tex
diff -u loncom/html/adm/help/tex/Latex_Header.tex:1.4 loncom/html/adm/help/tex/Latex_Header.tex:1.5
--- loncom/html/adm/help/tex/Latex_Header.tex:1.4 Tue Jun 10 16:47:10 2003
+++ loncom/html/adm/help/tex/Latex_Header.tex Thu Jul 24 21:18:04 2003
@@ -5,10 +5,12 @@
%\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage{geometry}
-\geometry{verbose,letterpaper,tmargin=1.25in,bmargin=1in,lmargin=1in,rmargin=1in}\pagestyle{headings}
+\geometry{verbose,letterpaper,tmargin=1.25in,bmargin=.25in,lmargin=1in,rmargin=1in}\pagestyle{headings}
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{longtable}
+\usepackage{makeidx}
+\makeindex
\makeatletter
Index: loncom/interface/loncreateuser.pm
diff -u loncom/interface/loncreateuser.pm:1.65 loncom/interface/loncreateuser.pm:1.66
--- loncom/interface/loncreateuser.pm:1.65 Sat Jul 19 20:39:01 2003
+++ loncom/interface/loncreateuser.pm Thu Jul 24 21:18:04 2003
@@ -1,7 +1,7 @@
# The LearningOnline Network with CAPA
# Create a user
#
-# $Id: loncreateuser.pm,v 1.65 2003/07/20 00:39:01 www Exp $
+# $Id: loncreateuser.pm,v 1.66 2003/07/25 01:18:04 bowersj2 Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -28,6 +28,36 @@
###
package Apache::loncreateuser;
+
+=pod
+
+=head1 NAME
+
+Apache::loncreateuser - handler to create users and custom roles
+
+=head1 SYNOPSIS
+
+Apache::loncreateuser provides an Apache handler for creating users,
+ editing their login parameters, roles, and removing roles, and
+ also creating and assigning custom roles.
+
+=head1 OVERVIEW
+
+=head2 Custom Roles
+
+In LON-CAPA, roles are actually collections of privileges. "Teaching
+Assistant", "Course Coordinator", and other such roles are really just
+collection of privileges that are useful in many circumstances.
+
+Creating custom roles can be done by the Domain Coordinator through
+the Create User functionality. That screen will show all privileges
+that can be assigned to users. For a complete list of privileges,
+please see C</home/httpd/lonTabs/rolesplain.tab>.
+
+Custom role definitions are stored in the C<roles.db> file of the role
+author.
+
+=cut
use strict;
use Apache::Constants qw(:common :http);
Index: loncom/interface/lonmsg.pm
diff -u loncom/interface/lonmsg.pm:1.57 loncom/interface/lonmsg.pm:1.58
--- loncom/interface/lonmsg.pm:1.57 Sat Jul 5 06:07:11 2003
+++ loncom/interface/lonmsg.pm Thu Jul 24 21:18:04 2003
@@ -1,7 +1,7 @@
# The LearningOnline Network with CAPA
# Routines for messaging
#
-# $Id: lonmsg.pm,v 1.57 2003/07/05 10:07:11 www Exp $
+# $Id: lonmsg.pm,v 1.58 2003/07/25 01:18:04 bowersj2 Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -44,6 +44,68 @@
#
package Apache::lonmsg;
+=pod
+
+=head1 NAME
+
+Apache::lonmsg: supports internal messaging
+
+=head1 SYNOPSIS
+
+lonmsg provides routines for sending messages, receiving messages, and
+a handler to allow users to read, send, and delete messages.
+
+=head1 OVERVIEW
+
+=head2 Messaging Overview
+
+X<messages>LON-CAPA provides an internal messaging system similar to
+email, but customized for LON-CAPA's usage. LON-CAPA implements its
+own messaging system, rather then building on top of email, because of
+the features LON-CAPA messages can offer that conventional e-mail can
+not:
+
+=over 4
+
+=item * B<Critical messages>: A message the recipient B<must>
+acknowlegde receipt of before they are allowed to continue using the
+system, preventing a user from claiming they never got a message
+
+=item * B<Receipts>: LON-CAPA can reliably send reciepts informing the
+sender that it has been read; again, useful for preventing students
+from claiming they did not see a message. (While conventional e-mail
+has some reciept support, it's sporadic, e-mail client-specific, and
+generally the receiver can opt to not send one, making it useless in
+this case.)
+
+=item * B<Context>: LON-CAPA knows about the sender, such as where
+they are in a course. When a student mails an instructor asking for
+help on the problem, the instructor receives not just the student's
+question, but all submissions the student has made up to that point,
+the user's rendering of the problem, and the complete view the student
+saw of the resource, including discussion up to that point. Finally,
+the instructor is reading all of this inside of LON-CAPA, not their
+email program, so they have full access to LON-CAPA's grading
+interface, or other features they may wish to use in response to the
+student's query.
+
+=back
+
+Users can ask LON-CAPA to forward messages to conventional e-mail
+addresses on their B<PREF> screen, but generally, LON-CAPA messages
+are much more useful then traditional email can be made to be, even
+with HTML support.
+
+Right now, this document will cover just how to send a message, since
+it is likely you will not need to programmatically read messages,
+since lonmsg already implements that functionality.
+
+=head1 FUNCTIONS
+
+=over 4
+
+=cut
+
use strict;
use Apache::lonnet();
use vars qw($msgcount);
@@ -192,6 +254,13 @@
# =============================== Automated message to the author of a resource
+=pod
+
+=item * B<author_res_msg($filename, $message)>: Sends message $message to the owner
+ of the resource with the URI $filename.
+
+=cut
+
sub author_res_msg {
my ($filename,$message)=@_;
unless ($message) { return 'empty'; }
@@ -255,6 +324,14 @@
# New routine that respects "forward" and calls old routine
+=pod
+
+=item * B<user_crit_msg($user, $domain, $subject, $message, $sendback)>: Sends
+ a critical message $message to the $user at $domain. If $sendback is true,
+ a reciept will be sent to the current user when $user recieves the message.
+
+=cut
+
sub user_crit_msg {
my ($user,$domain,$subject,$message,$sendback)=@_;
my $status='';
@@ -335,6 +412,14 @@
# New routine that respects "forward" and calls old routine
+=pod
+
+=item * B<user_normal_msg($user, $domain, $subject, $message,
+ $citation, $baseurl, $attachmenturl)>: Sends a message to the
+ $user at $domain, with subject $subject and message $message.
+
+=cut
+
sub user_normal_msg {
my ($user,$domain,$subject,$message,$citation,$baseurl,$attachmenturl)=@_;
my $status='';
@@ -969,6 +1054,12 @@
BEGIN {
$msgcount=0;
}
+
+=pod
+
+=back
+
+=end
1;
__END__
Index: loncom/interface/lonnavmaps.pm
diff -u loncom/interface/lonnavmaps.pm:1.217 loncom/interface/lonnavmaps.pm:1.218
--- loncom/interface/lonnavmaps.pm:1.217 Mon Jul 21 16:25:42 2003
+++ loncom/interface/lonnavmaps.pm Thu Jul 24 21:18:04 2003
@@ -1,7 +1,7 @@
# The LearningOnline Network with CAPA
# Navigate Maps Handler
#
-# $Id: lonnavmaps.pm,v 1.217 2003/07/21 20:25:42 bowersj2 Exp $
+# $Id: lonnavmaps.pm,v 1.218 2003/07/25 01:18:04 bowersj2 Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -564,11 +564,11 @@
=head1 OVERVIEW
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".
+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
Index: loncom/lonnet/perl/lonnet.pm
diff -u loncom/lonnet/perl/lonnet.pm:1.393 loncom/lonnet/perl/lonnet.pm:1.394
--- loncom/lonnet/perl/lonnet.pm:1.393 Sat Jul 19 20:39:02 2003
+++ loncom/lonnet/perl/lonnet.pm Thu Jul 24 21:18:04 2003
@@ -1,7 +1,7 @@
# The LearningOnline Network
# TCP networking package
#
-# $Id: lonnet.pm,v 1.393 2003/07/20 00:39:02 www Exp $
+# $Id: lonnet.pm,v 1.394 2003/07/25 01:18:04 bowersj2 Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -4246,45 +4246,125 @@
=back
-=head1 INTRODUCTION
+=head1 OVERVIEW
-This module provides subroutines which interact with the
-lonc/lond (TCP) network layer of LON-CAPA. And Can be used to ask about
-- classes
-- users
-- resources
+lonnet provides subroutines which interact with the
+lonc/lond (TCP) network layer of LON-CAPA. They can be used to ask
+about classes, users, and resources.
For many of these objects you can also use this to store data about
them or modify them in various ways.
-This is part of the LearningOnline Network with CAPA project
-described at http://www.lon-capa.org.
+=head2 Symbs
-=head1 RETURN MESSAGES
+To identify a specific instance of a resource, LON-CAPA uses symbols
+or "symbs"X<symb>. These identifiers are built from the URL of the
+map, the resource number of the resource in the map, and the URL of
+the resource itself. The latter is somewhat redundant, but might help
+if maps change.
-=over 4
+An example is
-=item *
+ msu/korte/parts/part1.sequence___19___msu/korte/tests/part12.problem
-con_lost : unable to contact remote host
+The respective map entry is
-=item *
+ <resource id="19" src="/res/msu/korte/tests/part12.problem"
+ title="Problem 2">
+ </resource>
-con_delayed : unable to contact remote host, message will be delivered
-when the connection is brought back up
+Symbs are used by the random number generator, as well as to store and
+restore data specific to a certain instance of for example a problem.
-=item *
+=head2 Storing And Retrieving Data
-con_failed : unable to contact remote host and unable to save message
-for later delivery
+X<store()>X<cstore()>X<restore()>Three of the most important functions
+in C<lonnet.pm> are C<&Apache::lonnet::cstore()>,
+C<&Apache::lonnet:restore()>, and C<&Apache::lonnet::store()>, which
+is is the non-critical message twin of cstore. These functions are for
+handlers to store a perl hash to a user's permanent data space in an
+easy manner, and to retrieve it again on another call. It is expected
+that a handler would use this once at the beginning to retrieve data,
+and then again once at the end to send only the new data back.
-=item *
+The data is stored in the user's data directory on the user's
+homeserver under the ID of the course.
-error: : an error a occured, a description of the error follows the :
+The hash that is returned by restore will have all of the previous
+value for all of the elements of the hash.
-=item *
+Example:
+
+ #creating a hash
+ my %hash;
+ $hash{'foo'}='bar';
+
+ #storing it
+ &Apache::lonnet::cstore(\%hash);
-no_such_host : unable to fund a host associated with the user/domain
+ #changing a value
+ $hash{'foo'}='notbar';
+
+ #adding a new value
+ $hash{'bar'}='foo';
+ &Apache::lonnet::cstore(\%hash);
+
+ #retrieving the hash
+ my %history=&Apache::lonnet::restore();
+
+ #print the hash
+ foreach my $key (sort(keys(%history))) {
+ print("\%history{$key} = $history{$key}");
+ }
+
+Will print out:
+
+ %history{1:foo} = bar
+ %history{1:keys} = foo:timestamp
+ %history{1:timestamp} = 990455579
+ %history{2:bar} = foo
+ %history{2:foo} = notbar
+ %history{2:keys} = foo:bar:timestamp
+ %history{2:timestamp} = 990455580
+ %history{bar} = foo
+ %history{foo} = notbar
+ %history{timestamp} = 990455580
+ %history{version} = 2
+
+Note that the special hash entries C<keys>, C<version> and
+C<timestamp> were added to the hash. C<version> will be equal to the
+total number of versions of the data that have been stored. The
+C<timestamp> attribute will be the UNIX time the hash was
+stored. C<keys> is available in every historical section to list which
+keys were added or changed at a specific historical revision of a
+hash.
+
+B<Warning>: do not store the hash that restore returns directly. This
+will cause a mess since it will restore the historical keys as if the
+were new keys. I.E. 1:foo will become 1:1:foo etc.
+
+Calling convention:
+
+ my %record=&Apache::lonnet::restore($symb,$courseid,$domain,$uname,$home);
+ &Apache::lonnet::cstore(\%newrecord,$symb,$courseid,$domain,$uname,$home);
+
+For more detailed information, see lonnet specific documentation.
+
+=head1 RETURN MESSAGES
+
+=over 4
+
+=item * B<con_lost>: unable to contact remote host
+
+=item * B<con_delayed>: unable to contact remote host, message will be delivered
+when the connection is brought back up
+
+=item * B<con_failed>: unable to contact remote host and unable to save message
+for later delivery
+
+=item * B<error:>: an error a occured, a description of the error follows the :
+
+=item * B<no_such_host>: unable to fund a host associated with the user/domain
that was requested
=back
@@ -4295,15 +4375,18 @@
=over 4
-=item *
-
-appenv(%hash) : the value of %hash is written to the user envirnoment
-file, and will be restored for each access this user makes during this
-session, also modifies the %ENV for the current process
+=item *
+X<appenv()>
+B<appenv(%hash)>: the value of %hash is written to
+the user envirnoment file, and will be restored for each access this
+user makes during this session, also modifies the %ENV for the current
+process
=item *
-
-delenv($regexp) : removes all items from the session environment file that matches the regular expression in $regexp. The values are also delted from the current processes %ENV.
+X<delenv()>
+B<delenv($regexp)>: removes all items from the session
+environment file that matches the regular expression in $regexp. The
+values are also delted from the current processes %ENV.
=back
@@ -4312,50 +4395,51 @@
=over 4
=item *
-
-queryauthenticate($uname,$udom) : try to determine user's current
+X<queryauthenticate()>
+B<queryauthenticate($uname,$udom)>: try to determine user's current
authentication scheme
=item *
-
-authenticate($uname,$upass,$udom) : try to authenticate user from domain's lib
-servers (first use the current one), $upass should be the users password
+X<authenticate()>
+B<authenticate($uname,$upass,$udom)>: try to
+authenticate user from domain's lib servers (first use the current
+one). C<$upass> should be the users password.
=item *
-
-homeserver($uname,$udom) : find the server which has the user's
-directory and files (there must be only one), this caches the answer,
-and also caches if there is a borken connection.
+X<homeserver()>
+B<homeserver($uname,$udom)>: find the server which has
+the user's directory and files (there must be only one), this caches
+the answer, and also caches if there is a borken connection.
=item *
-
-idget($udom,@ids) : find the usernames behind a list of IDs (IDs are a
-unique resource in a domain, there must be only 1 ID per username, and
-only 1 username per ID in a specific domain) (returns hash:
-id=>name,id=>name)
+X<idget()>
+B<idget($udom,@ids)>: find the usernames behind a list of IDs
+(IDs are a unique resource in a domain, there must be only 1 ID per
+username, and only 1 username per ID in a specific domain) (returns
+hash: id=>name,id=>name)
=item *
-
-idrget($udom,@unames) : find the IDs behind a list of usernames (returns hash:
-name=>id,name=>id)
+X<idrget()>
+B<idrget($udom,@unames)>: find the IDs behind a list of
+usernames (returns hash: name=>id,name=>id)
=item *
-
-idput($udom,%ids) : store away a list of names and associated IDs
+X<idput()>
+B<idput($udom,%ids)>: store away a list of names and associated IDs
=item *
-
-rolesinit($udom,$username,$authhost) : get user privileges
+X<rolesinit()>
+B<rolesinit($udom,$username,$authhost)>: get user privileges
=item *
-
-usection($udom,$uname,$cname) : finds the section of student in the
+X<usection()>
+B<usection($udom,$uname,$cname)>: finds the section of student in the
course $cname, return section name/number or '' for "not in course"
and '-1' for "no section"
=item *
-
-userenvironment($udom,$uname,@what) : gets the values of the keys
+X<userenvironment()>
+B<userenvironment($udom,$uname,@what)>: gets the values of the keys
passed in @what from the requested user's environment, returns a hash
=back
--bowersj21059095884--