Updated 8.6.2013 based on version 1.2.

	
    INDEX
    -----

  1. Quickstart
  2. Files included
  3. How to edit ircstats.cfg
  4. Common errors explained
  5. Some final words
  6. About the source



  1. Quickstart
  -------------

1. Unpack IRCStats-1.2.tgz

2. To compile you only need to run "make".

3. Edit ircstats.cfg to make your own configs.

4. Edit or remove ircstatsheader.txt and ircstatsfooter.txt
   The original text isn't something that you want to have
   on your page.

5. Convert the logfile to a proper format if you need to
   Programs for that can be found from the webpage.

6. Run ircstats.

7. View the generated html with a graphical browser and return
   to step 3 if it didn't look like you wanted.


  2. Files included
  -----------------

CHANGES             List of changes between versions.
COPYING             License information.
INSTALL             Install instructions.
Makefile            Information for the compiler.
README              This file.
TODO                Some features that should be added some day.
colors(dir)         Directory for color configs
data(dir)           Directory for history data
html(dir)           Directory for html file and few images
htmlhead.txt        File that has lines that will be included inside 
                    <head> tags
ircstats.cfg        Config file
ircstatsfooter.txt  Lines that will be included near of the end of 
                    the html file.
ircstatsheader.txt  Lines that will be included near of the beginning 
                    of the html file.
languages(dir)      Directory for language files.
nickjoin.txt        List on nicks that should be joined manually.
src(dir)            Directory containing the source code.
tslog.irc           Logging script for IrcII.


  3. How to edit ircstats.cfg
  ---------------------------

First thing that you have to make sure is that your editor doesn't
add any extra characters to the file. The file is a plain text file
so IRCStats won't be able to read it if it's for example in Word Document
format. Emacs, vi, pico and so on are good editors if you use linux
to edit the file. Don't try to edit the file under Windows unless you
really know that the editor would save the file in the same format
that a linux editor would.

But now to the file. Each line starting with "//" are comments and aren't
parsed by IRCStats. You can add those if you like to. The config tags used
are trying to be selfexplaining but here's the list again with more comments.

> // Basic settings
> creatorOfLog: someone
> channelName: #MyChannel

These should be clear to everyone. :)

> // Files
> htmlFilename: html/index.html
> languageFilename: language/english.lang
> excludeFilename: ircstatsexclude.txt
> nickjoinFilename: nickjoin.txt
> htmlheadFilename: htmlhead.txt
> colorsFilename: colors/uglyDefault.cfg
> headerFilename: ircstatsheader.txt
> footerFilename: ircstatsfooter.txt
> historydataDir: data/
> backgroundFilename: None

The language file is searched from the languages. By default all paths
to files are relative ones but a full path can also be used. Same goes 
to colors file that is searched from the colors directory.
If you want to have a background picture then specify it here and use
the html path (http://myserv.er/dir/picture.jpg) for it. The exclude file
is a plain text file (not included since it would be empty anyway) that
contains nicks that should be excluded. The format is one nick on every
line. Wildcards are not supported, but nickjoin.txt is executed before
excluding so it's possible to for example join every excluded nick into 
one and then exclude that nick.


> // Advanced settings
> useNickjoin.txt: True
> showTopic: True
> showBigNumbers: True
> showLongEndText: True
> showAverageChar/Line: True
> showDailyIRCingActivity: True
> showTimeOfDay: True 
> showDatesInDailyIRCingActivity: False

Dates aren't based in any datestamp found from the log but calculated
backwards from the current day. Enable this only if you know that log
is generated the same day. See also "dayCorrection".

> nickconnection: 4

How many letters will be used to make difference between nicks. Choose -1
if you don't want nicks to be joined. Short example: let's assume
nickconnection is set to 4 and the channel has nicks "foobar" and "foober".
IRCStats will assume that those both are the same nick because the 4 first
letters are the same. If such behavior isn't wanted then rising the number
will help. In this case 5 is enough to make the difference.

> isNickconnectorCaseSensitive: True
> isNickjoin.txtCaseSensitive: True

Selecting if nickjoining should be case sensitive or not. If you select
'False' then for example AbC, ABC and aBC would be seen as the same nick.

> topTalkerLength: 50

With this you can change the number of nicks shown in the top talker
list. However it won't generate any random nicks if you for example
select 100 and you have only 60 nicks in the log.

> linesRequired: 0

Nicks having less than the number of lines specified here won't
be shown in the stats.

> topTalkerTableWidth: 0

The width of the top talker table can be specified here if you for
some reason would like to change it.

> quoteLength: 65

How many letters will be shown in quotes.With this you can have some 
control on the length of quotes. Currently splitting is done
even inside words.

> quoteMinimum: 35

How many letters should the quotes at least be. Using this you can
eliminate quotes that have only few words or a smiley.

> standardWhenDoWe: 0

'When do we...' starts from: 0 = 0, 1 = 6
With this the starting hour of 'When do we...' section can be selected.
Some think that it looks better if it starts from 6 o'clock.

> useHistorySystem: False

The history system makes it possible to use small logs when updating
without loosing information about nicks. You just have to make sure that
the log doesn't contain any lines that are already analyzed once.
Otherwise the daycounter and some other things will go wrong.

> scaleLinePipes: True

Should pipes indicating number of lines in top talker be scaled
compared to the nick who has most lines. Setting this to false will
give everyone a pipe with the same width. This way is might be
easier to see how lines are divided by hours.

> timezoneCorrection: 0

Use this if the log was generated using some other timezone and you'd like
to correct the error. For example if the difference is 1 hour then use the 
value 1 instead of 0. Those values can also be negative.

> dayCorrection: 0

With this option it's possible to adjust when the last day of the log was.
For example if the log is always analyzed 2 days after logging it then
2 would be the right value. 

> // Output level: 0 = no, 1 = normal, 2 = debug
> outputLevel: 1

How much IRCStats will generate output to the terminal. When
using 'debug', the output should be piped to a file since
it will show every line of the long and include some additional
information.


  4. Common errors explained
  --------------------------

Here are the most common errors that I've been getting. However answer
given here might not work in every case.

1. Unable to open file
''''''''''''''''''''''

> Error:
> Unable to open file "colors/uglyDefault.cfg" for reading configs!

In most cases this error comes because the user is trying to run
IRCStats using its full path (/some/dir/to/ircstats/ircstats).
Currently IRCStats has to be run using ./ircstats (yes, that dot
should be there). This problem can be fixed be just adding a "cd
/some/dir/to/ircstats/" before ./ircstats in the case that a shell
script is used for example from crontab or using full paths to files
in the config and giving the config as one parameter to IRCStats.

2. Distorted error message
''''''''''''''''''''''''''

> Error:
> " for reading configs!olors/uglyDefault.cfg

The config file (ircstats.cfg or some other used) has become corrupted
for some reason. In most cases this error comes when the file has been
edited using some Windows editor. To fix this, get the default config
from the archive and use some linux based editor to edit it. It might
also be good to try if even the default config works before editing it.

3. Userlimit reached
''''''''''''''''''''

> Error:
> Userlimit reached, unable to continue.

By default IRCStats has a limit of 20000 different nicks. The reason for
this is to limit the memory usage. However some channels seem to have more
nicks than I expected, so in these cases the limit should be changed.
This limit is hardcoded in the source on line 36. Changing the limit to
40000 should be enough for most who even got the error. Recompiling
the source is required after this change.


  5. Some final words (of wisdom?-)
  ---------------------------------

IRCStats was designed to update the stats once a day. It's still possible to
make it update the stats much more often but remember that the bigger the
log is the more time it takes to analyze. Also when using the history
system there might be problems getting good random quotes and topics.
In my opinion updating stats every 5min. is a little bit overkill. Does
someone really look stats that often?

If you want to make updating automatic then crontab might be a good
choice.


  6. About the source
  -------------------

I started writing IRCStats 3 years ago with very little experience of C.
First it was only a simple program that counted lines from text files, but
it slowly got the aspects of a stats program. However my mistake was to
continue adding new features at the point where I should have started
redesigning everything. That's why there's currently still parts of that
old nonflexibly code limiting the possibility to add new features. Also
because IRCStats currently has most features I need, I haven't had much
interest to rewrite everything.

What I'm trying to say is that the source is a good example of coding
without designing and that was one reason why I didn't make in open at the
beginning. The other reason was my fear of a patch flood, but releasing
vnStat (http://humdi.net/vnstat/) proved that wrong. Nevertheless
I promised that I'd make the source public when the project would start to
be kind of frozen and I think now it the time.
