--- loncom/interface/lonindexer.pm	2001/11/01 15:59:11	1.22
+++ loncom/interface/lonindexer.pm	2001/11/28 16:47:25	1.23
@@ -15,16 +15,34 @@
 # 6/26,7/8 H. K. Ng
 # 8/6,8/7,8/10 Scott Harrison
 # 8/14 H. K. Ng
-# 8/28,10/15 Scott Harrison
+# 8/28,10/15,11/28 Scott Harrison
+#
+# $Id: lonindexer.pm,v 1.23 2001/11/28 16:47:25 harris41 Exp $
+###
+
+###############################################################################
+##                                                                           ##
+## ORGANIZATION OF THIS PERL MODULE                                          ##
+##                                                                           ##
+## 1. Description of functions                                               ##
+## 2. Modules used by this module                                            ##
+## 3. Choices for different output views (detailed, summary, xml, etc)       ##
+## 4. BEGIN block (to be run once after compilation)                         ##
+## 5. Handling routine called via Apache and mod_perl                        ##
+## 6. Other subroutines                                                      ##
+##                                                                           ##
+###############################################################################
 
 package Apache::lonindexer;
 
+# ------------------------------------------------- modules used by this module
 use strict;
 use Apache::lonnet();
 use Apache::Constants qw(:common);
 use Apache::File;
 use GDBM_File;
 
+# ---------------------------------------- variables used throughout the module
 my %hash; # tied to a user-specific gdbm file
 my %dirs; # keys are directories, values are the open/close status
 my %language; # has the reference information present in language.tab
@@ -45,7 +63,7 @@ sub BEGIN {
     } <$fh>;
 }
 
-# ---------------------------------------------------------------- Main Handler
+# ----------------------------- Handling routine called via Apache and mod_perl
 sub handler {
     my $r = shift;
     $r->content_type('text/html');
@@ -55,7 +73,7 @@ sub handler {
     $dnum=0;
     untie %hash;
 
-# --------------------------------------------- machine configuration variables
+# ------------------------------------- read in machine configuration variables
     my $iconpath= $r->dir_config('lonIconsURL') . "/";
     my $domain  = $r->dir_config('lonDefDomain');
     my $role    = $r->dir_config('lonRole');
@@ -232,10 +250,10 @@ ENDHEADER
 	    } keys %hash;
 	}
 	
-# output title
+# ---------------------------------------------------------------- output title
 	$r->print('<h2><font color="#888888">The LearningOnline With CAPA '.
 		  'Network Directory Browser</font></h2>'."\n");
-# get state of file attributes to be showing
+# ---------------------------------- get state of file attributes to be showing
 	if ($ENV{'form.attrs'} ne "") {
 	    for (my $i=0; $i<=6; $i++) {
 		delete $hash{'display_attrs_'.$i};
@@ -249,7 +267,7 @@ ENDHEADER
 		$attrchk[$i] = "checked" if $hash{'display_attrs_'.$i} == 1;
 	    }
 	}
-# output state of file attributes to be showing
+# ------------------------------- output state of file attributes to be showing
 	$r->print(<<END);
 <b><font color="#666666">Display file attributes</font></b><br />
 <form method="post" name="fileattr" action="$uri"
@@ -274,7 +292,7 @@ $groupimportbutton
 </form>
 END
 
-    # output starting row to the indexed file/directory hierarchy
+# ----------------- output starting row to the indexed file/directory hierarchy
         my $titleclr="#ddffff";
         $r->print("<table border=0><tr><td bgcolor=#eeeeee>\n");
 	$r->print("<table border=0><tr>\n");
@@ -293,7 +311,7 @@ END
 	    if ($hash{'display_attrs_5'} == 1);
 	$r->print("</tr>");
 
-	# read in what directories have previously been set to "open"
+# ----------------- read in what directories have previously been set to "open"
 	map {
 	    if ($_ =~ /^diropen_status_/) {
 		my $key = $_;
@@ -331,7 +349,7 @@ END
 	    $toplevel = $hash{'top.level'};
 	}
 
-	# if not at top level, provide an uplink arrow
+# -------------------------------- if not at top level, provide an uplink arrow
 	if ($toplevel ne "/res/"){
 	    my (@uri_com) = split(/\//,$uri);
 	    pop @uri_com;
@@ -341,18 +359,18 @@ END
 	    $indent = 1;
 	}
 
-	# recursively go through all the directories and output as appropriate
+# -------- recursively go through all the directories and output as appropriate
 	&scanDir ($r,$toplevel,$indent,\%hash);
 	
-	# information useful for group import
+# ---------------------------- embed hidden information useful for group import
 	$r->print("<form name='fnum'>");
 	$r->print("<input type='hidden' name='fnum' value='$fnum'></form>");
 
-	# end the tables
+# -------------------------------------------------------------- end the tables
 	$r->print("</table>");
 	$r->print("</td></tr></table>");
 
-	# end the output and return
+# --------------------------------------------------- end the output and return
 	$r->print("</body></html>\n");
 	untie(%hash);
     } else {
@@ -363,7 +381,6 @@ END
     return OK;
 }
 
-
 # ----------------------------------------------- recursive scan of a directory
 sub scanDir {
     my ($r,$startdir,$indent,$hashref)=@_;
@@ -471,7 +488,7 @@ sub match_ext {
 }
 
 # ------------------------------- displays one line in appropriate table format
-sub display_line{
+sub display_line {
     my ($r,$diropen,$line,$indent,$startdir,$hashref,@list)=@_;
     my (@pathfn, $fndir, $fnptr);
     my $dirptr=16384;
@@ -740,4 +757,149 @@ sub start_fresh_session {
 }
 
 1;
-__END__
+
+=head1 NAME
+
+Apache::lonindexer - mod_perl module for cross server filesystem browsing
+
+=head1 SYNOPSIS
+
+Invoked by /etc/httpd/conf/srm.conf:
+
+ <LocationMatch "^/res.*/$">
+ SetHandler perl-script
+ PerlHandler Apache::lonindexer
+ </LocationMatch>
+
+=head1 INTRODUCTION
+
+This module enables a scheme of browsing across a cross server.
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+=head1 BEGIN SUBROUTINE
+
+This routine is only run once after compilation.
+
+=over 4
+
+=item *
+
+Initializes %language hash table.
+
+=back
+
+=head1 HANDLER SUBROUTINE
+
+This routine is called by Apache and mod_perl.
+
+=over 4
+
+=item *
+
+read in machine configuration variables
+
+=item *
+
+see if called from an interactive mode
+
+=item *
+
+refresh environment with user database values (in %hash)
+
+=item *
+
+define extra fields and buttons in case of special mode
+
+=item *
+
+set catalogmodefunctions to have extra needed javascript functionality
+
+=item *
+
+print header
+
+=item *
+
+evaluate actions from previous page (both cumulatively and chronologically)
+
+=item *
+
+output title
+
+=item *
+
+get state of file attributes to be showing
+
+=item *
+
+output state of file attributes to be showing
+
+=item *
+
+output starting row to the indexed file/directory hierarchy
+
+=item *
+
+read in what directories have previously been set to "open"
+
+=item *
+
+if not at top level, provide an uplink arrow
+
+=item *
+
+recursively go through all the directories and output as appropriate
+
+=item *
+
+information useful for group import
+
+=item *
+
+end the tables
+
+=item *
+
+end the output and return
+
+=back
+
+=head1 OTHER SUBROUTINES
+
+=over 4
+
+=item *
+
+scanDir - recursive scan of a directory
+
+=item *
+
+get_list - get complete matched list based on the uri (returns an array)
+
+=item *
+
+match_ext - filters out files based on extensions (returns an array)
+
+=item *
+
+display_line - displays one line in appropriate table format
+
+=item *
+
+begin_form - prints the beginning of a form for directory or file link
+
+=item *
+
+get_unprocessed_cgi - grab unprocessed CGI variables that may have been
+appended to URL
+
+=item *
+
+start_fresh_session - settings whenever the user causes the indexer window
+to be launched
+
+=back
+
+=cut