Pisg

From Base de connaissances eggdrops & TCL
Jump to: navigation, search
Eye.png Cet article est en cours de traduction, n'hésitez pas à aider

What is pisg?

pisg is an IRC statistics generator. It takes IRC logfiles and turns them into nice looking stats.

In general, you would do something like this to get it running:

  • Enable logging in an IRC bot, or in your IRC client. The log will be outputted into a file.
  • You set up pisg, you define the channel name, and the path to the logfile you created.
  • You run pisg, pisg runs the log through and create statistics, it then creates an HTML page which you can upload to a webserver.

What are the requirements to run pisg?

  • An IRC client or bot where pisg supports the output logfile.
  • Any operating system which Perl runs on, this includes popular OSes such as Linux, FreeBSD, Windows and Mac. You will have a hard time finding an OS where Perl isn't supported. For Windows this means that you need to download ActivePerl.
  • Optional - a system to host the statistics page 24 hours a day, 7 days a week.
  • Optional - a system to log the channel, 24 hours a day, 7 days a week.

Setting up pisg for the first time

Most configuration happens through the pisg.cfg file, the file format is made to be easy to read, and easy to extend for further use. It uses an XML-like format, with elements and attributes.

Setting up a channel

An element called Channel is made for defining channels, a quick example of a channel is here:

<channel="#channel">
   Logfile = "channel.log"
   Format = "mIRC"
   Maintainer = "John"
   OutputFile = "mychan.html"
</channel>

The above will define a Channel called #channel, the logfile pisg will look for is called channel.log and the Format of the logfile will be mIRC. The Maintainer (which will be stated on the output page) is John.

That is basically it! Now, there are a lot more options that you can use for your channels, for this please refer to the reference documentation.

Also be-aware of the fact that pisg uses various images to show the time-related bars. These images are placed in the gfx/ folder and should be placed into the same directory as your outputted HTML file.

Specifying user options

User options are set with a simple XML-like syntax in the form:

<user nick="NICK" option="VALUE">

Remember, the nick is always required. For example to add aliases to a nick, then you could do this:

<user nick="Joe" alias="Joe^*">

The asterisk (*) means that it will match all nicks starting with 'Joe^'. So it will add all Joe^'s to 'Joe' in the stats. Another thing you can do is to add a picture to a user:

<user nick="Ben" pic="ben_holiday.jpg">

If you have a larger picture of the user as well, you can make the picture on the stats page link to it:

<user nick="Ben" pic="ben_holiday.jpg" bigpic="ben-big.jpg">

You can include * or ? to enable filename globbing to randomly choose one from several pictures: (see documentation for the ImageGlobPath option)

<user nick="Ben" pic="ben_*.jpg">

You can also set a user's sex. The sex setting can be "f"emale, "m"ale, or "b"ot:

<user nick="Ben" sex="m">

Also you can add links to URLs and e-mails:

<user nick="Christine" link="http://www.christine.com">

or

<user nick="Chris" link="chris@host.com">

The last thing you can do is to ignore nicks (for example bots):

<user nick="nameofbot" ignore="y">

You don't have to do all this in many lines, you could just as easily do:

<user nick="Joe" alias="Joe^away Joe^work" pic="joe.jpg" link="joe@joe.com" sex="m">

(Here the aliases are a space separated list of nicks, that also works! But * as a wildcard is smarter, although it is slower).

Setting global options

Many times, it will be useful to set up global options, global options are set like this:

<set option="VALUE">

Any global option will be overriden by anything defined within channel elements (see Section 2.1) For example, to change the background color of the stats page, you could do:

<set bgcolor="black">

You can set many options in a single set:

<set lang="DE" timeoffset="+1">

The above will set the language on the statistics page to DE (Deutsch, German) and set the time offset to +1. All options available are mentioned in the reference documentation.

Ignoring links

It's possible to ignore links in the "Most referenced URLs" section:

<link url="http://www.slashdot.org" ignore="y">

Including common settings for various channels

If you have, for example, more than one channel, where the users are the same, or you don't want to maintain more than one user file, you can use the "include" setting in the main config file:

<include="/home/vetinari/pisg/users.cfg">

This will include the file /home/vetinari/pisg/users.cfg in the config at the place where the include statement is set.

Note, that you can NOT include a file from an included file!

Changing the layout of your stats page

The standard layout and colors in the outputted HTML page are made to be somewhat clean and neutral. But you have the chance to change the layout yourself.

There are a few predefined color schemes for you to use, use the ColorScheme option when using them. The colorschemes distributed with pisg are: default (which is the default), darkgalaxy, darkred, justgrey, ocean, orange_grey, pisg, softgreen.

When changing it, you need a fair knowledge of CSS (Cascading Style Sheets). CSS is what most of the web uses today to define styles and layout on HTML pages. With the pisg distribution, look in the layout directory. In it resides default.css which is the file being included onto the HTML page. Open it in a text editor like vi or notepad. Then change it until you're happy with it. Be aware that you might want to look at the HiCell and HiCell2 options through pisg.cfg for changing the last two colors.

If you have created a nice stylesheet which other can take advantage of, you are encouraged to send it to the pisg mailing list so that it can be distributed with the next version of pisg.

If you want to embed the statistics into another page, use the "none" color scheme. Pisg will then omit the HTML header and write only the body part.

Running pisg

When everything is set up in the pisg configuration file (pisg.cfg), then you simply run pisg on the command-line.

  • Using Linux, BSD or another UNIX-like system: user@host:pisg-0.37$ ./pisg
  • Using Windows: c:\pisg> perl pisg

The program will run and parse the logfiles you specified in the configuration file.

If you are using Linux, BSD or another UNIX-like system and want run pisg automatically several times a day, then see the crontab file in the scripts/ directory.

For Windows, see the windows-upload-ftp.txt file with the pisg distribution, this file is also placed in the scripts/ directory.

Obtaining help and reporting bugs

If your problem could not be resolved through here, then you should send an e-mail to the pisg mailing list. You can subscribe and see more info at http://lists.sourceforge.net/lists/listinfo/pisg-general.

If you believe that you have found a bug, you should use the SourceForge bug tracking system.

General pisg options

Ces options permettent d'effectuer les réglages initiaux pour un canal.


Lire l'article

Options for various statistics features

Ces options permettent de choisir les données statistiques qui seront affichées sur la page HTML générée.


Lire l'article

Picture options

PicLocation

  • Name: PicLocation -- path to images on stats page
  • Synopsis:
<set PicLocation="gfx/">
  • Description: The location to the pictures used on the stats page - not the user pictures but the different bars in "Most Active Times".
  • Default: Current directory

UserPics

  • Name: UserPics -- number of user pictures per row
  • Synopsis:
<channel="#channel">
   Logfile = "channel.log"
   UserPics = "no"
</channel>
<set UserPics="3">
  • Description: UserPics allows you to configure the number of user pictures per row. Per default, one picture will be shown. Since pictures are usually higher than one line of text, this lets the table grow. With settings greater than 1, several pictures will be placed next to each other. A good setting would be UserPics=3 and pictures of size 60x60. Set UserPics to no or 0 to disable user pictures. The latter is useful if you share a user config file between channels and want to disable user pictures for some channels.
  • Default: yes (1)

ImagePath

  • Name: ImagePath -- path to user pictures (HTML page)
  • Synopsis:
<channel="#channel">
   Logfile = "channel.log"
   Format = "mIRC"
   ImagePath = "userpics/"
</channel>
<set ImagePath="users/">
  • Description: ImagePath defines the path to where user pictures are located, relative to the HTML page generated. The default is that user pictures is located in the same directory as the HTML page.
  • Default: current directory

DefaultPic

Name DefaultPic -- use a default user picture Synopsis


       <channel="#channel">
        Logfile = "channel.log"
        Format = "mIRC"
        DefaultPic = "not_available.jpg"
       </channel>
       <set DefaultPic="unknown.gif">
     
   

Description

DefaultPic defines a picture to be displayed for all users which have no other picture defined in the user element. This is good for showing "No picture available" or something. May contain globbing patterns, see ImageGlobPath below. Default

unset

ImageGlobPath

Name ImageGlobPath -- path to user pictures (output generation) Synopsis


       <channel="#channel">
        Logfile = "channel.log"
        Format = "mIRC"
        ImageGlobPath = "users/"
       </channel>
       <set ImageGlobPath="/var/www/pisg/">
       <set DefaultPic="default-??.gif">
     
   

Description

ImageGlobPath defines the path to the directory where user pictures are located, relative to the current directory. This setting is used to choose random pictures if ? or * (globbing characters) are used in the picture name. ? matches a single character, * matches a (possibly empty) string. The default is the ImagePath setting. (NB: This setting will be different from ImagePath if the latter is not relative to the current directory, e.g. if you are writing the HTML file outside of the current directory.) Default

current ImagePath setting

PicWidth

Name PicWidth -- define a standard width for user pictures Synopsis


       <channel="#channel">
        Logfile = "channel.log"
        Format = "mIRC"
        PicWidth = "500"
       </channel>
       <set PicWidth="500">
     
   

Description

PicWidth defines the standard width for user pictures. Setting the 'width' attribute of image-elements on the outputted stats page. See also PicHeight. Default

unset

PicHeight

Name PicHeight -- define a standard height for user pictures Synopsis


       <channel="#channel">
        Logfile = "channel.log"
        Format = "mIRC"
        PicHeight = "500"
       </channel>
       <set PicHeight="500">
     
   

Description

PicHeight defines the standard height for user pictures. Setting the 'height' attribute of image-elements on the outputted stats page. See also PicWidth. Default

unset

Misc options

Charset Name Charset -- character set to use for stats page Synopsis


       <channel="#channel">
        Logfile = "channel.log"
        Format = "xchat"
        Charset = "utf-8"
       </channel>
       <set Charset="iso-8859-15">
     
   

Description

The pisg stats page defines a character set in a meta tag, this can be used if your country is using a different one than the default. Pisg will also use this setting to convert the language templates from LangFile if the language defines a source charset. Note: you also have to tell your webserver to transmit the charset to the browser. With Apache, use "AddDefaultCharset off" in the server config. Default

iso-8859-1 LogCharset Name LogCharset -- character set for logfiles Synopsis


       <channel="#channel">
        Logfile = "channel.log"
        Format = "xchat"
        Charset = "iso-8859-1"
        LogCharset = "utf-8"
       </channel>
       <set Charset="iso-8859-15">
       <set LogCharset="iso-8859-15">
     
   

Description

If LogCharset is set and different from Charset, pisg will convert the charset using Text::Iconv. Using this option slows down log processing. Default

empty (no conversion) LogCharsetFallback Name LogCharsetFallback -- fallback character set for logfiles Synopsis


       <channel="#channel">
        Logfile = "channel.log"
        Format = "xchat"
        Charset = "utf-8"
        LogCharset = "utf-8"
        LogCharsetFallback = "iso-8859-1"
       </channel>
       <set Charset="utf-8">
       <set LogCharset="utf-8">
       <set LogCharsetFallback="iso-8859-15">
     
   

Description

LogCharsetFallback defines a fallback charset for the LogCharset conversion. This is useful if you have mixed unicode/iso-8859-* logs. Pisg will first try the conversion from LogCharset. If that fails, LogCharsetFallback is used. Note that this only works for charsets where certain byte sequences are illegal, like UTF-8. (In short: LogCharset = utf-8, LogCharsetFallback = iso-8859-15 works, the other way round does not.) Default

empty (no fallback conversion) TimeOffset Name TimeOffset -- use a different time zone than the local machine Synopsis


       <channel="#channel">
        Logfile = "channel.log"
        Format = "mIRC"
        Maintainer = "John"
        TimeOffset = "+5"
       </channel>
       <set TimeOffset="+2">
     
   

Description

By default, pisg uses the time of the local machine to display the time of the generated stats. Sometimes when you have a shell on an external box, and it's in another country, you want to use another time. This is accomplished by the TimeOffset command. Default

+0 RegexpAliases Name RegexpAliases -- use regular expressions in user aliases Synopsis


       <user nick="Joe" alias="Joe\d+">
       <set RegexpAliases="1">
     
   

Description

Enabling this option will make all aliases in <user> lines be parsed as regular expressions; this setting also applies to the IgnoreWords, FoulWords, and ViolentWords settings. Default

0 (disabled) LangFile Name LangFile -- filename of language file Synopsis


       <set LangFile="mylang.txt">
     
   

Description

With this option you have an alternative way to define the name and/or path to the language file. Usually you don't have to touch this option. Default

lang.txt CssDir Name CssDir -- path to directory with CSS files Synopsis


       <set CssDir="/usr/share/pisg/layout/">
     
   

Description

CssDir is used to define the paths to the CSS files (the ColorSchemes). Usually you don't need to change this. This setting is only used when statically including the CSS file. Default

layout/ (in current directory) HiCell, HiCell2 Name HiCell, HiCell2 -- colors for color gradient in most active nicks section Synopsis


       <set HiCell="#BABADD" HiCell2="#CCCCCC">
       <set HiCell="">
     
   

Description

HiCell and HiCell2 define the colors to be used for the color gradient in the most active nicks section. They should match your ColorScheme. When setting HiCell the empty string (""), pisg will not generate a color gradient; you might want to use this with ColorScheme="none" or AltColorScheme. Default

  1. BABADD, #CCCCCC

LogType Name LogType -- type of log (not the format of the log) Synopsis


       <set LogType="Logfile">
     
   

Description

The type of logs kept for your channel. Currently only "Logfile" is supported, so you don't need to change this option. Default

Logfile StatsDump Name StatsDump -- dump raw statistics into file Synopsis


       <set StatsDump="statsdump">
     
   

Description

This option is intended for debugging pisg, but might be useful to process the parsed logs with another program. The file contains the %stats and %lines hashes in perl's Data::Dumper format. Default

Unset

Copyright and License

pisg - Perl IRC Statistics Generator

Copyright (C) 2001-2005 Morten Brix Pedersen - <morten at wtf.dk>

Copyright (C) 2003-2005 Christoph Berg <cb at df7cb.de>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA