[LON-CAPA-cvs] cvs: loncom /publisher lonpublisher.pm
harris41
lon-capa-cvs@mail.lon-capa.org
Tue, 10 Sep 2002 14:52:35 -0000
This is a MIME encoded message
--harris411031669555
Content-Type: text/plain
harris41 Tue Sep 10 10:52:35 2002 EDT
Modified files:
/loncom/publisher lonpublisher.pm
Log:
asymptotically approaching brain explosion as I lower the "truly amazing"
coefficient of this module; POD sections should be in caps;
increasing documentation of various subroutines; XHTML-ifying most of the
output; one spelling fix
--harris411031669555
Content-Type: text/plain
Content-Disposition: attachment; filename="harris41-20020910105235.txt"
Index: loncom/publisher/lonpublisher.pm
diff -u loncom/publisher/lonpublisher.pm:1.93 loncom/publisher/lonpublisher.pm:1.94
--- loncom/publisher/lonpublisher.pm:1.93 Mon Aug 12 10:48:32 2002
+++ loncom/publisher/lonpublisher.pm Tue Sep 10 10:52:35 2002
@@ -1,7 +1,7 @@
# The LearningOnline Network with CAPA
# Publication Handler
#
-# $Id: lonpublisher.pm,v 1.93 2002/08/12 14:48:32 matthew Exp $
+# $Id: lonpublisher.pm,v 1.94 2002/09/10 14:52:35 harris41 Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -67,28 +67,42 @@
=pod
-=head1 Name
+=head1 NAME
lonpublisher - LON-CAPA publishing handler
-=head1 Synopsis
+=head1 SYNOPSIS
-lonpublisher takes the proper steps to add resources to the LON-CAPA
+B<lonpublisher> is used by B<mod_perl> inside B<Apache>. This is the
+invocation by F<loncapa_apache.conf>:
+
+ <Location /adm/publish>
+ PerlAccessHandler Apache::lonacc
+ SetHandler perl-script
+ PerlHandler Apache::lonpublisher
+ ErrorDocument 403 /adm/login
+ ErrorDocument 404 /adm/notfound.html
+ ErrorDocument 406 /adm/unauthorized.html
+ ErrorDocument 500 /adm/errorhandler
+ </Location>
+
+=head1 DESCRIPTION
+
+B<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.
+B<lonpublisher> is many things to many people.
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
+=head2 SUBROUTINES
+
+Many of the undocumented subroutines implement various magical
+parsing shortcuts.
=over 4
@@ -130,9 +144,26 @@
=pod
-=item metaeval
+=item B<metaeval>
+
+Evaluates a string that contains metadata. This subroutine
+stores values inside I<%metadatafields> and I<%metadatakeys>.
+The hash key is a I<$unikey> corresponding to a unique id
+that is descriptive of the parser location inside the XML tree.
+
+Parameters:
+
+=over 4
-Evaluate string with metadata
+=item I<$metastring>
+
+A string that contains metadata.
+
+=back
+
+Returns:
+
+nothing
=cut
@@ -185,10 +216,34 @@
=pod
-=item metaread
+=item B<metaread>
Read a metadata file
+Parameters:
+
+=over
+
+=item I<$logfile>
+
+File output stream to output errors and warnings to.
+
+=item I<$fn>
+
+File name (including path).
+
+=back
+
+Returns:
+
+=over 4
+
+=item Scalar string (if successful)
+
+XHTML text that indicates successful reading of the metadata.
+
+=back
+
=cut
#########################################
@@ -196,10 +251,10 @@
sub metaread {
my ($logfile,$fn)=@_;
unless (-e $fn) {
- print $logfile 'No file '.$fn."\n";
+ print($logfile 'No file '.$fn."\n");
return '<br><b>No file:</b> <tt>'.$fn.'</tt>';
}
- print $logfile 'Processing '.$fn."\n";
+ print($logfile 'Processing '.$fn."\n");
my $metastring;
{
my $metafh=Apache::File->new($fn);
@@ -214,10 +269,30 @@
=pod
-=item sqltime
+=item B<sqltime>
Convert 'time' format into a datetime sql format
+Parameters:
+
+=over 4
+
+=item I<$timef>
+
+Seconds since 00:00:00 UTC, January 1, 1970.
+
+=back
+
+Returns:
+
+=over 4
+
+=item Scalar string
+
+MySQL-compatible datetime string.
+
+=back
+
=cut
#########################################
@@ -236,15 +311,21 @@
=pod
-=item Form field generating functions
+=item Form-field-generating subroutines.
+
+For input parameters, these subroutines take in values
+such as I<$name>, I<$value> and other form field metadata.
+The output (scalar string that is returned) is an XHTML
+string which presents the form field (foreseeably inside
+<form></form> tags).
=over 4
-=item textfield
+=item B<textfield>
-=item hiddenfield
+=item B<hiddenfield>
-=item selectbox
+=item B<selectbox>
=back
@@ -255,12 +336,12 @@
sub textfield {
my ($title,$name,$value)=@_;
return "\n<p><b>$title:</b><br>".
- '<input type=text name="'.$name.'" size=80 value="'.$value.'">';
+ '<input type="text" name="'.$name.'" size=80 value="'.$value.'" />';
}
sub hiddenfield {
my ($name,$value)=@_;
- return "\n".'<input type=hidden name="'.$name.'" value="'.$value.'">';
+ return "\n".'<input type="hidden" name="'.$name.'" value="'.$value.'" />';
}
sub selectbox {
@@ -283,7 +364,7 @@
=pod
-=item urlfixup
+=item B<urlfixup>
Fix up a url? First step of publication
@@ -316,9 +397,9 @@
=pod
-=item absoluteurl
+=item B<absoluteurl>
-Currently undocumented
+Currently undocumented.
=cut
@@ -339,7 +420,7 @@
=pod
-=item set_allow
+=item B<set_allow>
Currently undocumented
@@ -370,7 +451,7 @@
=pod
-=item get_subscribed_hosts
+=item B<get_subscribed_hosts>
Currently undocumented
@@ -404,7 +485,7 @@
}
}
} else {
- &Apache::lonnet::logthis("Un able to open $target.subscription");
+ &Apache::lonnet::logthis("Unable to open $target.subscription");
}
&Apache::lonnet::logthis("Got list of ".join(':',@subscribed));
return @subscribed;
@@ -416,7 +497,7 @@
=pod
-=item get_max_ids_indices
+=item B<get_max_ids_indices>
Currently undocumented
@@ -460,7 +541,7 @@
=pod
-=item get_all_text_unbalanced
+=item B<get_all_text_unbalanced>
Currently undocumented
@@ -502,7 +583,7 @@
=pod
-=item fix_ids_and_indices
+=item B<fix_ids_and_indices>
Currently undocumented
@@ -654,7 +735,7 @@
=pod
-=item store_metadata
+=item B<store_metadata>
Store the metadata in the metadata table in the loncapa database.
Uses lonmysql to access the database.
@@ -710,9 +791,13 @@
=pod
-=item publish
+=item B<publish>
+
+This is the workhorse function of this module. This subroutine generates
+backup copies, performs any automatic processing (prior to publication,
+especially for rat and ssi files),
-Currently undocumented. This is the workhorse function of this module.
+I<Additional documentation needed.>
=cut
@@ -769,8 +854,8 @@
if (
&Apache::lonnet::getfile($Apache::lonnet::perlvar{'lonDocRoot'}.'/'.
$thisdep.'.meta') eq '-1') {
- $scrout.=
- ' - <font color=red>Currently not available</font>';
+ $scrout.= ' - <font color="red">Currently not available'.
+ '</font>';
} else {
my %temphash=(&Apache::lonnet::declutter($target).'___'.
&Apache::lonnet::declutter($thisdep).'___usage'
@@ -787,23 +872,24 @@
#Encode any High ASCII characters
$outstring=&HTML::Entities::encode($outstring,"\200-\377");
-# ------------------------------------------------------------- Write modified
+# ------------------------------------------------------------- Write modified.
{
my $org;
unless ($org=Apache::File->new('>'.$source)) {
print $logfile "No write permit to $source\n";
return
- "<font color=red>No write permission to $source, FAIL</font>";
+ '<font color="red">No write permission to '.$source.
+ ', FAIL</font>';
}
- print $org $outstring;
+ print($org $outstring);
}
$content=$outstring;
}
-# --------------------------------------------- Initial step done, now metadata
+# -------------------------------------------- Initial step done, now metadata.
-# ---------------------------------------- Storage for metadata keys and fields
+# --------------------------------------- Storage for metadata keys and fields.
%metadatafields=();
%metadatakeys=();
@@ -1014,8 +1100,8 @@
$scrout.=&textfield('Publisher/Owner','owner',
$metadatafields{'owner'});
-# --------------------------------------------------- Correct copyright for rat
+# -------------------------------------------------- Correct copyright for rat.
if ($style eq 'rat') {
if ($metadatafields{'copyright'} eq 'public') {
delete $metadatafields{'copyright'};
@@ -1032,10 +1118,11 @@
(&Apache::loncommon::copyrightids));
}
- my $copyright_help = Apache::loncommon::help_open_topic("Publishing_Copyright");
+ my $copyright_help =
+ Apache::loncommon::help_open_topic('Publishing_Copyright');
$scrout =~ s/DISTRIBUTION:/'DISTRIBUTION: ' . $copyright_help/ge;
return $scrout.
- '<p><input type="submit" value="Finalize Publication" /></p></form>';
+ '<p><input type="submit" value="Finalize Publication" /></p></form>';
}
#########################################
@@ -1043,11 +1130,34 @@
=pod
-=item phasetwo
+=item B<phasetwo>
Render second interface showing status of publication steps.
This is publication step two.
+Parameters:
+
+=over 4
+
+=item I<$source>
+
+=item I<$target>
+
+=item I<$style>
+
+=item I<$distarget>
+
+=back
+
+Returns:
+
+=over 4
+
+=item Scalar string
+
+String contains status (errors and warnings) and information associated with
+the server's attempts at publication.
+
=cut
#########################################
@@ -1270,10 +1380,11 @@
return $warning.$scrout.
- '<hr><a href="'.$thisdistarget.'"><font size=+2>View Published Version</font></a>'.
+ '<hr><a href="'.$thisdistarget.'"><font size="+2">'.
+ 'View Published Version</font></a>'.
'<p><a href="'.$thissrc.'"><font size=+2>Back to Source</font></a>'.
'<p><a href="'.$thissrcdir.
- '"><font size=+2>Back to Source Directory</font></a>';
+ '"><font size="+2">Back to Source Directory</font></a>';
}
@@ -1283,23 +1394,35 @@
=pod
-=item handler
+=item B<handler>
A basic outline of the handler subroutine follows.
=over 4
-=item Get query string for limited number of parameters
+=item *
+
+Get query string for limited number of parameters.
+
+=item *
+
+Check filename.
+
+=item *
+
+File is there and owned, init lookup tables.
+
+=item *
-=item Check filename
+Start page output.
-=item File is there and owned, init lookup tables
+=item *
-=item Start page output
+Evaluate individual file, and then output information.
-=item Individual file
+=item *
-=item publish from $thisfn to $thistarget with $thisembstyle
+Publishing from $thisfn to $thistarget with $thisembstyle.
=back
@@ -1378,7 +1501,7 @@
unless ($ENV{'form.phase'} eq 'two') {
-# --------------------------------- File is there and owned, init lookup tables
+# -------------------------------- File is there and owned, init lookup tables.
%addid=();
@@ -1402,17 +1525,18 @@
}
-# ----------------------------------------------------------- Start page output
+# ---------------------------------------------------------- Start page output.
$r->content_type('text/html');
$r->send_http_header;
$r->print('<html><head><title>LON-CAPA Publishing</title></head>');
$r->print(
- '<body bgcolor="#FFFFFF"><img align=right src=/adm/lonIcons/lonlogos.gif>');
+ '<body bgcolor="#FFFFFF"><img align="right" '.
+ 'src="/adm/lonIcons/lonlogos.gif" />');
my $thisfn=$fn;
-# ------------------------------------------------------------- Individual file
+# ---------------------- Evaluate individual file, and then output information.
{
$thisfn=~/\.(\w+)$/;
my $thistype=$1;
@@ -1433,25 +1557,26 @@
&Apache::loncommon::filedescription($thistype).' <tt>'.
$thisdisfn.'</tt></h2><b>Target:</b> <tt>'.$thisdistarget.'</tt><p>');
- if (($cuname ne $ENV{'user.name'}) || ($cudom ne $ENV{'user.domain'})) {
- $r->print('<h3><font color=red>Co-Author: '.$cuname.' at '.$cudom.
- '</font></h3>');
+ if (($cuname ne $ENV{'user.name'}) || ($cudom ne $ENV{'user.domain'})) {
+ $r->print('<h3><font color="red">Co-Author: '.$cuname.' at '.$cudom.
+ '</font></h3>');
}
if (&Apache::loncommon::fileembstyle($thistype) eq 'ssi') {
- $r->print('<br><a href="/adm/diff?filename=/~'.$cuname.'/'.
+ $r->print('<br /><a href="/adm/diff?filename=/~'.$cuname.'/'.
$thisdisfn.
- '&versionone=priv" target=cat>Diffs with Current Version</a><p>');
+ '&versionone=priv" target="cat">Diffs with Current Version</a><p>');
}
-# ------------ We are publishing from $thisfn to $thistarget with $thisembstyle
+# ------------------ Publishing from $thisfn to $thistarget with $thisembstyle.
unless ($ENV{'form.phase'} eq 'two') {
$r->print(
- '<hr>'.&publish($thisfn,$thistarget,$thisembstyle));
+ '<hr />'.&publish($thisfn,$thistarget,$thisembstyle));
} else {
$r->print(
- '<hr>'.&phasetwo($thisfn,$thistarget,$thisembstyle,$thisdistarget));
+ '<hr />'.&phasetwo($thisfn,$thistarget,
+ $thisembstyle,$thisdistarget));
}
}
--harris411031669555--