This is the README file for wcal.

Author:

   Adam Stein (adam@scan.mc.xerox.com)

Copyright:

  Copyright (c) 1999-2003  Xerox Corporation.  All Rights Reserved.

  Permission to use, copy, modify  and  distribute  without  charge
  this  software,  documentation, images, etc. is granted, provided
  that this copyright and the author's name is retained.

  A fee may be charged for this program ONLY to recover  costs  for
  distribution  (i.e.  media costs).  No profit can be made on this
  program.

  The author assumes no responsibility for  disasters  (natural  or
  otherwise) as a consequence of use of this software.

Description:

  This program allows the viewing, inserting, and deleting of CDE calendar
  appointments through the web.  The calendar can be viewed in day, week,
  month, or year views.

  The following commands are available:

    Previous ____	= Go to the previous {day|week|month|year}.  The ___
			  would be replaced depending on the view.
    Next ____		= Go to the next {day|week|month|year}.  The ___
			  would be replaced depending on the view.

    Go To Today		= Go to today's date (in month view)
    Go To...		= A pop-up window will allow the user to type in any
			  day.  All of the following are valid ways to
			  specify the date:

			  	4 22 99
				04/22/99
				Apr 22 '99
				Apr 22 1999
				===> April 22nd 1999 (birthday)
				Apr221999
				Apr2299
				ap2299
				42299
			        Thu Apr 22 09:39:02 EDT 1999  [from /bin/date]

			  Any format legal to Date::Calc's Decode_Date_US()
			  and Parse_Date() routines are valid.

			  The date will be shown in day view.

    Day View		  Show the calendar in day view
    Week View		  Show the calendar in week view
    Month View		  Show the calendar in month view
    Year View		  Show the calendar in year view

    List Calendars	= List all available calendars

    Add Appointment     = Add calendar appointment
			 
  A small graphic red X can be found on the left side of the appointment
  listings in the day and week views.  Clicking on the red X will
  delete the appointment.

  The latest version can always be found at:

	http://www.csh.rit.edu/~adam/Progs/

Requirements:

  This program requires Perl 5.6.1 or higher.  Also required are
  the following Perl modules:
  
	CGI		(by Lincoln Stein, version 2.93 or newer)
	Date::Calc	(by Steffen Beyer, version 4.3 or newer)

  The following Perl module is optional (the tradeoff is explained
  in Installation below):

	Calendar::CSA	(by Kenneth Albanowski, version 0.8 or newer)

  The Calendar::CSA module requires that you have the SUNWdtinc package
  installed.  You can see what packages you have installed by running
  the "pkginfo" command.

  The Calendar::CSA module needs an update to compile for Perl v5.6.1.
  See:

	http://www.dynalabs.de/mxp/cde/

  for more information.  The complete updated source code is available
  from this web site as well as a list of what the changes were.  It is
  important that Calendar::CSA be compiled using the same compiler that
  compiled your version of Perl.

  The following module is ONLY needed if using the CSA module:

	Time::Timezone  (by Graham Barr, David Muir, & Paul Foley, 
			 version 100.010301 or newer)

  The following module is ONLY needed if debugging this program:

	Data::Dumper	(by Gurusamy Sarathy, version 2.07 or newer)

  I believe Data::Dumper now comes with Perl 5.6.1 and later.

  All modules can be found at CPAN sites:
  
	ftp://theory.uwinnipeg.ca/pub/CPAN/SITES.html

  In addition, CGI can be found at:

	http://stein.cshl.org/WWW/software/CGI/

  Date::Calc can be found at:

	http://www.engelschall.com/u/sb/download/

  and the original Calendar::CSA can be found at:

	http://www.cpan.org/authors/id/KJALB/Calendar-CSA-0.8.tar.gz

  Older versions of these modules *might* work, no guarantees from me.
  I have no way of supporting multiple versions of modules.

Installation:

  This program has only been tested on Solaris 2.x systems running
  the Apache web server (http://www.apache.org/).

  As mentioned above, the Calendar::CSA module is optional.  If present,
  "wcal" will use it to communicate directly to the CDE calendar manager.
  If not present, "wcal" will use the program, "dtcm_lookup", to fetch
  appointments.  While I haven't timed it, I assume the CSA method of
  fetching appointments would be faster since it's talking directly to
  the calendar manager, whereas the "dtcm_lookup" is a middleman to
  the process.

  In addition, the "insert" and "delete" features are ONLY available when
  using the Calendar::CSA module.

  Modify line 28 in "wcal.tpl" (setting the value of FETCHWIN) if you want.
  Setting this value to 0 will NOT show the "Fetching..." popup window which
  displays when data is being retrieved from the calender.  Setting this value
  to 1 will display this window.  If you are running with a fast web server,
  then you should probably set this to 0 since the window won't stay up long
  enough to be of use.  If you are using a slow web server or connection, you
  might want to set this to 1 to indicate that something is happening when a
  calendar is being read.

  Modify "calendars.pl" to list all calendars to be accessed.  The format
  is explained within the file.  Wcal now has the ability to access
  any arbitrary calendars, not just those listed in this file (see Using below).
  The advantage to listing them in this file is when wcal is called without
  specifying a calendar, all the entries in "calendars.pl" are shown as
  clickable items.

  Modify permissions of the calendars listed in "calendars.pl".  See
  Setting Calendar Permissions below for details.  Wcal can automatically
  detect what permissions are available and will not show features that
  aren't available (i.e. the command to insert an appointment will not be
  shown if wcal doesn't have permission to insert entries into the
  calendar).

  For the rest of the installation, you have two choices: run the "install"
  script or do what that script does manually.

  If you choose to run the "install" script, it will ask a few questions
  and then install all the wcal files to the directories you specfied when
  answering the questions.

  If you want to install wcal manually, do the following:

  1) Replace "SED_PERLBIN" on the first line in "wcal.tpl" to reflect where
     Perl is installed on your system

  2) Replace "SED_IMGURL" on line 17 in "constants.tpl" to the appropriate
     URL value to use to fetch the images that come with "wcal".  This URL
     should be based on the web server "wcal" will be running under.

  3) Replace "SED_LIBDIR" on line 49 in "wcal.tpl" to reflect where all the
     *.pl files can be found.  These files don't need to be under the web
     server's control and can be placed anywhere in the filesystem (as long
     as the machine running the web server can access the directory).

  4) Copy the "wcal.tpl" program to your web server's cgi-bin directory and
     rename it "wcal.cgi"

  5) Copy the *.pl files to the directory you listed in step 3 above

  6) Copy the *.gif files to the directory you specified in step 2 above

Setting Calendar Permissions

  All instructions listed are for Solaris 2.6/7/8 with CDE installed.  Your
  mileage may vary.
  
  There are two choices when it comes to calendar permissions:
  
    1) add permissions for the web server account that runs CGI scripts
    2) run wcal as a normal user that already has the required permissions
       to the desired calendar

  Option #1
  ---------
  The command to set/view/remove permissions is "sdtcm_admin" which
  comes with CDE.  If you've installed CDE in the normal place, you
  can find it at "/usr/dt/bin/sdtcm_admin".  See the "sdtcm_admin"
  man page for a full list of permissions that you can set.  I will
  only be mentioning how to set public permissions.

  In order for calendar appointments to be viewed, permission must be
  given for the calendar to be accessed by "world" or by the account
  your web server runs CGI scripts as.  You can check permissions for
  a calendar with the command:

	sdtcm_admin -x -c calendar@host
  
  where "calendar@host" is the calendar to check (this defaults to the
  current user on the current machine).  "World" or your web server's
  CGI account should be listed as having the access "pu=v" (which means
  permission to view public appointments).

  If the account you need isn't listed, permission can be added by the command:

	sdtcm_admin -p pu=v -n account -c calendar@host

  where "account" is "world" or your web server's CGI account.  Without
  enabling this access, "wcal" cannot view appointments (a warning message
  comes up if there are problems getting appointments).  "world" access
  is the same as letting any acccount (including the nobody account)
  viewing privileges.
  
  Access to view can be removed by executing:

	sdtcm_admin -z -n account -c calendar@host

  This should NOT be done if the calendar is to be accessed by "wcal"
  (I'm just listing it in case anybody is interested or overly paranoid).

  If you wish to add permissions for inserting appointments, the command is:

	sdtcm_admin -p pu+i -n account -c calendar@host

  Removing insertion privileges is:

	sdtcm_admin -p pu-i -n account -c calendar@host

   Giving deletion privileges is:

	sdtcm_admin -p at+v -n account -c calendar@host

   Removing deletion privileges is:

	 sdtcm_admin -p at-v -n account -c calendar@host

  Option #2
  ---------
  It is possible to have your web server run wcal as a regular user.  In
  this case, whatever privileges that user has to a particular calendar
  would take effect.  This can be used to set up an account with a group
  calendar and have wcal run as that account.

  For the Apache web server, you will need to use the "su-exec" module
  to allow scripts to be run as normal users.  I don't know what the
  equivalent would be (if there is one) for any other web server.

Using

  To use, just call the "wcal.cgi" script through the web browser.  This
  will list all available calendars.  Clicking on a calendar will then
  show that user's calendar appointments.  The URL examples shown below
  may be different from what you actually need to use (for example, if
  you were using the Apache "su-exec" module).

  To directly view a user's calendar, use a URL of the form:

	http://<your web sever>/cgi-bin/wcal.cgi?key=<key>

  where <your web server> is your server's address/name and <key> is
  the key for a calendar as specified in the "calendars.pl" file or
  the full address of a calendar in the form of:

	user@machine

  The view can also be specified in the URL:

	http://<your web sever>/cgi-bin/wcal.cgi?key=<key>&view=<view>

  where <view> is:

	0 for "day" view
	1 for "week" view
	2 for "month" view
	3 for "year" view

Credits

  The icons (prev.gif, next.gif) were found at "Everyicon"
  (http://www.everyicon.com/) in "Arrows Group 5".  The images were
  reduced 50% from their original size.

  Thanks to Viet Hoang (vhoang@lucent.com) for finding bugs and
  suggesting enhancements to create v1.1.

  Thanks to Bruno Kriner (kriner@tls.cena.fr) for finding bugs and
  submitting patches to create v1.2.

  Thanks to Philip Brown (phil@bolthole.com) for suggesting the ability
  to insert appointments (that led to me creating v1.3) and for the
  install script.

  Thanks to Peter Polkinghorne (pjmp@ksblaw.co.uk) for sending a patch
  to fix access to a calendar when world access is turned on.  This patch
  also allows entries that have a start time and no end time.

Bugs/Additions:

  I would appreciate knowing about any bugs either found or
  fixed and any enhancements made.  I would like to keep a
  centralized version with the upgrades so that there aren't
  50 million different versions.  I can't make any
  guarantees to when bug fixes would be made (if any are
  found :-{), but I'll do my best.

  I hope this program is of use to you, either in it's capacity or as
  an example in Perl/CGI/JavaScript programming.

