   ____ _   _    _  _____    _        _
  / ___| | | |  / \|_   _|__| |_ __ _| |_ ___
 | |   | |_| | / _ \ | |/ __| __/ _` | __/ __|
 | |___|  _  |/ ___ \| |\__ \ || (_| | |_\__ \
  \____|_| |_/_/   \_\_||___/\__\__,_|\__|___/
               3.1.0 by Baerchen, October 2001
                  for eggdrop 1.4.x+ & TCL 8.3
                     baerchen@germany-chat.net
       latest versions @ home.dal.net/baerchen

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

- Put chatstats.tcl in your /scripts directory and make an entry in
  the bot config (e.g. source scripts/chatstats.tcl)
  
  Upgraders from 2.x:
  -------------------
  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.
  
- Copy chatstats.help in your /help directory and make an entry in
  the bot config (e.g. loadhelp chatstats.help)
  
- Copy the supplied templates in $cs(workdir) (see configuration) or
  use your own ones (see the HTML TEMPLATES manual below).

- Copy 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, you're finished.
Next chapter deals with how to make your own templates.

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 be 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 parameters 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 -->

In opposite to variables and placeholders, 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 -->
<!-- TopActiveUsers 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
-----------------------------------
VARIABLE      RETURNS .. 
--------      ----------

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

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

<!-- Bans 0,0 -->
!!BAN         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       time start range e.g. 00:00
!!TIME2       time end range, e.g. 01:00
!!VALUE	      words spoken in time range
!!PERCENT     !!VALUE's percentage in relation to total
!!WIDTH          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        user's nick (e.g. from TopTalkers)
!!RANK        !!USER's ranking
!!VALUE       !!USER's count (joins, words, etc.)
!!PERCENT     !!VALUE's percentual share
!!WIDTH       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

%%TOTALWORDS         Toptalkers' + AllStar's words
%%TOTALLINES         Toptalkers' + AllStar's words
%%TOTALRATIO         Toptalkers' + AllStar's 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
%%TOTALACTIVE        added active chatting time of all users

%%CHANNEL            channel name
%%CHANMODES          channel modes
%%CHANTOPIC          channel topic
%%CHANTOPSETTER      nick who set the topic and date
%%CHANUSERS          channel's total user amount
%%CHANOPS            channel's ops
%%CHANVOICES         channel's voices
%%CHANOTHERS         channel's other users
%%CHAN%USERS         channel's total users percentual 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" or "no" for CHATstats en- or disbaled
%%SCRIPTSTARTED      date of CHATstats' very first start
%%SCRIPTSTOPPED      date when CHAtstats was last stopped
%%SCRIPTCYCLE        date of the last cycle

%%BOTNICK            botnick
%%BOTIRCSERVER       IRC server the bot is connected to
%%BOTONLINE          time the 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>

As might have noticed, it doesn't matter whether you put several 
variables or placeholders in one line or each of them in a single
line. You can also mix them. 

To get a better impression, have a look at the templates supplied
with the script.