path: root/doc/en/weechat.en.xml

<?xml version="1.0" encoding="iso-8859-1"?>

<!--

WeeChat documentation (english version)

Copyright (c) 2003-2006 by FlashCode <flashcode@flashtux.org>

This manual 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 manual 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., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

-->

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd"
[
  <!ENTITY config.xml SYSTEM "config.xml">
  <!ENTITY weechat_commands.xml SYSTEM "weechat_commands.xml">
  <!ENTITY irc_commands.xml SYSTEM "irc_commands.xml">
  <!ENTITY key_functions.xml SYSTEM "key_functions.xml">
]>

<book lang="en">
  
  <bookinfo>
    
    <title>WeeChat 0.1.8-cvs - User guide</title>
    <subtitle>Fast, light and extensible IRC client</subtitle>
    
    <author>
      <firstname>Sébastien</firstname>
      <surname>Helleu</surname>
      <email>flashcode AT flashtux.org</email>
    </author>
    
    <copyright>
      <year>2006</year>
      <holder>Sébastien Helleu</holder>
    </copyright>
    
    <legalnotice>
      <para>
        This manual 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.
      </para>
      <para>
        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.
      </para>
      <para>
        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., 51 Franklin St, Fifth Floor, Boston, MA
        02110-1301 USA
      </para>
    </legalnotice>
    
    <abstract>
      <para>
        This manual documents WeeChat IRC client, it is part of WeeChat.
      </para>
      <para>
        Latest version of this document can be found on this page:
        <ulink url="http://weechat.flashtux.org/doc.php">
          http://weechat.flashtux.org/doc.php
        </ulink>
      </para>
    </abstract>
    
  </bookinfo>
  
  <!-- =========================== Introduction =========================== -->
  
  <chapter id="chapIntroduction">
    <title>Introduction</title>
    
    <para>
      This chapter describes WeeChat and pre-requisites for its installation.
    </para>
    
    <section id="secDescription">
      <title>Description</title>
      
      <para>
        WeeChat (Wee Enhanced Environment for Chat) is a free
        <acronym>IRC</acronym> client, fast and light, designed for many
        operating systems.
      </para>
      
      <para>
        Main features are:
        <itemizedlist>
          <listitem>
            <para>
              multi-servers connection (with SSL, IPv6, proxy)
            </para>
          </listitem>
          <listitem>
            <para>
              many GUI: Curses, wxWidgets, Gtk and Qt
            </para>
          </listitem>
          <listitem>
            <para>
              small, fast and light
            </para>
          </listitem>
          <listitem>
            <para>
              customizable and extensible with plugins and scripts
            </para>
          </listitem>
          <listitem>
            <para>
              compliant with <acronym>RFC</acronym>s
              <ulink url="http://www.ietf.org/rfc/rfc1459.txt">1459</ulink>,
              <ulink url="http://www.ietf.org/rfc/rfc2810.txt">2810</ulink>,
              <ulink url="http://www.ietf.org/rfc/rfc2811.txt">2811</ulink>,
              <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink> and
              <ulink url="http://www.ietf.org/rfc/rfc2813.txt">2813</ulink>
            </para>
          </listitem>
          <listitem>
            <para>
              multi-platform (GNU/Linux, *BSD, MacOS X, Windows and other)
            </para>
          </listitem>
          <listitem>
            <para>
              100% GPL, free software
            </para>
          </listitem>
        </itemizedlist>
      </para>
      
      <para>
        WeeChat homepage is here:
        <ulink url="http://weechat.flashtux.org">
          http://weechat.flashtux.org
        </ulink>
      </para>
      
    </section>
    
    <section id="secPreRequis">
      <title>Pre-requisites</title>
      
      <para>
        In order to install WeeChat, you <emphasis>need</emphasis>:
        <itemizedlist>
          <listitem>
            <para>
              a running GNU/Linux system (with compiler tools for source
              package)
            </para>
          </listitem>
          <listitem>
            <para>
              "root" privileges (to install WeeChat)
            </para>
          </listitem>
          <listitem>
            <para>
              according to GUI, one of the following libraries:
              <itemizedlist>
                <listitem>
                  <para>
                    Curses: ncurses library
                  </para>
                </listitem>
                <listitem>
                  <para>
                    Gtk: <emphasis>*** GUI not developed ***</emphasis>
                  </para>
                </listitem>
                <listitem>
                  <para>
                    WxWidgets: <emphasis>*** GUI not developed ***</emphasis>
                  </para>
                </listitem>
                <listitem>
                  <para>
                    Qt: <emphasis>*** GUI not developed ***</emphasis>
                  </para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>
        </itemizedlist>
      </para>
      
    </section>
  </chapter>
  
  <!-- =========================== Installation =========================== -->
  
  <chapter id="chapInstallation">
    <title>Installation</title>
    
    <para>
      This chapter explains how to install WeeChat.
    </para>
    
    <section id="secBinaryPackages">
      <title>Binary packages</title>
      
      <para>
        Binary packages are available for these distributions:
        <itemizedlist>
          <listitem>
            <para>
              Debian (or any Debian compatible distribution):
              <userinput>apt-get install weechat</userinput>
            </para>
          </listitem>
          <listitem>
            <para>
              Mandriva/RedHat (or any RPM compatible distribution):
              <userinput>
                rpm -i /chemin/weechat-x.y.z-1.i386.rpm
              </userinput>
            </para>
          </listitem>
          <listitem>
            <para>
              Gentoo :
              <userinput>emerge weechat</userinput>
            </para>
          </listitem>
        </itemizedlist>
        
        For other distributions, please look at your manual for
        installation instructions.
      </para>
      
    </section>
    
    <section id="secSourcePackage">
      <title>Source package</title>
      
      <para>
        All you have to do is to run in a console or a terminal:
<screen><prompt>$ </prompt><userinput>./configure</userinput>
<prompt>$ </prompt><userinput>make</userinput></screen>
      </para>
      <para>
        Then get root privileges and install WeeChat:
<screen><prompt>$ </prompt><userinput>su</userinput>
(enter root password)
<prompt># </prompt><userinput>make install</userinput></screen>
      </para>
      
    </section>
    
    <section id="secCVSSources">
      <title>CVS sources</title>
      
      <para>
        Warning: CVS sources are for advanced users: it may not compile
        or not be stable. You're warned!
      </para>
      
      <para>
        To get CVS sources, issue this command:
<screen><prompt>$ </prompt><userinput>cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/weechat co weechat</userinput></screen>
      </para>
      
      <para>
        Execute this script:
        <userinput>./autogen.sh</userinput>
      </para>
      
      <para>
        Then follow instructions for source package
        (see <xref linkend="secSourcePackage" />)
      </para>
      
    </section>
    
  </chapter>
  
  <!-- ============================== Usage =============================== -->
  
  <chapter id="chapUsage">
    <title>Usage</title>
    
    <para>
      This chapter explains how to run WeeChat, the default key bindings
      used, internal and IRC commands, setup file, and FIFO pipe use.
    </para>
    
    <section id="secRunningWeeChat">
      <title>Running WeeChat</title>
    
      <para>
        Command line arguments:
        <informaltable colsep="0" frame="none">
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Parameter</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><literal>-a, --no-connect</literal></entry>
                <entry>
                  Disable auto-connect to servers at startup
                </entry>
              </row>
              <row>
                <entry><literal>-c, --config</literal></entry>
                <entry>
                  Display config help (list of options)
                </entry>
              </row>
              <row>
                <entry><literal>-d, --dir &lt;path&gt;</literal></entry>
                <entry>
                  Set path as home for WeeChat (used for configuration files,
                  logs, user plugins and scripts). Default value is
                  "<literal>~/.weechat</literal>". Please note that directory
                  is created if not found by WeeChat.
                </entry>
              </row>
              <row>
                <entry><literal>-f, --key-functions</literal></entry>
                <entry>
                  Display WeeChat internal functions for keys
                </entry>
              </row>
              <row>
                <entry><literal>-h, --help</literal></entry>
                <entry>
                  Display help
                </entry>
              </row>
              <row>
                <entry><literal>-i, --irc-commands</literal></entry>
                <entry>
                  Display IRC commands list
                </entry>
              </row>
              <row>
                <entry><literal>-k, --keys</literal></entry>
                <entry>
                  Display WeeChat default keys
                </entry>
              </row>
              <row>
                <entry><literal>-l, --license</literal></entry>
                <entry>
                  Display WeeChat license
                </entry>
              </row>
              <row>
                <entry><literal>-p, --no-plugin</literal></entry>
                <entry>
                  Disable plugins auto-load
                </entry>
              </row>
              <row>
                <entry><literal>-v, --version</literal></entry>
                <entry>
                  Display WeeChat version
                </entry>
              </row>
              <row>
                <entry><literal>-w, --weechat-commands</literal></entry>
                <entry>
                  Display WeeChat commands list
                </entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </para>
      
      <para>
        It is also possible to give URL for one or many IRC servers, as
        follow:
        <screen>irc[6][s]://[pseudo[:mot_passe]@]irc.example.org[:port][/channel][,channel[...]</screen>
        Example to join #weechat and #toto on
        "<literal>irc.freenode.net</literal>" server, default port (6667),
        with "nono" nick:
        <screen><prompt>$ </prompt><userinput>weechat-curses irc://nono@irc.freenode.net/#weechat,#toto</userinput></screen>
      </para>
      
      <para>
        To start WeeChat, issue this command:
        <itemizedlist>
          <listitem>
            <para>
              for Curses GUI: <userinput>weechat-curses</userinput>
            </para>
          </listitem>
          <listitem>
            <para>
              for Gtk GUI: <userinput>weechat-gtk</userinput>
            </para>
          </listitem>
          <listitem>
            <para>
              for wxWidgets GUI: <userinput>weechat-wxwidgets</userinput>
            </para>
          </listitem>
          <listitem>
            <para>
              for Qt GUI: <userinput>weechat-qt</userinput>
            </para>
          </listitem>
        </itemizedlist>
      </para>
      
      <para>
        When you run WeeChat for the first time, a default configuration
        file is created, with default options.
        The default configuration file is:
        "<literal>~/.weechat/weechat.rc</literal>"
      </para>
      
      <para>
        You can edit this file at your convenience to configure WeeChat
        (ONLY if WeeChat is not running), or you can set parameters with
        "<literal>/set</literal>" command in WeeChat
        (see <xref linkend="secWeeChatCommands" />)
      </para>
      
    </section>
    
    <section id="secKeyboardShortcuts">
      <title>Key bindings</title>
      
      <para>
        <informaltable colsep="0" frame="none">
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Key</entry>
                <entry>Action</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>Left arrow</entry>
                <entry>
                  Go to previous char in command line
                </entry>
              </row>
              <row>
                <entry>Right arrow</entry>
                <entry>
                  Go to next char in command line
                </entry>
              </row>
              <row>
                <entry>Ctrl + left arrow</entry>
                <entry>
                  Go to previous word in command line
                </entry>
              </row>
              <row>
                <entry>Ctrl + right arrow</entry>
                <entry>
                  Go to next word in command line
                </entry>
              </row>
              <row>
                <entry>Home / Ctrl + A</entry>
                <entry>
                  Go to the beginning of command line
                </entry>
              </row>
              <row>
                <entry>End / Ctrl + E</entry>
                <entry>
                  Go to the end of command line
                </entry>
              </row>
              <row>
                <entry>Ctrl + K</entry>
                <entry>
                  Delete from cursor until end of command line
                </entry>
              </row>
              <row>
                <entry>Ctrl + L</entry>
                <entry>
                  Redraw whole window
                </entry>
              </row>
              <row>
                <entry>Ctrl + U</entry>
                <entry>
                  Delete from cursor until beginning of command line
                </entry>
              </row>
              <row>
                <entry>Ctrl + W</entry>
                <entry>
                  Delete previous word of command line
                </entry>
              </row>
              <row>
                <entry>Backspace</entry>
                <entry>
                  Delete previous char in command line
                </entry>
              </row>
              <row>
                <entry>Delete</entry>
                <entry>
                  Delete next char in command line
                </entry>
              </row>
              <row>
                <entry>Tab</entry>
                <entry>
                  Complete command or nick
                  (Tab again: find next completion)
                </entry>
              </row>
              <row>
                <entry>Any char</entry>
                <entry>
                  Insert char at cursor position in command line
                </entry>
              </row>
              <row>
                <entry>Enter</entry>
                <entry>
                  Execute command or send message
                </entry>
              </row>
              <row>
                <entry>Up arrow / Down arrow</entry>
                <entry>
                  Call again last commands/messages
                </entry>
              </row>
              <row>
                <entry>Ctrl + up arrow / Ctrl + down arrow</entry>
                <entry>
                  Call again last commands/messages in global history
                  (common for all buffers)
                </entry>
              </row>
              <row>
                <entry>PageUp / PageDown</entry>
                <entry>
                  Scroll up / down one page in buffer history
                </entry>
              </row>
              <row>
                <entry>Alt + PageUp / Alt + PageDown</entry>
                <entry>
                  Scroll up / down a few lines in buffer history
                </entry>
              </row>
              <row>
                <entry>F5 / Alt + left arrow</entry>
                <entry>
                  Switch to previous buffer
                </entry>
              </row>
              <row>
                <entry>F6 / Alt + right arrow</entry>
                <entry>
                  Switch to next buffer
                </entry>
              </row>
              <row>
                <entry>F7</entry>
                <entry>
                  Switch to previous window
                </entry>
              </row>
              <row>
                <entry>F8</entry>
                <entry>
                  Switch to next window
                </entry>
              </row>
              <row>
                <entry>F10</entry>
                <entry>
                  Remove last infobar message
                </entry>
              </row>
              <row>
                <entry>F11 / F12</entry>
                <entry>
                  Scroll nicklist
                </entry>
              </row>
              <row>
                <entry>Alt + Home / Alt + End</entry>
                <entry>
                  Go to the beginning / the end of nicklist
                </entry>
              </row>
              <row>
                <entry>Alt + A</entry>
                <entry>
                  Switch to next buffer with activity
                  (with priority: highlight, message, other)
                </entry>
              </row>
              <row>
                <entry>Alt + B</entry>
                <entry>
                  Go to previous word in command line
                </entry>
              </row>
              <row>
                <entry>Alt + D</entry>
                <entry>
                  Delete next word in command line
                </entry>
              </row>
              <row>
                <entry>Alt + F</entry>
                <entry>
                  Go to next word in command line
                </entry>
              </row>
              <row>
                <entry>Alt + H</entry>
                <entry>
                  Clear hotlist
                  (activity notification on other buffers)
                </entry>
              </row>
              <row>
                <entry>Alt + J then Alt + D</entry>
                <entry>
                  Display DCC buffer
                </entry>
              </row>
              <row>
                <entry>Alt + J then Alt + L</entry>
                <entry>
                  Switch to last buffer
                </entry>
              </row>
              <row>
                <entry>Alt + J then Alt + S</entry>
                <entry>
                  Switch to server buffer
                </entry>
              </row>
              <row>
                <entry>Alt + J then Alt + X</entry>
                <entry>
                  Switch to first channel of next buffer
                  (or server buffer if no channel is opened)
                </entry>
              </row>
              <row>
                <entry>Alt + digit (0-9)</entry>
                <entry>
                  Switch to buffer by number (0 = 10)
                </entry>
              </row>
              <row>
                <entry>Alt + J then number (01-99)</entry>
                <entry>
                  Switch to buffer by number
                </entry>
              </row>
              <row>
                <entry>Alt + K</entry>
                <entry>
                  Grab a key and insert its code in command line
                </entry>
              </row>
              <row>
                <entry>Alt + N</entry>
                <entry>
                  Scroll to next highlight
                </entry>
              </row>
              <row>
                <entry>Alt + P</entry>
                <entry>
                  Scroll to previous highlight
                </entry>
              </row>
              <row>
                <entry>Alt + R</entry>
                <entry>
                  Delete entire command line
                </entry>
              </row>
              <row>
                <entry>Alt + S</entry>
                <entry>
                  Switch servers on servers buffer
                  (if option "look_one_server_buffer" is enabled)
                </entry>
              </row>
              <row>
                <entry>Alt + U</entry>
                <entry>
                  Scroll to first unread line in buffer
                </entry>
              </row>
              <row>
                <entry>Alt + W then Alt + arrow</entry>
                <entry>
                  Switch to window with direction
                </entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </para>
      
    </section>
    
    <section id="secCommandLine">
      <title>Command line</title>
      
      <para>
        WeeChat command line (at the bottom of window) lets you send text on
        channels and execute WeeChat or IRC commands (see
        <xref linkend="secWeeChatIRCCommands" />).
      </para>
      
      <para>
        Commands begin with "/" char, followed by name of command.
        For example, to initiate a private chat with "<literal>toto</literal>":
        <screen><userinput>/query toto</userinput></screen>
      </para>
      
      <para>
        Text sent to a channel is any text that does not begin with "/" char.
        For example, to send text "<literal>hello</literal>" on current
        channel:
        <screen><userinput>hello</userinput></screen>
      </para>
      
      <para>
        However, it is possible to start with "/" char, by adding another.
        For example, to send text "<literal>/query toto</literal>" on current
        channel:
        <screen><userinput>//query toto</userinput></screen>
      </para>
      
      <para>
        If option for sending IRC colors ("<literal>irc_colors_send</literal>")
        is enabled, you can use color codes and attributes, as follow:
        <informaltable colsep="0" frame="none">
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Code</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>%B</entry>
                <entry>
                  bold text
                </entry>
              </row>
              <row>
                <entry>%Cxx</entry>
                <entry>
                  text color "<literal>xx</literal>"
                  (see colors table below)
                </entry>
              </row>
              <row>
                <entry>%Cxx,yy</entry>
                <entry>
                  text color "<literal>xx</literal>"
                  and background "<literal>yy</literal>"
                  (see colors table below)
                </entry>
              </row>
              <row>
                <entry>%O</entry>
                <entry>
                  disable color and attributes
                </entry>
              </row>
              <row>
                <entry>%R</entry>
                <entry>
                  reverse video (revert text color with background)
                </entry>
              </row>
              <row>
                <entry>%U</entry>
                <entry>
                  underlined text
                </entry>
              </row>
              <row>
                <entry>%%</entry>
                <entry>
                  display one "<literal>%</literal>"
                </entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
        Note: the same code (without number for %C) may be used to stop the
        attribute.
      </para>
      
      <para>
        Color codes for %C are:
        <informaltable colsep="0" frame="none">
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Code</entry>
                <entry>Color</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>00</entry>
                <entry>white</entry>
              </row>
              <row>
                <entry>01</entry>
                <entry>black</entry>
              </row>
              <row>
                <entry>02</entry>
                <entry>dark blue</entry>
              </row>
              <row>
                <entry>03</entry>
                <entry>dark green</entry>
              </row>
              <row>
                <entry>04</entry>
                <entry>light red</entry>
              </row>
              <row>
                <entry>05</entry>
                <entry>dark red</entry>
              </row>
              <row>
                <entry>06</entry>
                <entry>magenta</entry>
              </row>
              <row>
                <entry>07</entry>
                <entry>orange</entry>
              </row>
              <row>
                <entry>08</entry>
                <entry>yellow</entry>
              </row>
              <row>
                <entry>09</entry>
                <entry>light green</entry>
              </row>
              <row>
                <entry>10</entry>
                <entry>cyan</entry>
              </row>
              <row>
                <entry>11</entry>
                <entry>light cyan</entry>
              </row>
              <row>
                <entry>12</entry>
                <entry>light blue</entry>
              </row>
              <row>
                <entry>13</entry>
                <entry>light magenta</entry>
              </row>
              <row>
                <entry>14</entry>
                <entry>gray</entry>
              </row>
              <row>
                <entry>15</entry>
                <entry>light gray (white)</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </para>
      
      <para>
        Example: display of "<literal>hello everybody!</literal>" with
        "<literal>hello</literal>" in light blue bold, and 
        "<literal>everybody</literal>" in light red underlined:
<screen><userinput>%C12%Bhello%B%C04%U everybody%U%C!</userinput></screen>
      </para>
      
    </section>
    
    <section id="secWeeChatIRCCommands">
      <title>WeeChat / IRC commands</title>
      
      <para>
        This chapter lists all WeeChat and IRC commands.
      </para>
      
      <section id="secWeeChatCommands">
        <title>WeeChat commands</title>
        
        <para>
          &weechat_commands.xml;
        </para>
        
      </section>
      
      <section id="secKeyFunctions">
        <title>Key functions</title>
        
        <para>
          <informaltable colsep="0" frame="none">
            <tgroup cols="2">
              <thead>
                <row>
                  <entry>Function</entry>
                  <entry>Description</entry>
                </row>
              </thead>
              <tbody>
                
                &key_functions.xml;
                
              </tbody>
            </tgroup>
          </informaltable>
        </para>
        
      </section>
      
      <section id="secIRCCommands">
        <title>IRC commands</title>
        
        <para>
          &irc_commands.xml;
        </para>
        
      </section>
        
    </section>
    
    <section id="secConfigurationFile">
      <title>Configuration file</title>
      
      <para>
        List of options for config file:
        <informaltable colsep="0" frame="none">
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Option</entry>
                <entry>Type</entry>
                <entry>Values</entry>
                <entry>Default</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              
              &config.xml;
              
            </tbody>
          </tgroup>
        </informaltable>
      </para>
      
      <para>
        Colors for Curses GUI are:
        <informaltable colsep="0" frame="none">
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Keyword</entry>
                <entry>Color</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><literal>default</literal></entry>
                <entry>default color (transparent for background)</entry>
              </row>
              <row>
                <entry><literal>black</literal></entry>
                <entry>black</entry>
              </row>
              <row>
                <entry><literal>red</literal></entry>
                <entry>dark red</entry>
              </row>
              <row>
                <entry><literal>lightred</literal></entry>
                <entry>light red</entry>
              </row>
              <row>
                <entry><literal>green</literal></entry>
                <entry>dark green</entry>
              </row>
              <row>
                <entry><literal>lightgreen</literal></entry>
                <entry>light green</entry>
              </row>
              <row>
                <entry><literal>brown</literal></entry>
                <entry>brown</entry>
              </row>
              <row>
                <entry><literal>yellow</literal></entry>
                <entry>yellow</entry>
              </row>
              <row>
                <entry><literal>blue</literal></entry>
                <entry>dark blue</entry>
              </row>
              <row>
                <entry><literal>lightblue</literal></entry>
                <entry>light blue</entry>
              </row>
              <row>
                <entry><literal>magenta</literal></entry>
                <entry>dark magenta</entry>
              </row>
              <row>
                <entry><literal>lightmagenta</literal></entry>
                <entry>light magenta</entry>
              </row>
              <row>
                <entry><literal>cyan</literal></entry>
                <entry>dark cyan</entry>
              </row>
              <row>
                <entry><literal>lightcyan</literal></entry>
                <entry>light cyan</entry>
              </row>
              <row>
                <entry><literal>white</literal></entry>
                <entry>white</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </para>
      
    </section>
    
    <section id="secFIFOpipe">
      <title>FIFO pipe</title>
      
      <para>
        You can remote control WeeChat, by sending commands or text to a
        FIFO pipe (you have to enable option "irc_fifo_pipe", it is disabled
        by default).
      </para>
      
      <para>
        The FIFO pipe is located in "<literal>~/.weechat/</literal>" and is
        called "weechat_fifo_xxxxx" (where xxxxx is the process ID (PID) of
        running WeeChat). So if many WeeChat are running, you have many FIFO
        pipes, one for each session.
      </para>
      
      <para>
        The syntax for the FIFO pipe commands/text is:
        <screen>server,channel *text or command here</screen>
        where server and channel are optional, but if channel is here, server
        should be too.
      </para>
      
      <para>
        Some examples:
        <itemizedlist>
          <listitem>
            <para>
              nick change on freenode to "mynick|out" :
              <screen><prompt>$ </prompt><userinput>echo "freenode */nick mynick|out" &gt;~/.weechat/weechat_fifo_12345</userinput></screen>
            </para>
          </listitem>
          <listitem>
            <para>
              display text on #weechat channel:
              <screen><prompt>$ </prompt><userinput>echo "freenode,#weechat *hello everybody!" >~/.weechat/weechat_fifo_12345</userinput></screen>
            </para>
          </listitem>
          <listitem>
            <para>
              display text on current channel (buffer displayed by WeeChat):
              <screen><prompt>$ </prompt><userinput>echo "*hello!" >~/.weechat/weechat_fifo_12345</userinput></screen>
              <emphasis>Warning:</emphasis> this is dangerous and you should
              not do that except if you know what you do!
            </para>
          </listitem>
          <listitem>
            <para>
              send two commands to unload/reload Perl scripts (you have to
              separate them with "\n"):
              <screen><prompt>$ </prompt><userinput>echo -e "freenode */perl unload\nfreenode */perl autoload" >~/.weechat/weechat_fifo_12345</userinput></screen>
            </para>
          </listitem>
        </itemizedlist>
      </para>
      
      <para>
        You can write a script to send command to all running WeeChat at same
        time, for example:
<screen>
#!/bin/sh
if [ $# -eq 1 ]; then
    for fifo in $(/bin/ls ~/.weechat/weechat_fifo_* 2>/dev/null); do
        echo -e "$1" >$fifo
    done
fi
</screen>
        If the script is called "auto_weechat_command", you can run it with:
        <screen><prompt>$ </prompt><userinput>./auto_weechat_command "freenode,#weechat *hello"</userinput></screen>
      </para>
      
    </section>
    
  </chapter>
  
  <!-- ============================ Extensions ============================ -->
  
  <chapter id="chapPlugins">
    <title>Plugins</title>
    
    <para>
      This chapter describes WeeChat plugins interface (API) and
      the default scripts plugins (Perl, Python, Ruby, Lua), provided with
      WeeChat.
    </para>
    
    <section id="secPluginsInWeeChat">
      <title>Plugins in WeeChat</title>
      
      <para>
        A plugin is a C program which can call WeeChat functions defined in
        an interface.
      </para>
      
      <para>
        This C program does not need WeeChat sources to compile and can be
        dynamically loaded into WeeChat with command
        <command>/plugin</command>.
      </para>
      
      <para>
        The plugin has to be a dynamic library, for dynamic loading by
        operating system.
        Under GNU/Linux, the file has ".so" extension, ".dll" under
        Windows.
      </para>
      
    </section>
    
    <section id="secWriteAPlugin">
      <title>Write a plugin</title>
      
      <para>
        The plugin has to include "weechat-plugin.h" file (available in
        WeeChat source code).
        This file defines structures and types used to communicate with
        WeeChat.
      </para>
      
      <para>
        The plugin must have some variables and functions (mandatory,
        without them the plugin can't load):
        <informaltable colsep="0" frame="none">
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Variable</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><literal>char plugin_name[]</literal></entry>
                <entry>plugin name</entry>
              </row>
              <row>
                <entry><literal>char plugin_version[]</literal></entry>
                <entry>plugin version</entry>
              </row>
              <row>
                <entry><literal>char plugin_description[]</literal></entry>
                <entry>short description of plugin</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
        
        <informaltable colsep="0" frame="none">
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Function</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><literal>int weechat_plugin_init (t_weechat_plugin *plugin)</literal></entry>
                <entry>
                  function called when plugin is loaded, must return
                  PLUGIN_RC_OK if successful, PLUGIN_RC_KO if error
                  (if error, plugin will NOT be loaded)
                </entry>
              </row>
              <row>
                <entry><literal>void weechat_plugin_end (t_weechat_plugin *plugin)</literal></entry>
                <entry>function called when plugin is unloaded</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </para>
      
      <section id="secAPIFunctions">
        <title>API functions</title>
        
        <section id="secAPI_ascii_strcasecmp">
          <title>ascii_strcasecmp</title>
          
          <para>
            Prototype:
            <command>
              int ascii_strcasecmp (t_weechat_plugin *plugin,
              char *string1, char *string2)
            </command>
          </para>
          <para>
            Locale and case independent string comparison.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>string1</option>: first string for comparison
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>string2</option>: second string for comparison
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: difference between two strings: negative if
            string1 &lt; string2, zero if string1 == string2, positive if
            string1 &gt; string2
          </para>
          <para>
            Example:
            <screen>if (plugin->ascii_strcasecmp (plugin, "abc", "def") != 0) ...</screen>
          </para>
        </section>
        
        <section id="secAPI_ascii_strncasecmp">
          <title>ascii_strncasecmp</title>
          
          <para>
            Prototype:
            <command>
              int ascii_strncasecmp (t_weechat_plugin *plugin,
              char *string1, char *string2, int max)
            </command>
          </para>
          <para>
            Locale and case independent string comparison, for "max" chars.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin struct
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>string1</option>: first string for comparison
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>string2</option>: second string for comparison
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>max</option>: max number of chars for comparison
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: difference between two strings: negative if
            string1 &lt; string2, zero if string1 == string2, positive if
            string1 &gt; string2
          </para>
          <para>
            Example:
            <screen>if (plugin->ascii_strncasecmp (plugin, "abc", "def", 2) != 0) ...</screen>
          </para>
        </section>
        
        <section id="secAPI_explode_string">
          <title>explode_string</title>
          
          <para>
            Prototype:
            <command>
              char **explode_string (t_weechat_plugin *plugin, char *string,
              char *separators, int num_items_max, int *num_items)
            </command>
          </para>
          <para>
            Explode a string according to one or more delimiter(s).
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin struct
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>string</option>: string to explode
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>separators</option>: delimiters used for explosion
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>num_items_max</option>: maximum number of items
                  created (0 = no limit)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>num_items</option>: pointer to int which will
                  contain number of items created
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: array of strings, NULL if problem.
          </para>
          <para>
            Note: result has to be free by a call to "free_exloded_string"
            after use.
          </para>
          <para>
            Example:
<screen>
char **argv;
int argc;
argv = plugin->explode_string (plugin, string, " ", 0, &amp;argc);
...
if (argv != NULL)
    plugin->free_exploded_string (plugin, argv);
</screen>
          </para>
        </section>
        
        <section id="secAPI_free_exploded_string">
          <title>free_exploded_string</title>
          
          <para>
            Prototype:
            <command>
              char **free_exploded_string (t_weechat_plugin *plugin,
              char **string)
            </command>
          </para>
          <para>
            Free memory used by a string explosion.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>string</option>: string exploded by
                  "explode_string" function
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: none.
          </para>
          <para>
            Example:
<screen>
char *argv;
int argc;
argv = plugin->explode_string (plugin, string, " ", 0, &amp;argc);
...
if (argv != NULL)
    plugin->free_exploded_string (plugin, argv);
</screen>
          </para>
        </section>
        
        <section id="secAPI_exec_on_files">
          <title>exec_on_files</title>
          
          <para>
            Prototype:
            <command>
              void exec_on_files (t_weechat_plugin *plugin, char *repertoire,
              int (*callback)(t_weechat_plugin *, char *))
            </command>
          </para>
          <para>
            Execute a function on all files of a directory.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>directory</option>: directory for searching files
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>callback</option>: function called for each file
                  found
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: none.
          </para>
          <para>
            Example:
<screen>
int callback (t_weechat_plugin *plugin, char *file)
{
    plugin->print_server (plugin, "file: %s", file);
    return 1;
}
...
plugin->exec_on_files (plugin, "/tmp", &amp;callback);
</screen>
          </para>
        </section>
        
        <section id="secAPI_print">
          <title>print</title>
          
          <para>
            Prototype:
            <command>
              void print (t_weechat_plugin *plugin,
              char *server, char *channel, char *message, ...)
            </command>
          </para>
          <para>
            Display a message on a WeeChat buffer, identified by server and
            channel (both may be NULL for current buffer).
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>server</option>: internal name of server to find
                  buffer for message display (may be NULL)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>channel</option>: name of channel to find buffer
                  for message display (may be NULL)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>message</option>: message
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: none.
          </para>
          <para>
            Examples:
<screen>
plugin->print (plugin, NULL, NULL, "hello");
plugin->print (plugin, NULL, "#weechat", "hello");
plugin->print (plugin, "freenode", "#weechat", "hello");
</screen>
          </para>
        </section>
        
        <section id="secAPI_print_server">
          <title>print_server</title>
          
          <para>
            Prototype:
            <command>
              void print_server (t_weechat_plugin *plugin,
              char *message, ...)
            </command>
          </para>
          <para>
            Display a message on current server buffer.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>message</option>: message
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: none.
          </para>
          <para>
            Example: <screen>plugin->print_server (plugin, "hello");</screen>
          </para>
        </section>
        
        <section id="secAPI_print_infobar">
          <title>print_infobar</title>
          
          <para>
            Prototype:
            <command>
              void print_infobar (t_weechat_plugin *plugin,
              int time, char *message, ...)
            </command>
          </para>
          <para>
            Display a message in infobar for a specified time.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>time</option>: time (in seconds) for displaying
                  message (0 = never erased)
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: none.
          </para>
          <para>
            Example:
<screen>
plugin->print_infobar (plugin, 5, "hello");
</screen>
          </para>
        </section>
        
        <section id="secAPI_log">
          <title>log</title>
          
          <para>
            Prototype:
            <command>
              void log (t_weechat_plugin *plugin,
              char *server, char *channel, char *message, ...)
            </command>
          </para>
          <para>
            Write a message in log file for a server or a channel.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>server</option>: internal name of server to find
                  buffer for log (may be NULL)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>channel</option>: name of channel to find buffer
                  for log (may be NULL)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>message</option>: message
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: none.
          </para>
          <para>
            Example:
<screen>
plugin->log (plugin, "freenode", "#weechat", "test");
</screen>
          </para>
        </section>
        
        <section id="secAPI_msg_handler_add">
          <title>msg_handler_add</title>
          
          <para>
            Prototype:
            <command>
              t_plugin_handler *msg_handler_add (t_weechat_plugin
              *plugin, char *message, t_plugin_handler_func *function,
              char *handler_args, void *handler_pointer)
            </command>
          </para>
          <para>
            Add an IRC message handler, called when an IRC message is
            received.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>message</option>: name of IRC message.
                  To know list of IRC messages, please consult
                  <acronym>RFC</acronym>s
                  <ulink url="http://www.ietf.org/rfc/rfc1459.txt">1459</ulink> and
                  <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink>
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>function</option>: function called when message
                  is received
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>handler_args</option>: arguments given to function
                  when called
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>handler_pointer</option>: pointer given to function
                  when called
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: pointer to new message handler.
          </para>
          <para>
            Note: function called when message is received has to return
            one of following values:
            <itemizedlist>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_KO</literal>: function failed
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_OK</literal>: function successfully
                  completed
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_OK_IGNORE_WEECHAT</literal>: message
                  will not be sent to WeeChat
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_OK_IGNORE_PLUGINS</literal>: message
                  will not be sent to other plugins
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_OK_IGNORE_ALL</literal>: message
                  will not be sent to WeeChat neither other plugins
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Example:
<screen>
int msg_kick (t_weechat_plugin *plugin, char *server, char *command,
              char *arguments, char *handler_args, void *handler_pointer)
{
    plugin->print (plugin, server, NULL, "KICK received");
    return PLUGIN_RC_OK;
}
...
plugin->msg_handler_add (plugin, "KICK", &amp;msg_kick, NULL, NULL);
</screen>
          </para>
        </section>
        
        <section id="secAPI_cmd_handler_add">
          <title>cmd_handler_add</title>
          
          <para>
            Prototype:
            <command>
              t_plugin_handler *cmd_handler_add (t_weechat_plugin
              *plugin, char *command, char *description, char *arguments,
              char *arguments_description, char *completion_template,
              t_plugin_handler_func *fonction, char *handler_args,
              void *handler_pointer)
            </command>
          </para>
          <para>
            Add a WeeChat command handler, called when user uses command
            (for example /command).
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>command</option>: the new command name, which
                  may be an existing command (be careful, replaced command
                  will not be available until plugin is unloaded)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>description</option>: short command description
                  (displayed by /help command)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>arguments</option>: short description of command
                  arguments (displayed by /help command)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>arguments_description</option>: long description
                  of command arguments (displayed by /help command)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>completion_template</option>: template for
                  completion, like "<literal>abc|%w def|%i</literal>"
                  which means "abc" or a WeeChat command for first argument,
                  "def" or IRC command for second.
                  An empty string lets WeeChat complete any argument with
                  a nick from current channel, NULL disable completion for
                  all command arguments.
                </para>
                <para>
                  Following codes can be used:
                  <informaltable colsep="0" frame="none">
                    <tgroup cols="2">
                      <thead>
                        <row>
                          <entry>Code</entry>
                          <entry>Description</entry>
                        </row>
                      </thead>
                      <tbody>
                        <row>
                          <entry><literal>%-</literal></entry>
                          <entry>no completion for argument</entry>
                        </row>
                        <row>
                          <entry><literal>%a</literal></entry>
                          <entry>alias</entry>
                        </row>
                        <row>
                          <entry><literal>%A</literal></entry>
                          <entry>
                            alias and commands (WeeChat, IRC and plugins)
                          </entry>
                        </row>
                        <row>
                          <entry><literal>%c</literal></entry>
                          <entry>current channel</entry>
                        </row>
                        <row>
                          <entry><literal>%C</literal></entry>
                          <entry>channels of current server</entry>
                        </row>
                        <!-- <row>
                          <entry><literal>%f</literal></entry>
                          <entry>file name</entry>
                        </row> -->
                        <row>
                          <entry><literal>%h</literal></entry>
                          <entry>plugins commands</entry>
                        </row>
                        <row>
                          <entry><literal>%i</literal></entry>
                          <entry>IRC commands (sent)</entry>
                        </row>
                        <row>
                          <entry><literal>%I</literal></entry>
                          <entry>IRC commands (received)</entry>
                        </row>
                        <row>
                          <entry><literal>%k</literal></entry>
                          <entry>key functions</entry>
                        </row>
                        <row>
                          <entry><literal>%n</literal></entry>
                          <entry>nicks of current channel</entry>
                        </row>
                        <row>
                          <entry><literal>%o</literal></entry>
                          <entry>setup options</entry>
                        </row>
                        <row>
                          <entry><literal>%p</literal></entry>
                          <entry>default "part" message</entry>
                        </row>
                        <row>
                          <entry><literal>%q</literal></entry>
                          <entry>default "quit" message</entry>
                        </row>
                        <row>
                          <entry><literal>%s</literal></entry>
                          <entry>current server name</entry>
                        </row>
                        <row>
                          <entry><literal>%S</literal></entry>
                          <entry>all servers names</entry>
                        </row>
                        <row>
                          <entry><literal>%t</literal></entry>
                          <entry>topic of current channel</entry>
                        </row>
                        <row>
                          <entry><literal>%v</literal></entry>
                          <entry>setup option value</entry>
                        </row>
                        <row>
                          <entry><literal>%w</literal></entry>
                          <entry>WeeChat commands</entry>
                        </row>
                      </tbody>
                    </tgroup>
                  </informaltable>
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>function</option>: function called when command
                  is executed
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>handler_args</option>: arguments given to function
                  when called
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>handler_pointer</option>: pointer given to function
                  when called
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: pointer to new command handler.
          </para>
          <para>
            Note: function called when command is executed has to return
            one of following values:
            <itemizedlist>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_KO</literal>: function failed
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_OK</literal>: function successfully
                  completed
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Example:
<screen>
int cmd_test (t_weechat_plugin *plugin, char *server,
              char *command, char *arguments, char *handler_args,
              void *handler_pointer)
{
    plugin->print (plugin, server, NULL,
                   "test command, nick: %s",
                   (arguments) ? arguments : "none");
    return PLUGIN_RC_OK;
}
...
plugin->cmd_handler_add (plugin, "test", "Test command",
                         "[nick]", "nick: nick of channel",
                         "%n", &amp;cmd_test, NULL, NULL);
</screen>
          </para>
        </section>
        
        <section id="secAPI_timer_handler_add">
          <title>timer_handler_add</title>
          
          <para>
            Prototype:
            <command>
              t_plugin_handler *timer_handler_add (t_weechat_plugin
              *plugin, int interval, t_plugin_handler_func *function,
              char *handler_args, void *handler_pointer)
            </command>
          </para>
          <para>
            Add a timer handler which periodically calls a function.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>interval</option>: interval (in seconds) between
                  two calls of function.
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>function</option>: function called
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>handler_args</option>: arguments given to function
                  when called
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>handler_pointer</option>: pointer given to function
                  when called
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: pointer to new message handler.
          </para>
          <para>
            Note: function called has to return one of following values:
            <itemizedlist>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_KO</literal>: function failed
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_OK</literal>: function successfully
                  completed
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Example:
<screen>
int my_timer (t_weechat_plugin *plugin, char *server, char *command,
              char *arguments, char *handler_args, void *handler_pointer)
{
    plugin->print (plugin, NULL, NULL, "my timer");
    return PLUGIN_RC_OK;
}
...
plugin->timer_handler_add (plugin, 60, &amp;my_timer);
</screen>
          </para>
        </section>
        
        <section id="secAPI_handler_remove">
          <title>handler_remove</title>
          
          <para>
            Prototype:
            <command>
              void handler_remove (t_weechat_plugin *plugin,
              t_plugin_handler *handler)
            </command>
          </para>
          <para>
            Remove a handler.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>handler</option>: handler to remove
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: none.
          </para>
          <para>
            Example:
            <screen>plugin->handler_remove (plugin, my_handler);</screen>
          </para>
        </section>
        
        <section id="secAPI_handler_remove_all">
          <title>handler_remove_all</title>
          
          <para>
            Prototype:
            <command>
              void handler_remove_all (t_weechat_plugin *plugin)
            </command>
          </para>
          <para>
            Remove all handlers for a plugin.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: none.
          </para>
          <para>
            Example:
            <screen>plugin->handler_remove_all (plugin);</screen>
          </para>
        </section>
        
        <section id="secAPI_exec_command">
          <title>exec_command</title>
          
          <para>
            Prototype:
            <command>
              void exec_command (t_weechat_plugin
              *plugin, char *server, char *channel, char *command)
            </command>
          </para>
          <para>
            Execute a WeeChat command (or send a message to a channel).
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>server</option>: internal name of server for
                  executing command (may be NULL)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>channel</option>: name of channel for executing
                  command (may be NULL)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>command</option>: command
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: none.
          </para>
          <para>
            Examples:
<screen>
plugin->exec_command (plugin, NULL, NULL, "/help nick");
plugin->exec_command (plugin, "freenode", "#weechat", "hello");
</screen>
          </para>
        </section>
        
        <section id="secAPI_get_info">
          <title>get_info</title>
          
          <para>
            Prototype:
            <command>
              char *get_info (t_weechat_plugin *plugin,
              char *info, char *server)
            </command>
          </para>
          <para>
            Return an info about WeeChat or a channel.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>info</option> : name of info to read:
                  <informaltable colsep="0" frame="none">
                    <tgroup cols="2">
                      <thead>
                        <row>
                          <entry>Info</entry>
                          <entry>Description</entry>
                        </row>
                      </thead>
                      <tbody>
                        <row>
                          <entry><literal>version</literal></entry>
                          <entry>WeeChat's version</entry>
                        </row>
                        <row>
                          <entry><literal>nick</literal></entry>
                          <entry>nick</entry>
                        </row>
                        <row>
                          <entry><literal>channel</literal></entry>
                          <entry>
                            name of channel (NULL for a server or private)
                          </entry>
                        </row>
                        <row>
                          <entry><literal>server</literal></entry>
                          <entry>name of server</entry>
                        </row>
                        <row>
                          <entry><literal>away</literal></entry>
                          <entry>"away" flag</entry>
                        </row>
                        <row>
                          <entry><literal>weechat_dir</literal></entry>
                          <entry>
                            WeeChat home directory
                            (by default: ~/.weechat/)
                          </entry>
                        </row>
                        <row>
                          <entry><literal>weechat_libdir</literal></entry>
                          <entry>WeeChat system lib directory</entry>
                        </row>
                        <row>
                          <entry><literal>weechat_sharedir</literal></entry>
                          <entry>WeeChat system share directory</entry>
                        </row>
                      </tbody>
                    </tgroup>
                  </informaltable>
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>server</option>: internal name of server for
                  reading info (if needed)
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: information asked, NULL if not found.
          </para>
          <para>
            Note: result has to be free by a call to "free" function after
            use.
          </para>
          <para>
            Examples:
<screen>
char *version = plugin->get_info (plugin, "version", NULL);
char *nick = plugin->get_info (plugin, "nick", "freenode");
</screen>
          </para>
        </section>
        
        <section id="secAPI_get_dcc_info">
          <title>get_dcc_info</title>
          
          <para>
            Prototype:
            <command>
              t_plugin_info_dcc *get_dcc_info (t_weechat_plugin *plugin)
            </command>
          </para>
          <para>
            Return list of DCC currently active or finished.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: linked list of DCC.
            <informaltable colsep="0" frame="none">
              <tgroup cols="2">
                <thead>
                  <row>
                    <entry>Type</entry>
                    <entry>Field</entry>
                    <entry>Description</entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>server</literal></entry>
                    <entry>IRC server</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>channel</literal></entry>
                    <entry>IRC channel</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>type</literal></entry>
                    <entry>
                      DCC type:
                      0 = chat received,
                      1 = chat sent,
                      2 = file received,
                      3 = file sent
                    </entry>
                  </row>
                  <row>
                    <entry>int*</entry>
                    <entry><literal>status</literal></entry>
                    <entry>
                      DCC status:
                      0 = waiting,
                      1 = connecting,
                      2 = active,
                      3 = finished,
                      4 = failed,
                      5 = interrupted by user
                    </entry>
                  </row>
                  <row>
                    <entry>time_t</entry>
                    <entry><literal>start_time</literal></entry>
                    <entry>date/time of DCC creation</entry>
                  </row>
                  <row>
                    <entry>time_t</entry>
                    <entry><literal>start_transfer</literal></entry>
                    <entry>date/time of DCC transfer start</entry>
                  </row>
                  <row>
                    <entry>unsigned long</entry>
                    <entry><literal>addr</literal></entry>
                    <entry>IP address of remote user</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>port</literal></entry>
                    <entry>port used for DCC</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>nick</literal></entry>
                    <entry>remote nick</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>filename</literal></entry>
                    <entry>file name</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>local_filename</literal></entry>
                    <entry>local file name</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>filename_suffix</literal></entry>
                    <entry>suffix if renaming file</entry>
                  </row>
                  <row>
                    <entry>unsigned long</entry>
                    <entry><literal>size</literal></entry>
                    <entry>file size</entry>
                  </row>
                  <row>
                    <entry>unsigned long</entry>
                    <entry><literal>pos</literal></entry>
                    <entry>position in file</entry>
                  </row>
                  <row>
                    <entry>unsigned long</entry>
                    <entry><literal>start_resume</literal></entry>
                    <entry>start position after interruption</entry>
                  </row>
                  <row>
                    <entry>unsigned long</entry>
                    <entry><literal>bytes_per_sec</literal></entry>
                    <entry>
                      number of bytes per second since transfer start
                    </entry>
                  </row>
                  <row>
                    <entry>t_plugin_dcc_info *</entry>
                    <entry><literal>prev_dcc</literal></entry>
                    <entry>
                      pointer to previous DCC info
                    </entry>
                  </row>
                  <row>
                    <entry>t_plugin_dcc_info *</entry>
                    <entry><literal>next_dcc</literal></entry>
                    <entry>
                      pointer to next DCC info
                    </entry>
                  </row>

                </tbody>
              </tgroup>
            </informaltable>
          </para>
          <para>
            Note: result has to be free by a call to "free_dcc_info" function
            after use.
          </para>
          <para>
            Examples:
<screen>
t_plugin_dcc_info *dcc_info = plugin->get_dcc_info (plugin);
for (ptr_dcc = dcc_info; ptr_dcc; ptr_dcc = ptr_dcc->next_dcc)
{
    plugin->print_server (plugin, "DCC type=%d, with: %s",
                          ptr_dcc->type, ptr_dcc->nick);
}
if (dcc_info)
    plugin->free_dcc_info (plugin, dcc_info);
</screen>
          </para>
        </section>
        
        <section id="secAPI_free_dcc_info">
          <title>free_dcc_info</title>
          
          <para>
            Prototype:
            <command>
              void free_dcc_info (t_weechat_plugin *plugin,
              t_plugin_dcc_info *dcc_info)
            </command>
          </para>
          <para>
            Free memory used by a DCC list.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>dcc_info</option>: pointer to DCC list returned by
                  "get_dcc_info" function
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: none.
          </para>
          <para>
            Example:
            <screen>plugin->free_dcc_info (plugin, dcc_info);</screen>
          </para>
        </section>

        <section id="secAPI_get_server_info">
          <title>get_server_info</title>
          
          <para>
            Prototype:
            <command>
              t_plugin_server_info *get_server_info (t_weechat_plugin *plugin)
            </command>
          </para>
          <para>
            Return list of IRC servers (connected or not).
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: linked list of IRC servers.
            <informaltable colsep="0" frame="none">
              <tgroup cols="2">
                <thead>
                  <row>
                    <entry>Type</entry>
                    <entry>Field</entry>
                    <entry>Description</entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>name</literal></entry>
                    <entry>server internal name</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>autoconnect</literal></entry>
                    <entry>1 if autoconnect at start-up, 0 otherwise</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>autoreconnect</literal></entry>
                    <entry>
                      1 if autoreconnect when disconnected,
                      0 otherwise
                    </entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>autoreconnect_delay</literal></entry>
                    <entry>delay before trying again connection</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>command_line</literal></entry>
                    <entry>
                      1 if server was on command line (so it is temporary),
                      0 otherwise
                    </entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>address</literal></entry>
                    <entry>server address (host or IP)</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>port</literal></entry>
                    <entry>port</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>ipv6</literal></entry>
                    <entry>IPv6 connection</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>ssl</literal></entry>
                    <entry>SSL connection</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>password</literal></entry>
                    <entry>server password</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>nick1</literal></entry>
                    <entry>first nickname</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>nick2</literal></entry>
                    <entry>alternate nickname</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>nick3</literal></entry>
                    <entry>second alternate nickname</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>username</literal></entry>
                    <entry>user name</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>real name</literal></entry>
                    <entry>real name</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>command</literal></entry>
                    <entry>command run once connected</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>command_delay</literal></entry>
                    <entry>delay after execution of command</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>autojoin</literal></entry>
                    <entry>channels joined automatically</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>autorejoin</literal></entry>
                    <entry>
                      1 if channels are rejoined when kicked,
                      0 otherwise
                    </entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>notify_levels</literal></entry>
                    <entry>channels notify levels</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>charset_decode_iso</literal></entry>
                    <entry>channels charsets for decoding ISO</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>charset_decode_utf</literal></entry>
                    <entry>channels charsets for decoding UTF</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>charset_encode</literal></entry>
                    <entry>channels charsets for encoding messages</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>is_connected</literal></entry>
                    <entry>1 if connected to server, 0 otherwise</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>ssl_connected</literal></entry>
                    <entry>1 if connected with SSL, 0 otherwise</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>nick</literal></entry>
                    <entry>current nickname</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>is_away</literal></entry>
                    <entry>1 if away, 0 otherwise</entry>
                  </row>
                  <row>
                    <entry>time_t</entry>
                    <entry><literal>away_time</literal></entry>
                    <entry>time when user is marking as away</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>lag</literal></entry>
                    <entry>lag (in milliseconds)</entry>
                  </row>
                  <row>
                    <entry>t_plugin_server_info *</entry>
                    <entry><literal>prev_server</literal></entry>
                    <entry>pointer to previous server info</entry>
                  </row>
                  <row>
                    <entry>t_plugin_server_info *</entry>
                    <entry><literal>next_server</literal></entry>
                    <entry>pointer to next server info</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
          </para>
          <para>
            Note: result has to be free by a call to "free_server_info"
            function after use.
          </para>
          <para>
            Example:
<screen>
t_plugin_server_info *server_info, *ptr_server_info;
server_info = plugin->get_server_info (plugin);
if (server_info)
{
    for (ptr_server_info = server_info; ptr_server_info;
         ptr_server_info = ptr_server_info->next_server)
    {
        plugin->print (plugin, NULL, NULL,
                       "server: %s, address: %s, port: %d %s",
                       ptr_server_info->name,
                       ptr_server_info->address,
                       ptr_server_info->port,
                       (ptr_server_info->is_connected) ? "(connected)" : "");
    }
    plugin->free_server_info (plugin, server_info);
}
</screen>
          </para>
        </section>
        
        <section id="secAPI_free_server_info">
          <title>free_server_info</title>
          
          <para>
            Prototype:
            <command>
              void free_server_info (t_weechat_plugin *plugin,
              t_plugin_server_info *server_info)
            </command>
          </para>
          <para>
            Free memory used by server info list.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>server_info</option>: pointer to server list
                  returned by "get_server_info" function
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: none.
          </para>
          <para>
            Example:
            <screen>plugin->free_server_info (plugin, server_info);</screen>
          </para>
        </section>
        
        <section id="secAPI_get_channel_info">
          <title>get_channel_info</title>
          
          <para>
            Prototype:
            <command>
              t_plugin_channel_info *get_channel_info (t_weechat_plugin *plugin,
              char *server)
            </command>
          </para>
          <para>
            Return list of IRC channels for a server.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>server</option>: internal server name
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: linked list of IRC channels for server.
            <informaltable colsep="0" frame="none">
              <tgroup cols="2">
                <thead>
                  <row>
                    <entry>Type</entry>
                    <entry>Field</entry>
                    <entry>Description</entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry>int</entry>
                    <entry><literal>type</literal></entry>
                    <entry>0 for a channel, 1 for a private</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>name</literal></entry>
                    <entry>name of channel</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>topic</literal></entry>
                    <entry>topic of channel</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>modes</literal></entry>
                    <entry>channel modes</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>limit</literal></entry>
                    <entry>user limit</entry>
                  </row>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>key</literal></entry>
                    <entry>channel key</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>nicks_count</literal></entry>
                    <entry>number of nicks on channel</entry>
                  </row>
                  <row>
                    <entry>t_plugin_channel_info *</entry>
                    <entry><literal>prev_channel</literal></entry>
                    <entry>pointer to previous channel info</entry>
                  </row>
                  <row>
                    <entry>t_plugin_channel_info *</entry>
                    <entry><literal>next_channel</literal></entry>
                    <entry>pointer to next channel info</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
          </para>
          <para>
            Note: result has to be free by a call to "free_channel_info"
            function after use.
          </para>
          <para>
            Example:
<screen>
t_plugin_channel_info *channel_info, *ptr_chan_info;
channel_info = plugin->get_channel_info (plugin, "freenode");
if (channel_info)
{
    for (ptr_chan_info = channel_info; ptr_chan_info;
         ptr_chan_info = ptr_chan_info->next_channel)
    {
        plugin->print (plugin, NULL, NULL,
                       "  %s (type %d)",
                       ptr_chan_info->name,
                       ptr_chan_info->type);
    }
    plugin->free_channel_info (plugin, channel_info);
}
</screen>
          </para>
        </section>
        
        <section id="secAPI_free_channel_info">
          <title>free_channel_info</title>
          
          <para>
            Prototype:
            <command>
              void free_channel_info (t_weechat_plugin *plugin,
              t_plugin_channel_info *channel_info)
            </command>
          </para>
          <para>
            Free memory used by channel info list.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>channel_info</option>: pointer to channel info list
                  returned by "get_channel_info" function
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: none.
          </para>
          <para>
            Example:
            <screen>plugin->free_channel_info (plugin, channel_info);</screen>
          </para>
        </section>

        <section id="secAPI_get_nick_info">
          <title>get_nick_info</title>
          
          <para>
            Prototype:
            <command>
              t_plugin_nick_info *get_nick_info (t_weechat_plugin *plugin,
              char *server, char *channel)
            </command>
          </para>
          <para>
            Return list of nicks for a channel.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>server</option>: internal server name
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>channel</option>: channel name
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: linked list of nicks on channel.
            <informaltable colsep="0" frame="none">
              <tgroup cols="2">
                <thead>
                  <row>
                    <entry>Type</entry>
                    <entry>Field</entry>
                    <entry>Description</entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry>char *</entry>
                    <entry><literal>nick</literal></entry>
                    <entry>nick name</entry>
                  </row>
                  <row>
                    <entry>int</entry>
                    <entry><literal>flags</literal></entry>
                    <entry>
                      nick flags, binary "or" between values (1 = channel
                      owner, 2 = channel admin, 4 = op, 8 = halfop,
                      16 = voice, 32 = away)
                    </entry>
                  </row>
                  <row>
                    <entry>t_plugin_nick_info *</entry>
                    <entry><literal>prev_nick</literal></entry>
                    <entry>pointer to previous nick info</entry>
                  </row>
                  <row>
                    <entry>t_plugin_nick_info *</entry>
                    <entry><literal>next_nick</literal></entry>
                    <entry>pointer to next nick info</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
          </para>
          <para>
            Note: result has to be free by a call to "free_nick_info"
            function after use.
          </para>
          <para>
            Example:
<screen>
t_plugin_nick_info *nick_info, *ptr_nick_info;
nick_info = plugin->get_nick_info (plugin, "freenode", "#weechat");
if (nick_info)
{
    for (ptr_nick_info = nick_info; ptr_nick_info;
         ptr_nick_info = ptr_nick_info->next_nick)
    {
        plugin->print (plugin, NULL, NULL,
                       "  %s (flags: %d)",
                       ptr_nick_info->nick,
                       ptr_nick_info->flags);
    }
    plugin->free_nick_info (plugin, nick_info);
}
</screen>
          </para>
        </section>
        
        <section id="secAPI_free_nick_info">
          <title>free_nick_info</title>
          
          <para>
            Prototype:
            <command>
              void free_nick_info (t_weechat_plugin *plugin,
              t_plugin_nick_info *nick_info)
            </command>
          </para>
          <para>
            Free memory used by nick info list.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>nick_info</option>: pointer to nick info list
                  returned by "get_nick_info" function
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: none.
          </para>
          <para>
            Example:
            <screen>plugin->free_nick_info (plugin, nick_info);</screen>
          </para>
        </section>
        
        <section id="secAPI_get_config">
          <title>get_config</title>
          
          <para>
            Prototype:
            <command>
              char *get_config (t_weechat_plugin *plugin, char *option)
            </command>
          </para>
          <para>
            Return value of a WeeChat config option.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>option</option>: name of option to read
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: option value, NULL if not found.
          </para>
          <para>
            Note: result has to be free by a call to "free" function after
            use.
          </para>
          <para>
            Examples:
<screen>
char *value1 = plugin->get_config (plugin, "look_set_title");
char *value2 = plugin->get_config (plugin, "freenode.server_autojoin");
</screen>
          </para>
        </section>
        
        <section id="secAPI_set_config">
          <title>set_config</title>
          
          <para>
            Prototype:
            <command>
              int set_config (t_weechat_plugin *plugin,
              char *option, char *value)
            </command>
          </para>
          <para>
            Update value of a WeeChat config option.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>option</option>: name of option to update
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>value</option>: new value for option
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: 1 if option was successfully updated, 0 if an
            error occurred.
          </para>
          <para>
            Example:
<screen>
plugin->set_config (plugin, "look_nicklist", "off");
</screen>
          </para>
        </section>
        
        <section id="secAPI_get_plugin_config">
          <title>get_plugin_config</title>
          
          <para>
            Prototype:
            <command>
              char *get_plugin_config (t_weechat_plugin *plugin, char *option)
            </command>
          </para>
          <para>
            Return value of a plugin option.
            Option is read from file "<literal>~/.weechat/plugins.rc</literal>"
            and is like: "<literal>plugin.option=value</literal>"
            (note: plugin name is automatically added).
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>option</option>: name of option to read
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: option value, NULL if not found.
          </para>
          <para>
            Note: result has to be free by a call to "free" function after
            use.
          </para>
          <para>
            Example:
<screen>
char *value = plugin->get_plugin_config (plugin, "my_var");
</screen>
          </para>
        </section>
        
        <section id="secAPI_set_plugin_config">
          <title>set_plugin_config</title>
          
          <para>
            Prototype:
            <command>
              int set_plugin_config (t_weechat_plugin *plugin,
              char *option, char *value)
            </command>
          </para>
          <para>
            Update value of a plugin option.
            Option is written in file "<literal>~/.weechat/plugins.rc</literal>"
            and is like: "<literal>plugin.option=value</literal>"
            (note: plugin name is automatically added).
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>plugin</option>: pointer to plugin structure
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>option</option>: name of option to update
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>value</option>: new value for option
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: 1 if option was successfully updated, 0 if an
            error occurred.
          </para>
          <para>
            Example :
<screen>
plugin->set_plugin_config (plugin, "my_var", "value");
</screen>
          </para>
        </section>
        
      </section>
      
      <section id="secCompilePlugin">
        <title>Compile plugin</title>
        
        <para>
          Compile does not need WeeChat sources, only file
          "<literal>weechat-plugin.h</literal>".
        </para>
        
        <para>
          To compile a plugin which has one file "toto.c" (under GNU/Linux):
<screen>
<prompt>$ </prompt><userinput>gcc -fPIC -Wall -c toto.c</userinput>
<prompt>$ </prompt><userinput>gcc -shared -fPIC -o libtoto.so toto.o</userinput>
</screen>
        </para>
        
      </section>
      
      <section id="secLoadPlugin">
        <title>Load plugin into WeeChat</title>
        
        <para>
          Copy "libtoto.so" file into system plugins directory (for example
          "<literal>/usr/local/lib/weechat/plugins</literal>") or into
          user's plugins directory (for example
          "<literal>/home/xxxxx/.weechat/plugins</literal>").
        </para>
        
        <para>
          Under WeeChat:
          <screen><userinput>/plugin load toto</userinput></screen>
        </para>
        
      </section>
      
      <section id="secPluginExample">
        <title>Plugin example</title>
        
        <para>
          Full example of plugin, which adds a /double command, which displays
          two times arguments on current channel (ok that's not very useful, but
          that's just an example!):
<screen>
#include &lt;stdlib.h&gt;

#include "weechat-plugin.h"

char plugin_name[]        = "Double";
char plugin_version[]     = "0.1";
char plugin_description[] = "Test plugin for WeeChat";

/* "/double" command manager */

int double_cmd (t_weechat_plugin *plugin, char *server,
                       char *command, char *arguments,
                       char *handler_args, void *handler_pointer)
{
    if (arguments &amp;&amp; arguments[0] &amp;&amp; (arguments[0] != '/'))
    {
        plugin->exec_command (plugin, NULL, NULL, arguments);
        plugin->exec_command (plugin, NULL, NULL, arguments);
    }
    return PLUGIN_RC_OK;
}

int weechat_plugin_init (t_weechat_plugin *plugin)
{
    plugin->cmd_handler_add (plugin, "double",
                             "Display two times a message",
                             "msg",
                             "msg: message to display two times",
                             NULL,
                             &amp;double_cmd,
                             NULL, NULL);
    return PLUGIN_RC_OK;
}

void weechat_plugin_end (t_weechat_plugin *plugin)
{
    /* nothing done here */
}
</screen>
        </para>
        
      </section>
      
    </section>
    
    <section id="secScriptsPlugins">
      <title>Scripts plugins</title>
      
      <para>
        Four plugins are provided with WeeChat to use script languages:
        Perl, Python, Ruby and Lua.
      </para>
      
      <section id="secLoadUnloadScripts">
        <title>Load / unload scripts</title>
        
        <para>
          Scripts are loaded and unloaded with <command>/perl</command>,
          <command>/python</command>, <command>/ruby</command> and
          <command>/lua</command> commands
          (type <command>/help</command> in WeeChat for help about commands).
        </para>
        
        <para>
          Examples:
          <itemizedlist>
            <listitem>
              <para>
                Load a Perl script:
                <command><userinput>/perl load /tmp/test.pl</userinput></command>
              </para>
            </listitem>
            <listitem>
              <para>
                List all loaded Perl scripts:
                <command><userinput>/perl</userinput></command>
              </para>
            </listitem>
            <listitem>
              <para>
                Load a Python script:
                <command><userinput>/python load /tmp/test.py</userinput></command>
              </para>
            </listitem>
            <listitem>
              <para>
                List all loaded Python scripts:
                <command><userinput>/python</userinput></command>
              </para>
            </listitem>
            <listitem>
              <para>
                Load a Ruby script:
                <command><userinput>/ruby load /tmp/test.rb</userinput></command>
              </para>
            </listitem>
            <listitem>
              <para>
                List all loaded Ruby scripts:
                <command><userinput>/ruby</userinput></command>
              </para>
            </listitem>
            <listitem>
              <para>
                Load a Lua script:
                <command><userinput>/lua load /tmp/test.lua</userinput></command>
              </para>
            </listitem>
            <listitem>
              <para>
                List all loaded Lua scripts:
                <command><userinput>/lua</userinput></command>
              </para>
            </listitem>
          </itemizedlist>
        </para>
        
      </section>
      
      <section id="secSyntaxByLanguage">
        <title>Syntax by language</title>
        
        <section>
          <title>Perl</title>
          
          <para>
            In a WeeChat Perl script, all API functions and variables are
            prefixed by "<literal>weechat::</literal>".
            Example:
<screen>weechat::register("test", "1.0", "end_test", "WeeChat perl script");</screen>
          </para>
          
        </section>
        
        <section>
          <title>Python</title>
          
          <para>
            A WeeChat Python script has to start by importing weechat:
            <screen>import weechat</screen>
          </para>
          
          <para>
            All API functions and variables are prefixed by
            "<literal>weechat.</literal>".
            Example:
<screen>weechat.register("test", "1.0", "end_test", "WeeChat python script")</screen>
          </para>
          
        </section>
        
        <section>
          <title>Ruby</title>
          
          <para>
            In a WeeChat Ruby script, all code has to be in functions.
            So for main code, you have to define a
            "<literal>weechat_init</literal>" function, which is automatically
            called when script is loaded by WeeChat. Example:
<screen>
def weechat_init
    Weechat.register("test", "1.0", "end_test", "WeeChat ruby script")
    Weechat.add_command_handler("command", "my_command")
    return Weechat::PLUGIN_RC_OK
end

def my_command(server, args)
    Weechat.print("my command")
    return Weechat::PLUGIN_RC_OK
end
</screen>
          </para>
          
          <para>
            All API functions are prefixed by
            "<literal>Weechat.</literal>" and variables by
            "<literal>Weechat::</literal>".
          </para>
          
        </section>
        
        <section>
          <title>Lua</title>
          
          <para>
            In a WeeChat Lua script, all API functions are prefixed by
            "<literal>weechat.</literal>".
            Variables are prefixed by "<literal>weechat.</literal>" and
            suffixed by "<literal>()</literal>".
            Example:
<screen>
function message_handler(server, args)
   weechat.print("I am a message handler")
   return weechat.PLUGIN_RC_OK()
end
</screen>
          </para>
          
        </section>
        
      </section>
      
      <section id="secWeeChatScriptsAPI">
        <title>WeeChat / scripts API</title>
        
        <section>
          <title>register</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::register(name, version, end_function, description);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.register(name, version, end_function, description)
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.register(name, version, end_function, description)
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.register(name, version, end_function, description)
            </command>
          </para>
          <para>
            This is first function to call in script.
            All WeeChat scripts have to call this function.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>name</option>: unique name to identify script
                  (each script must have unique name)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>version</option>: script version
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>end_function</option>: function called when script is
                  unloaded (optional parameter, empty string means nothing is
                  called at the end)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>description</option>: short description of script
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: 1 if script was registered, 0 if an error occured.
          </para>
          <para>
            Examples:
<screen>
# perl
weechat::register("test", "1.0", "end_test", "Test script!");

# python
weechat.register("test", "1.0", "end_test", "Test script!")

# ruby
Weechat.register("test", "1.0", "end_test", "Test script!")

-- lua
weechat.register("test", "1.0", "end_test", "Test script!")
</screen>
          </para>
        </section>
        
        <section>
          <title>print</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::print(message, [channel, [server]])
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.prnt(message, [channel, [server]])
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.print(message, [channel, [server]])
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.print(message, [channel, [server]])
            </command>
          </para>
          <para>
            Display a message on a WeeChat buffer, identified by server
            and channel.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>message</option>: message
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>channel</option>: name of channel to find buffer
                  for message display
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>server</option>: internal name of server to find
                  buffer for message display
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: 1 if success, 0 if an error occurred.
          </para>
          <para>
            Examples:
<screen>
# perl
weechat::print("message");
weechat::print("message", "#weechat");
weechat::print("message", "#weechat", "freenode");

# python
weechat.prnt("message")
weechat.prnt("message", "#weechat")
weechat.prnt("message", "#weechat", "freenode")

# ruby
Weechat.print("message")
Weechat.print("message", "#weechat")
Weechat.print("message", "#weechat", "freenode")

-- lua
weechat.print("message")
weechat.print("message", "#weechat")
weechat.print("message", "#weechat", "freenode")
</screen>
          </para>
        </section>
        
        <section>
          <title>print_infobar</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::print_infobar(time, message);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.print_infobar(time, message)
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.print_infobar(time, message)
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.print_infobar(time, message)
            </command>
          </para>
          <para>
            Display a message in infobar for a specified time.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>time</option>: time (in seconds) for displaying
                  message (0 = never erased)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>message</option>: message
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: 1 if success, 0 if an error occurred.
          </para>
          <para>
            Examples:
<screen>
# perl
weechat::print_infobar(5, "message");

# python
weechat.print_infobar(5, "message")

# ruby
Weechat.print_infobar(5, "message")

-- lua
weechat.print_infobar(5, "message")
</screen>
          </para>
        </section>
        
        <section>
          <title>log</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::log(message, [channel, [server]]);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.log(message, [channel, [server]])
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.log(message, [channel, [server]])
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.log(message, [channel, [server]])
            </command>
          </para>
          <para>
            Write a message in log file for a server or a channel.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>message</option>: message
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>channel</option>: name of channel to find buffer
                  for log
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>server</option>: internal name of server to find
                  buffer for log
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: 1 if success, 0 if an error occurred.
          </para>
          <para>
            Examples:
<screen>
# perl
weechat::log("message", "#weechat", "freenode");

# python
weechat.log("message", "#weechat", "freenode")

# ruby
Weechat.log("message", "#weechat", "freenode")

-- lua
weechat.log("message", "#weechat", "freenode")
</screen>
          </para>
        </section>
        
        <section>
          <title>add_message_handler</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::add_message_handler(message, function);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.add_message_handler(message, function)
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.add_message_handler(message, function)
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.add_message_handler(message, function)
            </command>
          </para>
          <para>
            Add an IRC message handler, called when an IRC message is
            received.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>message</option>: name of IRC message. To know list
                  of IRC messages, please consult <acronym>RFC</acronym>s
                  <ulink url="http://www.ietf.org/rfc/rfc1459.txt">1459</ulink> and
                  <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink>
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>function</option>: function called when message is
                  received
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: 1 if success, 0 if an error occurred.
          </para>
          <para>
            Examples:
<screen>
# perl
weechat::add_message_handler ("privmsg", "my_function");
sub my_function
{
    weechat::print("server=$_[0]");
    ($null, $channel, $message) = split ":",$_[1],3;
    ($mask, $null, $channel) = split " ", $channel;
    weechat::print("mask=$mask, channel=$channel, msg=$message");
    return weechat::PLUGIN_RC_OK;
}

# python
weechat.add_message_handler ("privmsg", "my_function")
def my_function(server, args):
    weechat.prnt("server="+server)
    null, channel, message = string.split(args, ":", 2)
    masque, null, channel = string.split(string.strip(channel), " ", 2)
    weechat.prnt("mask="+mask+", canal="+channel+", message="+message)
    return weechat.PLUGIN_RC_OK

# ruby
Weechat.add_message_handler("privmsg", "my_function")
def my_function(server, args)
    Weechat.print("server=#{server}, args=#{args}")
    return Weechat::PLUGIN_RC_OK
end

-- lua
weechat.add_message_handler ("privmsg", "my_function")
function my_function(server, args)
    weechat.print("server=" .. server .. ", args=" .. args)
    return weechat.PLUGIN_RC_OK()
end
</screen>
          </para>
          <para>
            Note: function called when message is received has to return
            one of following values:
            <itemizedlist>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_KO</literal>: function failed
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_OK</literal>: function successfully
                  completed
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_OK_IGNORE_WEECHAT</literal>: message
                  will not be sent to WeeChat
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_OK_IGNORE_PLUGINS</literal>: message
                  will not be sent to other plugins
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_OK_IGNORE_ALL</literal>: message
                  will not be sent to WeeChat neither other plugins
                </para>
              </listitem>
            </itemizedlist>
          </para>
        </section>
        
        <section>
          <title>add_command_handler</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::add_command_handler(command, function,
              [description, arguments, arguments_description,
              completion_template]);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.add_command_handler(command, function,
              [description, arguments, arguments_description,
              completion_template])
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.add_command_handler(command, function,
              [description, arguments, arguments_description,
              completion_template])
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.add_command_handler(command, function,
              [description, arguments, arguments_description,
              completion_template])
            </command>
          </para>
          <para>
            Add a WeeChat command handler, called when user uses command
            (for example /command).
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>command</option>: the new command name, which
                  may be an existing command (be careful, replaced command
                  will not be available until script is unloaded)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>function</option>: function called when command
                  is executed
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>arguments</option>: short description of command
                  arguments (displayed by /help command)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>arguments_description</option>: long description
                  of command arguments (displayed by /help command)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>completion_template</option>: template for
                  completion, like "<literal>abc|%w def|%i</literal>" which
                  means "abc" or a WeeChat command for first argument,
                  "def" or IRC command for second.
                  (see <xref linkend="secAPI_cmd_handler_add" />)
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: 1 if success, 0 if an error occurred.
          </para>
          <para>
            Examples:
<screen>
# perl
weechat::add_command_handler("command", "my_command");
sub my_command
{
    weechat::print("server= $_[0], args: $_[1]");
    return weechat::PLUGIN_RC_OK;
}

# python
weechat.add_command_handler("command", "my_command")
def my_command(server, args):
    weechat.prnt("server="+server+", args="+args)
    return weechat.PLUGIN_RC_OK

# ruby
Weechat.add_command_handler("command", "my_command")
def my_command(server, args)
    Weechat.print("server=#{server}, args=#{args}")
    return Weechat::PLUGIN_RC_OK
end

-- lua
weechat.add_command_handler("command", "my_command")
def my_command(server, args)
    weechat.print("server="..server..", args="..args)
    return weechat.PLUGIN_RC_OK()
end
</screen>
          </para>
          <para>
            Notes: function called when command is executed has to return
            one of following values:
            <itemizedlist>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_KO</literal> : function failed
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_OK</literal> : function successfully
                  completed
                </para>
              </listitem>
            </itemizedlist>
          </para>
        </section>
        
        <section>
          <title>add_timer_handler</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::add_timer_handler(message, function);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.add_timer_handler(message, function)
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.add_timer_handler(message, function)
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.add_timer_handler(message, function)
            </command>
          </para>
          <para>
            Add a timer handler which periodically calls a function.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>interval</option>: interval (in seconds) between
                  two calls of function.
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>function</option>: function called
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: 1 if success, 0 if an error occurred.
          </para>
          <para>
            Examples:
<screen>
# perl
weechat::add_timer_handler(60, "my_timer");
sub my_timer
{
    weechat::print("this is timer handler");
    return weechat::PLUGIN_RC_OK;
}

# python
weechat.add_timer_handler(60, "my_timer")
def my_timer(server, args):
    weechat.prnt("this is timer handler")
    return weechat.PLUGIN_RC_OK

# ruby
Weechat.add_timer_handler(60, "my_timer")
def my_timer(server, args)
    Weechat.print("this is timer handler")
    return Weechat::PLUGIN_RC_OK
end

-- lua
weechat.add_timer_handler(60, "my_timer")
function my_timer(server, args)
    weechat.print("this is timer handler)
    return weechat.PLUGIN_RC_OK()
end
</screen>
          </para>
          <para>
            Note: function called has to return one of following values:
            <itemizedlist>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_KO</literal>: function failed
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal>PLUGIN_RC_OK</literal>: function successfully
                  completed
                </para>
              </listitem>
            </itemizedlist>
          </para>
        </section>
        
        <section>
          <title>remove_handler</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::remove_handler(name, function);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.remove_handler(name, function)
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.remove_handler(name, function)
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.remove_handler(name, function)
            </command>
          </para>
          <para>
            Remove a message or command handler.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>name</option>: name of IRC message or command
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>function</option>: function
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: 1 if success, 0 if an error occurred.
          </para>
          <para>
            Examples:
<screen>
# perl
weechat::remove_handler("command", "my_command");

# python
weechat.remove_handler("command", "my_command")

# ruby
Weechat.remove_handler("command", "my_command")

-- lua
weechat.remove_handler("command", "my_command")
</screen>
          </para>
        </section>
        
        <section>
          <title>remove_timer_handler</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::remove_timer_handler(function);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.remove_timer_handler(function)
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.remove_timer_handler(function)
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.remove_timer_handler(function)
            </command>
          </para>
          <para>
            Remove a timer handler.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>function</option>: function
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: 1 if success, 0 if an error occurred.
          </para>
          <para>
            Examples:
<screen>
# perl
weechat::remove_timer_handler("my_timer");

# python
weechat.remove_timer_handler("my_timer")

# ruby
Weechat.remove_timer_handler("my_timer")

-- lua
weechat.remove_timer_handler("my_timer")
</screen>
          </para>
        </section>
        
        <section>
          <title>command</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::command(command, [channel, [server]]);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.command(command, [channel, [server]])
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.command(command, [channel, [server]])
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.command(command, [channel, [server]])
            </command>
          </para>
          <para>
            Execute a WeeChat command (or send a message to a channel).
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>command</option>: command
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>channel</option>: name of channel for executing
                  command
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>server</option>: internal name of server for
                  executing command
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: 1 if success, 0 if an error occurred.
          </para>
          <para>
            Examples:
<screen>
# perl
weechat::command("hello everybody!");
weechat::command("/kick toto please leave this channel", "#weechat");
weechat::command("/nick newnick", "", "freenode");

# python
weechat.command("hello everybody!")
weechat.command("/kick toto please leave this channel", "#weechat")
weechat.command("/nick newnick", "", "freenode")

# ruby
Weechat.command("hello everybody!")
Weechat.command("/kick toto please leave this channel", "#weechat")
Weechat.command("/nick newnick", "", "freenode")

-- lua
weechat.command("hello everybody!")
weechat.command("/kick toto please leave this channel", "#weechat")
weechat.command("/nick newnick", "", "freenode")
</screen>
          </para>
        </section>
        
        <section>
          <title>get_info</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::get_info(name, [server]);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.get_info(name, [server])
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.get_info(name, [server])
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.get_info(name, [server])
            </command>
          </para>
          <para>
            Return an info about WeeChat or a channel.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>name</option>: name of info to read
                  (see <xref linkend="secAPI_get_info" />)
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>server</option>: internal name of server for
                  reading info (if needed)
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: information asked, empty string if an error
            occurred.
          </para>
          <para>
            Examples:
<screen>
# perl
$version = get_info("version");
$nick = get_info("nick", "freenode");

# python
version = weechat.get_info("version")
nick = weechat.get_info("nick", "freenode")

# ruby
version = Weechat.get_info("version")
nick = Weechat.get_info("nick", "freenode")

-- lua
version = weechat.get_info("version")
nick = weechat.get_info("nick", "freenode")
</screen>
          </para>
        </section>
        
        <section>
          <title>get_dcc_info</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::get_dcc_info();
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.get_dcc_info()
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.get_dcc_info()
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.get_dcc_info()
            </command>
          </para>
          <para>
            Return list of DCC currently active or finished.
          </para>
          <para>
            Return value: list of DCC
            (see <xref linkend="secAPI_get_dcc_info" />).
          </para>
          <para>
            Examples:
<screen>
# perl
my @dccs = weechat::get_dcc_info();
if (@dccs)
{
    foreach my $dcc (@dccs)
    {
        while (my ($key, $value) = each %$dcc)
        {
            weechat::print("$key = '$value'");
        }
    }
}
else
{
    weechat::print("no DCC");
}

# python
dccs = weechat.get_dcc_info()
if dccs != None:
    if dccs == []:
        weechat.prnt("no DCC")
    else:
        for d in dccs:
            for b in d.keys():
                weechat.prnt("%s = '%s'" %(b, d[b]))
else:
    weechat.prnt("error while getting DCC")

# ruby
dccs = Weechat.get_dcc_info()
if dccs != nil   
    if dccs == []
        Weechat.print("no DCC")
    else
        dccs.each do |m|
            m.each do |key, value|
                Weechat.print("#{key} = '#{value}'")
            end
        end
    end
else
    Weechat.print("error while getting DCC")
end

-- lua
dccs = weechat.get_dcc_info()
if dccs ~= nil then
    if dccs then
        dcc, dccinfos = next (dccs, nil)
        while (dcc) do
            key, value = next (dccinfos, nil)
            while (key) do
                weechat.print(key.." = '"..value.."'")
                key, value = next (dccinfos, key)
            end
            dcc, dccinfos = next (dccs, dcc)
        end 
    else
        weechat.print("no DCC")
    end
else
    weechat.print("error while getting DCC")
end
</screen>
          </para>
        </section>
        
        <section>
          <title>get_server_info</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::get_server_info();
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.get_server_info()
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.get_server_info()
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.get_server_info()
            </command>
          </para>
          <para>
            Return list of IRC servers (connected or not).
          </para>
          <para>
            Return value: list of servers
            (see <xref linkend="secAPI_get_server_info" />).
          </para>
          <para>
            Examples:
<screen>
# perl
my $servers = weechat::get_server_info();
if ($servers)
{
    while (my ($srvname, $srvinfos) = each %$servers)
    {
        while ( my ($key, $value) = each %$srvinfos)
        {
            weechat::print("$srvname -> $key = '$value'");
        }
    }
}
else
{
    weechat::print("no server");
}

# python
servers = weechat.get_server_info()
if servers != None:
    if servers == {}:
        weechat.prnt("no server")
    else:
        for s in servers:
            for i in servers[s]:
                weechat.prnt("%s -> %s = '%s'" % (s, i, str(servers[s][i])))
else:
    weechat.prnt("error while getting servers")

# ruby
servers = Weechat.get_server_info()
if servers != nil
    if servers == []
        Weechat.print("no server")
    else
        servers.each do |n, s|
            s.each do |key, value|
                Weechat.print("#{n} -> #{key} = '#{value}'")
            end
        end
    end
else
    Weechat.print("error while getting servers")
end

-- lua
servers = weechat.get_server_info()
if servers ~= nil then
    if servers then
        srv, srvinfos = next (servers, nil)
        while (srv) do
            key, value = next (srvinfos, nil)
            while (key) do
                weechat.print(srv.." -> "..key.." = '"..value.."'")
                key, value = next (srvinfos, key)
            end	
            srv, srvinfos = next (servers, srv)
        end
    else
        weechat.print("no server")
    end
else
    weechat.print("error while getting servers")
end
</screen>
          </para>
        </section>
        
        <section>
          <title>get_channel_info</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::get_channel_info(server);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.get_channel_info(server)
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.get_channel_info(server)
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.get_channel_info(server)
            </command>
          </para>
          <para>
            Return list of IRC channels for a server.
          </para>
          <para>
            Return value: list of IRC channels for server
            (see <xref linkend="secAPI_get_channel_info" />).
          </para>
          <para>
            Examples:
<screen>
# perl
my $channels = weechat::get_channel_info(weechat::get_info("server"));
if ($channels)
{
    while (my ($channame, $chaninfos) = each %$channels)
    {
        while (my ($key, $value) = each %$chaninfos)
        {
            weechat::print("$channame -> $key = '$value'");
        }
    }
}
else
{
    weechat::print("no channel");
}

# python
chans = weechat.get_channel_info(weechat.get_info("server"))
if chans != None:
    if chans == {}:
        weechat.prnt("no channel")
    else:
        for s in chans:
            for i in chans[s]:
                weechat.prnt("%s -> %s = '%s'" % (s, i, str(chans[s][i])))
else:
    weechat.prnt("error while getting channels")

# ruby
channels = Weechat.get_channel_info(Weechat.get_info("server"))
if channels != nil
    if channels == {}
        Weechat.print("no channel")
    else
        channels.each do |n, c|
            c.each do |key, value|
                Weechat.print("#{n} -> #{key} = '#{value}'")
            end
        end
    end
else
    Weechat.print("error while getting channels")
end

-- lua
chans = weechat.get_channel_info(weechat.get_info("server"))
if chans ~= nil then
    if chans then
        chan, chaninfos = next (chans, nil)
        while (chan) do
            key, value = next (chaninfos, nil)
            while (key) do
                weechat.print(chan.." -> "..key.." = '"..value.."'")
                key, value = next (chaninfos, key)
            end
            chan, chaninfos = next (chans, chan)
        end
    else
        weechat.print("no channel")
    end
else
    weechat.print("error while getting channels")
end
</screen>
          </para>
        </section>
        
        <section>
          <title>get_nick_info</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::get_nick_info(server, channel);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.get_nick_info(server, channel)
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.get_nick_info(server, channel)
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.get_nick_info(server, channel)
            </command>
          </para>
          <para>
            Return list of nicks for a channel.
          </para>
          <para>
            Return value: list of nicks on channel
            (see <xref linkend="secAPI_get_nick_info" />).
          </para>
          <para>
            Examples:
<screen>
# perl
my $nicks = weechat::get_nick_info("freenode", "#weechat");
if ($nicks)
{
    while (my ($nickname, $nickinfos) = each %$nicks)
    {
        while ( my ($key, $value) = each %$nickinfos)
        {
            weechat::print("$nickname -> $key = '$value'");
        }
    }
}
else
{
    weechat::print("no nick");
}

# python
nicks = weechat.get_nick_info("freenode", "#weechat")
if nicks != None:
    if nicks == {}:
        weechat.prnt("no nick")
    else:
        for n in nicks:
            for f in nicks[n]:
                weechat.prnt("%s -> %s = '%s'" % (n, f, str(nicks[n][f])))
else:
    weechat.prnt("error while getting nicks")

# ruby
nicks = Weechat.get_nick_info("freenode", "#weechat")
if nicks != nil
    if nicks == {}
        Weechat.print("no nick")
    else
        nicks.each do |nk, nattr|
            nattr.each do |key, value|
                Weechat.print("#{nk} -> #{key} = '#{value}'")
            end
        end
    end
else
    Weechat.print("error while getting nicks")
end

-- lua
nicks = weechat.get_nick_info("freenode", "#weechat")
if nicks ~= nil then
    if nicks then	
        nick, nickinfos = next (nicks, nil)
        while (nick) do
            key, value = next (nickinfos, nil)
            while (key) do
                weechat.print(nick.." -> "..key.." = '"..value.."'")
                key, value = next (nickinfos, key)
            end
            nick, nickinfos = next (nicks, nick)
        end
    else
        weechat.print("no nick")
    end
else
    weechat.print("error while getting nicks")
end
</screen>
          </para>
        </section>
        
        <section>
          <title>get_config</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::get_config(option);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.get_config(option)
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.get_config(option)
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.get_config(option)
            </command>
          </para>
          <para>
            Return value of a WeeChat config option.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>option</option>: name of option to read
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: option value, empty string if not found.
          </para>
          <para>
            Examples:
<screen>
# perl
$value1 = weechat::get_config("look_nicklist");
$value2 = weechat::get_config("freenode.server_autojoin");

# python
value1 = weechat.get_config("look_nicklist")
value2 = weechat.get_config("freenode.server_autojoin")

# ruby
value1 = Weechat.get_config("look_nicklist")
value2 = Weechat.get_config("freenode.server_autojoin")

-- lua
value1 = weechat.get_config("look_nicklist")
value2 = weechat.get_config("freenode.server_autojoin")
</screen>
          </para>
        </section>
        
        <section>
          <title>set_config</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::set_config(option, value);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.set_config(option, value)
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.set_config(option, value)
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.set_config(option, value)
            </command>
          </para>
          <para>
            Update value of a WeeChat config option.
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>option</option>: name of option to update
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>value</option>: new value for option
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: 1 if option was successfully updated, 0 if an error
            occurred.
          </para>
          <para>
            Examples:
<screen>
# perl
weechat::set_config("look_nicklist", "off");
weechat::set_config("freenode.server_autojoin, "#weechat");

# python
weechat.set_config("look_nicklist", "off")
weechat.set_config("freenode.server_autojoin, "#weechat")

# ruby
Weechat.set_config("look_nicklist", "off")
Weechat.set_config("freenode.server_autojoin, "#weechat")

-- lua
weechat.set_config("look_nicklist", "off")
weechat.set_config("freenode.server_autojoin, "#weechat")
</screen>
          </para>
        </section>
        
        <section>
          <title>get_plugin_config</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::get_plugin_config(option);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.get_plugin_config(option)
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.get_plugin_config(option)
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.get_plugin_config(option)
            </command>
          </para>
          <para>
            Return value of a plugin option. Option is read from file
            "<literal>~/.weechat/plugins.rc</literal>" and is like:
            "<literal>plugin.option=value</literal>" (note: plugin name
            is automatically added).
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>option</option>: name of option to read
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: value of option, empty string if not found.
          </para>
          <para>
            Examples :
<screen>
# perl
$value = weechat::get_plugin_config("my_var");

# python
value = weechat.get_plugin_config("my_var")

# ruby
value = Weechat.get_plugin_config("my_var")

-- lua
value = weechat.get_plugin_config("my_var")
</screen>
          </para>
        </section>
        
        <section>
          <title>set_plugin_config</title>
          
          <para>
            Perl prototype:
            <command>
              weechat::set_plugin_config(option, value);
            </command>
          </para>
          <para>
            Python prototype:
            <command>
              weechat.set_plugin_config(option, value)
            </command>
          </para>
          <para>
            Ruby prototype:
            <command>
              Weechat.set_plugin_config(option, value)
            </command>
          </para>
          <para>
            Lua prototype:
            <command>
              weechat.set_plugin_config(option, value)
            </command>
          </para>
          <para>
            Update value of a plugin option. Option is written in file
            "<literal>~/.weechat/plugins.rc</literal>" and is like:
            "<literal>plugin.option=value</literal>" (note: plugin name
            is automatically added).
          </para>
          <para>
            Arguments:
            <itemizedlist>
              <listitem>
                <para>
                  <option>option</option>: name of option to update
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>value</option>: new value for option
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            Return value: 1 if option was successfully updated, 0 if an error
            occurred.
          </para>
          <para>
            Examples:
<screen>
# perl
weechat::set_plugin_config("my_var", "value");

# python
weechat.set_plugin_config("my_var", "value")

# ruby
Weechat.set_plugin_config("my_var", "value")

-- lua
weechat.set_plugin_config("my_var", "value")
</screen>
          </para>
        </section>
        
      </section>
        
    </section>
    
  </chapter>
  
  <!-- ======================== Auteurs / Support ========================= -->
  
  <chapter id="chapAuthorsSupport">
    <title>Authors / Support</title>
    
    <para>
      This chapter lists authors and contributors for WeeChat, and
      shows ways to get support.
    </para>
    
    <section id="secAuthors">
      <title>Authors</title>
      
      <para>
        WeeChat is developed by:
        <itemizedlist>
          <listitem>
            <para>
              <emphasis>FlashCode (Sébastien Helleu)</emphasis>
              <email>flashcode AT flashtux.org</email> -
              main developer
            </para>
          </listitem>
          <listitem>
            <para>
              <emphasis>Kolter</emphasis>
              <email>kolter AT free.fr</email> -
              developer
            </para>
          </listitem>
          <listitem>
            <para>
              <emphasis>Ptitlouis</emphasis>
              <email>ptitlouis AT sysif.net</email> -
              Debian packager
            </para>
          </listitem>
        </itemizedlist>
      </para>
      
    </section>
    
    <section id="secContributors">
      <title>Contributors</title>
      
      <para>
        Following people contributed to WeeChat:
        <itemizedlist>
          <listitem>
            <para>
              <emphasis>Jiri Golembiovsky</emphasis> -
              czech translation, patches
            </para>
          </listitem>
          <listitem>
            <para>
              <emphasis>Rudolf Polzer</emphasis> -
              patches
            </para>
          </listitem>
          <listitem>
            <para>
              <emphasis>Jim Ramsay</emphasis> -
              patches
            </para>
          </listitem>
          <listitem>
            <para>
              <emphasis>Odin</emphasis> -
              SuSE RPM
            </para>
          </listitem>
          <listitem>
            <para>
              <emphasis>Pistos</emphasis> -
              patches
            </para>
          </listitem>
          <listitem>
            <para>
              <emphasis>Gwenn</emphasis> -
              patches
            </para>
          </listitem>
          <listitem>
            <para>
              <emphasis>voroskoi</emphasis> -
              hungarian translation
            </para>
          </listitem>
        </itemizedlist>
      </para>
      
    </section>
    
    <section id="secSupport">
      <title>Get support</title>
      
      <para>
        Before asking for support, be sure you've read documentation and FAQ
        provided with WeeChat (documentation is this document, if you don't
        read all lines until this sentence, you can start again!)
      </para>
      
      <para>
        <itemizedlist>
          <listitem>
            <para>
              IRC: server "<literal>irc.freenode.net</literal>",
              channel "<literal>#weechat</literal>"
            </para>
          </listitem>
          <listitem>
            <para>
              WeeChat forum:
              <ulink url="http://forums.flashtux.org">
                http://forums.flashtux.org
              </ulink>
            </para>
          </listitem>
          <listitem>
            <para>
              Mailing list:
              <itemizedlist>
                <listitem>
                  <para>
                    To subscribe:
                    <ulink url="http://mail.nongnu.org/mailman/listinfo/weechat-support">
                      http://mail.nongnu.org/mailman/listinfo/weechat-support
                    </ulink>
                  </para>
                </listitem>
                <listitem>
                  <para>
                    To send a mail on mailing list:
                    <email>weechat-support@nongnu.org</email>
                  </para>
                </listitem>
              </itemizedlist>
              Mailing list archives are available here:
              <ulink url="http://mail.nongnu.org/archive/html/weechat-support">
                http://mail.nongnu.org/archive/html/weechat-support
              </ulink>
            </para>
          </listitem>
        </itemizedlist>
      </para>
      
    </section>
      
  </chapter>
  
</book>