This is the README file for an Events Calendar service for
www.math.ufl.edu


			INSTRUCTIONS

------------

    To start a new week,

(1)  Run

	make

to recompile the events.html files in each week and to
rebuild custom/index.html.

(2)  Copy the events.html file from the appropriate week??
directory into this directory.  Better yet, use a link

	rm events.html events.txt
	ln -s weekXY/events.html .
	ln -s weekXY/events.txt .

The Makefile has a target to automate this, 

	make week-link

-- which invokes a possibly-broken Perl script called
link-week.pl.   The week-link facility may need tuneup
as the events calendar gets used in earnest.  (Look for
errors in computing the appropriate week of the semester,
and note that this script may become invalid after
December 31, 1999.)

------------

    To start a new semester,

(1)  Change the dates and labels in dates.sed.  This is a file
of sed instructions, so be careful about the shape of the lines,
which are modeled on 

s/SEMESTER/Fall Semester/


(2)  Run

	make startup

from this directory.  (Note that this make will clean out the week??
directories, so any material you want to archive should be copied out
of them beforehand.)

(3) The makefile should copy eventbook.pl into
/depot/www/cgi-bin/events-tools, if its source has changed.  (The
destination is set in CGIDIR at the top of the main Makefile.)

You may need to check permissions, group, and ownership on this file,
which is the entry tool for seminar contact people.  Modifications to
this file should be made in eventbook.src -- the Makefile in the present
directory applies some substitutions to the source file to build
a Perl script.

(4)  As seminar contact persons change, we need to change the
password for the `events' pseudo-user.  This is done with
`htadm' applied to /depot/www/config/passwd.

Reporters or contact people for the seminars are all given the
events password, so they need to be aware that this password should
not be spread indiscriminately.

(5) When changes are required, make your modifications to <file>.src
where those exist - they are twiddled and assembled during the Make
runs to create lots of different pieces of the puzzle.


--------------------------------------------


		COMMENTS


See the TO-DO file for comments which lead to chores.

This calendar suite uses a script in /depot/www/cgi-bin/events-tools/
and the Makefile here to build a weekly calendar from
items submitted by seminar bosses.  Everything required is contained
in this directory:  eventbook.pl, the cgi script, is built here and
then copied into the cgi-bin directory.  

Access control lists should be used to set the password and username
shared by seminar bosses.  The hope is that apart from managing those
passwords and ACLs and correcting occasional errors, staff or system
time will not be required to maintain the events service, beyond the
weekly update, which could go into the /usr/local/adm/Weekly list.
(If people get used to looking into the past and future, then more
frequent updates might be desirable.)

Revisions to this scheme should be feasible with changes to
files in
	this top-level directory
	the sample-week subdirectory
and 
	recopying eventbook.pl
into cgi-bin/events-tools, as needed.  A lot of the HTML or Perl
files in this top-level directory are built from .src files.

Seminar reporters may use HTML versions of accents and special
characters in speakers' names and other text fields. 


What's Cool
-----------

If it works, the auto-linking of the appropriate week into
TOPDIR/events.html is useful.

The Makefile builds eventbook.pl, which calls the Makefile to rebuild
events listings.  


What's Not
----------

If it does not work, the auto-linking of the appropriate week into
TOPDIR/events.html is a pain in the neck.   This might not want to
go into the Weekly script until it is well tested.   In any case,
the week-computing code needs to be checked and extended past 1999.



--------------------------------------------

		DETAILS

subdirectories
--------------

The subdirectories of the main events directory are (at this
writing):

	bin -- executables are made here, but the heavily-used
		ones are copied into cgi-bin/events-tools
	docs -- documentation on the event-tools
	src -- the .src files from which many different things
		are built live here.

The directories above should have access limited to math.ufl.edu,
or to an even smaller list of users.

	custom -- depository for customized submission forms
	sample-week -- models for the weekly calendar subdirectories
			(sample-week and the weekly directories are
			completely rebuilt during ``make startup'')

	old -- backups and discards
	week?? -- the weekly calendar subdirectories


security
--------

Use access protection in the HTTPD server config file
and ACL's (at least for cgi-bin) to protect these directories:

	events/bin
	events/docs
	events/src
	cgi-bin/events-tools <<-- This is the most important one to test.

backwards compatibility
-----------------------

bin/events.sh  is a replacement script for the old `events' function.



eventbook.pl
------------

This is the main CGI script, which began life as a guestbook
script.  It takes submissions as Form input and writes them
to appropriate files in the weekly directories.  This script
is built from eventbook.src by the main Makefile, which copies
the rebuilt eventbook.pl into cgi-bin/events-tools/.

Do not change eventbook.pl -- make mods to eventbook.src instead,
and be sure to make a backup of eventbook.src before you start
fooling around.


events.html, events.txt
-----------------------

eventbook.pl (as of May 4, 1997) generates both HTML and plain
text versions of event entries.  The weekxy Makefiles grind these
into weekly calendars called events.html and events.txt, which
the linking script soft-links into /depot/www/math-homepages/events/.

events.txt is mainly intended for email distribution, but as of
the date above we have *not* automated email distribution.  I am
not certain that it is a terrific idea, in fact.  (If a graffiti
artist gets into the events page, we would be better off if we do
not mail his handiwork to 150 readers.  Format cleanup and other
corrections also might want a human hand.)


dates.sed
---------

The dates.sed file contains substitutions required for converting
the .src files into HTML, Perl, or Bourne shell, with appropriate
values for dates and paths.  

You probably want to save past versions of these, at least for
one each of fall, spring, and summer semesters.  Make a new dates.sed
file by perturbing an appropriate model slightly.

Important fields in dates.sed whose names might not tell everything
include

	STARTMONTH -- numerical version of the first month of the semester
			(January == 01, May == 05, August == 08)

	STARTWEEK -- numerical version of the first week of the semester
			(in the range 1-53)

	TOPDIR -- path to the events directory

	WEBDIR -- the URL for the events directory is
		http://www.math.ufl.edu/WEBDIR/


The custom directory
--------------------

Following Jean Larson's suggestion, we've now got tools to produce
seminar-specific submission pages so that seminar reporters can
work a little faster if there are no changes in the basic data
(seminar name, time, place, web page).

The customized pages are written into the `custom' directory,
and the index.html file in that directory gets rebuilt whenever
the calendars are rebuilt by a default make on the top-level
directory.

A modified version of the main CGI script does the work.  See
customize.pl and its source code (customize.src).  The customize.pl
Perl script gets copied into the cgi-bin/events-tools subdirectory
alongside eventbook.pl.  Both should be password-protected on
the HTTPD server.


------------

cws

April 1997