JavaScript Clock version 0.7
----------------------------

This SquirrelMail plugin displays a digital clock in the folders
frame using an assortment of little PNG images (some transparent,
some fanciful).  Options include the "face" (font) of the clock, the
position of the clock (above or below the folders), hour format (12 or
24), seconds display (Disabled, Enabled, with tenths or hundreds).

JSClock has been tested with squirrelmail-1.2.6, 1-2.10, 1.3.2, 1.4.0rc2a
and with PHP versions 4.0.6, a few 4.1.x and 4.2.3
Previously it required a hook in generic_header but doesn't anymore, so
it should be compatible with lots of other SM versions.

Time junkies will be happy to note that I've taken care to update the
display on precise time changes (to the closest most reasonable millisecond)
so that if you're running NTP, you'll be able the set a watch to it.  JSClock
displays the client browser's time, not the server's.

JSClock will _NOT_ inject javascript code unless the users specifically
enable it.

Fonts in this package include:

 - Two small transparent fonts which will display using the frame background
   color.
   
 - Anti-aliased fonts that look very smooth even on non-anti-aliased
   browsers.  They use the same background color as the one in the
   default theme.
   
 - A Nixie tube font for that cool retro look (Nixie tubes are vacuum tubes
   that predate LEDs and gas-discharge display.  Google "Nixie" for more
   info.)  The Nixie images are (C)opyrighted Mike Harrison, of Mike's
   electric stuff fame, at www.electricstuff.co.uk and are reproduced with
   his permission.  Thanks Mike!

 - A 7-segment red LED display.

 - A 7-segment LCD display.

 - A 4-dot binary LED display.

 - For the trekkies: Klingon digits.

 - Yellow and green LED modules

 - Odometer (Web-Counter)

 - Musical notes

 - Vacuum Fluorescent Displays (VFD)

 - Etc...


Installation
------------

Like most plugins, go in the plugins directory, extract the archive by
doing tar xvzf .../jsclock-X.X.tgz, change to the main directory (cd ..),
run configure, add the plugin.

If you're upgrading from an earlier version than 0.5, please remove
the "faces" directory and its contents.  The new one is called "fonts"
instead, to differentiate old GIFs versus new PNGs.  If you see userdoc.html
and/or showfaces.php, go ahead and remove them.

By default the plugin is disabled so that users who do not have
preferences for it will not see javascript code appear.  The clock
can then be enabled by selecting a face in the display preferences.
"None" can be selected to disable it again.

Once you've changed the Javascript Clock option, do "Refresh folder list"
to update your display.


Note to webmasters
------------------

Every folder refresh entails a reload of 10 to 14 (very small) images.
Multiply that by the number of users you have who use the clock and the
frequency at which they automatically refresh the folders and you end
up with a large number of entries in your access logs.  Playing with
"expires" meta tag doesn't help; refreshes cause a reload.  You have
been warned.  As far as bandwith is concerned, the average image size
for JSClock stands at 268 bytes.  Multiplied by 12 that's 3216 bytes.
Add TCP headers,syn,ack,rst,fin,http protocol,javascript code, etc...
It adds up.

For example, `tcpdump -s 1500 -w /tmp/cap host webserver` while an
auto-refresh happens gives me (YMMV):

Packet count    Total capture size   JSClock face
    21               16228           None  (plugin disabled)
    54               31356           _5x7_ Tiny  (Smallest images)
    76               46082           23x32 Nixie tubes (Largest)

If you're concerned about bandwidth usage, you can rename or remove the "fonts"
directory.  Doing so will restrict users to an image-less text-only clock
display which only entails 542 bytes of JavaScript code.


Adding faces/fonts
------------------

Adding a new face to JSClock is pretty darn easy.  First, choose a name
for your font (any name except "None" or "text_*" is fine.)
Next, using your favorite graphics editor (I use GIMP),
save the ten digits in separate PNG files named X.png (X=digit).

All 10 digits should have exactly the same height and width, otherwise
the clock face will "shimmy" from side to side.  Also, include space on
the left and/or right side so that the images look good stuck next to
each other.

Save colon.png (:) and period.png (.)  You should crop them so that
they're thinner than the digits.  Optionaly, you may also add
leftmargin.png, rightmargin.png, topmargin.png, and bottommargin.png .

Create a sub-directory of plugins/jsclock/fonts, put all your images and a file
called "info.txt" in there.  info.txt should contain a single line that
describes the size and appearance of the font.  Do not change the directory
names because they are used in the users' preference files to point to the
right font.

That's it!  If you create nice/cool fonts for JSClock, don't forget to send
me a copy.  I'll include it in the next version.

Also included: a shell script called "alphaextract.sh".  Which will extract
digits from a cropped image that looks like "0123456789:." and produce
alpha-enabled PNGs automatically.   Read the script for notes on usage.


Comments/flames/questions welcomed at:

  echo qnaal+pvz.zptvyy.pn | tr "[a-m][n-z]+" "[n-z][a-m]\100"

Go ahead and drop me a note, I enjoy the correspondance.



Revision history
----------------
0.7  2003/02/01
     Added code to support {top,left,right,bottom}margin.png
     Captured font: SNES FF6 TV
     Drew from scratch: Vacuum Fluorescent Display font, 3 sizes.  Nice glow.
     Drew from scratch: PlayStation2 font. (Ratchet&Clank rule! :)
     Captured and doctored Winblowze dialog (looks funny :)
     Changed non-specified defaults to above, 24hrs, seconds enabled.
     Fixed so that it works with PHP 4.0.6 and SM 1.2.7 (Thanks Vinh!)
     Added support for low-bandwidth image-less text face, 7 sizes.
     Added padding and color selection around clock face.
     Changed userdoc.html to userdoc.php.
     Added a whole bunch of clickable option settings in userdoc.php.

0.6  2003/01/11
     Made changes so that it now works with register_globals = Off,
     Tested with 1.2.10 and 1.4.
     Unhooked from folders preferences.
     Added another font (big Chancery black & white) because I couldn't
     very well make another release without a new font!

0.5  2003/01/09
     Major change: converted every image to PNG format.
     The field is clear for nice alpha-enabled fonts (Which IE is too stupid
     to display correctly(Oh well, complain to Microsoft or use a better
     browser or non-alpha fonts.))  IE does transparency fine, not alpha. PFFF!
     Put fonts in "fonts" directory and split fonts per named sub-directories.
     More alpha faces: Luxi-sans 10,28, Bookman 14, in black and white.
     More alpha faces: Slanted black
     Other standard faces: computerese, black & white.
     Hooked in Display preferences.
     Forgot that midnight is 12 in 12 hour mode, not 00.  Added code for that.
     Split js code in two to pre-load images before display.  (Thanks Rob!)
     Added note about weblogs and bandwidth usage.
     Changed set_faces so that it reads font description from .../info.txt

0.4  2003/01/02
     Added more faces (odo,note,ostyle,inverse shadow,crt,chinese,japanese,gold)
     from http://www.digitmania.holowww.com/.
     Added more faces (gothic)
     Removed leading zero in 12 hour mode.
     Moved images to separate "faces" directory.
     Added hour format and seconds toggle link in face.
     Wrote userdoc.html with link from folder preferences.
     Added extract10digits script.
     Fixed face wrapping with "nowrap".  Doh.
     Simplified PHP code a bit.
     Changed every occurence of " for ' where possible in PHP code.
     Added missing image index which caused funky display in NS4.

0.3  2002/12/27
     Added more faces.
     Got report that it works with SM 1.3.x.  (Thanks Wolf!)
     Removed dependency with generic_header hook.  Apparently, the javascript
     code did not need to be in the header.  Cool: JSClock should now work
     with earlier versions of squirellmail.  Cool: better update behaviour.
     Fixed missing /select tag. (Thanks Rob!)
     Cleaned-up indentation in generated javascript code.
     Made javascript much leaner by generalizing the output formatter,
     removing extra spaces, shortening names, etc... Makes script a bit
     harder to read but much shorter(good on slow links.)
     Fixed missing ""+ in js code (Thanks Don!)

0.2  2002/12/22
     Added/Created Nixie, LED, LCD fonts.
     Fixed millis compute for tenths.
     Added hundreds(dreths?) option.  Crazy.  Looks cool with Nixies.
     Added code for "None", disabling all javascript.

0.1  2002/12/20
     Initial code
     Squeleton code stolen from http://www.netcomuk.co.uk/~wwl/count.html
     Heavy mods/additions for SquirrelMail


ToDo
----
- More faces!
- Date display (Thanks Rob!)  Have to figure out localization...
