--- loncom/publisher/lonpubdir.pm	2008/08/08 10:08:48	1.110
+++ loncom/publisher/lonpubdir.pm	2008/11/10 13:43:51	1.111
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # Construction Space Directory Lister
 #
-# $Id: lonpubdir.pm,v 1.110 2008/08/08 10:08:48 bisitz Exp $
+# $Id: lonpubdir.pm,v 1.111 2008/11/10 13:43:51 jms Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -27,6 +27,118 @@
 #
 ###
 
+=head1 NAME
+
+Apache::lonpubdir - Construction space directory lister
+
+=head1 SYNOPSIS
+
+Invoked (for various locations) by /etc/httpd/conf/srm.conf:
+
+ <LocationMatch "^/\~.*/$">
+ PerlAccessHandler       Apache::loncacc
+ SetHandler perl-script
+ PerlHandler Apache::lonpubdir
+ ErrorDocument     403 /adm/login
+ ErrorDocument     404 /adm/notfound.html
+ ErrorDocument     406 /adm/unauthorized.html
+ ErrorDocument	  500 /adm/errorhandler
+ </LocationMatch>
+
+ <Location /adm/pubdir>
+ PerlAccessHandler       Apache::lonacc
+ SetHandler perl-script
+ PerlHandler Apache::lonpubdir
+ ErrorDocument     403 /adm/login
+ ErrorDocument     404 /adm/notfound.html
+ ErrorDocument     406 /adm/unauthorized.html
+ ErrorDocument	  500 /adm/errorhandler
+ </Location>
+
+=head1 INTRODUCTION
+
+This module publishes a directory of files.
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+=head1 HANDLER SUBROUTINE
+
+This routine is called by Apache and mod_perl.
+
+=over 4
+
+=item *
+
+read in information
+
+=item *
+
+start page output
+
+=item *
+
+run through list of files and attempt to publish unhidden files
+
+=back
+
+=head2 subroutines:
+
+=head3 startpage($r, $uame, $udom, $thisdisfn)
+
+Output the header of the page.  This includes:
+ - The HTML header 
+ - The H1/H3  stuff which includes the directory.
+ 
+    startpage($r, $uame, $udom, $thisdisfn);
+        $r     - The apache request object.
+        $uname - User name.
+        $udom  - Domain name the user is logged in under.
+        $thisdisfn - Displayable version of the filename.
+
+=head3 getTitleString($fullname)
+
+    Get the title string or "[untitled]" if the file has no title metadata:
+    Without the latter substitution, it's impossible to examine metadata for
+    untitled resources.  Resources may be legitimately untitled, to prevent
+    searches from locating them.
+    
+    $str = getTitleString($fullname);
+        $fullname - Fully qualified filename to check.
+
+=head3 putdirectory(r, base, here, dirname, modtime)
+
+    Put out a directory table row:
+    
+    putdirectory($r, $base, $here, $dirname, $modtime)
+        $r       - Apache request object.
+        $reqfile - File in request.
+        $here    - Where we are in directory tree.
+        $dirname - Name of directory special file.
+        $modtime - Encoded modification time.
+
+=head3 CategorizeFiles($location, $files)
+    
+    Categorize files in the directory.
+    For each file in a list of files in a file directory, 
+    the  file categorized as one of:
+        - directory  
+        - sequence
+        - problem 
+        - Other resource.
+
+    For each file the modification date is determined as well.
+    Returned is a list of sublists:
+        (directories, sequences, problems, other)
+    each of the sublists contains entries of the following form (sorted by filename):
+    (filename, typecode, lastmodtime)
+    
+        $list = CategorizeFiles($location, $files)
+        $location   - Directory in which the files live (relative to our execution)
+        $files      - list of files.
+
+=cut
+
 package Apache::lonpubdir;
 
 use strict;
@@ -785,59 +897,4 @@ sub CategorizeFiles {
 1;
 __END__
 
-=head1 NAME
-
-Apache::lonpubdir - Construction space directory lister
-
-=head1 SYNOPSIS
-
-Invoked (for various locations) by /etc/httpd/conf/srm.conf:
 
- <LocationMatch "^/\~.*/$">
- PerlAccessHandler       Apache::loncacc
- SetHandler perl-script
- PerlHandler Apache::lonpubdir
- ErrorDocument     403 /adm/login
- ErrorDocument     404 /adm/notfound.html
- ErrorDocument     406 /adm/unauthorized.html
- ErrorDocument	  500 /adm/errorhandler
- </LocationMatch>
-
- <Location /adm/pubdir>
- PerlAccessHandler       Apache::lonacc
- SetHandler perl-script
- PerlHandler Apache::lonpubdir
- ErrorDocument     403 /adm/login
- ErrorDocument     404 /adm/notfound.html
- ErrorDocument     406 /adm/unauthorized.html
- ErrorDocument	  500 /adm/errorhandler
- </Location>
-
-=head1 INTRODUCTION
-
-This module publishes a directory of files.
-
-This is part of the LearningOnline Network with CAPA project
-described at http://www.lon-capa.org.
-
-=head1 HANDLER SUBROUTINE
-
-This routine is called by Apache and mod_perl.
-
-=over 4
-
-=item *
-
-read in information
-
-=item *
-
-start page output
-
-=item *
-
-run through list of files and attempt to publish unhidden files
-
-=back
-
-=cut