--- loncom/publisher/lonpublisher.pm	2002/08/09 17:57:48	1.89
+++ loncom/publisher/lonpublisher.pm	2002/08/09 17:59:14	1.90
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # Publication Handler
 #
-# $Id: lonpublisher.pm,v 1.89 2002/08/09 17:57:48 matthew Exp $
+# $Id: lonpublisher.pm,v 1.90 2002/08/09 17:59:14 matthew Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -61,6 +61,43 @@
 ##                                                                           ##
 ###############################################################################
 
+
+######################################################################
+######################################################################
+
+=pod 
+
+=head1 Name
+
+lonpublisher - LON-CAPA publishing handler
+
+=head1 Synopsis
+
+lonpublisher takes the proper steps to add resources to the LON-CAPA
+digital library.  This includes updating the metadata table in the
+LON-CAPA database.
+
+=head1 Description
+
+lonpublisher is many things to many people.  
+To all people it is woefully documented.  
+This documentation conforms to this standard.
+
+This module publishes a file.  This involves gathering metadata,
+versioning the file, copying file from construction space to
+publication space, and copying metadata from construction space
+to publication space.
+
+=head2 Internal Functions
+
+=over 4
+
+=cut
+
+######################################################################
+######################################################################
+
+
 package Apache::lonpublisher;
 
 # ------------------------------------------------- modules used by this module
@@ -88,7 +125,19 @@ my $docroot;
 my $cuname;
 my $cudom;
 
-# ----------------------------------------------- Evaluate string with metadata
+#########################################
+#########################################
+
+=pod
+
+=item metaeval
+
+Evaluate string with metadata
+
+=cut
+
+#########################################
+#########################################
 sub metaeval {
     my $metastring=shift;
    
@@ -131,7 +180,19 @@ sub metaeval {
        }
 }
 
-# -------------------------------------------------------- Read a metadata file
+#########################################
+#########################################
+
+=pod
+
+=item metaread
+
+Read a metadata file
+
+=cut
+
+#########################################
+#########################################
 sub metaread {
     my ($logfile,$fn)=@_;
     unless (-e $fn) {
@@ -148,7 +209,19 @@ sub metaread {
     return '<br><b>Processed file:</b> <tt>'.$fn.'</tt>';
 }
 
-# ---------------------------- convert 'time' format into a datetime sql format
+#########################################
+#########################################
+
+=pod
+
+=item sqltime
+
+Convert 'time' format into a datetime sql format
+
+=cut
+
+#########################################
+#########################################
 sub sqltime {
     my $timef=shift @_;
     my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
@@ -157,8 +230,28 @@ sub sqltime {
     return "$year-$mon-$mday $hour:$min:$sec";
 }
 
-# --------------------------------------------------------- Various form fields
 
+#########################################
+#########################################
+
+=pod
+
+=item Form field generating functions
+
+=over 4
+
+=item textfield
+
+=item hiddenfield
+
+=item selectbox
+
+=back
+
+=cut
+
+#########################################
+#########################################
 sub textfield {
     my ($title,$name,$value)=@_;
     return "\n<p><b>$title:</b><br>".
@@ -185,8 +278,19 @@ sub selectbox {
     return $selout.'</select>';
 }
 
-# -------------------------------------------------------- Publication Step One
+#########################################
+#########################################
+
+=pod
+
+=item urlfixup
+
+Fix up a url?  First step of publication
 
+=cut
+
+#########################################
+#########################################
 sub urlfixup {
     my ($url,$target)=@_;
     unless ($url) { return ''; }
@@ -207,7 +311,19 @@ sub urlfixup {
     return $url;
 }
 
+#########################################
+#########################################
+
+=pod
+
+=item absoluteurl
+
+Currently undocumented    
+
+=cut
 
+#########################################
+#########################################
 sub absoluteurl {
     my ($url,$target)=@_;
     unless ($url) { return ''; }
@@ -218,6 +334,19 @@ sub absoluteurl {
     return $url;
 }
 
+#########################################
+#########################################
+
+=pod
+
+=item set_allow
+
+Currently undocumented    
+
+=cut
+
+#########################################
+#########################################
 sub set_allow {
     my ($allow,$logfile,$target,$tag,$oldurl)=@_;
     my $newurl=&urlfixup($oldurl,$target);
@@ -236,6 +365,19 @@ sub set_allow {
     return $return_url
 }
 
+#########################################
+#########################################
+
+=pod
+
+=item get_subscribed_hosts
+
+Currently undocumented    
+
+=cut
+
+#########################################
+#########################################
 sub get_subscribed_hosts {
     my ($target)=@_;
     my @subscribed;
@@ -269,6 +411,19 @@ sub get_subscribed_hosts {
 }
 
 
+#########################################
+#########################################
+
+=pod
+
+=item get_max_ids_indices
+
+Currently undocumented    
+
+=cut
+
+#########################################
+#########################################
 sub get_max_ids_indices {
     my ($content)=@_;
     my $maxindex=10;
@@ -300,6 +455,19 @@ sub get_max_ids_indices {
     return ($needsfixup,$maxid,$maxindex);
 }
 
+#########################################
+#########################################
+
+=pod
+
+=item get_all_text_unbalanced
+
+Currently undocumented    
+
+=cut
+
+#########################################
+#########################################
 sub get_all_text_unbalanced {
     #there is a copy of this in lonxml.pm
     my($tag,$pars)= @_;
@@ -329,6 +497,19 @@ sub get_all_text_unbalanced {
     return $result
 }
 
+#########################################
+#########################################
+
+=pod
+
+=item fix_ids_and_indices
+
+Currently undocumented    
+
+=cut
+
+#########################################
+#########################################
 #Arguably this should all be done as a lonnet::ssi instead
 sub fix_ids_and_indices {
     my ($logfile,$source,$target)=@_;
@@ -524,6 +705,19 @@ sub store_metadata {
     return (undef,$status);
 }
 
+#########################################
+#########################################
+
+=pod
+
+=item publish
+
+Currently undocumented.  This is the workhorse function of this module.
+
+=cut
+
+#########################################
+#########################################
 sub publish {
 
     my ($source,$target,$style)=@_;
@@ -843,8 +1037,20 @@ END
       '<p><input type="submit" value="Finalize Publication" /></p></form>';
 }
 
-# -------------------------------------------------------- Publication Step Two
+#########################################
+#########################################
+
+=pod 
+
+=item phasetwo
+
+Render second interface showing status of publication steps.
+This is publication step two.
+
+=cut
 
+#########################################
+#########################################
 sub phasetwo {
 
     my ($source,$target,$style,$distarget)=@_;
@@ -1067,8 +1273,36 @@ if (-e $target) {
 
 }
 
-# ================================================================ Main Handler
 
+#########################################
+#########################################
+
+=pod
+
+=item handler
+
+A basic outline of the handler subroutine follows.
+
+=over 4
+
+=item Get query string for limited number of parameters
+
+=item Check filename
+
+=item File is there and owned, init lookup tables
+
+=item Start page output
+
+=item Individual file
+
+=item publish from $thisfn to $thistarget with $thisembstyle
+
+=back
+
+=cut
+
+#########################################
+#########################################
 sub handler {
   my $r=shift;