README

   1  onis 0.8.2 - README - 2005-06-07
   2 ==================================
   3 http://verplant.org/onis/
   4
   5
   6  Table of Contents
   7 -------------------
   8  1. Brief description
   9  2. Setting it up
  10  3. Using it
  11  4. Language Files
  12  5. User configuration
  13
  14
  15  1. Brief description
  16 ======================
  17 ``onis'' is a small perl-script that generates html-files out of your
  18 irc-logs that contain some statistic information about what's going on on
  19 that channel. For a sample look at the onis-homepage.
  20
  21
  22  2. Setting it up
  23 ==================
  24 Just follow the example in 'config'. Please make sure to edit it!
  25
  26
  27  3. Using it
  28 =============
  29 Once set up right you can run onis with a command along these lines:
  30
  31 octo@leeloo:~/onis-0.5.1 $ ./onis --output reports/channel.html my-logs/*
  32
  33  3.1 Timestamps
  34 ----------------
  35 Timestamps in the logfiles are an absolute requirement. If your logfiles
  36 don't have timestamps you can't use onis with them. So enable them now ;)
  37
  38  3.2 Persistency
  39 -----------------
  40 Persistency is there for one reason: speed. It's simply faster to load
  41 already-parsed data into memory than to re-parse it again. However, since
  42 you start with nothing the first run will take as long as ever.
  43
  44 Also, since this feature isn't easy for the program there are some issues
  45 which might be confusing for the user. First, the program has to `know' if
  46 the saved data is good and fresh and useable. It does so by comparing the
  47 current configuration and the configuration saved with the old data. So if
  48 you add or remove a plugin, change the ``min_word_length'' setting or edit
  49 the user configuration your old-data will not be re-used and overwritten.
  50
  51 The second issue effects only the ``Eggdrop'' parser: For persistency to
  52 work the program has to determine the ABSOLUTE time of each line (i.e. the
  53 date and time to at least the accuracy of one minute). The eggdrop version
  54 I use (1.6.15) saves such a date/time entry at the end of each logfile.
  55 That means that as long as the end of the file isn't written (i.e. the
  56 whole day it covers) onis is unable to determine the date of that file. So
  57 running onis every 15 minutes changes the random quotes picked but that's
  58 it. It will not add the latest file unless the date is written which
  59 happends at midnight.
  60
  61  3.3 Purge Logs
  62 ----------------
  63 Please be very carefull with this option. This is a new, unstable and
  64 hardly tested feature! There may be bugs and they may delete your logfiles
  65 (if you use this feature, that is). Don't yell at me if you accidentially
  66 get rid of two years worth of logs.. It is possible to use ``purge_logs''
  67 without activating ``use_persistency''. That's your own damn fault.
  68 You have been warned.
  69
  70 There are two modes of operation:
  71 - ``truncate'' deletes the content of a parsed logfile. The logfile itself
  72                survives, so that clients that don't create new logs
  73                automatically don't fall on their face.
  74 - ``delete''   deletes the file itself. That might come in handy when a
  75                client creates a new logfile every day.
  76
  77 For both modes it is essential that onis can open the logfiles in
  78 write-mode. It _could_ delete files without the write-bit set, but it
  79 won't for obvious reasons.
  80
  81  3.4 Data aging
  82 ----------------
  83 This is a experimental feature introduced in 0.7.0: Since there is a lot
  84 of absolutely useless data in the persistency files, the data gathered now
  85 ages over the time. This may result in weird effects and I am not quite
  86 sure it works as expected, so I'll have an eye on it and hopefully improve
  87 it as needed ;) Anyways, here's what I do:
  88   Idents have a line-counter. This counter is decremented one tenth per
  89 run and afterwards rounded down. This means, that you have to write at
  90 very least one line every day. If an ident writes 120 lines, it will be
  91 deleted after 30 runs (one month, when run dayly) unless he/she writes
  92 some lines in the meantime.. Obviously this might be a problem for persons
  93 who run onis hourly..
  94   The nicks and words age a little differently: For everyitem there is an
  95 ``age'' and a ``ttl'' (time to life) setting. With every occurence the age
  96 is reset to zero and ttl increased. At the end of each session ``ttl'' is
  97 decreased by ``age'' and afterwards ``age'' is increased by one. If
  98 ``ttl'' becomes smaller than one the record is deleted.
  99   In the future I will propably switch to keeping a timestamp and
 100 calculating days, rather than counting runs, but I wanted to try this
 101 approach first..
 102
 103
 104  4. Language Files
 105 ===================
 106 onis 0.4.3 has a first experimental support for translations. I don't
 107 speak any languages other than english and german so I'm hoping for
 108 volunteers to send in more translations. The language-files are very very
 109 simple, so my mom _could_ create them ;) I'll use a simple example:
 110
 111 -- BEGIN: fooish.lang --
 112 # Language file for Fooish
 113 "foobar": "translation"; # Should be fixed!
 114 "Something": "Translation one", "Translation two";
 115 -- END:   fooish.lang --
 116
 117 One can observe the following rules:
 118 - Everything outside of double-quotes is ignored. Colons and semi-colons
 119   should be added anyways.
 120 - Everything after an ``hash'' (`#') (up to the end of the line) is a
 121   comment and will be ignored. (Except when inside quotes, of course)
 122 - The first string in a line is the original, all strings after that are
 123   translations. (If there is more than one translation for a given phrase
 124   a random one will be choosen at runtime)
 125 - If no translation can bve found the original string will be used.
 126 - The string provided here will be fed to a printf-call. DO NOT CHANGE any
 127   of those `%s', `%u', `%.1f' etc. thingies, since they will be replaced
 128   by whatever makes sense.
 129
 130 If you have any problems with this, please let me know.
 131
 132
 133  5. User configuration
 134 =======================
 135 Starting with version 0.4.7 onis offers the ability to configure (or
 136 hardcode) a user configuration. The user configuration is able to:
 137 - map one or more hostmasks to a user,
 138 - specify a realname for a user,
 139 - add a link to the user's homepage and
 140 - add an image to the user.
 141 - ignore users
 142
 143 The configuration file (default: ``users.conf'') has the following syntax:
 144
 145 -- BEGIN: users.conf --
 146 # User configuration for #channel
 147 nickname
 148 {
 149         name:   Realname;
 150         host:   *!real*@*.provider.com;
 151         link:   http://homepage.url/;
 152         image:  http://homepage.url/my_pic.png;
 153 }
 154 -- END:   users.conf --
 155
 156 As you can see each record starts with a username followed by curly
 157 brackets which contain the settings for this username. The settings are in
 158 the form ``key: value;'' and valid keys (as of now) are ``name'',
 159 ``host'', ``link'' and ``image''. Each setting can come in any order and
 160 as often as needed. If more than one `name', `link' or `image' is set one
 161 will be chosen randomly at runtime.
 162 - ``name'' Sets the realname for this nick. This name is set as ``title''
 163   for the call containing the username, which some browsers display as
 164   tooltip.
 165 - ``host'' sets the hostmask for this username. You can use `*' and `?'
 166   which are interpreted as bash-like wildcards, i.e. `*' is a string of
 167   any length (including empty) and `?' is any character (which must be
 168   present). Oh, and the user-flags (like `~', `+', etc) are removed before
 169   matching against this string, so you should not specify them here.
 170 - ``link'' sets the users homepage. A link to this homepage will be
 171   included in the statistics page.
 172 - ``image'' specifies the URL of an image which will be displayed in later
 173   versions. The URL is inserted as-is without ANY checking. This means
 174   that it you enter a relative-URL it must be relative to the
 175   output-file's location.
 176
 177 There is one special user, ``ignore''. Every nick that matches the
 178 enclosed ``host'' settings will be ignored.
 179
 180 Everything after a hash-sign `#' up to the end of the line is considered a
 181 comment and is removed before processing the config. But I think you've
 182 guessed that ;)
 183
 184 Keep in mind that changing the user configuration renders your persistency
 185 file useless and it (the persistency file) will be deleted the next time
 186 you run onis! (Read section 3.2!)
 187 --
 188 octo (at verplant.org)