   ____ _   _    _  _____    _        _
  / ___| | | |  / \|_   _|__| |_ __ _| |_ ___
 | |   | |_| | / _ \ | |/ __| __/ _` | __/ __|
 | |___|  _  |/ ___ \| |\__ \ || (_| | |_\__ \
  \____|_| |_/_/   \_\_||___/\__\__,_|\__|___/
               3.0 by Baerchen, September 2001
                  for eggdrop 1.4.x+ & TCL 8.3
                     baerchen@germany-chat.net

INSTALLATION
**********************************************************************

- Put chatstats.tcl in your /scripts directory and make an entry in
  the bot config (e.g. source scripts/chatstats.tcl)
  Upgraders:
  **********
  CHATstats 3.0 uses a different database than previous versions.
  If CHATstats finds "csconvertdb.tcl" in the same directory where
  chatstats.tcl is in, it assumes that you want to have your old
  databases converted. It will then search for the files
  cs_toptalkers.dat
  cs_allstars.dat
  cs_activity.dat
  in $cs(workdir) and convert them to the new database format. It is
  absolutely necessary to delete csconvertdb.tcl before the next
  rehash or restart takes place, else it would try to convert again.
  
  Although the script offers the possibility, I highly recommend
  _not_ to upgrade the database, but instead to start from the
  scratch. Some relational stats will appear really messed up.
  
- Put chatstats.help in your /help directory and make an entry in the
  bot config (e.g. loadhelp chatstats.help)
  
- Put the supplied templates in $cs(workdir) (see configuration) or
  use your own ones (see the HTML TEMPLATES manual below).

- Put redbar.gif in the same directory where the HTMLs are
  uploaded/moved to.

- First time installers: rehash
  Upgraders: restart (else the bot will go nuts)

- Each user except the owner, who is allowed to use the channel
  commands has to be flagged +C| or |+C (UPPERCASE C) (except for
  the command "show" which is, of course, open to all users)

- Use .go <channel> in DCC to start monitoring <channel> (even if you
  upgraded)

STOP! If you decided to use the supplied templates, stop reading
here. If you want to create your own templates, go on ..

HTML TEMPLATES
*********************************************************************

In earlier versions of CHATstats, you've had to go with my crappy
in-script HTML. With the templates, you _can_ now use your own HTML.
Just set up a file in notepad.exe, Frontpage or whatever, insert a
few variables and you're done. You can define HOW MUCH of WHAT goes
WHERE. Use ten webpages or just one, your choice. Although this seems
to be more complicated than to go with predefined in-script HTML,
it gives all users the opportunity to freely adapt CHATstats' output
to their website's design and therefore a high degree of integration.

NAMING A TEMPLATE
---------------------------------------------------------------------
All templates have to named like this:

blabla.global.template
                 ^--- Never change this part. Must be "template".
         ^--- This part decides whether the template is used for just
              one channel or for all channels
  ^--- whatever you want, e.g. 'toptalkers' to indicate the
       this is the toptalkers template.
                 
The script looks for all files in $cs(workdir) with the suffix
'.global.template' and uses them for _all_ channels. If there's one
channel that needs a different template, copy the global template,
apply the HTML changes, replace ".global." by the channelname 
(no "#" !) and save it to $cs(workdir). CHATstats will then use this
template solely for that channel. There's no need to rehash or
restart - just do '.update'. Also, you can add and delete templates
from the directoy as you like - CHATstats uses only what it finds and
will only complain if it finds no templates at all.
Example:

You have three channels #foo #bar and #foobar

1. There's only the file toptalkers.global.template:
   This is used for all three channels #foo, #bar & #foobar
2. Now you add the file toptalkers.foo.template to the directory:
   This file is used only for channel #foo. #bar and #foobar will
   still use toptalkers.global.template

Don't forget the dots within the filenames.

INSERTING PLACEHOLDERS AND VARIABLES
---------------------------------------------------------------------

While parsing the templates, the bot needs to know where to put what.
For many information, we just have to insert a PLACEHOLDER into the
HTML code - like %%CHANNEL would always and everywhere be replaced by
the channelname e.g. #foo. Easy.
Listings like TopTalkers a.o. work a little bit different. What we
just can't do is to insert

 rank1 toptalker1 wordcount1 percent1
 rank2 toptalker2 wordcount2 percent2
 rank3 toptalker3 wordcount3 percent3

in the HTML. This would work for three TopTalkers, but not for four.
Instead we would type

 rank toptalker wordcount percent

and repeat this incl. the HTML code until our listing is complete.
Rank, toptalker, wordcount etc. is what I call VARIABLES.

Let's get into this. First, we need to tell CHATstats when a listing
starts and ends. We do this by inserting an HTML comment and the type
of listing within the comment:

<!-- type-of-listing x,y -->

x and y are arguments discussed later
Then comes the HTML stuff and the needed variables
Then we define the end of the listing by 

<!-- end of type-of-listing -->

These two comments need to be on a line by itself. Never ever add
other stuff

AVAILABLE LISTINGS
------------------

<!-- Partyline 0,0 -->
<!-- ChanUsers 0,0 -->
<!-- Bans 0,0 -->
<!-- Activity x,0 -->
<!-- TopJoiners x,y -->
<!-- TopVisitors x,y -->
<!-- TopIdlers x,y -->
<!-- TopTalkers x,y -->
<!-- TopAllStars x,y -->
<!-- TopKickers x,y -->
<!-- TopBanners x,y -->
<!-- TopKicked x,y -->
<!-- TopBanned x,y -->

x = maximum width in pixels of the graphical bar (the script needs
    to know how long the drawn bar can be at maximum)
y = the amount of max. enumerations (you don't want to see all
    354 TopTalkers, do you ?)

AVAILABLE VARIABLES WITHIN LISTINGS
-----------------------------------

<!-- Partyline 0,0 -->
!!USER          returns a user on the partyline according to 'whom *'
!!BOT           returns the bot !!USER is on
!!CHAN          returns the botchannel !!USER is on
<!-- end of Partyline -->

<!-- ChanUsers 0,0 -->
!!USER          returns a channel user according to /names
!!HOST          returns !!USER's ident@host
!!DUR           returns !!USER's online time
!!IDLE          returns !!USER's idle time
<!-- end of ChanUsers -->

<!-- Bans 0,0 -->
!!BAN           returns one ban from the channel's banlist. You
                can use this more than once e.g. to put two bans in
                one row
<!-- end of Bans -->

<!-- Activity x,0 -->
!!TIME1      returns time start range e.g. 00:00
!!TIME2      returns time end range, e.g. 01:00
!!VALUE	     returns words spoken in time range
!!PERCENT    returns !!VALUE's percentage in relation to total
!!WIDTH      returns the current width of the bar
x is the maximum width of the bar in pixels, e.g. 250
<!-- end of Activity -->

All starting with "Top"
e.g. <!-- TopTalkers x,y -->
!!USER          returns user's nick (e.g. TopTalkers)
!!RANK          returns !!USER's ranking
!!VALUE         returns !!USER's count (joins, words, etc.)
!!PERCENT       returns !!VALUE's percentual share
!!WIDTH		returns the current width of the bar
x is the maximum width of the bar in pixels, e.g. 250
y is the maximum of returned results, e.g. 10 for 10 TopTalkers
e.g. <!-- end of TopTalkers x,y -->

AVAILABLE PLACEHODERS
---------------------

Placeholder          returns ..

%%TOPTALKERSAMOUNT   amount of all TopTalkers
%%TOPTALKERSWORDS    total wordcount of TopTalkers
%%TOPTALKERSLINES    total linecount of TopTalkers
%%TOPTALKERSRATIO    TopTalkers' words/line ratio
%%ALLSTARSAMOUNT     amount of all AllStars
%%ALLSTARSWORDS      total wordcount of AllStars
%%ALLSTARSLINES      total linecount of TopTalkers
%%ALLSTARSRATIO      AllStars' words/line ratio

%%TOTALJOINS         amount of joins by all users
%%TOTALKICKS         amount of all kicks the bot has seen
%%TOTALBANS          amount of all bans the bot has seen
%%TOTALONLINE        added online time of all users
%%TOTALIDLE          added idletime of all users

%%CHANNEL            channel name
%%CHANMODES          channel modes
%%CHANTOPIC          channel topic
%%CHANTOPSETTER      nick who set the topic and date
%%CHANUSERS          channel's total users
%%CHANOPS            channel's ops
%%CHANVOICES         channel's voices
%%CHANOTHERS         channel's other users
%%CHAN%USERS         channel's total users percetual share
%%CHAN%OPS           channel's ops percetual share
%%CHAN%VOICES        channel's voices percetual share
%%CHAN%OTHERS        channel's other users percetual share 

%%TIMEBALANCE        time balance according to $cs(timebalance)
%%TIMENOW            current day of week, date and time
%%TIMENEXTUPDATE     time of next update

%%SCRIPTSTATUS       "yes|no" for CHATstats en- or disbaled
%%SCRIPTSTARTED      date of CHATstats' very first start
%%SCRIPTSTOPPED      date when CHAtstats was stopped
%%SCRIPTCYCLE        date of the last cycle

%%BOTNICK            botnick
%%BOTIRCSERVER       IRC server bot is connected to
%%BOTONLINE          time bot is connected to %%BOTIRCSERVER
%%BOTNETBOTS         list of bots in the botnet delimited by ,
%%BOTNETSIZE         botnet size
%%BOTNETUSERS        amount of users in the bot channels
%%BOTUSERLIST        bot's userlist length
%%BOTUPLINK          bot's uplink
%%BOTDOWNLINKS       bot's downlinks
%%BOTUPTIME          bot's uptime
%%BOTOFFSET          bot's offset
%%BOTTIMEZONE        bot's timezone

EXAMPLES
*********************************************************************

1. You want a listing of all users currently on your channel:

<HTML>
<BODY>
Current users in %%CHANNEL
<TABLE WIDTH=640>
<!-- ChanUsers 0,0 -->
<TR>
<TD>!!USER</TD><TD>!!HOST</TD><TD>!!DUR</TD><TD>!!IDLE</TD>
</TR>
<!-- End of ChanUsers -->
</TABLE>
</BODY>
</HTML>

2. Now, you also want to add the TopVisitors to the same webpage:

<HTML>
<BODY>
Current users in <FONT COLOR=RED>%%CHANNEL</FONT>
<TABLE WIDTH=640>
<!-- ChanUsers 0,0 -->
<TR>
<TD>!!USER</TD><TD>!!HOST</TD><TD>!!DUR</TD><TD>!!IDLE</TD>
</TR>
<!-- End of ChanUsers -->
</TABLE>
The TopVisitors are:
<TABLE WIDTH=640>
<!-- TopVisitors 300,10 -->
<TR>
<TD>!!RANK</TD>
<TD>!!USER</TD>
<TD>!!VALUE</TD>
<TD><IMG SRC="redbar.gif" HEIGHT=10 WIDTH=!!WIDTH> !!PERCENT</TD>
</TR>
<!-- End of TopVisitors -->
<BR>
People's total online time in %%CHANNEL is %%TOTALONLINE.
</TABLE>
</BODY>
</HTML>

See, it's not too difficult. To get a better impression, have a look
at the templates supplied with the script.