Clock 1.0.1

     by Kevin Athey

Behold! Software (c)1995


The Most Recent Version
-----------------------
Always get the most recent version from:
URL:    http://www.he.net/~bbsbs/behold/clock.html
FTP:    ftp://ftp.adnc.com/ftp/dropboxes/bbsbs/behold
        Server:    ftp.adnc.com
        Directory: /ftp/dropboxes/bbsbs/behold
        File:      clk???.zip


What Is It?
-----------
- Creates a clock on your page using HTML via the <img src> method.
- Windows NT or 95 (32-bit) Console Application.
- Uses Standard CGI. (Different from Windows CGI.)
- Must be installed on your server.


Instructions
------------
Always start with a very simple clock and then build it up to what you
want.  Your first HTML piece should look something like this:

<img src=http://am.net/NS/CGI/Behold/clock>


If this doesn't work, you will have to look carefully at how you have things setup.


Usage
-----
Usage: clock [-f<fg clr>] [-b<bg clr> | -t<t idx>] [-s<style_name>]
             [-d<GIF dir>] [-r] [-l<LAYOUT>]
        -f<fg clr>     - color to render foreground in.
        -b<bg clr>     - color to render background in.
        -t<t idx>      - index to color which should be transparent.
        -s<style_name> - name of one of the standard styles on am.net.
        -r             - raw, no HTTP prefix. not useful in HTML,
                         only on the command line.
        -l<LAYOUT>     - specify format of time.  (default: ZH:MM)
                             CASE is SIGNIFICANT.
                         HH - 24-hour clock (no zero pad).
                         ZH - 24-hour clock (zero pad).
                         hh - 12-hour clock (no zero pad).
                         zh - 12-hour clock (zero pad).
                         MM - the minutes.
                         SS - the seconds.
                         m  - the meridiem.  (AM or PM).

You can get this same information by running the program at the command
line and specifying "-h" or "-?".


Some More Advanced And Complicated Examples
-------------------------------------------

HTML Example:
<img src=http://am.net/NS/CGI/Behold/clock?-f0000FF+-bFF0000>

This will put the graphic in your page.  The time will be displayed as a
24-hour clock without seconds: 20:54 or 08:54, depending on PM or AM.
This will create BLUE numbers on a RED background using the default digits.


Another HTML Example:
<img src=http://am.net/NS/CGI/Behold/clock?-t0+-f00FF00>

This will create GREEN numbers on a TRANSPARENT background using the
default digits.


Yet Another HTML Example:
<img src=http://am.net/NS/CGI/Behold/clock?-lhh:MM:SSm>

This will use the default digits to present the time and make it look
something like this: 8:54:32pm or 8:54:32am.


Ultimate Example: See my web page.
    http://cervantes.comptons.com/home.htm
Then view the source.

(BE SURE TO MODIFY THE URL AND FOR USE AT am.net!)

Separating Parameters
---------------------
You could use a "&" instead of "+" to separate parameters to the clock.


Specifying Colors
-----------------
When you are specifying colors you must use the following format.
RRGGBB, where each pair represents a hexadecimal number.  You must include
all necessary zeros.

Example: FF0000 - Bright Red
Example: 00FF00 - Bright Green
Example: 0000FF - Bright Blue


Adding Your Own Digits
----------------------
You can create your own digits.  They must be GIFs and they must all be
the same height in one group.  The naming convention is the digit
followed by the style name.  And for the colon (or separator) use 'c' to
replace the digit.  For AM use 'a' to replace the digit. For PM use 'p' to
replace the digit.  So your new complete set will have the following files
in it:

0mine.gif
1mine.gif
2mine.gif
3mine.gif
4mine.gif
5mine.gif
6mine.gif
7mine.gif
8mine.gif
9mine.gif
cmine.gif
amine.gif
pmine.gif

The style name will be 'mine'.

Furthermore, if you do create your own digits, please write me and tell me
about them or even send them to me.  I will want to add them to my digit
page (http://cervantes.comptons.com/digits).


Raw Output
----------
This parameter (-r) allows you to use the clock from the command line to
generate a GIF using the digits for a number.  I just added this feature to
make it easier than assembling the digits in some paint program.



QUESTIONS
---------
If you have any questions, write me: kathey@birdbrain.com

When writing, please answer these questions first, then tell me about your
problem.  If you don't answer these questions in your first piece of mail,
I will probably just copy these lines to the clipboard and into my reply,
and ask you to answer them again.

1. Where is your site?
2. Where is an example of your clock?
3. What is the exact HTML you are using to call the clock?
4. What server software are you using?
5. What are the contents of the "clock.err" file?


Cost
----
This product is donation ware.

If you want to send me $5.00 or more, I will cash your check.
This is totally voluntary.  I am simply asking for the money to
keep my private site up and keep good software coming your way.

Make it payable to Kevin Athey.
Mail it to:
    Behold! Software
    P.O.Box 83174
    San Diego, CA  92138


History
-------
   DATE       VERSION   COMMENT
-----------   -------   -------
14 Nov 1995    1.0.1    -Fixed bug affecting display of the twelfth hour in
                         non-zero padded 12-hour mode.

14 Nov 1995    1.0.0    -Initial release.



Authenticity Verification
-------------------------
If you use "pkunzip" to extract files from this archive, you should
see the following message when the files are completely extracted:

Authentic files Verified!   # LIW379
BirdBrain Systems

BirdBrain Systems is a sister company of Behold! Software.
If you don't see this, then the archive has probably been corrupted.


CREDITS
-------
This product uses "gd 1.2" for the GIF manipulation.
You can acquire this library at the following location:
http://siva.cshl.org/gd/gd.html

Here are all the copyrights required by it:

gd 1.2 is copyright 1994, 1995, Quest Protein Database Center, Cold Spring
Harbor Labs. Permission granted to copy and distribute this work provided that
this notice remains intact. Credit for the library must be given to the Quest
Protein Database Center, Cold Spring Harbor Labs, in all derived works. This
does not affect your ownership of the derived work itself, and the intent is
to assure proper credit for Quest, not to interfere with your use of gd. If
you have questions, ask. ("Derived works" includes all programs that utilize
the library. Credit must be given in user-visible documentation.) 

The Quest Protein Database Center is funded under Grant P41-RR02188 by the
National Institutes of Health. 

Written by Thomas Boutell (boutell@boutell.com), 2/94 - 7/95. 

The GIF compression code is based on that found in the pbmplus utilities,
which in turn is based on GIFENCOD by David Rowley. See the notice below: 

/*
** Based on GIFENCOD by David Rowley .A
** Lempel-Zim compression based on "compress".
**
** Modified by Marcel Wijkstra 
**
** Copyright (C) 1989 by Jef Poskanzer.
**
** Permission to use, copy, modify, and distribute this software and its
** documentation for any purpose and without fee is hereby granted, provided
** that the above copyright notice appear in all copies and that both that
** copyright notice and this permission notice appear in supporting
** documentation.  This software is provided "as is" without express or
** implied warranty.
**
** The Graphics Interchange Format(c) is the Copyright property of
** CompuServe Incorporated.  GIF(sm) is a Service Mark property of
** CompuServe Incorporated.
*/

The GIF decompression is based on that found in the pbmplus utilities, which
in turn is based on GIFDECOD by David Koblas. See the notice below: 

/* +-------------------------------------------------------------------+ */
/* | Copyright 1990, 1991, 1993, David Koblas.  (koblas@netcom.com)    | */
/* |   Permission to use, copy, modify, and distribute this software   | */
/* |   and its documentation for any purpose and without fee is hereby | */
/* |   granted, provided that the above copyright notice appear in all | */
/* |   copies and that both that copyright notice and this permission  | */
/* |   notice appear in supporting documentation.  This software is    | */
/* |   provided "as is" without express or implied warranty.           | */
/* +-------------------------------------------------------------------+ */


Warranty and Liability
----------------------
I have done my best to provide bug free code, but there is no possible way
for an imperfect human to create the perfect program.  Hence, I must say that
I can't possible be held accountable in way, shape or form (especially
financially) for any damage to your system or software which might result
from using this program.  But I can give you the unconditional guarantee that
I have done nothing malicious and that I have made every possible effort to
make this the best possible program I can.


Distribution
------------
You may freely redistribute this archive to all your friends at no cost to
them unless you charge them for the media on which they receive it.
The cost may not reasonably exceed the cost of the media on which this
archive resides.  You may never distribute this archive in pieces.  You must
distribute the archive from which you extracted this file (readme.txt).


*            -kevin-            *| ep |*    BirdBrain Systems     *
* sick with the good infection  *| ip |*    Makers of DisKing     *
*     kathey@birdbrain.com      *| ha |*                          *
* http://cervantes.comptons.com *| ny |* http://www.he.net/~bbsbs *