path: root/doc/en/weechat_user.en.txt

WeeChat User's Guide
====================
Sébastien Helleu <flashcode@flashtux.org>


This manual documents WeeChat chat client, it is part of WeeChat.

Latest version of this document can be found on this page:
http://www.weechat.org/doc


[[introduction]]
Introduction
------------

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

[[features]]
Features
~~~~~~~~

Main features are:

* multi-protocols (IRC, Jabber)
* multi-servers connection (with SSL, IPv6, proxy)
* many GUI: Curses (wxWidgets, Gtk and Qt under development)
* small, fast and light
* customizable and extensible with plugins and scripts
* compliant with IRC RFCs http://www.ietf.org/rfc/rfc1459.txt[1459],
  http://www.ietf.org/rfc/rfc2810.txt[2810],
  http://www.ietf.org/rfc/rfc2811.txt[2811],
  http://www.ietf.org/rfc/rfc2812.txt[2812] and
  http://www.ietf.org/rfc/rfc2813.txt[2813]
* multi-platform (GNU/Linux, *BSD, MacOS X, Windows and other)
* 100% GPL, free software

WeeChat homepage is here: http://www.weechat.org/

[[pre-requisites]]
Pre-requisites
~~~~~~~~~~~~~~

In order to install WeeChat, you need:

* a running GNU/Linux system (with compiler tools for source
  package), or compatible OS
* 'root' privileges (to install WeeChat in a system directory)
* ncurses library


[[install]]
Installation
------------

[[binary_packages]]
Binary packages
~~~~~~~~~~~~~~~

Binary packages are available for many distributions, including:

* Debian (or any Debian compatible distribution):
  `apt-get install weechat-curses`
* Mandriva/RedHat (or any RPM compatible distribution):
  `rpm -i /path/to/weechat-x.y.z-1.i386.rpm`
* Gentoo: `emerge weechat`
* Arch Linux: `pacman -S weechat`
* Fedora Core: `yum install weechat`
* Sourcemage: `cast weechat`

Some additional packages may be useful, like weechat-plugins.

For other distributions, please look at your manual for installation
instructions.

[[source_package]]
Source package
~~~~~~~~~~~~~~

WeeChat can be compiled with cmake or autotools (cmake is recommended way).

[[dependencies]]
Dependencies
^^^^^^^^^^^^

Following table shows list of packages that are required or optional to
compile WeeChat.

[width="80%",cols="4,^2,13",options="header"]
|========================================
| Package ^(1)^          | Required | Feature
| cmake                  | *yes*    | build (autotools still possible, but cmake is recommended)
| libncursesw5-dev ^(2)^ | *yes*    | ncurses interface
| libgcrypt11-dev        | no       | SASL authentication with IRC server using DH-BLOWFISH mechanism
| libgnutls-dev          | no       | SSL connection to IRC server
| libaspell-dev          | no       | aspell plugin
| libperl-dev            | no       | perl plugin
| python-dev             | no       | python plugin
| ruby1.8-dev            | no       | ruby plugin
| liblua5.1-0-dev        | no       | lua plugin
| tcl-dev (>= 8.5)       | no       | tcl plugin
| asciidoc (>= 8.2)      | no       | build documentation (HTML files)
| source-highlight       | no       | syntax highlight for sources in HTML documentation
|========================================

[NOTE]
^(1)^ Name comes from the Debian GNU/Linux distribution, versions and package
names may be different in different distributions and versions. +
^(2)^ WeeChat can compile with libncurses5-dev, but it is *NOT* recommended (you
will have display bugs with wide chars).

[[compile_with_cmake]]
Compile with cmake
^^^^^^^^^^^^^^^^^^

* Installation in system directories (requires 'root' privileges):

----------------------------------------
$ mkdir build
$ cd build
$ cmake ..
$ make
% make install    (as root)
----------------------------------------

* Installation in custom directory:

----------------------------------------
$ mkdir build
$ cd build
$ cmake .. -DPREFIX=/path/to/directory
$ make
$ make install
----------------------------------------

[[compile_with_autotools]]
Compile with autotools
^^^^^^^^^^^^^^^^^^^^^^

* Installation in system directories (requires 'root' privileges):

----------------------------------------
$ ./configure
$ make
% make install    (as root)
----------------------------------------

* Installation in custom directory:

----------------------------------------
$ ./configure --prefix=/path/to/directory
$ make
$ make install
----------------------------------------

[[git_sources]]
Git sources
~~~~~~~~~~~

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

To get GIT sources, issue this command:

----------------------------------------
$ git clone git://git.sv.gnu.org/weechat.git
----------------------------------------

If you're using autotools (and not cmake), execute this script:

----------------------------------------
$ ./autogen.sh
----------------------------------------

Then follow instructions for source package (see
<<source_package,source package>>).

[[report_crashes]]
Report crashes
~~~~~~~~~~~~~~

If you experienced crashes, or if you want to report any future WeeChat crash,
you have to:

* compile it with debug info (or install binary package with debug info)
* enable 'core' files on your system
* install gdb

[[debug_info]]
Debug info
^^^^^^^^^^

If you're compiling with cmake:

----------------------------------------
$ cmake .. -DCMAKE_BUILD_TYPE=Debug
----------------------------------------

If you're compiling with autotools, debug is default (`--with-debug=1`).

If you installed a binary package, then install package 'weechat-dbg'.

[[core_files]]
Core files
^^^^^^^^^^

To enable 'core' files, you have to use `ulimit` command.

For example under Linux with 'bash' shell, add this line to your `~/.bashrc`:

----------------------------------------
ulimit -c unlimited
----------------------------------------

Or max size:

----------------------------------------
ulimit -c 200000
----------------------------------------

[[gdb_backtrace]]
Get backtrace with gdb
^^^^^^^^^^^^^^^^^^^^^^

When WeeChat crashes, your system will create a file 'core' or 'core.12345'
('12345' is process id).
This file is created in directory where you have run WeeChat (this is *not*
directory where WeeChat is installed!).

For example if 'weechat-curses' is installed in '/usr/bin/' and 'core' file is
in '/home/xxx/', then run gdb with this command:

----------------------------------------
gdb /usr/bin/weechat-curses /home/xxx/core
----------------------------------------

[NOTE]
If you installed binary package 'weechat-dbg' (for example under Debian), then
you can use this path for WeeChat binary: '/usr/lib/debug/usr/bin/weechat-curses'

Then under gdb, use command `bt full` to display backtrace.
You will see something like that:

----------------------------------------
(gdb) bt full
#0  0x00007f9dfb04a465 in raise () from /lib/libc.so.6
#1  0x00007f9dfb04b8e6 in abort () from /lib/libc.so.6
#2  0x0000000000437f66 in weechat_shutdown (return_code=1, crash=1) at /some_path/src/core/weechat.c:351
#3  <signal handler called>
#4  0x000000000044cb24 in hook_process_timer_cb (arg_hook_process=0x254eb90, remaining_calls=<value optimized out>)
    at /some_path/src/core/wee-hook.c:1364
        hook_process = 0x254eb90
        status = <value optimized out>
#5  0x000000000044cc7d in hook_timer_exec () at /some_path/src/core/wee-hook.c:1025
        tv_time = {tv_sec = 1272693881, tv_usec = 212665}
        ptr_hook = 0x2811f40
        next_hook = 0x0
#6  0x000000000041b5b0 in gui_main_loop () at /some_path/src/gui/curses/gui-curses-main.c:319
        hook_fd_keyboard = 0x173b600
        tv_timeout = {tv_sec = 0, tv_usec = 0}
        read_fds = {fds_bits = {0 <repeats 16 times>}}
        write_fds = {fds_bits = {0 <repeats 16 times>}}
        except_fds = {fds_bits = {0 <repeats 16 times>}}
        max_fd = <value optimized out>
----------------------------------------

You must report this trace to developers, and tell them what action caused this
crash.

Thank you for your help!


[[usage]]
Usage
-----

[[running_weechat]]
Running WeeChat
~~~~~~~~~~~~~~~

Command line arguments:

-a, --no-connect::
    Disable auto-connect to servers when WeeChat is starting

-d, --dir 'path'::
    Set path as home for WeeChat (used for configuration files, logs, user
    plugins and scripts), default value is '~/.weechat' (note: directory is
    created if not found by WeeChat)

-h, --help::
    Display help

-k, --keys::
    Display WeeChat default keys

-l, --license::
    Display WeeChat license

-p, --no-plugin::
    Disable plugins auto-load

-s, --no-script::
    Disable scripts auto-load

-v, --version::
    Display WeeChat version

plugin:option::
    Option for plugin (see doc for each plugin)

To start WeeChat, issue this command:

----------------------------------------
$ weechat-curses
----------------------------------------

When you run WeeChat for the first time, a default configuration file is
created, with default options. The default configuration file is:
'~/.weechat/weechat.conf'.

You can edit this file at your convenience to configure WeeChat or you can set
parameters with `/set` command in WeeChat (see
<<weechat_commands,WeeChat commands>>).

[[screen_layout]]
Screen layout
~~~~~~~~~~~~~

Example of terminal with WeeChat:

........................................
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│Welcome to #test, this is a test channel                                                 │
│12:52:27    --> | flashy (n=flashcod@hellix.flashtux.org) has joined #test    │@ChanServ │
│12:52:27     -- | Nicks #test: [@ChanServ @flashy +_FlashB0t joe mike]        │@flashy   │
│12:52:27     -- | Channel #test: 5 nicks (2 ops, 0 halfop, 1 voice, 2 normal) │+_FlashB0t│
│12:52:27     -- | Channel created on Tue Jan 27 06:30:17 2009                 │joe       │
│12:54:15 flashy | hey!                                                        │mike      │
│12:55:01    joe | hi flashy!                                                  │          │
│                                                                              │          │
│                                                                              │          │
│                                                                              │          │
│                                                                              │          │
│                                                                              │          │
│                                                                              │          │
│                                                                              │          │
│                                                                              │          │
│                                                                              │          │
│                                                                              │          │
│                                                                              │          │
│                                                                              │          │
│                                                                              │          │
│[12:55] [4] [irc/freenode] 3:#test(+n){5}* [Act: 4,2]                                    │
│[flashy] hi joe!█                                                                        │
└─────────────────────────────────────────────────────────────────────────────────────────┘
........................................

Screen is composed by following areas:

* chat area (middle of screen) with chat lines, and for each line:
** time
** prefix (before "|")
** message (after "|")
* bars around chat area, default bars are:
** 'title' bar, above chat area
** 'status' bar, below chat area
** 'input' bar, below status bar
** 'nicklist' bar, on the right

Bar 'status' has following default items:

[width="100%",cols="^3,^3l,10",options="header"]
|========================================
| Item                  | Example        | Description

| time                  | [12:55]        |
  time

| buffer_count          | [4]            |
  number of opened buffers

| buffer_plugin         | [irc/freenode] |
  plugin of current buffer (irc plugin can add IRC server name used by buffer)

| buffer_number         | 3              |
  current buffer number

| buffer_name           | #test(+n)      |
  current buffer name

| buffer_nicklist_count | {5}            |
  number of nicks in nicklist

| buffer_filter         | *              |
  filtering indicator: `*` means some lines are filtered (hidden), empty value
  means all lines are displayed

| lag                   | [Lag: 2.5]     |
  lag indicator, in seconds (hidden if lag is low)

| hotlist               | [Act: 4,2]     |
  list of buffers with activity (unread messages)

| completion            | abc(2) def(5)  |
  list of words for completion, with number of possible completions for each
  word

| scroll                | -MORE(50)-     |
  scroll indicator, with number of lines below last line displayed
|========================================

Bar 'input' has following default items:

[width="100%",cols="^3,^6m,8",options="header"]
|========================================
| Item             | Example | Description

| input_paste      | [Paste 7 lines ? [ctrl-Y] Yes [ctrl-N] No] |
  question to user for pasting lines

| input_prompt     | [nick] |
  input prompt (nick for irc plugin)

| away             | (away) |
  away indicator

| input_search     | [Text search] |
  text search indicator

| input_text       | bla bla... |
  input text
|========================================

[[key_bindings]]
Default key bindings
~~~~~~~~~~~~~~~~~~~~

[[key_bindings_command_line]]
Keys for command line
^^^^^^^^^^^^^^^^^^^^^

[width="100%",cols="^.^4,.^15",options="header"]
|========================================
| Keys | Description and command

| Left arrow +
  Ctrl + `b` |
  Go to previous char in command line +
  `/input move_previous_char`

| Right arrow +
  Ctrl + `f` |
  Go to next char in command line +
  `/input move_next_char`

| Ctrl + left arrow +
  Alt + `b` |
  Go to previous word in command line +
  `/input move_previous_word`

| Ctrl + right arrow +
  Alt + `f` |
  Go to next word in command line +
  `/input move_next_word`

| Home +
  Ctrl + `a` |
  Go to the beginning of command line +
  `/input move_beginning_of_line`

| End +
  Ctrl + `e` |
  Go to the end of command line +
  `/input move_end_of_line`

| Ctrl + `c` then `b` |
  Insert code for bold text +
  `/input insert \x02`

| Ctrl + `c` then `c` |
  Insert code for colored text +
  `/input insert \x03`

| Ctrl + `c` then `i` |
  Insert code for italic text +
  `/input insert \x1D`

| Ctrl + `c` then `o` |
  Insert code for color reset +
  `/input insert \x0F`

| Ctrl + `c` then `r` |
  Insert code for reverse color +
  `/input insert \x12`

| Ctrl + `c` then `u` |
  Insert code for underlined text +
  `/input insert \x15`

| Delete +
  Ctrl + `d` |
  Delete next char in command line +
  `/input delete_next_char`

| Backspace +
  Ctrl + `h` |
  Delete previous char in command line +
  `/input delete_previous_char`

| Ctrl + `k` |
  Delete from cursor until end of command line (deleted string is copied to
  clipboard) +
  `/input delete_end_of_line`

| Ctrl + `r` |
  Search for text in buffer history (two times: search exact text),
  next/previous occurrences can be found with up and down arrows +
  `/input search_text`

| Ctrl + `t` |
  Transpose chars +
  `/input transpose_chars`

| Ctrl + `u` |
  Delete from cursor until beginning of command line (deleted string is copied
  to clipboard) +
  `/input delete_beginning_of_line`

| Ctrl + `w` |
  Delete previous word of command line (deleted string is copied to clipboard) +
  `/input delete_previous_word`

| Ctrl + `y` |
  Paste clipboard content +
  `/input clipboard_paste`

| Ctrl + `_` |
  Undo last action on command line +
  `/input undo`

| Alt + `_` |
  Redo last action on command line +
  `/input redo`

| Tab |
  Complete command or nick (Tab again: find next completion) +
  `/input complete_next`

| Shift + Tab |
  Without completion: do a partial completion, with pending completion:
  complete with previous completion +
  `/input complete_previous`

| Any char |
  Insert char at cursor position in command line

| Enter +
  Ctrl + `j` +
  Ctrl + `m` |
  Execute command or send message (in search mode: stop search) +
  `/input return`

| Up arrow |
  Call previous command/message (in search mode: search up) +
  `/input history_previous`

| Down arrow |
  Call next command/message (in search mode: search down) +
  `/input history_next`

| Ctrl + up arrow |
  Call previous command/message in global history (common for all buffers) +
  `/input history_global_previous`

| Ctrl + down arrow |
  Call next command/message in global history (common for all buffers) +
  `/input history_global_next`

| Alt + `d` |
  Delete next word in command line (deleted string is copied to clipboard) +
  `/input delete_next_word`

| Alt + `k` |
  Grab a key and insert its code (and command bound if key exists) in command
  line +
  `/input grab_key_command`

| Alt + `r` |
  Delete entire command line +
  `/input delete_line`
|========================================

[[key_bindings_buffers_windows]]
Keys for buffers / windows
^^^^^^^^^^^^^^^^^^^^^^^^^^

[width="100%",cols="^.^4,.^15",options="header"]
|========================================
| Keys | Description and command

| Ctrl + `l` |
  Redraw whole window +
  `/window refresh`

| Ctrl + `s` then Ctrl + `u` |
  Set unread marker on all buffers +
  `/input set_unread`

| Ctrl + `x` |
  Switch current buffer if buffers are attached with same number +
  `/input switch_active_buffer`

| Page up |
  Scroll up one page in buffer history +
  `/window page_up`

| Page down |
  Scroll down one page in buffer history +
  `/window page_down`

| Alt + Page up |
  Scroll up a few lines in buffer history +
  `/window scroll_up`

| Alt + Page down |
  Scroll down a few lines in buffer history +
  `/window scroll_down`

| Alt + Home |
  Scroll to top of buffer +
  `/window scroll_top`

| Alt + End |
  Scroll to bottom of buffer +
  `/window scroll_bottom`

| Alt + left arrow +
  Alt + up arrow +
  Ctrl + `p` +
  F5 |
  Switch to previous buffer +
  `/buffer -1`

| Alt + right arrow +
  Alt + down arrow +
  Ctrl + `n` +
  F6 |
  Switch to next buffer +
  `/buffer +1`

| F7 |
  Switch to previous window +
  `/window -1`

| F8 |
  Switch to next window +
  `/window +1`

| F9 |
  Scroll buffer's title on the left +
  `/bar scroll title * x-50%`

| F10 |
  Scroll buffer's title on the right +
  `/bar scroll title * x+50%`

| F11 |
  Scroll up one page in nicklist +
  `/bar scroll nicklist * y-100%`

| F12 |
  Scroll down one page in nicklist +
  `/bar scroll nicklist * y+100%`

| Alt + F11 |
  Go to the beginning of nicklist +
  `/bar scroll nicklist * yb`

| Alt + F12 |
  Go to the end of nicklist +
  `/bar scroll nicklist * ye`

| Alt + `a` |
  Switch to next buffer with activity (with priority: highlight, message,
  other) +
  `/input jump_smart`

| Alt + `j` then Alt + `l` |
  Switch to last buffer +
  `/input jump_last_buffer`

| Alt + `j` then Alt + `r` |
  Switch to IRC raw buffer +
  `/server raw`

| Alt + `j` then Alt + `s` |
  Switch to IRC server buffer +
  `/server jump`

| Alt + digit (0-9) |
  Switch to buffer by number (0 = 10) +
  `/buffer *N`

| Alt + `j` then number (01-99) |
  Switch to buffer by number +
  `/buffer NN`

| Alt + `n` |
  Scroll to next highlight +
  `/window scroll_next_highlight`

| Alt + `p` |
  Scroll to previous highlight +
  `/window scroll_previous_highlight`

| Alt + `u` |
  Scroll to first unread line in buffer +
  `/input scroll_unread`

| Alt + `w` then Alt + arrow |
  Switch to window with direction +
  `/window up` +
  `/window down` +
  `/window left` +
  `/window right`

| Alt + `z` |
  Zoom on current window (Alt + Z again: restore initial windows state, before
  zoom) +
  `/window zoom`

| Alt + `<` |
  Switch to previous buffer in list of visited buffers +
  `/input jump_previously_visited_buffer`

| Alt + `>` |
  Switch to next buffer in list of visited buffers +
  `/input jump_next_visited_buffer`
|========================================

[[key_bindings_other]]
Other keys
^^^^^^^^^^

[width="100%",cols="^.^4,.^15",options="header"]
|========================================
| Keys | Description and command

| Alt + `h` |
  Clear hotlist (activity notification on other buffers) +
  `/input hotlist_clear` +

| Alt + `=` |
  Toggle filters on/off +
  `/filter toggle` +
|========================================

[[command_line]]
Command line
~~~~~~~~~~~~

WeeChat command line (at the bottom of window) lets you execute commands or
send text to buffer.

[[command_line_syntax]]
Syntax
^^^^^^

Commands begin with "/" char, followed by name of command. For example, to see
list of all options:

----------------------------------------
/set
----------------------------------------

Text sent to a buffer is any text that does not begin with "/" char.
For example, to send text 'hello' on current buffer:

----------------------------------------
hello
----------------------------------------

However, it is possible to start with "/" char, by adding another.
For example, to send text '/set' on current buffer:

----------------------------------------
//set
----------------------------------------

[[command_line_colors]]
Colors
^^^^^^

For some plugins like IRC, you can use color codes and attributes, as
follow (press Ctrl-C then following letter, with optional value):

^Cb::
    bold text

^Ccxx::
    text color `xx` (see list of colors below)

^Ccxx,yy::
    text color `xx` and background `yy` (see list of colors below)

^Co::
    disable color and attributes

^Cr::
    reverse video (revert text color with background)

^Cu::
    underlined text

[NOTE]
The same code (without number for ^Cc) may be used to stop the
attribute.

Color codes for ^Cc are:

[width="35%",cols="^1m,3,3",options="header"]
|========================================
| Code | IRC           | WeeChat (curses)
| 00   | white         | white
| 01   | black         | black
| 02   | dark blue     | blue
| 03   | dark green    | green
| 04   | light red     | lightred
| 05   | dark red      | red
| 06   | magenta       | magenta
| 07   | orange        | brown
| 08   | yellow        | yellow
| 09   | light green   | lightgreen
| 10   | cyan          | cyan
| 11   | light cyan    | lightcyan
| 12   | light blue    | lightblue
| 13   | light magenta | lightmagenta
| 14   | gray          | default
| 15   | light gray    | white
|========================================

Example: display of "hello everybody!" with "hello" in light blue bold and
"everybody" in light red underlined:

----------------------------------------
^Cc12^Cbhello^Cb^Cc04^Cu everybody^Cu^Cc!
----------------------------------------

[[weechat_options]]
WeeChat options (weechat.conf)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

include::autogen/user/weechat_options.txt[]

[[curses_colors]]
Colors for Curses GUI
^^^^^^^^^^^^^^^^^^^^^

[width="50%",cols="^3m,8"]
|========================================
| default      | default terminal color (transparent for background)
| black        | black
| darkgray     | dark gray
| 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
| white        | white
|========================================

[[weechat_commands]]
WeeChat commands
~~~~~~~~~~~~~~~~

include::autogen/user/weechat_commands.txt[]


[[plugins]]
Plugins
-------

To learn more about plugin or script development (through API), please read
'WeeChat Plugin API Reference' or 'WeeChat Scripting Guide'.

[[plugins_in_weechat]]
Plugins in WeeChat
~~~~~~~~~~~~~~~~~~

A plugin is dynamic library, written in C and compiled, which is loaded by
WeeChat.
Under GNU/Linux, the file has ".so" extension, ".dll" under Windows.

Plugins found are automatically loaded when WeeChat is starting, and it is
possible to load or unload plugins while WeeChat is running.

It's important to make difference between a 'plugin' and a 'script': a
'plugin' is a binary file compiled and loaded with command `/plugin`, whereas
a 'script' is a text file loaded with a plugin like 'perl' with command
`/perl`.

You can use command `/plugin` to load/unload a plugin, or list all loaded
plugins.
When a plugin is unloaded, all buffers created by this plugin are
automatically closed.

Examples to load, unload or list plugins:

----------------------------------------
/plugin load irc
/plugin unload irc
/plugin list
----------------------------------------

Default plugins are:

[width="50%",cols="^1,5",options="header"]
|========================================
| Plugin    | Description
| alias     | Define alias for commands
| aspell    | Spell checking for command line
| charset   | Charset decoding/encoding for buffers
| demo      | Demo plugin (not compiled by default)
| fifo      | FIFO pipe used to remotely send commands to WeeChat
| irc       | IRC chat protocol
| logger    | Log buffers to files
| rmodifier | Alter modifier strings with regular expressions
| perl      | Perl scripting API
| python    | Python scripting API
| ruby      | Ruby scripting API
| lua       | Lua scripting API
| tcl       | Tcl scripting API
| xfer      | File transfer and direct chat
|========================================

[[alias_plugin]]
Alias plugin
~~~~~~~~~~~~

Alias plugin lets you create alias for commands (from WeeChat or other
plugins).

[[alias_commands]]
Commands
^^^^^^^^

include::autogen/user/alias_commands.txt[]

[[aspell_plugin]]
Aspell plugin
~~~~~~~~~~~~

Aspell plugin lets you check spelling in command line. It is possible to use
many languages by buffer.

[[aspell_options]]
Options (aspell.conf)
^^^^^^^^^^^^^^^^^^^^^

include::autogen/user/aspell_options.txt[]

[[aspell_commands]]
Commands
^^^^^^^^

include::autogen/user/aspell_commands.txt[]

[[charset_plugin]]
Charset plugin
~~~~~~~~~~~~~~

Charset plugin lets you decode or encode data using charsets.

There is default charset for decode/encode, and specific charsets for buffers
(or group of buffers).

This plugin is optional, but recommended: if it's not loaded, WeeChat
can only read/write UTF-8 data.

Charset plugin should be autoloaded by WeeChat. To be sure plugin is loaded,
try:

----------------------------------------
/charset
----------------------------------------

If command is not found, then load plugin with command:

----------------------------------------
/plugin load charset
----------------------------------------

If plugin is not found, then you should compile again WeeChat with
plugins and Charset support.

When Charset plugin starts, it displays terminal and internal charsets.
Terminal charset depends on your locale, and internal is UTF-8.

For example:

........................................
charset: terminal: ISO-8859-15, internal: UTF-8
........................................

[[charset_options]]
Options (charset.conf)
^^^^^^^^^^^^^^^^^^^^^^

include::autogen/user/charset_options.txt[]

[[charset_commands]]
Commands
^^^^^^^^

include::autogen/user/charset_commands.txt[]

[[charset_set]]
Set charset
^^^^^^^^^^^

To set global decode and encode charsets, use command `/set`.

For example:

----------------------------------------
/set charset.default.decode ISO-8859-15
/set charset.default.encode ISO-8859-15
----------------------------------------

If global decode charset is not set (for example during first
load of Charset plugin), it will be automatically set to terminal
charset (if it's different from UTF-8), or by default to 'ISO-8859-1'.

Default encode value is empty, so it sends by default with
internal charset (UTF-8).

To set IRC server charset, use command `/charset` on server buffer.
If you give only charset, then it will set decoding and encoding values.

For example:

----------------------------------------
/charset ISO-8859-15
----------------------------------------

It's equivalent to:

----------------------------------------
/charset decode ISO-8859-15
/charset encode ISO-8859-15
----------------------------------------

To set IRC channel (or private) charset, use same commands as server,
but on channel (or private) buffer.

To see all charsets used, use following command:

----------------------------------------
/set charset.*
----------------------------------------

[[charset_troubleshooting]]
Troubleshooting
^^^^^^^^^^^^^^^

For any problem with charsets, please look at 'WeeChat FAQ'.

[[fifo_plugin]]
Fifo plugin
~~~~~~~~~~~

You can remote control WeeChat, by sending commands or text to a FIFO pipe (if
option "plugins.var.fifo.fifo" is enabled, it is by default).

The FIFO pipe is located in '~/.weechat/' and is called 'weechat_fifo_xxxx'
(where 'xxxx' is the process ID (PID) of running WeeChat).

Syntax for the FIFO pipe commands/text is one of following:

........................................
  plugin.buffer *text or command here
  *text or command here
........................................

Some examples:

* nick change on IRC server freenode to "newnick":

----------------------------------------
$ echo 'irc.server.freenode */nick newnick' >~/.weechat/weechat_fifo_12345
----------------------------------------

* display text on IRC #weechat channel:

----------------------------------------
$ echo 'irc.freenode.#weechat *hello!' >~/.weechat/weechat_fifo_12345
----------------------------------------

* display text on current buffer:

----------------------------------------
$ echo '*hello!' >~/.weechat/weechat_fifo_12345
----------------------------------------

* send two commands to unload/reload Perl scripts (you have to separate them
  with "\n"):

----------------------------------------
$ echo -e '*/perl unload\n*/perl autoload' >~/.weechat/weechat_fifo_12345
----------------------------------------

You can write a script to send command to all running WeeChat at same time,
for example:

[source,shell]
----------------------------------------
#!/bin/sh
if [ $# -eq 1 ]; then
    for fifo in ~/.weechat/weechat_fifo_*
    do
        echo -e "$1" >$fifo
    done
fi
----------------------------------------

If the script is called "auto_weechat_command", you can run it with:

----------------------------------------
$ ./auto_weechat_command 'irc.freenode.#weechat *hello'
----------------------------------------

[[irc_plugin]]
IRC plugin
~~~~~~~~~~

The IRC plugin is designed to chat through IRC protocol with other people.

It is multi-servers, and offers all supported IRC commands including DCC chat
and file transfer (via xfer plugin, see <<xfer_plugin,Xfer plugin>>).

[[irc_command_line_options]]
Command line options
^^^^^^^^^^^^^^^^^^^^

It is possible to give URL for one or many IRC servers, as follow:

----------------------------------------
irc[6][s]://[pseudo[:mot_passe]@]irc.example.org[:port][/channel][,channel[...]
----------------------------------------

Example to join '#weechat' and '#toto' on server 'irc.freenode.net' server,
default port (6667), with nick 'nono':

----------------------------------------
$ weechat-curses irc://nono@irc.freenode.net/#weechat,#toto
----------------------------------------

[[irc_options]]
Options (irc.conf)
^^^^^^^^^^^^^^^^^^

include::autogen/user/irc_options.txt[]

[[irc_commands]]
Commands
^^^^^^^^

include::autogen/user/irc_commands.txt[]

[[irc_ssl_certificates]]
SSL certificates
^^^^^^^^^^^^^^^^

When connecting to IRC server with SSL, WeeChat checks by default that the
connection is fully trusted.

Some options are used to control SSL connection:

weechat.network.gnutls_ca_file::
    path to file with certificate authorities (by default: "%h/ssl/CAs.pem")

irc.server.xxx.ssl_cert::
    SSL certificate file used to automatically identify your nick (for example
    CertFP on oftc, see below)

irc.server.xxx.ssl_dhkey_size::
    size of the key used during the Diffie-Hellman Key Exchange (by default:
    2048)

irc.server.xxx.ssl_verify::
    check that the SSL connection is fully trusted (on by default)

[NOTE]
Option "ssl_verify" is on by default, so verification is strict and may fail,
even if it was ok with versions prior to 0.3.1.

[[irc_connect_oftc_with_certificate]]
First example: connect to oftc and check certificate
++++++++++++++++++++++++++++++++++++++++++++++++++++

* Import certificate in shell:

----------------------------------------
$ mkdir ~/.weechat/ssl
$ wget -O ~/.weechat/ssl/CAs.pem http://www.spi-inc.org/secretary/spi-cacert.crt
----------------------------------------

Note: it is possible to concatenate many certificates in file CAs.pem.

* In WeeChat, with "oftc" server already created:

----------------------------------------
/connect oftc
----------------------------------------

[[irc_connect_oftc_with_certfp]]
Second example: connect to oftc using CertFP
++++++++++++++++++++++++++++++++++++++++++++

* Create certificate in shell:

----------------------------------------
$ openssl req -nodes -newkey rsa:2048 -keyout nick.key -x509 -days 365 -out nick.cer
$ cat nick.cer nick.key > ~/.weechat/ssl/nick.pem
----------------------------------------

* In WeeChat, with "oftc" server already created:

----------------------------------------
/set irc.server.oftc.ssl_cert "%h/ssl/nick.pem"
/connect oftc
/msg nickserv cert add
----------------------------------------

For more information, look at http://www.oftc.net/oftc/NickServ/CertFP

[[irc_smart_filter_join_part_quit]]
Smart filter for join/part/quit messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A smart filter is available to filter join/part/quit messages when nick did not
say something during past X minutes on channel.

Smart filter is enabled by default, but you must add a filter to hide lines on
buffers, for example:

----------------------------------------
/filter add irc_smart * irc_smart_filter *
----------------------------------------

It is possible to create filter for one channel only or channels beginning with
same name (see `/help filter`):

----------------------------------------
/filter add irc_smart_weechat irc.freenode.#weechat irc_smart_filter *
/filter add irc_smart_weechats irc.freenode.#weechat* irc_smart_filter *
----------------------------------------

You can hide only join or part/quit with following options:

----------------------------------------
/set irc.look.smart_filter_join on
/set irc.look.smart_filter_quit on
----------------------------------------

You can setup delay (in minutes):

----------------------------------------
/set irc.look.smart_filter_delay 5
----------------------------------------

If a nick did not speak during last 5 minutes, its join and/or part/quit will be
hidden on channel.

[[irc_ctcp_replies]]
CTCP replies
^^^^^^^^^^^^

It is possible to customize CTCP replies, or block some CTCP queries (do not
reply).

For example, to customize reply to CTCP "VERSION", use following command:

----------------------------------------
/set irc.ctcp.version "I'm running WeeChat $version, it rocks!"
----------------------------------------

If you want to block CTCP "VERSION" (do not reply to a query), then set empty
string:

----------------------------------------
/set irc.ctcp.version ""
----------------------------------------

Even unknown CTCP can be customized, for example you can reply to
CTCP "BLABLA":

----------------------------------------
/set irc.ctcp.blabla "This is my answer to CTCP BLABLA"
----------------------------------------

It is possible to customize CTCP for one server only, using its internal name
before CTCP name:

----------------------------------------
/set irc.ctcp.freenode.version "WeeChat $version (for freenode)"
----------------------------------------

If you want to restore standard CTCP reply, then remove option:

----------------------------------------
/unset irc.ctcp.version
----------------------------------------

Following codes can be used in strings and are automatically expanded by WeeChat
when replying to CTCP:

[width="100%",cols="^2l,4,8l",options="header"]
|========================================
| Code         | Description                 | Value/example
| $clientinfo  | list of supported CTCP      | ACTION DCC CLIENTINFO FINGER PING SOURCE TIME USERINFO VERSION
| $version     | WeeChat version             | 0.3.0
| $compilation | WeeChat compilation date    | Sep 13 2009
| $osinfo      | info about OS               | Linux 2.6.31 / i686
| $site        | WeeChat site                | http://www.weechat.org
| $download    | WeeChat site, download page | http://www.weechat.org/download
| $time        | current date/time           | Sun Sep 13 15:48:31 2009
| $username    | username on IRC server      | nick
| $realname    | realname on IRC server      | My name
|========================================

If CTCP options are not defined (by default), CTCP replies are:

[width="100%",cols="^2,4l,8l",options="header"]
|========================================
| CTCP         | Reply format                    | Example
| CLIENTINFO   | $clientinfo                     | ACTION DCC CLIENTINFO FINGER PING SOURCE TIME USERINFO VERSION
| FINGER       | WeeChat $version                | WeeChat 0.3.0
| SOURCE       | $download                       | http://www.weechat.org/download
| TIME         | $time                           | Sun Sep 13 15:48:31 2009
| USERINFO     | $username ($realname)           | nick (My name)
| VERSION      | WeeChat $version ($compilation) | WeeChat 0.3.0 (Sep 13 2009)
|========================================

[[irc_target_buffer]]
Target buffer for IRC messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It is possible to customize target buffer for IRC messages (buffer used to
display message) with options `irc.msgbuffer.*`.

For some IRC messages (see list below), you can use value:

current::
    current buffer (if it's IRC buffer, or on server buffer by default)

private::
    private buffer for nick, or current/server buffer if not found (according
    to option 'irc.look.msgbuffer_fallback')

weechat::
    WeeChat "core" buffer

Default is server buffer (when option is not set).

Non-exhaustive list of IRC messages or alias that you can customize:

[width="50%",cols="^1m,^1m,3",options="header"]
|========================================
| message | alias  | description
| invite  |        | invited on a channel
| notice  |        | notice
| wallops |        | wallops
| 221     |        | user mode string
| 275     | whois  | whois (secure connection)
| 301     | whois  | whois (away)
| 303     |        | ison
| 305     | unaway | unaway
| 306     | away   | away
| 307     | whois  | whois (registered nick)
| 310     | whois  | whois (help mode)
| 311     | whois  | whois (user)
| 312     | whois  | whois (server)
| 313     | whois  | whois (operator)
| 314     | whowas | whowas
| 315     | who    | who (end)
| 317     | whois  | whois (idle)
| 318     | whois  | whois (end)
| 319     | whois  | whois (channels)
| 320     | whois  | whois (identified user)
| 321     | list   | list (start)
| 322     | list   | list (channel)
| 323     | list   | list (end)
| 326     | whois  | whois (has oper privs)
| 327     | whois  | whois (host)
| 330     | whois  | whois (logged in as)
| 335     | whois  | whois (is a bot on)
| 338     | whois  | whois (host)
| 341     |        | inviting
| 344     | reop   | channel reop
| 345     | reop   | channel reop (end)
| 351     |        | server version
| 352     | who    | who
| 369     | whowas | whowas (end)
| 378     | whois  | whois (connecting from)
| 379     | whois  | whois (using modes)
| 432     |        | erroneous nickname
| 433     |        | nickname already in use
| 438     |        | not authorized to change nickname
| 671     | whois  | whois (secure connection)
| 901     |        | you are now logged in
|========================================

Other numeric commands can be customized as well.

Message can be prefixed by server name to be specific to an irc server
(for example: `freenode.whois`).

Some examples:

* display result of `/whois` on private buffer:

----------------------------------------
/set irc.msgbuffer.whois private
----------------------------------------

* restore default buffer for whois (server buffer):

----------------------------------------
/unset irc.msgbuffer.whois
----------------------------------------

* display invitation on current buffer, only for "freenode" server:

----------------------------------------
/set irc.msgbuffer.freenode.invite current
----------------------------------------

* display message "303" (ison) on WeeChat "core" buffer:

----------------------------------------
/set irc.msgbuffer.303 weechat
----------------------------------------

[[logger_plugin]]
Logger plugin
~~~~~~~~~~~~~

The Logger plugin lets you save content of buffers to files, with options
about what and how it is saved.

[[logger_options]]
Options (logger.conf)
^^^^^^^^^^^^^^^^^^^^^

include::autogen/user/logger_options.txt[]

[[logger_commands]]
Commands
^^^^^^^^

include::autogen/user/logger_commands.txt[]

[[logger_log_levels]]
Log levels
^^^^^^^^^^

Logging is made with a level for each buffer. Default level is 9 (log
all messages displayed on buffer).
You can change level for one buffer, or a group of buffers.

Possible levels are 0 to 9. Zero means "do not log anything" and 9 means
"log all messages".

Plugins are using different levels for messages displayed.
IRC plugin uses following levels:

* level 1: message from user (on channel or private)
* level 2: nick change (you or someone else)
* level 3: any server message (except join/part/quit)
* level 4: server message join/part/quit

So if you set level 3 for an IRC channel, WeeChat will log all messages,
but not join/part/quit.

Some examples:

* set level 3 for IRC channel #weechat:

----------------------------------------
/set logger.level.irc.freenode.#weechat 3
----------------------------------------

* set level 3 for freenode server buffer:

----------------------------------------
/set logger.level.irc.server.freenode 3
----------------------------------------

* set level 3 for all channels on server freenode:

----------------------------------------
/set logger.level.irc.freenode 3
----------------------------------------

* set level 2 for all IRC buffers:

----------------------------------------
/set logger.level.irc 2
----------------------------------------

[[logger_filenames_masks]]
Filenames masks
^^^^^^^^^^^^^^^

It is possible to define a filename mask for each buffer, and use local buffer
variables to build filename. To see local variables for current buffer:

----------------------------------------
/buffer localvar
----------------------------------------

For example if you want one directory by IRC server and one file by channel
inside:

----------------------------------------
/set logger.mask.irc "irc/$server/$channel.weechatlog"
----------------------------------------

You'll have following files:

........................................
~/.weechat/
    |--- logs/
        |--- irc/
            |--- freenode/
            |       freenode.weechatlog
            |       #weechat.weechatlog
            |       #mychan.weechatlog
            |--- oftc/
            |       oftc.weechatlog
            |       #chan1.weechatlog
            |       #chan2.weechatlog
........................................

[[rmodifier_plugin]]
Rmodifier plugin
~~~~~~~~~~~~~~~~

The Rmodifier plugin lets you alter modifier strings using regular expressions.
Typical use is to hide password when you type them, or when WeeChat saves
them in command history. For example, it is possible to replace each char in
these passwords by "*".

[[rmodifier_options]]
Options (rmodifier.conf)
^^^^^^^^^^^^^^^^^^^^^^^^

include::autogen/user/rmodifier_options.txt[]

[[rmodifier_commands]]
Commands
^^^^^^^^

include::autogen/user/rmodifier_commands.txt[]

[[rmodifier_creation]]
Rmodifier creation
^^^^^^^^^^^^^^^^^^

A rmodifier consists of three elements:

. one or more "modifiers"
. a regular expression, to capture "groups"
. a string that describes output using number of "groups" captured in regular
  expression

For list of modifiers used by WeeChat or plugins, see
'WeeChat Plugin API Reference', function 'weechat_hook_modifier'.

For each captured group, following actions are possible:

* keep group as-is (by using group number)
* replace all chars in group to hide content (group number + "*")
* remove group (if group is not used in string)

Example of default rmodifier for command `/oper`:

* modifiers: `history_add,input_text_display`
** `history_add`: called when WeeChat stores command in history
** `input_text_display`: called when command line has changed
   (applies only on display, not content of command line)
* regular expression: `^(/oper +\S+ +)(.*)`
* groupes: `1,2*`

Each time modifiers "history_add" or "input_text_display" are called, regular
expression is checked. If string matches, then it is replaced by captured groups,
as defined in string with groups.

In this example, we keep number 1 as-is, and we replace all chars of group 2 by
replacement char defined in configuration (option 'rmodifier.look.hide_char').

If command line contains: `/oper nick password` then display becomes:
`/oper nick ********`.

[[scripts_plugins]]
Scripts plugins
~~~~~~~~~~~~~~~

WeeChat provides 5 scripting plugins: Perl, Python, Ruby, Lua and Tcl.
These plugins can load, execute and unload scripts for these languages.

For more information about how to write scripts, or WeeChat API for
scripts, please read 'WeeChat Scripting Guide'.

You can find some scripts for WeeChat here: http://www.weechat.org/scripts

[[perl_commands]]
Perl commands
^^^^^^^^^^^^^

include::autogen/user/perl_commands.txt[]

[[python_commands]]
Python commands
^^^^^^^^^^^^^^^

include::autogen/user/python_commands.txt[]

[[ruby_commands]]
Ruby commands
^^^^^^^^^^^^^

include::autogen/user/ruby_commands.txt[]

[[lua_commands]]
Lua commands
^^^^^^^^^^^^

include::autogen/user/lua_commands.txt[]

[[tcl_commands]]
Tcl commands
^^^^^^^^^^^^

include::autogen/user/tcl_commands.txt[]

[[xfer_plugin]]
Xfer plugin
~~~~~~~~~~~

Xfer plugin brings:

* direct chat (between two hosts, without server): for example "DCC Chat" via
  IRC plugin
* file transfer, for example "DCC" via IRC plugin

[[xfer_options]]
Options (xfer.conf)
^^^^^^^^^^^^^^^^^^^^^

include::autogen/user/xfer_options.txt[]

[[xfer_commands]]
Commands
^^^^^^^^

include::autogen/user/xfer_commands.txt[]


[[authors]]
Authors
-------

[[developers]]
Developers
~~~~~~~~~~

Sébastien Helleu (FlashCode)::
    main developer

[[contributors]]
Contributors
~~~~~~~~~~~~

Emmanuel Bouthenot (kolter)::
    debian packager

Ptitlouis::
    old debian packager

Jiri Golembiovsky::
    czech translation, patches

soltys::
    polish translation

Nils Görs::
rettub::
Frank Zacharias::
    german translation

Pavel Shevchuk::
    russian translation

m4v::
    spanish translation

Voroskoi::
    hungarian translation

Marco Paolone::
    italian translation

Dmitry Kobylin::
    tcl plugin

Rudolf Polzer::
Jim Ramsay::
Pistos::
Gwenn::
Dominik Honnef::
    patches

Odin::
    SuSE RPM


[[support]]
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!).

Ways to get support:

* IRC: server 'irc.freenode.net', channels '#weechat' (english) and
  '#weechat-fr' (french)
* WeeChat forum: http://forums.flashtux.org/
* Mailing list:
** subscribe: http://mail.nongnu.org/mailman/listinfo/weechat-support
** send mail to weechat-support@nongnu.org
** archives: http://mail.nongnu.org/archive/html/weechat-support