Introduction
************

Description
===========

WeeChat (Wee Enhanced Environment for Chat) is a free IRC client, fast and light, designed for many operating systems.

Main features are:

  - multi-servers connection

  - many GUI (Graphical User Interface): Curses, Gtk and Qt

  - small, fast and light

  - customizable and extensible with scripts

  - compliant with RFCs 1459, 2810, 2811, 2812, and 2813

  - multi-platform (Gnu/Linux, *BSD, Windows and other)

  - 100% GPL, free software

WeeChat homepage is here:

http://weechat.flashtux.org

Pre-requisites
==============

In order to install WeeChat, you need:

  * A running Gnu/Linux system (with compiler tools for source package)

  * "root" privileges (to install WeeChat)

  * According to GUI, one of the following libraries:

       - Curses: ncurses library,

       - Gtk: *** GUI not developed ***,

       - Qt: *** GUI not developed ***,

Installation
************

Binary package
==============

Binary packages are available for these distributions:

  * Debian (or any Debian compatible distribution)

     To install: dpkg -i /path/weechat_x.y.z-1_i386.deb

  * Mandrake/Redhat (or any RPM compatible distribution)

     To install: rpm -i /path/weechat-x.y.z-1.i386.rpm

  * Gentoo

     To install: emerge weechat

  * *BSD (not available!)

  * Slackware (not available!)

  * Windows (not available!)

where x.y.z is the version (for example 0.0.1)

Source package
==============

All you have to do is to run in a console or a terminal:

./configure

make

Nota: to build only some interfaces, you can give parameters to ./configure, type ./configure --help for help about options.

Then get root privileges and install WeeChat:

su

(enter root password)

make install

CVS sources
===========

Warning: CVS sources are for advanced users: it may not compile or not be stable. You're warned!

To get CVS sources, issue these commands:

cvs -d:pserver:anoncvs@subversions.gnu.org:/cvsroot/weechat login

cvs -z3 -d:pserver:anoncvs@subversions.gnu.org:/cvsroot/weechat co weechat

(when prompted for a password, just press Enter key)

Execute this script:

./autogen.sh

Then follow instructions for source package - see Source package.

Usage
*****

Run WeeChat
===========

Command line parameters
-----------------------

-c, --config
     Display config file help (list of options)

-h, --help
     Display help screen

-l, --license
     Display WeeChat license

-v, --version
     Display WeeChat version

Run WeeChat
-----------

Just issue this command to run WeeChat:

weechat-curses (for Curses front-end)

or weechat-gtk (for Gtk front-end)

or weechat-qt (for Qt front-end)

When you run WeeChat for the first time, a default configuration file is created, with default options.

The default configuration file is: ~/.weechat/weechat.rc

You can edit this file at your convenience to configure WeeChat, or you can set parameters with /set command in WeeChat - see WeeChat commands.

Config file
===========

Here is a list of all options for config file:

look_set_title
     Set title for window (terminal for Curses GUI) with name & version

     Type: boolean (values: 'on' or 'off'), default value: 'on'

look_startup_logo
     Display WeeChat logo at startup

     Type: boolean (values: 'on' or 'off'), default value: 'on'

look_startup_version
     Display WeeChat version at startup

     Type: boolean (values: 'on' or 'off'), default value: 'on'

look_weechat_slogan
     WeeChat slogan (if empty, slogan is not used)

     Type: string (any string), default value: 'the geekest IRC client!'

look_color_nicks
     Display nick names with different colors

     Type: boolean (values: 'on' or 'off'), default value: 'on'

look_color_actions
     Display actions with different colors

     Type: boolean (values: 'on' or 'off'), default value: 'on'

look_remove_colors_from_msgs
     Remove colors from incoming messages

     Type: boolean (values: 'on' or 'off'), default value: 'on'

look_nicklist
     Display nicklist window (for channel windows)

     Type: boolean (values: 'on' or 'off'), default value: 'on'

look_nicklist_position
     Nicklist position (top, left, right (default), bottom)

     Type: string (values: 'left', 'right', 'top', 'bottom'), default value: 'right'

look_nicklist_min_size
     Min size for nicklist (width or height, depending on look_nicklist_position (0 = no min size))

     Type: integer (values: between 0 and 100), default value: 0

look_nicklist_max_size
     Max size for nicklist (width or height, depending on look_nicklist_position (0 = no max size; if min == max and > 0, then size is fixed))

     Type: integer (values: between 0 and 100), default value: 0

look_no_nickname
     Text to display instead of nick when not connected

     Type: string (any string), default value: '-cmd-'

look_nickmode
     Display nick mode ((half)op/voice) before each nick

     Type: boolean (values: 'on' or 'off'), default value: 'on'

look_nickmode_empty
     Display space if nick mode is not (half)op/voice

     Type: boolean (values: 'on' or 'off'), default value: 'off'

look_nick_completor
     The string inserted after nick completion

     Type: string (any string), default value: ':'

look_display_away
     Display message to all channels when (un)marking as away

     Type: boolean (values: 'on' or 'off'), default value: 'on'

look_infobar
     Enable info bar

     Type: boolean (values: 'on' or 'off'), default value: 'on'

look_infobar_timestamp
     Timestamp for time in infobar

     Type: string (any string), default value: '%B, %A %d %G - %H:%M'

look_infobar_delay_highlight
     Delay (in seconds) for highlight messages in infobar (0 = disable highlight notifications in infobar)

     Type: integer (values: between 0 and 2147483647), default value: 7

col_title
     Color for title bar

     Type: color (Curses or Gtk color), default value: 'gray'

col_title_bg
     Background for title bar

     Type: color (Curses or Gtk color), default value: 'blue'

col_chat
     Color for chat text

     Type: color (Curses or Gtk color), default value: 'gray'

col_chat_time
     Color for time in chat window

     Type: color (Curses or Gtk color), default value: 'gray'

col_chat_time_sep
     Color for time separator (chat window)

     Type: color (Curses or Gtk color), default value: 'brown'

col_chat_prefix1
     Color for 1st and 3rd char of prefix

     Type: color (Curses or Gtk color), default value: 'lightcyan'

col_chat_prefix2
     Color for middle char of prefix

     Type: color (Curses or Gtk color), default value: 'white'

col_chat_nick
     Color for nicks in actions (chat window)

     Type: color (Curses or Gtk color), default value: 'lightcyan'

col_chat_host
     Color for hostnames (chat window)

     Type: color (Curses or Gtk color), default value: 'cyan'

col_chat_channel
     Color for channel names in actions (chat window)

     Type: color (Curses or Gtk color), default value: 'white'

col_chat_dark
     Color for dark separators (chat window)

     Type: color (Curses or Gtk color), default value: 'green'

col_chat_highlight
     Color for highlighted nick (chat window)

     Type: color (Curses or Gtk color), default value: 'yellow'

col_chat_bg
     Background for chat window

     Type: color (Curses or Gtk color), default value: 'default'

col_status
     Color for status bar

     Type: color (Curses or Gtk color), default value: 'gray'

col_status_delimiters
     Color for status bar delimiters

     Type: color (Curses or Gtk color), default value: 'cyan'

col_status_data_msg
     Color for window with new messages (status bar)

     Type: color (Curses or Gtk color), default value: 'yellow'

col_status_highlight
     Color for window with highlight (status bar)

     Type: color (Curses or Gtk color), default value: 'lightmagenta'

col_status_data_other
     Color for window with new data (not messages) (status bar)

     Type: color (Curses or Gtk color), default value: 'gray'

col_status_more
     Color for window with new data (status bar)

     Type: color (Curses or Gtk color), default value: 'white'

col_status_bg
     Background for status window

     Type: color (Curses or Gtk color), default value: 'blue'

col_infobar
     Color for info bar text

     Type: color (Curses or Gtk color), default value: 'black'

col_infobar_highlight
     Color for info bar highlight notification

     Type: color (Curses or Gtk color), default value: 'white'

col_infobar_bg
     Background for info bar window

     Type: color (Curses or Gtk color), default value: 'cyan'

col_input
     Color for input text

     Type: color (Curses or Gtk color), default value: 'gray'

col_input_channel
     Color for input text (channel name)

     Type: color (Curses or Gtk color), default value: 'white'

col_input_nick
     Color for input text (nick name)

     Type: color (Curses or Gtk color), default value: 'lightgreen'

col_input_bg
     Background for input window

     Type: color (Curses or Gtk color), default value: 'default'

col_nick
     Color for nicknames

     Type: color (Curses or Gtk color), default value: 'gray'

col_nick_op
     Color for operator symbol

     Type: color (Curses or Gtk color), default value: 'lightgreen'

col_nick_halfop
     Color for half-operator symbol

     Type: color (Curses or Gtk color), default value: 'lightmagenta'

col_nick_voice
     Color for voice symbol

     Type: color (Curses or Gtk color), default value: 'yellow'

col_nick_sep
     Color for nick separator

     Type: color (Curses or Gtk color), default value: 'blue'

col_nick_self
     Color for local nick

     Type: color (Curses or Gtk color), default value: 'white'

col_nick_private
     Color for other nick in private window

     Type: color (Curses or Gtk color), default value: 'gray'

col_nick_bg
     Background for nicknames

     Type: color (Curses or Gtk color), default value: 'default'

col_chat_dcc_selected
     Color for selected DCC (chat window)

     Type: color (Curses or Gtk color), default value: 'white'

col_dcc_waiting
     Color for "waiting" dcc status

     Type: color (Curses or Gtk color), default value: 'white'

col_dcc_connecting
     Color for "connecting" dcc status

     Type: color (Curses or Gtk color), default value: 'yellow'

col_dcc_active
     Color for "active" dcc status

     Type: color (Curses or Gtk color), default value: 'lightblue'

col_dcc_done
     Color for "done" dcc status

     Type: color (Curses or Gtk color), default value: 'lightgreen'

col_dcc_failed
     Color for "failed" dcc status

     Type: color (Curses or Gtk color), default value: 'lightred'

col_dcc_aborted
     Color for "aborted" dcc status

     Type: color (Curses or Gtk color), default value: 'lightred'

history_max_lines
     Maximum number of lines in history for one server/channel/private window (0 = unlimited)

     Type: integer (values: between 0 and 2147483647), default value: 4096

history_max_commands
     Maximum number of user commands in history (0 = unlimited)

     Type: integer (values: between 0 and 2147483647), default value: 100

log_auto_server
     Automatically log server messages

     Type: boolean (values: 'on' or 'off'), default value: 'on'

log_auto_channel
     Automatically log channel chats

     Type: boolean (values: 'on' or 'off'), default value: 'on'

log_auto_private
     Automatically log private chats

     Type: boolean (values: 'on' or 'off'), default value: 'on'

log_path
     Path for WeeChat log files

     Type: string (any string), default value: '~/.weechat/logs/'

log_timestamp
     Timestamp for log (see man strftime for date/time specifiers)

     Type: string (any string), default value: '%Y %b %d %H:%M:%S'

dcc_auto_accept_files
     Automatically accept incoming dcc files

     Type: boolean (values: 'on' or 'off'), default value: 'off'

dcc_auto_accept_chats
     Automatically accept dcc chats (use carefully!)

     Type: boolean (values: 'on' or 'off'), default value: 'on'

dcc_timeout
     Timeout for dcc request (in seconds)

     Type: integer (values: between 1 and 2147483647), default value: 300

dcc_blocksize
     Block size for dcc packets in bytes (default: 1024)

     Type: integer (values: between 1024 and 102400), default value: 1024

dcc_download_path
     Path for writing incoming files with dcc (default: user home)

     Type: string (any string), default value: '~'

dcc_upload_path
     Path for reading files when sending thru dcc (when no path is specified)

     Type: string (any string), default value: '~'

dcc_auto_rename
     Rename incoming files if already exists (add '.1', '.2', ...)

     Type: boolean (values: 'on' or 'off'), default value: 'on'

dcc_auto_resume
     Automatically resume dcc transfer if connection with remote host is loosed

     Type: boolean (values: 'on' or 'off'), default value: 'on'

proxy_use
     Use a proxy server to connect to irc server

     Type: boolean (values: 'on' or 'off'), default value: 'off'

proxy_address
     Proxy server address (IP or hostname)

     Type: string (any string), default value: ''

proxy_port
     Port for connecting to proxy server

     Type: integer (values: between 0 and 65535), default value: 1080

proxy_password
     Password for proxy server

     Type: string (any string), default value: ''

server_name
     Name associated to IRC server (for display only)

     Type: string (any string), default value: ''

server_autoconnect
     Automatically connect to server when WeeChat is starting

     Type: boolean (values: 'on' or 'off'), default value: 'on'

server_address
     IP address or hostname of IRC server

     Type: string (any string), default value: ''

server_port
     Port for connecting to server

     Type: integer (values: between 0 and 65535), default value: 6667

server_password
     Password for IRC server

     Type: string (any string), default value: ''

server_nick1
     Nickname to use on IRC server

     Type: string (any string), default value: ''

server_nick2
     Alternate nickname to use on IRC server (if nickname is already used)

     Type: string (any string), default value: ''

server_nick3
     2nd alternate nickname to use on IRC server (if alternate nickname is already used)

     Type: string (any string), default value: ''

server_username
     User name to use on IRC server

     Type: string (any string), default value: ''

server_realname
     Real name to use on IRC server

     Type: string (any string), default value: ''

server_command
     First command to run when connected to server

     Type: string (any string), default value: ''

server_autojoin
     Comma separated list of channels to join when connected to server

     Type: string (any string), default value: ''

Colors for Curses GUI are:

  - default: default color (transparent for background)

  - black: black

  - red: dark red

  - lightred: light red

  - green: dark green

  - lightgreen: light green

  - brown: brown

  - yellow: yellow

  - blue: dark blue

  - lightblue: light blue

  - magenta: dark magenta

  - lightmagenta: light magenta

  - cyan: dark cyan

  - lightcyan: light cyan

  - gray: gray

  - white: white

Key bindings
============

Left arrow / Right arrow
     Go to previous / next char in command line

Ctrl + left arrow / Ctrl + right arrow
     Go to previous / next word in command line

Home / End
     Go to the beginning / end of command line

Backspace / Delete
     Erase previous / next char of command line

Ctrl + Backspace
     Erase previous word of command line

Tab
     Complete command or nick (Tab again: find next completion)

Any char
     Insert char to cursor position in the command line

Enter
     Execute command or send message

Up arrow / Down arrow
     Call again last commands/messages

PageUp / PageDown
     Show buffer history

F6 / F7
     Switch to previous / next buffer

F8
     Switch to next window

F10
     Remove last infobar message

Alt + left arrow / Alt + right arrow
     Same as F6 / F7

Alt + A
     Switch to next buffer with activity (with priority: highlight, message, other)

Alt + D
     Display current DCC

Alt + R
     Clear hotlist (activity notification on other buffers)

Alt + digit (1-9)
     Switch to buffer by number

WeeChat commands
================

NOT WRITTEN!

Extensions
**********

Perl scripts
============

Load/unload Perl scripts
------------------------

Perl scripts are loaded and unloaded with /perl command. (type /help perl within WeeChat to get help about command).

Examples:

  * Load a Perl script: /perl load /tmp/sample.pl

  * Unload all Perl scripts: /perl unload

  * List all Perl scripts: /perl

WeeChat / Perl API
------------------

  * IRC::register ( name, version, shutdown_function, description );

     This is first function to call in Perl script.

     All Perl scripts for WeeChat should call this function.

     Arguments:

       - name: unique name to identify script (each script must have unique name)

       - version: script's version

       - shutdown_function: Perl function called when script is unloaded (optional parameter, empty string means nothing is called at the end)

       - description: short description of script.

     Example:

     IRC::register ("sample", "1.0", "sample_end", "Sample script!");

  * IRC::print ( message );

     Print message in current window (channel or server).

     Arguments:

       - message: message to display

     Example:

     IRC::print ("message");

  * IRC::print_with_channel ( channel, [server,] message );

     Print message in a channel.

     Arguments:

       - channel: name of channel

       - server: internal name of server

       - message: message to display

     Examples:

     IRC::print_with_channel ("#weechat", "freenode", "message");

     IRC::print_with_channel ("#weechat", "message");

  * IRC::print_infobar ( delay, message );

     Print message in infobar.

     Arguments:

       - delay: after this delay (in seconds), message will be erased (if 0, message will not be erased).

       - message: message to display

     Example:

     IRC::print_infobar (5, "message");

  * IRC::add_message_handler ( name, function );

     Attach a Perl function to an IRC message.

     Function will be called each time IRC message will be received.

     Arguments:

       - name: name of IRC message
          To know list of IRC messages, please refer to RFC 1459 and/or 2812:

          RFC 1459: ftp://ftp.rfc-editor.org/in-notes/rfc1459.txt

          RFC 2812: ftp://ftp.rfc-editor.org/in-notes/rfc2812.txt

       - function: Perl function called when message is received

     Example:

     IRC::add_message_handler ("privmsg", my_function);

     sub my_function

     {

         IRC::print ("server=$_[0]\n");

         ($null, $channel, $message) = split ":",$_[1],3;

         ($hostmask, $null, $channel) = split " ", $channel;

         IRC::print ("host=$hostmask, chan=$channel, msg=$message\n");

     }

  * IRC::add_command_handler ( name, function );

     Create new WeeChat command, linked with Perl function.

     Function will be called when user will launch command with /name.

     Arguments:

       - name: name of new command
          This name may be existing command, so that the command is overrided by Perl function. Be careful when overriding WeeChat commands, they'll not be available until your Perl script will be unloaded.

       - function: Perl function linked with command

     Example:

     IRC::add_command_handler ("command", my_command);

     sub my_command

     {

         IRC::print("Server: $_[0], arguments: $_[1]\n");

         return 0;

     }

  * IRC::get_info ( [server,] name );

     Get various info about WeeChat, server or user.

     Arguments:

       - server: internal name of server

       - name: name of info to retrieve:

            - 0 or version: get WeeChat version

            - 1 or nick: get nickname

            - 2 or channel: get channel name

            - 3 or server: get server name

            - 4 or weechatdir: get WeeChat home directory

            - 5 or away: get away flag for server

     Examples:

     $version = get_info("version");

     $nick = get_info("freenode", "nick");

Python scripts
==============

Not developed!

Ruby scripts
============

Not developed!

Authors / Support
*****************

Authors
=======

WeeChat is developed by:

  * FlashCode <flashcode AT flashtux.org>

  * Bounga <bounga AT altern.org>

  * Xahlexx <xahlexx AT tuxfamily.org>

  * Crevetor <crevetor AT caramail.com>

Get support
===========

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!)

  * Support with IRC:

     - server: irc.freenode.net

     - channel: #weechat

  * WeeChat forum: http://forums.flashtux.org

  * Support with mailing list:

     - to subscribe/unsubscribe:
     http://mail.nongnu.org/mailman/listinfo/weechat-support.

     - to send mail to all mailing list subscribers, send your mail to
     weechat-support@nongnu.org.

     Mailing archives are available here:

     http://mail.nongnu.org/archive/html/weechat-support

  * Look for WeeChat support page for detail:

     http://weechat.flashtux.org/support.php?lang=en