--- loncom/interface/loncommon.pm	2002/04/23 21:00:01	1.34
+++ loncom/interface/loncommon.pm	2002/04/23 21:42:01	1.35
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # a pile of common routines
 #
-# $Id: loncommon.pm,v 1.34 2002/04/23 21:00:01 matthew Exp $
+# $Id: loncommon.pm,v 1.35 2002/04/23 21:42:01 matthew Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -38,6 +38,40 @@
 # Inputs result_from_symbread, user, domain, course_id
 # Reads in non-network-related .tab files
 
+# POD header:
+
+=head1 NAME
+
+Apache::loncommon - pile of common routines
+
+=head1 SYNOPSIS
+
+Referenced by other mod_perl Apache modules.
+
+Invocation:
+ &Apache::loncommon::SUBROUTINENAME(ARGUMENTS);
+
+=head1 INTRODUCTION
+
+Common collection of used subroutines.  This collection helps remove
+redundancy from other modules and increase efficiency of memory usage.
+
+Current things done:
+
+ Makes a table out of the previous homework attempts
+ Inputs result_from_symbread, user, domain, course_id
+ Reads in non-network-related .tab files
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+=head2 Subroutines
+
+=over 4
+
+=cut 
+
+# End of POD header
 package Apache::loncommon;
 
 use strict;
@@ -65,6 +99,14 @@ my $thethreshold=0.1/$thefuzzy;
 my $theavecount;
 
 # ----------------------------------------------------------------------- BEGIN
+=item BEGIN() 
+
+Initialize values from language.tab, copyright.tab, filetypes.tab,
+and filecategories.tab.
+
+=cut
+# ----------------------------------------------------------------------- BEGIN
+
 BEGIN {
 
     unless ($readit) {
@@ -149,6 +191,16 @@ BEGIN {
 ###############################################################
 ##        Home server <option> list generating code          ##
 ###############################################################
+#-------------------------------------------
+
+=item get_domains()
+
+Returns an array containing each of the domains listed in the hosts.tab
+file.
+
+=cut
+
+#-------------------------------------------
 sub get_domains {
     # The code below was stolen from "The Perl Cookbook", p 102, 1st ed.
     my @domains;
@@ -159,6 +211,17 @@ sub get_domains {
     return @domains;
 }
 
+#-------------------------------------------
+
+=item select_dom_form($defdom,$name)
+
+Returns a string containing a <select name='$name' size='1'> form to 
+allow a user to select the domain to preform an operation in.  
+See loncreateuser.pm for an example invocation and use.
+
+=cut
+
+#-------------------------------------------
 sub select_dom_form {
     my ($defdom,$name) = @_;
     my @domains = get_domains();
@@ -172,6 +235,17 @@ sub select_dom_form {
     return $selectdomain;
 }
 
+#-------------------------------------------
+
+=item get_home_servers($domain)
+
+Returns a hash which contains keys like '103l3' and values like 
+'kirk.lite.msu.edu'.  All of the keys will be for machines in the
+given $domain.
+
+=cut
+
+#-------------------------------------------
 sub get_home_servers {
     my $domain = shift;
     my %home_servers;
@@ -183,6 +257,16 @@ sub get_home_servers {
     return %home_servers;
 }
 
+#-------------------------------------------
+
+=item home_server_option_list($domain)
+
+returns a string which contains an <option> list to be used in a 
+<select> form input.  See loncreateuser.pm for an example.
+
+=cut
+
+#-------------------------------------------
 sub home_server_option_list {
     my $domain = shift;
     my %servers = &get_home_servers($domain);
@@ -205,6 +289,35 @@ sub home_server_option_list {
 ## hash, and have reasonable default values.
 ##
 ##    formname = the name given in the <form> tag.
+#-------------------------------------------
+
+=item authform_xxxxxx
+
+The authform_xxxxxx subroutines provide javascript and html forms which 
+handle some of the conveniences required for authentication forms.  
+This is not an optimal method, but it works.  
+
+See loncreateuser.pm for invocation and use examples.
+
+=over 4
+
+=item authform_header
+
+=item authform_authorwarning
+
+=item authform_nochange
+
+=item authform_kerberos
+
+=item authform_internal
+
+=item authform_filesystem
+
+=back
+
+=cut
+
+#-------------------------------------------
 sub authform_header{  
     my %in = (
         formname => 'cu',
@@ -846,110 +959,71 @@ sub csv_samples_select_table {
 1;
 __END__;
 
+=item languageids() 
 
-=head1 NAME
-
-Apache::loncommon - pile of common routines
-
-=head1 SYNOPSIS
-
-Referenced by other mod_perl Apache modules.
-
-Invocation:
- &Apache::loncommon::SUBROUTINENAME(ARGUMENTS);
-
-=head1 INTRODUCTION
-
-Common collection of used subroutines.  This collection helps remove
-redundancy from other modules and increase efficiency of memory usage.
-
-Current things done:
-
- Makes a table out of the previous homework attempts
- Inputs result_from_symbread, user, domain, course_id
- Reads in non-network-related .tab files
-
-This is part of the LearningOnline Network with CAPA project
-described at http://www.lon-capa.org.
-
-=head1 HANDLER SUBROUTINE
-
-There is no handler subroutine.
-
-=head1 OTHER SUBROUTINES
-
-=over 4
-
-=item *
-
-BEGIN() : initialize values from language.tab, copyright.tab, filetypes.tab,
-and filecategories.tab.
-
-=item *
-
-languageids() : returns list of all language ids
+returns list of all language ids
 
-=item *
+=item languagedescription() 
 
-languagedescription() : returns description of a specified language id
+returns description of a specified language id
 
-=item *
+=item copyrightids() 
 
-copyrightids() : returns list of all copyrights
+returns list of all copyrights
 
-=item *
+=item copyrightdescription() 
 
-copyrightdescription() : returns description of a specified copyright id
+returns description of a specified copyright id
 
-=item *
+=item filecategories() 
 
-filecategories() : returns list of all file categories
+returns list of all file categories
 
-=item *
+=item filecategorytypes() 
 
-filecategorytypes() : returns list of file types belonging to a given file
+returns list of file types belonging to a given file
 category
 
-=item *
+=item fileembstyle() 
 
-fileembstyle() : returns embedding style for a specified file type
+returns embedding style for a specified file type
 
-=item *
+=item filedescription() 
 
-filedescription() : returns description for a specified file type
+returns description for a specified file type
 
-=item *
+=item filedescriptionex() 
 
-filedescriptionex() : returns description for a specified file type with
+returns description for a specified file type with
 extra formatting
 
-=item *
+=item get_previous_attempt() 
 
-get_previous_attempt() : return string with previous attempt on problem
+return string with previous attempt on problem
 
-=item *
+=item get_student_view() 
 
-get_student_view() : show a snapshot of what student was looking at
+show a snapshot of what student was looking at
 
-=item *
+=item get_student_answers() 
 
-get_student_answers() : show a snapshot of how student was answering problem
+show a snapshot of how student was answering problem
 
-=item *
+=item get_unprocessed_cgi() 
 
-get_unprocessed_cgi() : get unparsed CGI parameters
+get unparsed CGI parameters
 
-=item *
+=item cacheheader() 
 
-cacheheader() : returns cache-controlling header code
+returns cache-controlling header code
 
-=item *
+=item nocache() 
 
-nocache() : specifies header code to not have cache
+specifies header code to not have cache
 
-=item *
+=item add_to_env($name,$value) 
 
-add_to_env($name,$value) : adds $name to the %ENV hash with value
+adds $name to the %ENV hash with value
 $value, if $name already exists, the entry is converted to an array
 reference and $value is added to the array.