onis 0.8.2 - README - 2005-06-07
==================================
https://verplant.org/onis/


 Table of Contents
-------------------
 1. Brief description
 2. Setting it up
 3. Using it
 4. Language Files
 5. User configuration


 1. Brief description
======================
``onis'' is a small perl-script that generates html-files out of your
irc-logs that contain some statistic information about what's going on on
that channel. For a sample look at the onis-homepage.


 2. Setting it up
==================
Just follow the example in 'config'. Please make sure to edit it!


 3. Using it
=============
Once set up right you can run onis with a command along these lines:

octo@leeloo:~/onis-0.5.1 $ ./onis --output reports/channel.html my-logs/*

 3.1 Timestamps
----------------
Timestamps in the logfiles are an absolute requirement. If your logfiles
don't have timestamps you can't use onis with them. So enable them now ;)

 3.2 Persistency
-----------------
Persistency is there for one reason: speed. It's simply faster to load
already-parsed data into memory than to re-parse it again. However, since
you start with nothing the first run will take as long as ever. 

Also, since this feature isn't easy for the program there are some issues
which might be confusing for the user. First, the program has to `know' if
the saved data is good and fresh and useable. It does so by comparing the
current configuration and the configuration saved with the old data. So if
you add or remove a plugin, change the ``min_word_length'' setting or edit
the user configuration your old-data will not be re-used and overwritten.

The second issue effects only the ``Eggdrop'' parser: For persistency to
work the program has to determine the ABSOLUTE time of each line (i.e. the
date and time to at least the accuracy of one minute). The eggdrop version
I use (1.6.15) saves such a date/time entry at the end of each logfile.
That means that as long as the end of the file isn't written (i.e. the
whole day it covers) onis is unable to determine the date of that file. So
running onis every 15 minutes changes the random quotes picked but that's
it. It will not add the latest file unless the date is written which
happends at midnight.

 3.3 Purge Logs
----------------
Please be very carefull with this option. This is a new, unstable and
hardly tested feature! There may be bugs and they may delete your logfiles
(if you use this feature, that is). Don't yell at me if you accidentially
get rid of two years worth of logs.. It is possible to use ``purge_logs''
without activating ``use_persistency''. That's your own damn fault.
You have been warned.

There are two modes of operation:
- ``truncate'' deletes the content of a parsed logfile. The logfile itself
               survives, so that clients that don't create new logs
	       automatically don't fall on their face.
- ``delete''   deletes the file itself. That might come in handy when a
               client creates a new logfile every day.

For both modes it is essential that onis can open the logfiles in
write-mode. It _could_ delete files without the write-bit set, but it
won't for obvious reasons.

 3.4 Data aging
----------------
This is a experimental feature introduced in 0.7.0: Since there is a lot
of absolutely useless data in the persistency files, the data gathered now
ages over the time. This may result in weird effects and I am not quite
sure it works as expected, so I'll have an eye on it and hopefully improve
it as needed ;) Anyways, here's what I do:
  Idents have a line-counter. This counter is decremented one tenth per
run and afterwards rounded down. This means, that you have to write at
very least one line every day. If an ident writes 120 lines, it will be
deleted after 30 runs (one month, when run dayly) unless he/she writes
some lines in the meantime.. Obviously this might be a problem for persons
who run onis hourly..
  The nicks and words age a little differently: For everyitem there is an
``age'' and a ``ttl'' (time to life) setting. With every occurence the age
is reset to zero and ttl increased. At the end of each session ``ttl'' is
decreased by ``age'' and afterwards ``age'' is increased by one. If
``ttl'' becomes smaller than one the record is deleted.
  In the future I will propably switch to keeping a timestamp and
calculating days, rather than counting runs, but I wanted to try this
approach first..


 4. Language Files
===================
onis 0.4.3 has a first experimental support for translations. I don't
speak any languages other than english and german so I'm hoping for
volunteers to send in more translations. The language-files are very very
simple, so my mom _could_ create them ;) I'll use a simple example:

-- BEGIN: fooish.lang --
# Language file for Fooish
"foobar": "translation"; # Should be fixed!
"Something": "Translation one", "Translation two";
-- END:   fooish.lang --

One can observe the following rules:
- Everything outside of double-quotes is ignored. Colons and semi-colons
  should be added anyways.
- Everything after an ``hash'' (`#') (up to the end of the line) is a
  comment and will be ignored. (Except when inside quotes, of course)
- The first string in a line is the original, all strings after that are
  translations. (If there is more than one translation for a given phrase
  a random one will be choosen at runtime)
- If no translation can bve found the original string will be used.
- The string provided here will be fed to a printf-call. DO NOT CHANGE any
  of those `%s', `%u', `%.1f' etc. thingies, since they will be replaced
  by whatever makes sense.

If you have any problems with this, please let me know.


 5. User configuration
=======================
Starting with version 0.4.7 onis offers the ability to configure (or
hardcode) a user configuration. The user configuration is able to:
- map one or more hostmasks to a user,
- specify a realname for a user,
- add a link to the user's homepage and
- add an image to the user.
- ignore users

The configuration file (default: ``users.conf'') has the following syntax:

-- BEGIN: users.conf --
# User configuration for #channel
nickname
{
	name:	Realname;
	host:	*!real*@*.provider.com;
	link:	https://homepage.url/;
	image:	https://homepage.url/my_pic.png;
}
-- END:   users.conf --

As you can see each record starts with a username followed by curly
brackets which contain the settings for this username. The settings are in
the form ``key: value;'' and valid keys (as of now) are ``name'',
``host'', ``link'' and ``image''. Each setting can come in any order and
as often as needed. If more than one `name', `link' or `image' is set one
will be chosen randomly at runtime.
- ``name'' Sets the realname for this nick. This name is set as ``title''
  for the call containing the username, which some browsers display as
  tooltip.
- ``host'' sets the hostmask for this username. You can use `*' and `?'
  which are interpreted as bash-like wildcards, i.e. `*' is a string of
  any length (including empty) and `?' is any character (which must be
  present). Oh, and the user-flags (like `~', `+', etc) are removed before
  matching against this string, so you should not specify them here.
- ``link'' sets the users homepage. A link to this homepage will be
  included in the statistics page.
- ``image'' specifies the URL of an image which will be displayed in later
  versions. The URL is inserted as-is without ANY checking. This means
  that it you enter a relative-URL it must be relative to the
  output-file's location.

There is one special user, ``ignore''. Every nick that matches the
enclosed ``host'' settings will be ignored.

Everything after a hash-sign `#' up to the end of the line is considered a
comment and is removed before processing the config. But I think you've
guessed that ;)

Keep in mind that changing the user configuration renders your persistency
file useless and it (the persistency file) will be deleted the next time
you run onis! (Read section 3.2!)
--
octo (at verplant.org)