1 onis 0.7.2 - README - 2005-01-21
2 ==================================
3 http://verplant.org/onis/
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.
24 Just follow the example in 'config'. Please make sure to edit it!
29 Once set up right you can run onis with a command along these lines:
31 octo@leeloo:~/onis-0.5.1 $ ./onis --output reports/channel.html my-logs/*
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 ;)
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.
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.
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
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.
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.
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.
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
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
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:
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 --
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.
130 If you have any problems with this, please let me know.
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.
143 The configuration file (default: ``users.conf'') has the following syntax:
145 -- BEGIN: users.conf --
146 # User configuration for #channel
150 host: *!real*@*.provider.com;
151 link: http://homepage.url/;
152 image: http://homepage.url/my_pic.png;
154 -- END: users.conf --
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
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.
177 There is one special user, ``ignore''. Every nick that matches the
178 enclosed ``host'' settings will be ignored.
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
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!)
188 octo (at verplant.org)