Help

$Id: counter.pl,v 1.2 2003/01/02 20:59:13 Administrator Exp $

Usage: counter.pl [<switches>]

    It is important to note that the '-' prefix on the switches is
    optional. This makes it easier to code the IMG SRC reference in
    your HTML file.

    -align=[left,center,right]
        Define the alignment.

    -bg=<red>,<green>,<blue>
        The background color. Red is a number from 0-255 that
	specifies the red intensity. Green is a number from 0-255 that
	specifies the green intensity and blue is a number from 0-255
	that specifies the blue intensity. Here is an example usage
	that specifies a black background (the default): -bg=0,0,0

    -commas
        Insert commas, these are counted as digits. The default is to
	not insert commas.

    -counter_file=<file_name>
        The name of the counter file.

    -debug
        Enable interactive debugging. It should not be used from the
	CGI invocation. It causes the GIF data to be written to
	counter.gif instead of standard out. It also generates a
	number of informational messages.

    -fg=red,green,blue
        The foreground color. Red is a number from 0-255 that
	specifies the red intensity. Green is a number from 0-255 that
	specifies the green intensity and blue is a number from 0-255
	that specifies the blue intensity. Here is an example usage
	that specifies a white foreground (the default): -fg=255,255,255

    -font=[8x8,16x24]
        Specify the font. The 8x8 format is pretty small but useful
        because it conveys the information without cluttering up the
        page. The 16x24 is larger and more readable. Both were hand
        generated by me and can updated by editing this script. The
        8x8 font was derived from the font generated by text2gif from
        authors of the libungif package.

    -format=[gif,png]
        Specify the image format. The choices are uncompressed GIF and
	PNG.  Note that png format is not yet available.

    -help
        Display this help message and exit.

    -id=<unique_user_id>
        The user id that designates your unique counter in the data
	file. The unique id should only contain alpha-numeric
	characters, dots, dashes and underscores. It should be derived
	from something like your email address and project. For ccdoc,
	the id that I use is jlinoff-www.joelinoff.com-ccdoc.

	If no id is specified, the default __anonymous__. Beware that
	using this id will not provide valid count information unless
	you are using a custom data file.

    -img_file=<file_name>
        The output image file name (for debugging). If this switch is
	not specified, the image is output to stdout.

    -noct
        Don't output the content-type header. This is useful for
	debugging when creating a standalone GIF. In normal operation
	a type header is output to inform the HTML processor that the
	incoming bits represent a GIF image.

    -num_digits=<number>
        The number of digits to display (with leading zero's). This
        is the same as width.

    -pad=[space,zero]
        Defines the pad character.

    -text=<string>
        Manually specify a digit string on the command line. The
	string can contain only contain decimal digits.  When this
	switch is specified, no data is written to the counter file.

    -width
        The width of the field. Same as -num_digits.

    The examples below show how to use this script from the command line:

        % perl counter.pl -help
	% perl counter.pl -debug
	% perl counter.pl > tmp.gif
	% perl counter.pl -fg=255,0,0 -bg=0,255,0
	% perl counter.pl -commas -counter_file=counter.dat
	% perl counter.pl -noct -commas -num_digits=10 -text="1234567" > tmp.gif
	% perl counter.pl -noct -num_digits=10 -text="1234567" -img_file tmp.gif

    The example below shows how to use this script from an HTML
    file.

        <IMG BORDER=1
              SRC="http://mysite/cgi-bin/counter.pl?id=jlinoff-www.joelinoff.com-general&align=center&pad=space&commas&counter_file=/path/to/counter/dat/file/mycounter.dat">

    Acknowlegements:
        
    Eric S. Raymond
        For the libungif package. I used text2gif to derive the 8x8
        fonts used here.

    Dr. Tom Lane
       For his explanation of the LZW patent issues in his posting to
       comp.graphics.misc on Dec 05 1996 as referenced in Subject V-7
       in part of the FAQ found at:

       ftp://rtfm.mit.edu/pub/usenet/news.answers/graphics/fileformats-faq/part.

       I also used his explanation of where to insert the CC codes to
       create an uncompressed (or expanded) GIF that does not use the
       LZW algorithm.


HTML Examples

This section shows how to add a counter to your HTML file. All of the examples assume that the image statement looks like this: <img border=1 src=example>.

Example 1: Simple

<img border=1 src="http://www.joelinoff.com/cgi-bin/counter.pl?id=counter-help-examples">

Example 2: Pad with spaces

<img border=1 src="http://www.joelinoff.com/cgi-bin/counter.pl?id=counter-help-examples&pad=space">

Example 3: Center

<img border=1 src="http://www.joelinoff.com/cgi-bin/counter.pl?id=counter-help-examples&pad=space&align=center">

Example 4: Change the width

<img border=1 src="http://www.joelinoff.com/cgi-bin/counter.pl?id=counter-help-examples&num_digits=12">

Example 5: Change the foreground and background colors

<img border=1 src="http://www.joelinoff.com/cgi-bin/counter.pl?id=counter-help-examples&fg=255,0,0&bg=0,255,0">

Example 6: Change the font size

<img border=1 src="http://www.joelinoff.com/cgi-bin/counter.pl?id=counter-help-examples&font=16x24">

Example 7: Embed commas

<img border=1 src="http://www.joelinoff.com/cgi-bin/counter.pl?id=counter-help-examples&commas&pad=space&width=10">

Example 8: Write a fixed number

<img border=1 src="http://www.joelinoff.com/cgi-bin/counter.pl?id=counter-help-examples&commas&pad=space&width=14&text=1234567890&font=16x24&align=center">

Used Ids for counter.dat

Id                               Count
================================ ======
__anonymous__                       362
|ls|                                  1

TOTAL                                 2

License

Copyright (C) 1998-2003 by Joe Linoff (http://www.joelinoff.com)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL JOE LINOFF BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Comments and suggestions are always welcome.