Released under the GPL by Stefan Caunter. If you require a copy of the GPL
it can be found at http://gnu.org.

This software makes for an elegant and interesting time display for web pages.
It formats the time that has passed since the page's last update into English
words for the number of days, hours, minutes and seconds. 

To use this subroutine you need to do the following.

1. You must require the timestamp.lib file by giving the full path to it.
   A statement like

require ("/usr/local/lib/timestamp.lib");

   should do the job.

2. The file which you wish the timestamp displayed needs to be entered like 
   this.

timestamp("README");

   The example script example.pl asks for a timestamp to be displayed on
   the file you are reading.

3. I use the mod_rewrite module for apache to print out a timestamp on any
   requested file using the additional %ENV variable 'REQUEST_URI' like so.

timestamp("/usr/local/apache/htdocs/$ENV{'REQUEST_URI'}");

If you want something referring to you in your timestamp you can edit the 
print qq statement which forms the $done variable which the subroutine 
returns to your program.

That is all you need to do to be able to use this program.

HOW DOES IT WORK:
The program works by "statting" the file to be timestamped, and comparing its
age in seconds with the current time. Hence, an accurate and healthy 
localtime would be a good thing to have. Sometimes I cron an 
"rdate -s time.nrc.ca" job, and sometimes I run ntpdate. 

*/20 *	*  *  *	  ntpdate -s time.nrc.ca

will work.

Then follows math to calculate the necessary days, hours, minutes and seconds.
This is "plugged in" to the english wording possibilities and punctuation.
I have used "Standard English". The compound numbers from twenty to ninety
are hyphenated when combined with a number from one to nine. 
The day, hour, minute or second display is suppressed if zero, although this 
can be easily made to not happen. I think it makes for a more interesting
display, like the whole subroutine. The nouns are correctly singularized if
the time unit count is "one". 

If you can think of any enhancements, or if you find any mistakes, please send
me a note at stef@caunter.ca.

Stefan Caunter 
July 2002

Nov 14, 2002
Placed "@_" into the $done statement. Works nicely with $ENV{'REQUEST_URI'}.
