diff options
| author | Sébastien Helleu <flashcode@flashtux.org> | 2016-05-15 08:52:19 +0200 |
|---|---|---|
| committer | Sébastien Helleu <flashcode@flashtux.org> | 2016-05-15 08:52:19 +0200 |
| commit | b7bdbbdc505879450494bc75b706e2997e25120f (patch) | |
| tree | be3b6716c2706a9505278d05ae9cfbec5ffbdac5 /doc/en/weechat_user.en.asciidoc | |
| parent | 81fa60a23a29e3bb6525494587008d75eae44f28 (diff) | |
| download | weechat-b7bdbbdc505879450494bc75b706e2997e25120f.zip | |
core: rename .asciidoc files to .adoc (issue #722)
Diffstat (limited to 'doc/en/weechat_user.en.asciidoc')
| -rw-r--r-- | doc/en/weechat_user.en.asciidoc | 3487 |
1 files changed, 0 insertions, 3487 deletions
diff --git a/doc/en/weechat_user.en.asciidoc b/doc/en/weechat_user.en.asciidoc deleted file mode 100644 index 49e297aae..000000000 --- a/doc/en/weechat_user.en.asciidoc +++ /dev/null @@ -1,3487 +0,0 @@ -= WeeChat user's guide -:author: Sébastien Helleu -:email: flashcode@flashtux.org -:lang: en -:toc: left -:toclevels: 4 -:sectnums: -:sectnumlevels: 3 -:docinfo1: - - -This manual documents WeeChat chat client, it is part of WeeChat. - -Latest version of this document can be found on this page: -https://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 and Jabber (with script jabber.py or bitlbee/minbif) -* multi-servers connection (with SSL, IPv6, proxy) -* small, fast and light -* customizable and extensible with plugins and scripts -* compliant with IRC RFCs http://tools.ietf.org/html/rfc1459[1459], - http://tools.ietf.org/html/rfc2810[2810], - http://tools.ietf.org/html/rfc2811[2811], - http://tools.ietf.org/html/rfc2812[2812] and - http://tools.ietf.org/html/rfc2813[2813] -* IRC proxy and relay for remote interfaces -* multi-platform (GNU/Linux, *BSD, MacOS X, Windows and other) -* 100% GPL, free software - -WeeChat homepage is here: https://weechat.org/ - -[[prerequisites]] -=== Prerequisites - -In order to install WeeChat, you need: - -* a running GNU/Linux system (with compiler tools for source - package), or a compatible OS -* _root_ privileges (to install WeeChat in a system directory) -* some libraries (see <<dependencies,dependencies>>). - -[[install]] -== Installation - -[[binary_packages]] -=== Binary packages - -Binary packages are available for many distributions, including: - -* Arch Linux: `pacman -S weechat` -* Cygwin (Windows): select WeeChat packages in setup.exe -* Debian (or any Debian compatible distribution): - `apt-get install weechat-curses` -* Fedora Core: `dnf install weechat` -* Gentoo: `emerge weechat` -* Mandriva/RedHat (or any RPM compatible distribution): - `rpm -i /path/to/weechat-x.y.z-1.i386.rpm` -* openSUSE: `zypper in 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). - -[NOTE] -On OS X, you can use http://brew.sh/[Homebrew]: -`brew install weechat --with-python --with-perl` -(for help: `brew info weechat`). - -[[dependencies]] -==== Dependencies - -Following table shows list of packages that are required or optional to -compile WeeChat. - -[width="100%",cols="5,^3,^3,.^13",options="header"] -|=== -| Package ^(1)^ | Version | Required | Feature -| cmake | | *yes* | Build (autotools still possible, but cmake is recommended) -| pkg-config | | *yes* | Detect installed libraries -| libncursesw5-dev ^(2)^ | | *yes* | Ncurses interface -| libcurl4-gnutls-dev | | *yes* | URL transfer -| zlib1g-dev | | *yes* | Compression of packets in relay plugin (weechat protocol), script plugin -| libgcrypt20-dev | | *yes* | Secured data, IRC SASL authentication (DH-BLOWFISH/DH-AES), script plugin -| libgnutls28-dev | ≥ 2.2.0 ^(3)^ | | SSL connection to IRC server, support of SSL in relay plugin, IRC SASL authentication (ECDSA-NIST256P-CHALLENGE) -| gettext | | | Internationalization (translation of messages; base language is English) -| ca-certificates | | | Certificates for SSL connections -| libaspell-dev - ∥ libenchant-dev | | | Aspell plugin -| python-dev | ≥ 2.5 ^(4)^ | | Python plugin -| libperl-dev | | | Perl plugin -| ruby2.3-dev | ≥ 1.8 | | Ruby plugin -| liblua5.3-dev | | | Lua plugin -| tcl-dev | ≥ 8.5 | | Tcl plugin -| guile-2.0-dev | ≥ 2.0 | | Guile (scheme) plugin -| libv8-dev | ≤ 3.24.3 | | Javascript plugin -| asciidoctor | ≥ 1.5.4 | | Build man page and documentation -| libcpputest-dev | ≥ 3.4 | | Run tests -| C++ compiler | | | Run tests, javascript plugin -|=== - -[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). + -^(3)^ Gnutls ≥ 3.0.21 is required for IRC SASL authentication with mechanism -ECDSA-NIST256P-CHALLENGE. + -^(4)^ Recommended Python version is 2.7 (all scripts run fine with version 2.7, -but not with versions ≤ 2.6 or ≥ 3.0). - -[[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 .. -DCMAKE_INSTALL_PREFIX=/path/to/directory -$ make -$ make install ----- - -Options can be used for cmake, with format: "-DOPTION=VALUE". - -List of commonly used options: - -[width="100%",cols="2m,2,5m,12",options="header"] -|=== -| Option | Values | Default value | Description - -| CMAKE_BUILD_TYPE | `Debug`, `Release`, `RelWithDebInfo`, `MinSizeRel` | | - The type of build: `Debug` (or `RelWithDebInfo`) is recommended if you are - running development version of WeeChat. - -| CMAKE_INSTALL_PREFIX | directory | /usr/local | - The directory where WeeChat will be installed. - -| WEECHAT_HOME | directory | ~/.weechat | - The default home directory when running WeeChat. - -| CA_FILE | file | /etc/ssl/certs/ca-certificates.crt | - File containing the certificate authorities. - This is the default value of option - <<option_weechat.network.gnutls_ca_file,weechat.network.gnutls_ca_file>>. - -| ENABLE_ALIAS | `ON`, `OFF` | ON | - Compile <<alias_plugin,Alias plugin>>. - -| ENABLE_ASPELL | `ON`, `OFF` | ON | - Compile <<aspell_plugin,Aspell plugin>>. - -| ENABLE_CHARSET | `ON`, `OFF` | ON | - Compile <<charset_plugin,Charset plugin>>. - -| ENABLE_MAN | `ON`, `OFF` | OFF | - Compile man page. - -| ENABLE_DOC | `ON`, `OFF` | OFF | - Compile documentation (it takes a long time, recommended only if you build - a binary package embedding documentation or if you can't browse documentation - online). - -| ENABLE_ENCHANT | `ON`, `OFF` | OFF | - Compile <<aspell_plugin,Aspell plugin>> with Enchant. - -| ENABLE_EXEC | `ON`, `OFF` | ON | - Compile <<exec_plugin,Exec plugin>>. - -| ENABLE_FIFO | `ON`, `OFF` | ON | - Compile <<fifo_plugin,Fifo plugin>>. - -| ENABLE_GNUTLS | `ON`, `OFF` | ON | - Enable Gnutls (for SSL). - -| ENABLE_GUILE | `ON`, `OFF` | ON | - Compile <<scripts_plugins,Guile plugin>> (Scheme). - -| ENABLE_IRC | `ON`, `OFF` | ON | - Compile <<irc_plugin,IRC plugin>>. - -| ENABLE_JAVASCRIPT | `ON`, `OFF` | ON | - Compile <<scripts_plugins,Javascript plugin>>. - -| ENABLE_LARGEFILE | `ON`, `OFF` | ON | - Support of large files. - -| ENABLE_LOGGER | `ON`, `OFF` | ON | - Compile <<logger_plugin,Logger plugin>>. - -| ENABLE_LUA | `ON`, `OFF` | ON | - Compile <<scripts_plugins,Lua plugin>>. - -| ENABLE_NCURSES | `ON`, `OFF` | ON | - Compile Ncurses interface. - -| ENABLE_NLS | `ON`, `OFF` | ON | - Enable NLS (translations). - -| ENABLE_PERL | `ON`, `OFF` | ON | - Compile <<scripts_plugins,Perl plugin>>. - -| ENABLE_PYTHON | `ON`, `OFF` | ON | - Compile <<scripts_plugins,Python plugin>>. - -| ENABLE_PYTHON3 | `ON`, `OFF` | OFF | - Compile <<scripts_plugins,Python plugin>> using Python 3 (*NOT* recommended - because many scripts are not compatible with Python 3). - -| ENABLE_RELAY | `ON`, `OFF` | ON | - Compile <<relay_plugin,Relay plugin>>. - -| ENABLE_RUBY | `ON`, `OFF` | ON | - Compile <<scripts_plugins,Ruby plugin>>. - -| ENABLE_SCRIPT | `ON`, `OFF` | ON | - Compile <<scripts_plugins,Script plugin>>. - -| ENABLE_SCRIPTS | `ON`, `OFF` | ON | - Compile <<scripts_plugins,script plugins>> (Python, Perl, Ruby, Lua, Tcl, - Guile, Javascript). - -| ENABLE_TCL | `ON`, `OFF` | ON | - Compile <<scripts_plugins,Tcl plugin>>. - -| ENABLE_TRIGGER | `ON`, `OFF` | ON | - Compile <<trigger_plugin,Trigger plugin>>. - -| ENABLE_XFER | `ON`, `OFF` | ON | - Compile <<xfer_plugin,Xfer plugin>>. - -| ENABLE_TESTS | `ON`, `OFF` | OFF | - Compile tests. -|=== - -The other options can be displayed with this command: - ----- -$ cmake -LA ----- - -Or with Curses interface: - ----- -$ ccmake .. ----- - -[[compile_with_autotools]] -==== Compile with autotools - -[WARNING] -Only cmake is officially supported to build WeeChat. You should use autotools -only if you are not able to use cmake. + -Build with autotools requires more dependencies and is slower than with cmake. - -* Installation in system directories (requires _root_ privileges): - ----- -$ ./autogen.sh -$ mkdir build -$ cd build -$ ../configure -$ make -% make install (as root) ----- - -* Installation in custom directory: - ----- -$ ./autogen.sh -$ mkdir build -$ cd build -$ ../configure --prefix=/path/to/directory -$ make -$ make install ----- - -Options can be used for _configure_ script, they can be displayed with this -command: - ----- -$ ./configure --help ----- - -[[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 https://github.com/weechat/weechat.git ----- - -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 can use option -<<option_weechat.startup.sys_rlimit,weechat.startup.sys_rlimit>>: - ----- -/set weechat.startup.sys_rlimit "core:-1" ----- - -For WeeChat ≤ 0.3.8 or if you want to enable core files even before WeeChat -starts, you can 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_ is installed in _/usr/bin/_ and _core_ file is -in _/home/xxx/_, then run gdb with this command: - ----- -gdb /usr/bin/weechat /home/xxx/core ----- - -Then under gdb, use command `bt full` to display backtrace. -You will see something like that: - ----- -(gdb) set logging file /tmp/crash.txt -(gdb) set logging on -Copying output to /tmp/crash.txt. -(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! - -[[debug_running_weechat]] -==== Debug a running WeeChat - -To debug a running WeeChat (for example if WeeChat seems blocked), you can use -gdb with process id (replace _12345_ with PID of weechat process): - ----- -gdb /usr/bin/weechat 12345 ----- - -Then like for a crash, use command `bt full`: - ----- -(gdb) bt full ----- - -[[usage]] -== Usage - -[[running_weechat]] -=== Running WeeChat - -Command line arguments: - -include::cmdline_options.en.asciidoc[] - -To start WeeChat, issue this command: - ----- -$ weechat ----- - -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: - -.... - ▼ bar "title" -┌───────────────────────────────────────────────────────────────────────────┐ -│Welcome to #test, this is a test channel │ -│12:52:27 --> | Flashy (flashcode@weechat.org) has joined #test │@Flashy│ -│12:52:27 -- | Nicks #test: [@Flashy @joe +weebot peter] │@joe │ -│12:52:27 -- | Channel #test: 4 nicks (2 ops, 1 voice, 1 normal) │+weebot│ -│12:52:27 -- | Channel created on Tue Jan 27 06:30:17 2009 │peter │ -│12:54:15 peter | hey! │ │ -│12:55:01 @joe | hello │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│[12:55] [6] [irc/freenode] 3:#test(+n){4}* [H: 4:#abc(2,5), 6] │ -│[@Flashy(i)] hi peter!█ │ -└───────────────────────────────────────────────────────────────────────────┘ - ▲ bars "status" and "input" bar "nicklist" ▲ -.... - -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,^4,10",options="header"] -|=== -| Item | Example | Description -| time | `[12:55]` | Time -| buffer_last_number | `[6]` | Number of last buffer in list -| 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` | Current buffer name -| buffer_modes | `+n` | IRC channel modes -| buffer_nicklist_count | `{4}` | Number of nicks in nicklist -| buffer_zoom | ! | `!` means the merged buffer is zoomed (only this one is displayed), empty value means all merged buffers are displayed -| buffer_filter | `+*+` | Filtering indicator: `+*+` means some lines are filtered (hidden), empty value means all lines are displayed -| scroll | `-MORE(50)-` | Scroll indicator, with number of lines below last line displayed -| lag | `[Lag: 2.5]` | Lag indicator, in seconds (hidden if lag is low) -| hotlist | `[H: 4:#abc(2,5), 6]` | List of buffers with activity (unread messages) (in example, 2 highlights and 5 unread messages on _#abc_, one unread message on buffer #6) -| completion | `abc(2) def(5)` | List of words for completion, with number of possible completions for each word -|=== - -Bar _input_ has following default items: - -[width="100%",cols="^3,^4,10",options="header"] -|=== -| Item | Example | Description -| input_prompt | `[@Flashy(i)]` | Input prompt, for irc: nick and modes (mode "+i" means invisible on freenode) -| away | `(away)` | Away indicator -| input_search | `[Search (~ str,msg)]` | Search indicator ("`~`": case insensitive, "`==`": case sensitive, "`str`": search string, "`regex`": search regular expression, "`msg`": search in messages, "`pre`": search in prefixes, "`pre\|msg`": search in prefixes and messages) -| input_paste | `[Paste 7 lines ? [ctrl-Y] Yes [ctrl-N] No]` | Question to user for pasting lines -| input_text | `hi peter!` | Input text -|=== - -Other items available (not used in bars by default): - -[width="100%",cols="^3,^4,10",options="header"] -|=== -| Item | Example | Description -| aspell_dict | `fr,en` | Spelling dictionaries used on current buffer -| aspell_suggest | `print,prone,prune` | Spelling suggestions for word under cursor (if misspelled) -| buffer_count | `10` | Total number of buffers opened -| buffer_short_name | `#test` | Current buffer short name -| irc_channel | `#test` | Current IRC channel name -| irc_nick_modes | `@` | IRC modes for self nick -| mouse_status | `M` | Mouse status (empty if mouse is disabled) -| window_number | `2` | Current window number -|=== - -[[buffers_and_windows]] -=== Buffers and windows - -A _buffer_ is composed by a number, a name, lines displayed (and some other -data). - -Examples of buffers: - -* core buffer (created by WeeChat on startup, can not be closed) -* irc server (displays messages from server) -* irc channel -* irc private - -A _window_ is a screen area which displays a buffer. It is possible to split -your screen into many windows. - -Each window displays one buffer. A buffer can be hidden (not displayed by a -window) or displayed by one or more windows. - -Example of horizontal split (`/window splith`): - -.... - ▼ window #2 (buffer #4) -┌───────────────────────────────────────────────────────────────────────────┐ -│Welcome to #abc │ -│12:55:12 Max | hi │@Flashy│ -│12:55:20 @Flashy | hi Max! │Max │ -│12:55:32 Max | how are you? │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│[12:55] [6] [irc/freenode] 4:#abc(+n){2} │ -│[@Flashy] │ -│───────────────────────────────────────────────────────────────────────────│ -│Welcome to #test │ -│12:54:15 peter | hey! │@Flashy│ -│12:55:01 @joe | hello │@joe │ -│ │+weebot│ -│ │peter │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│[12:55] [6] [irc/freenode] 3:#test(+n){4} │ -│[@Flashy] hi peter!█ │ -└───────────────────────────────────────────────────────────────────────────┘ - ▲ window #1 (buffer #3) -.... - -Example of vertical split (`/window splitv`): - -.... -┌───────────────────────────────────────────────────────────────────────────┐ -│Welcome to #test │Welcome to #abc │ -│12:54:15 peter | hey! │@Flashy│12:55:12 Max | hi │@Flashy│ -│12:55:01 @joe | hello │@joe │12:55:20 @Flashy | hi Max! │Max │ -│ │+weebot│ │ │ -│ │peter │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│[12:55] [irc/oftc] 3:#test(+n){4} │[12:55] [irc/oftc] 4:#abc(+n){2} │ -│[@Flashy] hi peter!█ │[@Flashy] │ -└───────────────────────────────────────────────────────────────────────────┘ - ▲ window #1 (buffer #3) ▲ window #2 (buffer #4) -.... - -Example of vertical + horizontal splits: - -.... - ▼ window #3 (buffer #5) -┌───────────────────────────────────────────────────────────────────────────┐ -│Welcome to #test │Welcome to #def │ -│12:54:15 peter | hey! │@Flashy│12:55:42 @Flashy | hi │@Flashy│ -│12:55:01 @joe | hello │@joe │12:55:56 alex | hi Flashy │alex │ -│ │+weebot│ │ │ -│ │peter │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │[12:55] [irc/oftc] 5:#def(+n){2} │ -│ │ │[@Flashy] │ -│ │ │─────────────────────────────────────│ -│ │ │Welcome to #abc │ -│ │ │12:55:12 Max | hi │@Flashy│ -│ │ │12:55:20 @Flashy | hi Max! │Max │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -│[12:55] [irc/oftc] 3:#test(+n){4} │[12:55] [irc/oftc] 4:#abc(+n){2} │ -│[@Flashy] hi peter!█ │[@Flashy] │ -└───────────────────────────────────────────────────────────────────────────┘ - ▲ window #1 (buffer #3) ▲ window #2 (buffer #4) -.... - -[[bars]] -=== Bars - -A _bar_ is an area beside the chat that can contain any type of text. - -The bar options can be set with options `weechat.bar.name.option` where `name` -is the name of the bar and `option` the option for this bar. - -List of bar options: - -[width="100%",cols="2m,2,10",options="header"] -|=== -| Option | Values | Description - -| type | `root`, `window` | - A bar with type `root` is displayed exactly one time on screen, outside all - windows. There is no root bar by default, but an example is the bar _buffers_ - created by script _buffers.pl_ (sidebar with list of buffers). + - A bar with type `window` is displayed in each window, for example if you - split one time the screen (with `/window splith` or `/window splitv`), you - will have one bar in each window. The four default bars (_title_, _status_, - _input_, _nicklist_) have type `window`. - -| position | `top`, `bottom`, `left`, `right` | - Position of the bar: above/below chat, on the left/right. - -| priority | integer ≥ 0 | - Priority for display of bar: this is used for ordering the bars on screen when - many bars have same type and position. + - The bars are displayed from the edge of the screen to the center. A higher - priority will display bar at the beginning, so closer to the edge. + - Example: _input_ bar has priority 1000, so it is displayed before the _status_ - bar, which has priority 500. - -| size | integer ≥ 0 | - The size of the bar: number of columns for position left/right, number - of lines for position top/bottom. A size of `0` means automatic, so the size - will be computed according to content displayed in bar. - -| size_max | integer ≥ 0 | - The maximum size for a bar, `0` = no limit (this option is used only if - `size` = `0`). - -| color_bg | color | - The default background color for the bar. - -| color_fg | color | - The default text color for the bar. - -| color_delim | color | - The color for delimiters in bar. - -| hidden | `on`, `off` | - When option is `on`, the bar is hidden. + - Note: instead of changing this option, the command `/bar` is preferred, for - example: `/bar toggle nicklist` (see command <<command_weechat_bar,/bar>>). - -| separator | `on`, `off` | - When option is `on`, a separator (line) is displayed between this bar and - other bars (or chat). - -| items | string | - A list of _items_ (see <<bar_items,items>> for more info). - -| filling_left_right | `horizontal`, `vertical`, `columns_horizontal`, `columns_vertical` | - Type of filling for a bar which has position `left` or `right` (see - <<bar_filling,filling>> for more info). - -| filling_top_bottom | `horizontal`, `vertical`, `columns_horizontal`, `columns_vertical` | - Type of filling for a bar which has position `top` or `bottom` (see - <<bar_filling,filling>> for more info). - -| conditions | string | - The conditions to display the bar (see <<bar_conditions,conditions>> for more - info). -|=== - -[[bar_items]] -==== Items - -The option _items_ is a string with a list of bar items, separated by a comma -(space between items on screen) or "+" (glued items). - -The list of bar items is displayed with command `/bar listitems`. - -Before or after item name, you can use chars (that are not alphanumeric, "-" or -"_"). They will be displayed before/after item with the delimiters color -defined in bar (option _color_delim_). - -Example of bar with items "[time],buffer_number+:+buffer_plugin+.+buffer_name": - -.... -┌───────────────────────────────────────────────────────────────────────────┐ -│[12:55] 3:irc/freenode.#weechat │ -└───────────────────────────────────────────────────────────────────────────┘ -.... - -A special syntax can be used to force the buffer used when displaying the bar -item: "@buffer:item" (where "buffer" is the full name of buffer and "item" is -the name of a bar item). - -This is useful in root bars, to display item for a specific buffer which is -not displayed in the current window (or even not displayed at all). - -Example: nicklist of bitlbee in a root bar (if the bar is called -_bitlist_ and if bitlbee server is called _bitlbee_): - ----- -/set weechat.bar.bitlist.items "@irc.bitlbee.&bitlbee:buffer_nicklist" ----- - -[[bar_filling]] -==== Filling - -There are four types of filling: - -* `horizontal`: the items are displayed horizontally, from left to right. If - there are new lines in items, a space is used to separate lines. -* `vertical`: the items are displayed from top to bottom. If there are new - lines in items, a new line is used to separate lines. -* `columns_horizontal`: items are displayed using columns, where text is - aligned on the left. The first item is on top left, the second is on same - line, on the right. -* `columns_vertical`: items are displayed using columns, where text is aligned - on the left. The first item is on top left, the second is one line below. - -Default bars _title_, _status_ and _input_ have _horizontal_ filling, and -default bar _nicklist_ has _vertical_ filling. - -Some examples of filling for bar _nicklist_: - -.... -┌───────────────────────────────────────────────────────────────────────┐ -│Welcome to #test, this is a test channel │ -│12:54:15 peter | hey! │@carl │ -│12:55:01 +Max | hello │@jessika│ -│ │@maddy │ -│ │%Diego │ -│ │%Melody │ -│ │+Max │ -│ │ celia │ -│ │ Eva │ -│ │ freddy │ -│ │ Harold^│ -│ │ henry4 │ -│ │ jimmy17│ -│ │ jodie ▼│ -│[12:55] [6] [irc/freenode] 3:#test(+n){24} │ -│[@carl] █ │ -└───────────────────────────────────────────────────────────────────────┘ - filling_left_right = vertical ▲ - -┌───────────────────────────────────────────────────────────────────────┐ -│Welcome to #test, this is a test channel │ -│12:54:15 peter | hey! │@carl lee │ -│12:55:01 +Max | hello │@jessika louise │ -│ │@maddy mario │ -│ │%Diego mark │ -│ │%Melody peter │ -│ │+Max Rachel │ -│ │ celia richard│ -│ │ Eva sheryl │ -│ │ freddy Vince │ -│ │ Harold^ warren │ -│ │ henry4 zack │ -│ │ jimmy17 │ -│ │ jodie │ -│[12:55] [6] [irc/freenode] 3:#test(+n){24} │ -│[@carl] █ │ -└───────────────────────────────────────────────────────────────────────┘ - filling_left_right = columns_vertical ▲ - -┌───────────────────────────────────────────────────────────────────────┐ -│@carl %Diego celia Harold^ jodie mario Rachel Vince │ -│@jessika %Melody Eva henry4 lee mark richard warren │ -│@maddy +Max freddy jimmy17 louise peter sheryl zack │ -│───────────────────────────────────────────────────────────────────────│ -│ │ - filling_top_bottom = columns_vertical ▲ - -┌───────────────────────────────────────────────────────────────────────┐ -│@carl @jessika @maddy %Diego %Melody +Max celia Eva │ -│ freddy Harold^ henry4 jimmy17 jodie lee louise mario │ -│ mark peter Rachel richard sheryl Vince warren zack │ -│───────────────────────────────────────────────────────────────────────│ -│ │ - filling_top_bottom = columns_horizontal ▲ -.... - -[[bar_conditions]] -==== Conditions - -The option _conditions_ is a string which is evaluated to know if the bar -must be displayed or not. - -The string can be: - -* _active_: the window must be active -* _inactive_: the window must be inactive -* _nicklist_: the buffer displayed in window must have a nicklist -* an expression: it is evaluated as boolean (see command - <<command_weechat_eval,/eval>>) - -For the expression, following variables are available: - -* `${active}`: true if window is active -* `${inactive}`: true if window is inactive -* `${nicklist}`: true if buffer displayed in window has a nicklist - -Following pointers are available: - -* `${window}`: the window where condition is evaluated -* `${buffer}`: the buffer of window where condition is evaluated - -Example to display nicklist bar in all buffers with a nicklist, and only if -width of window is > 100 : - ----- -/set weechat.bar.nicklist.conditions "${nicklist} && ${window.win_width} > 100" ----- - -Same condition, but always display nicklist on buffer _&bitlbee_ (even if window -is small): - ----- -/set weechat.bar.nicklist.conditions "${nicklist} && (${window.win_width} > 100 || ${buffer.full_name} == irc.bitlbee.&bitlbee)" ----- - -[[bare_display]] -=== Bare display - -A special display, called "bare display" can be used for easy click on long URLs -and selection of text (using the mouse). - -The bare display has following features: - -* it displays only the content of current buffer: no window split neither bars - (no title, nicklist, status, input, ...) -* the WeeChat mouse support is disabled (if it was enabled): you can use your - mouse like you do in the terminal to click on URLs and select text -* ncurses is not used, therefore URLs are not cut at the end of lines. - -The default key to enabled bare display is kbd:[Alt+l], and same key to exit (or -by default anything changing the input will exit the bare display, see option -<<option_weechat.look.bare_display_exit_on_input,weechat.look.bare_display_exit_on_input>>). - -The time format can be customized with the option -<<option_weechat.look.bare_display_time_format,weechat.look.bare_display_time_format>>. - -The bare display can be enabled for a specific delay using the command -<<command_weechat_window,/window>>. - -If WeeChat looks like that: - -.... -┌───────────────────────────────────────────────────────────────────────────┐ -│Welcome to #test, this is a test channel │ -│12:52:27 --> | Flashy (flashcode@weechat.org) has joined #test │@Flashy│ -│12:52:27 -- | Nicks #test: [@Flashy @joe +weebot peter] │@joe │ -│12:52:27 -- | Channel #test: 4 nicks (2 ops, 1 voice, 1 normal) │+weebot│ -│12:52:27 -- | Channel created on Tue Jan 27 06:30:17 2009 │peter │ -│12:54:15 peter | hey! │ │ -│12:55:01 @joe | peter: hook_process: https://weechat.org/files/do │ │ -│ | c/devel/weechat_plugin_api.en.html#_weechat_hook_ │ │ -│ | process │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│[12:55] [6] [irc/freenode] 3:#test(+n){4}* [H: 4:#abc(2,5), 6] │ -│[@Flashy(i)] hi peter!█ │ -└───────────────────────────────────────────────────────────────────────────┘ -.... - -The screen will look like that in bare display: - -.... -┌───────────────────────────────────────────────────────────────────────────┐ -│ │ -│ │ -│ │ -│ │ -│ │ -│ │ -│ │ -│ │ -│ │ -│ │ -│ │ -│ │ -│ │ -│12:52 --> Flashy (flashcode@weechat.org) has joined #test │ -│12:52 -- Nicks #test: [@Flashy @joe +weebot peter] │ -│12:52 -- Channel #test: 4 nicks (2 ops, 1 voice, 1 normal) │ -│12:52 -- Channel created on Tue Jan 27 06:30:17 2009 │ -│12:54 <peter> hey! │ -│12:55 <@joe> peter: hook_process: https://weechat.org/files/doc/devel/weech│ -│at_plugin_api.en.html#_weechat_hook_process │ -└───────────────────────────────────────────────────────────────────────────┘ -.... - -So you can click the URL from _joe_ without any problem in your terminal (of -course this supposes that your terminal supports click on URLs). - -[[notify_levels]] -=== Notify levels - -Four levels are possible in messages displayed in buffers, from lower to higher: - -* _low_: message with low importance (for example irc join/part/quit) -* _message_: message from a user -* _private_: message in a private buffer -* _highlight_: message with highlight - -Each buffer has a notify level, which is used to decide what messages will add -buffer in hotlist. - -The default notify level can be set using option -<<option_weechat.look.buffer_notify_default,weechat.look.buffer_notify_default>>, -default is _all_. - -[width="50%",cols="3m,10",options="header"] -|=== -| Notify level | Level of messages added to hotlist -| none | (none) -| highlight | _highlight_ + _private_ -| message | _highlight_ + _private_ + _message_ -| all | _highlight_ + _private_ + _message_ + _low_ -|=== - -Notify level can be defined for a set of buffers, for example all buffers of -irc server "freenode": - ----- -/set weechat.notify.irc.freenode message ----- - -Set notify level _highlight_ on channel "#weechat" only: - ----- -/set weechat.notify.irc.freenode.#weechat highlight ----- - -The notify level for a buffer can be set with command `/buffer`: - ----- -/buffer notify highlight ----- - -[[key_bindings]] -=== Default key bindings - -[[key_bindings_command_line]] -==== Keys for command line - -[width="100%",cols="^.^3,.^8,.^5",options="header"] -|=== -| Key | Description | Command -| kbd:[←] + - kbd:[Ctrl+b] | Go to previous char in command line | `/input move_previous_char` -| kbd:[→] + - kbd:[Ctrl+f] | Go to next char in command line | `/input move_next_char` -| kbd:[Ctrl+←] + - kbd:[Alt+b] | Go to previous word in command line | `/input move_previous_word` -| kbd:[Ctrl+→] + - kbd:[Alt+f] | Go to next word in command line | `/input move_next_word` -| kbd:[Home] + - kbd:[Ctrl+a] | Go to the beginning of command line | `/input move_beginning_of_line` -| kbd:[End] + - kbd:[Ctrl+e] | Go to the end of command line | `/input move_end_of_line` -| kbd:[Ctrl+c], - kbd:[b] | Insert code for bold text | `/input insert \x02` -| kbd:[Ctrl+c], - kbd:[c] | Insert code for colored text | `/input insert \x03` -| kbd:[Ctrl+c], - kbd:[i] | Insert code for italic text | `/input insert \x1D` -| kbd:[Ctrl+c], - kbd:[o] | Insert code for color reset | `/input insert \x0F` -| kbd:[Ctrl+c], - kbd:[v] | Insert code for reverse color | `/input insert \x16` -| kbd:[Ctrl+c], - kbd:[_] | Insert code for underlined text | `/input insert \x1F` -| kbd:[Del] + - kbd:[Ctrl+d] | Delete next char in command line | `/input delete_next_char` -| kbd:[Backsp.] + - kbd:[Ctrl+h] | Delete previous char in command line | `/input delete_previous_char` -| kbd:[Ctrl+k] | Delete from cursor until end of command line (deleted string is copied to clipboard) | `/input delete_end_of_line` -| kbd:[Ctrl+r] | Search for text in buffer history (see <<key_bindings_search_context,keys for search context>>) | `/input search_text_here` -| kbd:[Ctrl+t] | Transpose chars | `/input transpose_chars` -| kbd:[Ctrl+u] | Delete from cursor until beginning of command line (deleted string is copied to clipboard) | `/input delete_beginning_of_line` -| kbd:[Ctrl+w] | Delete previous word of command line (deleted string is copied to clipboard) | `/input delete_previous_word` -| kbd:[Ctrl+y] | Paste clipboard content | `/input clipboard_paste` -| kbd:[Ctrl+_] | Undo last action on command line | `/input undo` -| kbd:[Alt+_] | Redo last action on command line | `/input redo` -| kbd:[Tab] | Complete command or nick (kbd:[Tab] again: find next completion) | `/input complete_next` -| kbd:[Shift+Tab] | Without completion: do a partial completion, with pending completion: complete with previous completion | `/input complete_previous` -| kbd:[Enter] + - kbd:[Ctrl+j] + - kbd:[Ctrl+m] | Execute command or send message (in search mode: stop search) | `/input return` -| kbd:[↑] | Call previous command/message (in search mode: search up) | `/input history_previous` -| kbd:[↓] | Call next command/message (in search mode: search down) | `/input history_next` -| kbd:[Ctrl+↑] | Call previous command/message in global history (common for all buffers) | `/input history_global_previous` -| kbd:[Ctrl+↓] | Call next command/message in global history (common for all buffers) | `/input history_global_next` -| kbd:[Alt+d] | Delete next word in command line (deleted string is copied to clipboard) | `/input delete_next_word` -| kbd:[Alt+k] | Grab a key and insert its code (and command bound if key exists) in command line | `/input grab_key_command` -| kbd:[Alt+r] | Delete entire command line | `/input delete_line` -| kbd:[Alt+s] | Toggle aspell | `/mute aspell toggle` -|=== - -[[key_bindings_buffers_windows]] -==== Keys for buffers / windows - -[width="100%",cols="^.^3,.^8,.^5",options="header"] -|=== -| Key | Description | Command -| kbd:[Ctrl+l] | Redraw whole window | `/window refresh` -| kbd:[Ctrl+s], - kbd:[Ctrl+u] | Set unread marker on all buffers | `/input set_unread` -| kbd:[Ctrl+x] | Switch current buffer if buffers are attached with same number | `/input switch_active_buffer` -| kbd:[Alt+x] | Zoom on merged buffer (kbd:[Alt+x] again: display all merged buffers) | `/input zoom_merged_buffer` -| kbd:[PgUp] | Scroll up one page in buffer history | `/window page_up` -| kbd:[PgDn] | Scroll down one page in buffer history | `/window page_down` -| kbd:[Alt+PgUp] | Scroll up a few lines in buffer history | `/window scroll_up` -| kbd:[Alt+PgDn] | Scroll down a few lines in buffer history | `/window scroll_down` -| kbd:[Alt+Home] | Scroll to top of buffer | `/window scroll_top` -| kbd:[Alt+End] | Scroll to bottom of buffer | `/window scroll_bottom` -| kbd:[Alt+←] + - kbd:[Alt+↑] + - kbd:[Ctrl+p] + - kbd:[F5] | Switch to previous buffer | `/buffer -1` -| kbd:[Alt+→] + - kbd:[Alt+↓] + - kbd:[Ctrl+n] + - kbd:[F6] | Switch to next buffer | `/buffer +1` -| kbd:[F7] | Switch to previous window | `/window -1` -| kbd:[F8] | Switch to next window | `/window +1` -| kbd:[F9] | Scroll buffer's title on the left | `+/bar scroll title * -30%+` -| kbd:[F10] | Scroll buffer's title on the right | `+/bar scroll title * +30%+` -| kbd:[F11] | Scroll up one page in nicklist | `/bar scroll nicklist * -100%` -| kbd:[F12] | Scroll down one page in nicklist | `/bar scroll nicklist * +100%` -| kbd:[Alt+F11] | Go to the beginning of nicklist | `/bar scroll nicklist * b` -| kbd:[Alt+F12] | Go to the end of nicklist | `/bar scroll nicklist * e` -| kbd:[Alt+a] | Switch to next buffer with activity (with priority: highlight, message, other) | `/input jump_smart` -| kbd:[Alt+h] | Clear hotlist (activity notification on other buffers) | `/input hotlist_clear` -| kbd:[Alt+j], - kbd:[Alt+f] | Switch to first buffer | `/buffer -` -| kbd:[Alt+j], - kbd:[Alt+l] | Switch to last buffer | `/buffer +` -| kbd:[Alt+j], - kbd:[Alt+r] | Switch to IRC raw buffer | `/server raw` -| kbd:[Alt+j], - kbd:[Alt+s] | Switch to IRC server buffer | `/server jump` -| kbd:[Alt+0...9] | Switch to buffer by number (0 = 10) | `/buffer *N` -| kbd:[Alt+j], - kbd:[01...99] | Switch to buffer by number | `/buffer *NN` -| kbd:[Alt+l] | Toggle bare display on/off | `/window bare` -| kbd:[Alt+m] | Toggle mouse | `/mouse toggle` -| kbd:[Alt+n] | Scroll to next highlight | `/window scroll_next_highlight` -| kbd:[Alt+p] | Scroll to previous highlight | `/window scroll_previous_highlight` -| kbd:[Alt+u] | Scroll to first unread line in buffer | `/window scroll_unread` -| kbd:[Alt+w], - kbd:[Alt+↑] | Switch to window above | `/window up` -| kbd:[Alt+w], - kbd:[Alt+↓] | Switch to window below | `/window down` -| kbd:[Alt+w], - kbd:[Alt+←] | Switch to window on the left | `/window left` -| kbd:[Alt+w], - kbd:[Alt+→] | Switch to window on the right | `/window right` -| kbd:[Alt+w], - kbd:[Alt+b] | Balance the sizes of all windows | `/window balance` -| kbd:[Alt+w], - kbd:[Alt+s] | Swap buffers of two windows | `/window swap` -| kbd:[Alt+z] | Zoom on current window (kbd:[Alt+z] again: restore initial windows state, before zoom) | `/window zoom` -| kbd:[Alt+<] | Switch to previous buffer in list of visited buffers | `/input jump_previously_visited_buffer` -| kbd:[Alt+>] | Switch to next buffer in list of visited buffers | `/input jump_next_visited_buffer` -| kbd:[Alt+/] | Switch to last buffer displayed (before last jump to a buffer) | `/input jump_last_buffer_displayed` -| kbd:[Alt+=] | Toggle filters on/off | `/filter toggle` -| kbd:[Alt+-] | Toggle filters on/off in current buffer | `/filter toggle @` -|=== - -[[key_bindings_search_context]] -==== Keys for "search" context - -These keys are used in context "search" (when kbd:[Ctrl+r] is pressed to search -text in buffer). - -[width="100%",cols="^.^3,.^8,.^5",options="header"] -|=== -| Key | Description | Command -| kbd:[Ctrl+r] | Switch search type: string (default), regular expression | `/input search_switch_regex` -| kbd:[Alt+c] | Switch exact case for search | `/input search_switch_case` -| kbd:[Tab] | Switch search in: messages (default), prefixes, prefixes + messages | `/input search_switch_where` -| kbd:[↑] | Search previous line | `/input search_previous` -| kbd:[↓] | Search next line | `/input search_next` -| kbd:[Enter] + - kbd:[Ctrl+j] + - kbd:[Ctrl+m] | Stop search at current position | `/input search_stop_here` -| kbd:[Ctrl+q] | Stop search and scroll to bottom of buffer | `/input search_stop` -|=== - -[[key_bindings_cursor_context]] -==== Keys for "cursor" context - -These keys are used in context "cursor" (free movement of cursor on screen). - -[width="100%",cols="^.^3,^.^2,.^7,.^7",options="header"] -|=== -| Key | Area | Description | Command -| kbd:[↑] | - | Move cursor one line up | `/cursor move up` -| kbd:[↓] | - | Move cursor one line down | `/cursor move down` -| kbd:[←] | - | Move cursor one column left | `/cursor move left` -| kbd:[→] | - | Move cursor one column right | `/cursor move right` -| kbd:[Alt+↑] | - | Move cursor one area up | `/cursor move area_up` -| kbd:[Alt+↓] | - | Move cursor one area down | `/cursor move area_down` -| kbd:[Alt+←] | - | Move cursor one area left | `/cursor move area_left` -| kbd:[Alt+→] | - | Move cursor one area right | `/cursor move area_right` -| kbd:[m] | chat | Quote message | `hsignal:chat_quote_message;/cursor stop` -| kbd:[q] | chat | Quote prefix + message | `hsignal:chat_quote_prefix_message;/cursor stop` -| kbd:[Q] | chat | Quote time + prefix + message | `hsignal:chat_quote_time_prefix_message;/cursor stop` -| kbd:[b] | nicklist | Ban nick | `/window ${_window_number};/ban ${nick}` -| kbd:[k] | nicklist | Kick nick | `/window ${_window_number};/kick ${nick}` -| kbd:[K] | nicklist | Kick and ban nick | `/window ${_window_number};/kickban ${nick}` -| kbd:[q] | nicklist | Open query with nick | `/window ${_window_number};/query ${nick};/cursor stop` -| kbd:[w] | nicklist | Do a whois on nick | `/window ${_window_number};/whois ${nick}` -| kbd:[Enter] + - kbd:[Ctrl+j] + - kbd:[Ctrl+m] | - | Stop cursor mode | `/cursor stop` -|=== - -[[key_bindings_mouse_context]] -==== Keys for "mouse" context - -These keys are used in context "mouse", namely when a mouse event occurs. - -[width="100%",cols="^.^3,^.^3,^.^3,.^8,.^8",options="header"] -|=== -| Button ^(1)^ | Gesture | Area | Description | Command -| ◾◽◽ | - | chat | Switch to window | `/window ${_window_number}` -| ◾◽◽ | left | chat | Switch to previous buffer | `/window ${_window_number};/buffer +1` -| ◾◽◽ | right | chat | Switch to next buffer | `/window ${_window_number};/buffer +1` -| ◾◽◽ | left (long) | chat | Switch to first buffer | `/window ${_window_number};/buffer 1` -| ◾◽◽ | right (long) | chat | Switch to last buffer | `/window ${_window_number};/input jump_last_buffer` -| ◾◽◽ | - | chat (script buffer) | Select line in script buffer | `/script go ${_chat_line_y}` -| ◽◽◾ | - | chat (script buffer) | Install/remove script | `/script go ${_chat_line_y};/script installremove -q ${script_name_with_extension}` -| ⇑ | - | chat | Scroll up a few lines in buffer history | `/window scroll_up -window ${_window_number}` -| ⇓ | - | chat | Scroll down a few lines in buffer history | `/window scroll_down -window ${_window_number}` -| ⇑ | - | chat (script buffer) | Move 5 lines up in script buffer | `/script up 5` -| ⇓ | - | chat (script buffer) | Move 5 lines down in script buffer | `/script down 5` -| kbd:[Ctrl+⇑] | - | chat | Scroll horizontally to the left | `/window scroll_horiz -window ${_window_number} -10%` -| kbd:[Ctrl+⇓] | - | chat | Scroll horizontally to the right | `/window scroll_horiz -window ${_window_number} +10%` -| ◾◽◽ | up | nicklist | Scroll up one page in nicklist | `/bar scroll nicklist ${_window_number} -100%` -| ◾◽◽ | down | nicklist | Scroll down one page in nicklist | `/bar scroll nicklist ${_window_number} +100%` -| ◾◽◽ | up (long) | nicklist | Go to the beginning of nicklist | `/bar scroll nicklist ${_window_number} b` -| ◾◽◽ | down (long) | nicklist | Go to the end of nicklist | `/bar scroll nicklist ${_window_number} e` -| ◾◽◽ | - | nicklist | Open query with nick | `/window ${_window_number};/query ${nick}` -| ◽◽◾ | - | nicklist | Do a whois on nick | `/window ${_window_number};/whois ${nick}` -| ◾◽◽ | left | nicklist | Kick nick | `/window ${_window_number};/kick ${nick}` -| ◾◽◽ | left (long) | nicklist | Kick and ban nick | `/window ${_window_number};/kickban ${nick}` -| ◽◽◾ | left | nicklist | Ban nick | `/window ${_window_number};/ban ${nick}` -| ◽◽◾ | - | input | Grab a mouse event and insert its code in command line | `/input grab_mouse_area` -| ⇑ | - | any bar | Scroll bar by -20% | `/bar scroll ${_bar_name} ${_window_number} -20%` -| ⇓ | - | any bar | Scroll bar by +20% | `/bar scroll ${_bar_name} ${_window_number} +20%` -| ◽◾◽ | - | anywhere | Start cursor mode at this point | `/cursor go ${_x},${_y}` -|=== - -[NOTE] -^(1)^ "⇑" and "⇓" are wheel up and down. - -[[mouse]] -=== Mouse support - -WeeChat supports mouse clicks and gestures. It is working with local terminal, -and remotely via ssh connection with or without screen/tmux. - -[[mouse_enable]] -==== Enable mouse - -To enable mouse at startup: - ----- -/set weechat.look.mouse on ----- - -To enable mouse now, press kbd:[Alt+m] or do following command: - ----- -/mouse enable ----- - -It is possible to temporarily disable mouse, and bind that on a key. For example -key kbd:[Alt+%] to disable mouse for 10 seconds: - ----- -/key bind meta-% /mouse toggle 10 ----- - -[IMPORTANT] -When mouse is enabled in WeeChat, all mouse events are caught by WeeChat, so -actions such as copy/paste or clicks on URLs are not sent to the terminal. + -Using kbd:[Shift] key causes the events to be sent directly to the terminal, -as if the mouse was disabled (on some terminals like iTerm, you have to use -kbd:[Alt] instead of kbd:[Shift]). - -[NOTE] -For any problem with mouse, please look at _WeeChat FAQ_. - -[[mouse_bind_events]] -==== Bind mouse events to commands - -Many default mouse events are already defined by WeeChat (see -<<key_bindings_mouse_context,keys for "mouse" context>>). - -You can change or add bindings with the command `/key` using context "mouse" -(for syntax, see command <<command_weechat_key,/key>>). - -Event name consists of a modifier (optional), a button/wheel name and a gesture -(optional). Different elements are separated by "-". - -List of modifiers: - -[width="50%",cols="3m,4",options="header"] -|=== -| Modifier | Description -| ctrl | Key kbd:[Ctrl] -| alt | Key kbd:[Alt] -| ctrl-alt | Keys kbd:[Ctrl] + kbd:[Alt] -|=== - -List of buttons/wheel: - -[width="50%",cols="3m,4",options="header"] -|=== -| Button/wheel | Description -| button1 | Click on left button -| button2 | Click on right button -| button3 | Click on middle button (often click on wheel) -| button4 ... button9 | Click on extra buttons -| wheelup | Wheel (up) -| wheeldown | Wheel (down) -|=== - -List of gestures (only for buttons, not wheel): - -[width="50%",cols="3m,4",options="header"] -|=== -| Gesture | Distance -| gesture-up | 3 ... 19 -| gesture-up-long | ≥ 20 -| gesture-down | 3 ... 19 -| gesture-down-long | ≥ 20 -| gesture-left | 3 ... 39 -| gesture-left-long | ≥ 40 -| gesture-right | 3 ... 39 -| gesture-right-long | ≥ 40 -|=== - -List of incomplete events (only for buttons, useful for plugins/scripts): - -[width="50%",cols="3m,4",options="header"] -|=== -| Event | Description -| event-down | Button was pressed but not released yet -| event-drag | Mouse was moved with button pressed down -|=== - -Example of events: - -* `button1` -* `ctrl-button1` -* `button1-gesture-right` -* `button1-event-down` -* `button1-event-drag` -* `alt-button2-gesture-down-long` -* `wheelup` -* `ctrl-alt-wheeldown` -* ... - -[TIP] -When binding a key in context "mouse", it's possible to match many events using -`+*+` at beginning or end of name, for example `+button1-gesture-*+` will match -any gesture made using left button. - -[TIP] -You can find an event name with command `/input grab_mouse` then doing event -with mouse. This will insert event name on command line. - -[[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]] -==== Color codes - -For some plugins like IRC, you can use color codes and attributes, as -follow (press kbd:[Ctrl+c] then following letter, with optional value): - -[width="60%",cols="3,5",options="header"] -|=== -| Key | Description -| kbd:[Ctrl+c], kbd:[b] | bold text -| kbd:[Ctrl+c], kbd:[c], - kbd:[xx] | text color `xx` (see list of colors below) -| kbd:[Ctrl+c], kbd:[c], - kbd:[xx], kbd:[,], - kbd:[yy] | text color `xx` and background `yy` (see list of colors below) -| kbd:[Ctrl+c], kbd:[i] | italic text -| kbd:[Ctrl+c], kbd:[o] | disable color and attributes -| kbd:[Ctrl+c], kbd:[v] | reverse video (revert text color with background) -| kbd:[Ctrl+c], kbd:[_] | underlined text -|=== - -[NOTE] -The same code (without number for kbd:[Ctrl+c], kbd:[c]) can be used to stop the -attribute. - -Color codes for kbd:[Ctrl+c], kbd:[c] are: - -include::autogen/user/irc_colors.asciidoc[] - -[NOTE] -To show all available colors in your terminal, you can do `/color` then -kbd:[Alt+c] in WeeChat or run this command in terminal: `weechat --colors`. - -Example: display of "hello everybody!" with "hello" in light blue bold and -"everybody" in light red underlined: - ----- -^Cc12^Cbhello ^Cb^Cc04^C_everybody^C_^Cc! ----- - -[NOTE] -In irc plugin, you can remap these colors using option -<<option_irc.color.mirc_remap,irc.color.mirc_remap>>. - -[[colors]] -=== Colors - -WeeChat can use up to 256 color pairs to display text in bars and chat area -(your terminal must support 256 colors to use them in WeeChat). - -According to value of _TERM_ environment variable, you may have following limits -for colors in WeeChat: - -[width="50%",cols="8,>2,>2",options="header"] -|=== -| $TERM | Colors | Pairs -| "rxvt-unicode", "xterm", ... | 88 | 256 -| "rxvt-256color", "xterm-256color", ... | 256 | 256 -| "screen" | 8 | 64 -| "screen-256color" | 256 | 256 -| "tmux" | 8 | 64 -| "tmux-256color" | 256 | 256 -|=== - -You can run `weechat --colors` or use command `/color` in WeeChat to -display limits for your environment. - -Some recommended values for _TERM_ if you want 256 colors: - -* under screen: _screen-256color_ -* under tmux: _screen-256color_ or _tmux-256color_ -* outside screen/tmux: _xterm-256color_, _rxvt-256color_, _putty-256color_, ... - -[NOTE] -You may have to install package "ncurses-term" to use these values in _TERM_ -variable. - -If you are using screen, you can add this line to your _~/.screenrc_: - ----- -term screen-256color ----- - -If your _TERM_ variable has wrong value and that WeeChat is already running, -you can change it with these two commands: - ----- -/set env TERM screen-256color -/upgrade ----- - -[[colors_basic]] -==== Basic colors - -Basic colors in WeeChat are: - -[width="50%",cols="^3m,8",options="header"] -|=== -| Name | Color -| 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 -| gray | Gray -| white | White -|=== - -[[colors_extended]] -==== Extended colors - -WeeChat dynamically allocates color pairs when colors are used on screen (to -display buffers and bars). - -In addition to basic colors, you can use a color number between 1 and the limit -of your terminal. - -Use command `/color` to see current colors and limits. With kbd:[Alt+c] you can -temporarily switch to terminal colors to choose a color. - -For example if you want to display time in orange in buffer, do: - ----- -/set weechat.color.chat_time 214 ----- - -Or if you want a very dark green background for status bar: - ----- -/set weechat.bar.status.color_bg 22 ----- - -[[colors_aliases]] -==== Aliases - -You can add color aliases with command `/color alias` and then use this alias -in any color option. - -For example: - ----- -/color alias 214 orange -/set weechat.color.chat_delimiters orange ----- - -[[colors_attributes]] -==== Attributes - -It is possible to use some attributes for colors. One or more attributes can be -added before color name or number: - -* `+*+` : bold text -* `+!+` : reverse video -* `+/+` : italic -* `+_+` : underlined text -* `+|+` : keep attributes: do not reset bold/reverse/italic/underlined when - changing color - -For example if you want self nick as white underlined, do: - ----- -/set weechat.color.chat_nick_self _white ----- - -Or if you want time in status bar as orange underlined with bold: - ----- -/set weechat.color.status_time *_214 ----- - -To use an attribute with default terminal color (-1), you must use a number -greater than last terminal color, for example max color in WeeChat: 99999. - -Example of bold with terminal foreground color: - ----- -/set weechat.color.status_time *99999 ----- - -[[secured_data]] -=== Secured data - -[[secured_data_storage]] -==== Storage - -WeeChat can encrypt passwords or private data using secured data, stored in file -_sec.conf_. - -This configuration file is read before any other file, and the values stored -inside can be used in various WeeChat or plugins/scripts options. - -You can set a passphrase to encrypt data in _sec.conf_. This is not mandatory -but highly recommended, otherwise data is stored as plain text in file. - ----- -/secure passphrase this is my passphrase ----- - -When a passphrase is set, WeeChat will ask you to enter it on startup (but not -on `/upgrade`). - -You can change this behavior and use a file with the passphrase (see option -<<option_sec.crypt.passphrase_file,sec.crypt.passphrase_file>>). - -[[secured_data_encryption]] -===== Encryption - -The encryption of data is made in 3 steps: - -. Derive a key from the passphrase (with optional salt). -. Compute hash of data to encrypt. -. Encrypt the hash + data (output is: salt + encrypted hash/data). - -[NOTE] -The cipher block mode is _CFB_. - -The result is put as hexadecimal string in file _sec.conf_, for example: - ----- -[data] -__passphrase__ = on -freenode = "53B1C86FCDA28FC122A95B0456ABD79B5AB74654F21C3D099A6CCA8173239EEA59533A1D83011251F96778AC3F5166A394" ----- - -[[secured_data_decryption]] -===== Decryption - -The decryption of data is made in 3 steps: - -. Derive a key using salt and passphrase. -. Decrypt hash + data. -. Check that decrypted hash == hash of data. - -[[secured_data_manage]] -==== Manage secured data - -To add secured data, use `/secure set`, for example a password for _freenode_ -IRC server: - ----- -/secure set freenode mypassword ----- - -For comfort, secured data can be displayed in a dedicated buffer (kbd:[Alt+v] on -buffer to see values), just do: - ----- -/secure ----- - -Secured data can be used in some options that can contain private data like -password, using this format: "${sec.data.xxx}" where "xxx" is the name of -secured data (used with `/secure set xxx ...`). + -For a complete list of supported options, see `/help secure`. - -To use the _freenode_ password, for example with -<<irc_sasl_authentication,SASL authentication>>: - ----- -/set irc.server.freenode.sasl_password "${sec.data.freenode}" ----- - -[[options_and_commands]] -=== Options and commands - -[[sec_options]] -==== Secured data options (sec.conf) - -Sections: - -[width="100%",cols="3m,6m,16",options="header"] -|=== -| Section | Control command | Description -| crypt | /set sec.crypt.* | Options for encryption -| data | <<command_weechat_secure,/secure>> | Secured data -|=== - -Options: - -include::autogen/user/sec_options.asciidoc[] - -[[weechat_options]] -==== WeeChat options (weechat.conf) - -Sections: - -[width="100%",cols="3m,6m,16",options="header"] -|=== -| Section | Control command | Description -| debug | <<command_weechat_debug,/debug set>> + - /set weechat.debug.* | Debug level, for core and plugins (options can be added/removed in section) -| startup | /set weechat.startup.* | Startup options -| look | /set weechat.look.* | Look and feel -| palette | <<command_weechat_color,/color alias>> + - /set weechat.palette.* | Color aliases (options can be added/removed in section) -| color | /set weechat.color.* | Colors -| completion | /set weechat.completion.* | Completion options -| history | /set weechat.history.* | History options (commands and buffers) -| proxy | <<command_weechat_proxy,/proxy>> + - /set weechat.proxy.* | Proxy options -| network | /set weechat.network.* | Network/SSL options -| bar | <<command_weechat_bar,/bar>> + - /set weechat.bar.* | Bar options -| layout | <<command_weechat_layout,/layout>> | Layouts -| notify | <<command_weechat_buffer,/buffer notify>> | Notify levels for buffers (options can be added/removed in section) -| filter | <<command_weechat_filter,/filter>> | Filters -| key | <<command_weechat_key,/key>> | Keys in default context -| key_search | <<command_weechat_key,/key>> | Keys in search context -| key_cursor | <<command_weechat_key,/key>> | Keys in cursor context -| key_mouse | <<command_weechat_key,/key>> | Keys in mouse context -|=== - -Options: - -include::autogen/user/weechat_options.asciidoc[] - -[[weechat_commands]] -==== WeeChat commands - -include::autogen/user/weechat_commands.asciidoc[] - -[[plugins]] -== Plugins - -A plugin is a 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 _python_ with command -`/python`. - -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="100%",cols="^1,5",options="header"] -|=== -| Plugin | Description -| alias | Define alias for commands -| aspell | Spell checking for command line -| charset | Charset decoding/encoding for buffers -| exec | Execution of external commands in WeeChat -| fifo | FIFO pipe used to remotely send commands to WeeChat -| irc | IRC chat protocol -| logger | Log buffers to files -| relay | Relay data via network -| script | Scripts manager -| python | Python scripting API -| perl | Perl scripting API -| ruby | Ruby scripting API -| lua | Lua scripting API -| tcl | Tcl scripting API -| guile | Guile (scheme) scripting API -| javascript | Javascript scripting API -| trigger | Text replacement and command execution on events triggered by WeeChat/plugins -| xfer | File transfer and direct chat -|=== - -To learn more about plugin or script development (through API), please read -_WeeChat Plugin API Reference_ or _WeeChat Scripting Guide_. - -[[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.asciidoc[] - -[[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) - -Sections: - -[width="100%",cols="3m,6m,16",options="header"] -|=== -| Section | Control command | Description -| color | /set aspell.color.* | Colors -| check | /set aspell.check.* | Options to control spell checking -| dict | <<command_aspell_aspell,/aspell setdict>> + - /set aspell.dict.* | Dictionaries used by buffer (options can be added/removed in section) -| option | /set aspell.option.* | <<aspell_speller_options,Speller options>> (options can be added/removed in section) -|=== - -Options: - -include::autogen/user/aspell_options.asciidoc[] - -[[aspell_commands]] -==== Commands - -include::autogen/user/aspell_commands.asciidoc[] - -[[aspell_speller_options]] -==== Speller options - -Speller options can be defined by adding options in section "option" of aspell -configuration. - -The option name is an aspell configuration option. List of options can be found -in a shell with following command: - ----- -$ aspell config ----- - -For example, to enable option "ignore-case": - ----- -/set aspell.option.ignore-case "true" ----- - -[[aspell_suggestions]] -==== Suggestions - -Suggestions are displayed in a bar item called "aspell_suggest". The number of -suggestions is set in option _aspell.check.suggestions_. - -To enable suggestions you must set option _aspell.check.suggestions_ to an -integer ≥ 0 and add the bar item "aspell_suggest" to a bar, like _status_. - -Example of suggestions with English dictionary (`en`): - -.... -│[12:55] [6] [irc/freenode] 3:#test(+n){4} [print,prone,prune] │ -│[@Flashy] prinr █ │ -└─────────────────────────────────────────────────────────────────────────────────┘ -.... - -Example of suggestions with English and French dictionaries (`en,fr`): - -.... -│[12:55] [6] [irc/freenode] 3:#test(+n){4} [print,prone,prune/prime,primer,primé] │ -│[@Flashy] prinr █ │ -└─────────────────────────────────────────────────────────────────────────────────┘ -.... - -[[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) - -Sections: - -[width="100%",cols="3m,6m,16",options="header"] -|=== -| Section | Control command | Description -| default | /set charset.default.* | Default decoding/encoding charset -| decode | <<command_charset_charset,/charset decode>> + - /set charset.decode.* | Decoding charset by buffer (options can be added/removed in section) -| encode | <<command_charset_charset,/charset encode>> + - /set charset.encode.* | Encoding charset by buffer (options can be added/removed in section) -|=== - -Options: - -include::autogen/user/charset_options.asciidoc[] - -[[charset_commands]] -==== Commands - -include::autogen/user/charset_commands.asciidoc[] - -[[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 set charset for all channels/privates of an IRC server: - ----- -/set charset.encode.irc.freenode ISO-8859-15 ----- - -To see all charsets used, use following command: - ----- -/set charset.* ----- - -[[charset_troubleshooting]] -==== Troubleshooting - -For any problem with charsets, please look at _WeeChat FAQ_. - -[[exec_plugin]] -=== Exec plugin - -The `/exec` command lets you execute external commands inside WeeChat and -display the output locally, or send it to a buffer. - -[[exec_options]] -==== Options (exec.conf) - -Sections: - -[width="100%",cols="3m,6m,16",options="header"] -|=== -| Section | Control command | Description -| command | /set exec.command.* | Options for commands -| color | /set exec.color.* | Colors -|=== - -Options: - -include::autogen/user/exec_options.asciidoc[] - -[[exec_commands]] -==== Commands - -include::autogen/user/exec_commands.asciidoc[] - -[[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 Python scripts (you have to separate them - with "\n"): - ----- -$ printf '%b' '*/python unload\n*/python autoload\n' >~/.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 - printf '%b\n' "$1" >"$fifo" - done -fi ----- - -If the script is called "auto_weechat_command", you can run it with: - ----- -$ ./auto_weechat_command 'irc.freenode.#weechat *hello' ----- - -[[fifo_commands]] -==== Commands - -include::autogen/user/fifo_commands.asciidoc[] - -[[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]://[nick[:password]@]irc.example.org[:port][/channel][,channel[...]] ----- - -Example to join _#weechat_ and _#toto_ on server _chat.freenode.net_ server, -default port (6667), with nick _nono_: - ----- -$ weechat irc://nono@chat.freenode.net/#weechat,#toto ----- - -[[irc_options]] -==== Options (irc.conf) - -Sections: - -[width="100%",cols="3m,6m,16",options="header"] -|=== -| Section | Control command | Description -| look | /set irc.look.* | Look and feel -| color | /set irc.color.* | Colors -| network | /set irc.network.* | Network options -| msgbuffer | /set irc.msgbuffer.* | <<irc_target_buffer,Target buffer for IRC messages>> (options can be added/removed in section) -| ctcp | /set irc.ctcp.* | <<irc_ctcp_replies,CTCP replies>> (options can be added/removed in section) -| ignore | <<command_irc_ignore,/ignore>> | Ignore people -| server_default | /set irc.server_default.* | Default values for servers (used when options in server are not defined) -| server | <<command_irc_server,/server>> + - /set irc.server.* | Servers -|=== - -Options: - -include::autogen/user/irc_options.asciidoc[] - -[[irc_commands]] -==== Commands - -include::autogen/user/irc_commands.asciidoc[] - -[[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 -p ~/.weechat/ssl -$ wget -O ~/.weechat/ssl/CAs.pem http://www.spi-inc.org/ca/spi-cacert.crt ----- - -[NOTE] -It is possible to concatenate many certificates in file CAs.pem. - -* In WeeChat, with "oftc" server already added: - ----- -/connect oftc ----- - -[[irc_connect_oftc_with_certfp]] -===== Second example: connect to oftc using CertFP - -* Create certificate in shell: - ----- -$ mkdir -p ~/.weechat/ssl -$ cd ~/.weechat/ssl -$ openssl req -nodes -newkey rsa:2048 -keyout nick.pem -x509 -days 365 -out nick.pem ----- - -* In WeeChat, with "oftc" server already added: - ----- -/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_sasl_authentication]] -==== SASL authentication - -WeeChat supports SASL authentication, using different mechanisms: - -* _plain_: plain text password (default) -* _ecdsa-nist256p-challenge_: challenge with public/private key -* _external_: client side SSL cert -* _dh-blowfish_: blowfish encrypted password (*insecure*, not recommended) -* _dh-aes_: AES encrypted password (*insecure*, not recommended) - -[NOTE] -The "gcrypt" library is required when compiling WeeChat in order to use -"dh-blowfish" and "dh-aes" mechanisms (see <<dependencies,dependencies>>). - -Options in servers are: - -* _sasl_mechanism_: mechanism to use (see above) -* _sasl_timeout_: timeout (in seconds) for authentication -* _sasl_fail_: action to perform if authentication fails -* _sasl_username_: username (nick) -* _sasl_password_: password -* _sasl_key_: file with ECC private key (for mechanism - _ecdsa-nist256p-challenge_) - -[[irc_sasl_ecdsa_nist256p_challenge]] -===== SASL ECDSA-NIST256P-CHALLENGE - -You must generate a private key in order to authentify with the -ECDSA-NIST256P-CHALLENGE mechanism (no password is required on connection). - -You can generate the key with this command: - ----- -$ openssl ecparam -genkey -name prime256v1 >~/.weechat/ecdsa.pem ----- - -Get the public key (encoded as base64) with this command: - ----- -$ openssl ec -noout -text -conv_form compressed -in ~/.weechat/ecdsa.pem | grep '^pub:' -A 3 | tail -n 3 | tr -d ' \n:' | xxd -r -p | base64 ----- - -Connect to the server, identify (for example with "nickserv identify") and set -your public key in your account, using nickserv (replace the base64 value with -your public key): - ----- -/connect freenode -/msg nickserv identify your_password -/msg nickserv set pubkey Av8k1FOGetUDq7sPMBfufSIZ5c2I/QYWgiwHtNXkVe/q ----- - -Configure the SASL options in the server: - ----- -/set irc.server.freenode.sasl_mechanism ecdsa-nist256p-challenge -/set irc.server.freenode.sasl_username "your_nickname" -/set irc.server.freenode.sasl_key "%h/ecdsa.pem" ----- - -Reconnect to the server: - ----- -/reconnect freenode ----- - -[[irc_tor_freenode]] -==== Connect to Freenode with TOR/SASL - -In addition to SSL, Freenode servers support connections with TOR -(https://www.torproject.org/), a network of virtual tunnels that allows people -and groups to improve their privacy and security on the Internet. - -In first place, install TOR. For Debian (and derived): - ----- -$ sudo apt-get install tor ----- - -In WeeChat you need to add a socks5 proxy for TOR service (hostname/IP and -port depend on your TOR configuration): - ----- -/proxy add tor socks5 127.0.0.1 9050 ----- - -Now, add a new server, for example: - ----- -/server add freenode-tor p4fsi4ockecnea7l.onion ----- - -Set proxy for TOR: - ----- -/set irc.server.freenode-tor.proxy "tor" ----- - -Set SASL authentication: - ----- -/set irc.server.freenode-tor.sasl_username "your_nickname" -/set irc.server.freenode-tor.sasl_password "your_password" ----- - -And finally, connection to server: - ----- -/connect freenode-tor ----- - -For more info about Freenode and TOR: http://freenode.net/irc_servers.shtml#tor - -[[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,8",options="header"] -|=== -| Code | Description | Value/example -| $clientinfo | List of supported CTCP | `ACTION DCC CLIENTINFO FINGER PING SOURCE TIME USERINFO VERSION` -| $version | WeeChat version | `0.4.0-dev` -| $versiongit | WeeChat version + git version ^(1)^ | `0.4.0-dev (git: v0.3.9-104-g7eb5cc4)` -| $git | Git version ^(1)^ | `v0.3.9-104-g7eb5cc4` -| $compilation | WeeChat compilation date | `Dec 16 2012` -| $osinfo | Info about OS | `Linux 2.6.32-5-amd64 / x86_64` -| $site | WeeChat site | `https://weechat.org/` -| $download | WeeChat site, download page | `https://weechat.org/download` -| $time | Current date/time | `Sun, 16 Dec 2012 10:40:48 +0100` -| $username | User name on IRC server | `name` -| $realname | Real name on IRC server | `John Doe` -|=== - -[NOTE] -^(1)^ The git version is the output of command `git describe`. It is known only -if WeeChat has been compiled inside the git repository and if git was installed. - -If CTCP options are not defined (by default), CTCP replies are: - -[width="100%",cols="^2,4,8",options="header"] -|=== -| CTCP | Reply format | Example -| CLIENTINFO | `$clientinfo` | `ACTION DCC CLIENTINFO FINGER PING SOURCE TIME USERINFO VERSION` -| FINGER | `WeeChat $versiongit` | `WeeChat 0.4.0-dev (git: v0.3.9-104-g7eb5cc4)` -| SOURCE | `$download` | `https://weechat.org/download` -| TIME | `$time` | `Sun, 16 Dec 2012 10:40:48 +0100` -| USERINFO | `$username ($realname)` | `name (John Doe)` -| VERSION | `WeeChat $versiongit ($compilation)` | `WeeChat 0.4.0-dev (git: v0.3.9-104-g7eb5cc4) (Dec 16 2012)` -|=== - -[[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_) - -server:: - server buffer - -weechat:: - WeeChat "core" buffer - -When option is not set (default), WeeChat chooses appropriate buffer, commonly -server or channel buffer. - -Non-comprehensive list of IRC messages or alias that you can customize: - -[width="60%",cols="^1m,^3m,8",options="header"] -|=== -| message | alias | description -| error | | error -| invite | | invited on a channel -| join | | join -| kick | | kick -| kill | | kill -| mode | | mode -| notice | | notice -| part | | part -| quit | | quit -| topic | | topic -| wallops | | wallops -| | ctcp | ctcp (sent or received, in a privmsg or notice message) -| 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) -| 328 | | channel URL -| 329 | | channel creation date -| 330 | whois | whois (logged in as) -| 331 | | no topic for channel -| 332 | | topic of channel -| 333 | | infos about topic -| 335 | whois | whois (is a bot on) -| 338 | whois | whois (host) -| 341 | | inviting -| 343 | whois | whois (is opered as) -| 344 | reop | channel reop -| 345 | reop | channel reop (end) -| 346 | invitelist | invite list -| 347 | invitelist | invite list (end) -| 348 | exceptionlist | exception list -| 349 | exceptionlist | exception list (end) -| 351 | | server version -| 352 | who | who -| 353 | names | list of users on channel -| 366 | names | end of /names list -| 367 | banlist | ban list -| 368 | banlist | end of ban list -| 369 | whowas | whowas (end) -| 378 | whois | whois (connecting from) -| 379 | whois | whois (using modes) -| 401 | whois | no such nick/channel -| 402 | whois | no such server -| 432 | | erroneous nickname -| 433 | | nickname already in use -| 438 | | not authorized to change nickname -| 671 | whois | whois (secure connection) -| 728 | quietlist | quiet list -| 729 | quietlist | end of quiet list -| 732 | monitor | list of monitored nicks -| 733 | monitor | list of monitored nicks (end) -| 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) - -Sections: - -[width="100%",cols="3m,6m,16",options="header"] -|=== -| Section | Control command | Description -| look | /set logger.look.* | Look and feel -| color | /set logger.color.* | Colors -| file | /set logger.file.* | Options for log files -| level | /set logger.level.* | Log level by buffer (options can be added/removed in section) -| mask | /set logger.mask.* | Filename mask by buffer (options can be added/removed in section) -|=== - -Options: - -include::autogen/user/logger_options.asciidoc[] - -[[logger_commands]] -==== Commands - -include::autogen/user/logger_commands.asciidoc[] - -[[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, on buffer "irc.freenode.#weechat", WeeChat will search a mask with -option name, in this order: - ----- -logger.mask.irc.freenode.#weechat -logger.mask.irc.freenode -logger.mask.irc -logger.file.mask ----- - -That means you can have masks specific for some IRC servers -("logger.mask.irc.freenode") or for a plugin ("logger.mask.irc"). - -[[logger_files_by_date]] -===== Log files by date - -To have log files by date, you can use date/time specifiers in mask (see -`man strftime` for formats), for example: - ----- -/set logger.file.mask "%Y/%m/$plugin.$name.weechatlog" ----- - -You'll have following files: - -.... -~/.weechat/ - |--- logs/ - |--- 2010/ - |--- 11/ - | irc.server.freenode.weechatlog - | irc.freenode.#weechat.weechatlog - |--- 2010/ - |--- 12/ - | irc.server.freenode.weechatlog - | irc.freenode.#weechat.weechatlog -.... - -[[logger_irc_files_by_server_channel]] -===== IRC log files by server and channel - -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 -.... - -[[relay_plugin]] -=== Relay plugin - -The Relay plugin is used to relay data via network, using different protocols: - -* _irc_: IRC proxy: used to share connections to IRC servers with one or many - other IRC clients -* _weechat_: protocol used by remote interfaces to display and interact with - WeeChat (for example QWeeChat or weechat-android) - -[[relay_options]] -==== Options (relay.conf) - -Sections: - -[width="100%",cols="3m,6m,16",options="header"] -|=== -| Section | Control command | Description -| look | /set relay.look.* | Look and feel -| color | /set relay.color.* | Colors -| network | /set relay.network.* | Network options -| irc | /set relay.irc.* | Options specific to irc protocol (irc proxy) -| port | <<command_relay_relay,/relay add>> + - /set relay.port.* | Ports used for relay (irc and weechat protocols) (options can be added/removed in section) -|=== - -Options: - -include::autogen/user/relay_options.asciidoc[] - -[[relay_commands]] -==== Commands - -include::autogen/user/relay_commands.asciidoc[] - -[[relay_password]] -==== Password - -It is highly recommended to set a password for relay, with command: - ----- -/set relay.network.password "mypassword" ----- - -This password is used for _irc_ and _weechat_ protocols. - -[[relay_ssl]] -==== SSL - -You can use SSL by creating a certificate and private key, and by using prefix -"ssl." in the name of protocol. - -The default file for certificate/key is _~/.weechat/ssl/relay.pem_ -(option <<option_relay.network.ssl_cert_key,relay.network.ssl_cert_key>>). - -You can create a certificate and private key with following commands: - ----- -$ mkdir -p ~/.weechat/ssl -$ cd ~/.weechat/ssl -$ openssl req -nodes -newkey rsa:2048 -keyout relay.pem -x509 -days 365 -out relay.pem ----- - -If WeeChat is already running, you can reload the certificate and private key -with command: - ----- -/relay sslcertkey ----- - -[[relay_irc_proxy]] -==== IRC proxy - -The Relay plugin can act as an IRC proxy: it will simulate an IRC server, and -you can connect to WeeChat with any other IRC client (including WeeChat itself). - -You can define one port by IRC server, or one generic port for all servers. - -When using one port for all servers, the client must send the internal name of -server in the IRC "PASS" command, with this format: - ----- -PASS server:password ----- - -Example: IRC proxy with SSL for any server (client will choose): - ----- -/relay add ssl.irc 8000 ----- - -Example: IRC proxy without SSL only for server "freenode": - ----- -/relay add irc.freenode 8000 ----- - -Now you can connect on port 8000 with any IRC client using server password -"mypassword" (or "freenode:mypassword" if no server was specified in the relay). - -[[relay_weechat_protocol]] -==== WeeChat protocol - -The Relay plugin can send data to remote interface using WeeChat protocol. - -You can connect with a remote interface, see the list on download page: -https://weechat.org/download - -[IMPORTANT] -WeeChat itself can NOT connect to another WeeChat with this protocol. - -For example: - ----- -/relay add weechat 9000 ----- - -Now you can connect on port 9000 with a remote interface using password -"mypassword". - -[[relay_websocket]] -==== WebSocket - -WebSocket protocol (http://tools.ietf.org/html/rfc6455[RFC 6455]) is supported -in Relay plugin for all protocols. - -The WebSocket handshake is automatically detected and socket becomes ready for -WebSocket if required headers are found in handshake and if origin is allowed -(see option -<<option_relay.network.websocket_allowed_origins,relay.network.websocket_allowed_origins>>). - -A WebSocket can be opened in a HTML5 with a single line of JavaScript: - -[source,js] ----- -websocket = new WebSocket("ws://server.com:9000/weechat"); ----- - -The port (9000 in example) is the port defined in Relay plugin. -The URI must always end with "/weechat" (for _irc_ and _weechat_ protocols). - -[[scripts_plugins]] -=== Scripts plugins - -WeeChat provides 7 scripting plugins: Python, Perl, Ruby, Lua, Tcl, Guile -(scheme) and Javascript. -These plugins can load, execute and unload scripts for these languages. - -Another plugin called "script" is a scripts manager and is used to load/unload -scripts of any language, and install/remove scripts of WeeChat scripts -repository, which are visible at this URL: https://weechat.org/scripts - -For more information about how to write scripts, or WeeChat API for -scripts, please read _WeeChat Scripting Guide_. - -[[script_options]] -==== Script options (script.conf) - -Sections: - -[width="100%",cols="3m,6m,16",options="header"] -|=== -| Section | Control command | Description -| look | /set script.look.* | Look and feel -| color | /set script.color.* | Colors -| scripts | /set script.scripts.* | Options for download of scripts -|=== - -Options: - -include::autogen/user/script_options.asciidoc[] - -[[script_commands]] -==== Script commands - -include::autogen/user/script_commands.asciidoc[] - -[[python_commands]] -==== Python commands - -include::autogen/user/python_commands.asciidoc[] - -[[perl_commands]] -==== Perl commands - -include::autogen/user/perl_commands.asciidoc[] - -[[ruby_commands]] -==== Ruby commands - -include::autogen/user/ruby_commands.asciidoc[] - -[[lua_commands]] -==== Lua commands - -include::autogen/user/lua_commands.asciidoc[] - -[[tcl_commands]] -==== Tcl commands - -include::autogen/user/tcl_commands.asciidoc[] - -[[guile_commands]] -==== Guile commands - -include::autogen/user/guile_commands.asciidoc[] - -[[javascript_commands]] -==== Javascript commands - -include::autogen/user/javascript_commands.asciidoc[] - -[[trigger_plugin]] -=== Trigger plugin - -Trigger is the Swiss Army knife for WeeChat: it can hook many things (signal, -modifier, print, ...), change the content of data, and execute one or more -commands. A condition can be used to prevent the trigger to run in some -circumstances. - -Using triggers require you to know how the signals, modifiers, ... are working. -So you might consider reading the _Hooks_ chapter in the -_WeeChat Plugin API Reference_. - -[[trigger_options]] -==== Options (trigger.conf) - -Sections: - -[width="100%",cols="3m,6m,16",options="header"] -|=== -| Section | Control command | Description -| look | /set trigger.look.* | Look and feel -| color | /set trigger.color.* | Colors -| trigger | <<command_trigger_trigger,/trigger add>> + - <<command_trigger_trigger,/trigger set>> + - /set trigger.trigger.* | Trigger options -|=== - -Options: - -include::autogen/user/trigger_options.asciidoc[] - -[[trigger_commands]] -==== Commands - -include::autogen/user/trigger_commands.asciidoc[] - -[[trigger_anatomy]] -==== Anatomy of a trigger - -A trigger has the following options (names are -`trigger.trigger.<name>.<option>`): - -[width="100%",cols="2m,2,10",options="header"] -|=== -| Option | Values | Description - -| enabled | `on`, `off` | - When option is `off`, the trigger is disabled and actions are not executed - any more. - -| hook | `signal`, `hsignal`, `modifier`, `print`, `command`, `command_run`, - `timer`, `config`, `focus` | - The hook used in trigger. For more information, see - _WeeChat Plugin API Reference_, chapter _Hooks_. - -| arguments | string | - The arguments for the hook, it depends on the hook type used. - -| conditions | string | - Conditions to execute the trigger; they are evaluated (see command - <<command_weechat_eval,/eval>>). - -| regex | string | - One or more POSIX extended regular expressions, to change data received in the - hook callback (and some stuff added by trigger plugin), see - <<trigger_regex,regular expression>>. - -| command | string | - Command to execute (many commands can be separated by semicolons); it is - evaluated (see command <<command_weechat_eval,/eval>>). - -| return_code | `ok`, `ok_eat`, `error` | - The return code of callback (default is `ok`, which should be used in almost - all triggers, the other values are rarely used). -|=== - -For example, the default _beep_ trigger has following options: - ----- -trigger.trigger.beep.enabled = on -trigger.trigger.beep.hook = print -trigger.trigger.beep.arguments = "" -trigger.trigger.beep.conditions = "${tg_highlight} || ${tg_msg_pv}" -trigger.trigger.beep.regex = "" -trigger.trigger.beep.command = "/print -beep" -trigger.trigger.beep.return_code = ok ----- - -[[trigger_execution]] -==== Execution - -When a trigger callback is called, following actions are executed, in this -order, if triggers are globally enabled and if the trigger itself is enabled: - -. check trigger conditions: if false, exit -. replace text in trigger using regular expression(s) -. execute command(s) -. exit with a return code (except for hooks _modifier_ and _focus_). - -[[trigger_hook_arguments]] -==== Hook arguments - -The arguments depend on the hook used. They are separated by semicolons. - -[width="100%",cols="2,6,7",options="header"] -|=== -| Hook | Arguments | Examples - -| signal | - 1. signal name (priority allowed) (required) + - 2. signal name (priority allowed) + - 3. ... | - `*,irc_in_privmsg` + - `*,irc_in_privmsg;*,irc_in_notice` + - `signal_sigwinch` - -| hsignal | - 1. signal name (priority allowed) (required) + - 2. signal name (priority allowed) + - 3. ... | - `nicklist_nick_added` - -| modifier | - 1. modifier name (priority allowed) (required) + - 2. modifier name (priority allowed) + - 3. ... | - `weechat_print` + - `5000\|input_text_display;5000\|history_add` - -| print | - 1. buffer name + - 2. tags + - 3. message + - 4. strip colors (0/1) | - `irc.freenode.*` + - `irc.freenode.#weechat` + - `irc.freenode.#weechat;irc_notice` + - `*;;;1` - -| command | - 1. command name (priority allowed) (required) + - 2. description + - 3. arguments + - 4. description of arguments + - 5. completion | - `test` + - `5000\|test` - -| command_run | - 1. command (priority allowed) (required) + - 2. command (priority allowed) + - 3. ... | - `/cmd arguments` - -| timer | - 1. interval in milliseconds (required) + - 2. alignment on second (default: 0) + - 3. max number of calls (default: 0, which means "no end") | - `3600000` + - `60000;0;5` - -| config | - 1. option name (priority allowed) (required) + - 2. option name (priority allowed) + - 3. ... | - `+weechat.look.*+` - -| focus | - 1. area name (priority allowed) (required) + - 2. area name (priority allowed) + - 3. ... | - `buffer_nicklist` -|=== - -[[trigger_conditions]] -==== Conditions - -The conditions are used to continue processing in trigger, or stop everything. - -They are evaluated, and data available in callback can be used -(see <<trigger_callback_data,data in callbacks>> and command -<<command_weechat_eval,/eval>>). - -Example: the default _beep_ trigger uses this condition to make a beep only on -highlight or private message: - ----- -${tg_highlight} || ${tg_msg_pv} ----- - -[[trigger_regex]] -==== Regular expression - -The regular expression is used to change variables in callback hashtable. - -The format is: "/regex/replace" or "/regex/replace/var" (where _var_ is a -variable of the hashtable). + -If _var_ is not specified, the default variable is used, it depends on hook -type: - -[width="50%",cols="4,5m",options="header"] -|=== -| Hook | Default variable -| signal | tg_signal_data -| hsignal | -| modifier | tg_string -| print | tg_message -| command | tg_argv_eol1 -| command_run | tg_command -| timer | tg_remaining_calls -| config | tg_value -| focus | -|=== - -Many regular expressions can be separated by a space, for example: -"/regex1/replace1/var1 /regex2/replace2/var2". - -The char "/" can be replaced by any char (one or more identical chars). - -Matching groups can be used in "replace": - -* `${re:0}` to `${re:99}`: `${re:0}` is the whole match, `${re:1}` to - `${re:99}` are groups captured -* `${re:+}`: the last match (with highest number) -* `${hide:c,${re:N}}`: match "N" with all chars replaced by "c" - (example: `+${hide:*,${re:2}}+` is the group #2 with all chars replaced by - `+*+`). - -Example: use bold for words between "*": - ----- -/\*(\S+)\*/*${color:bold}${re:1}${color:-bold}*/ ----- - -Example: default trigger _server_pass_ uses this regular expression to hide -password in commands `/server` and `/connect` (chars in passwords are replaced -by `+*+`): - ----- -==^(/(server|connect) .*-(sasl_)?password=)(\S+)(.*)==${re:1}${hide:*,${re:4}}${re:5} ----- - -[NOTE] -In this example, the delimiter used is "==" because there is a "/" in the -regular expression. - -[[trigger_command]] -==== Command - -The command is executed after replacement of text with the regular expression. -Many commands can be separated by semicolons. - -It is evaluated (see command <<command_weechat_eval,/eval>>) and text replaced -with a regular expression can be used in the command. - -Example: default _beep_ trigger uses this command to make a beep (BEL): - ----- -/print -beep ----- - -[[trigger_callback_data]] -==== Data in callbacks - -Data received in callbacks are stored in hashtables (pointers and strings) and -can be used in following options: - -* _conditions_ -* _regex_ -* _command_ - -The content of hashtables depend on the hook type. - -A convenient way to see data in a trigger is to open trigger monitor buffer, -using the command: - ----- -/trigger monitor ----- - -[[trigger_data_signal]] -===== Signal - -The "signal" callback sets following variables in hashtable: - -[width="100%",cols="3m,2,14",options="header"] -|=== -| Variable | Type | Description -| tg_signal | string | Name of signal -| tg_signal_data | string | Data sent with the signal -|=== - -If the signal contains an IRC message, the message is parsed and following data -is added in hashtable: - -[width="100%",cols="3m,2,14",options="header"] -|=== -| Variable | Type | Description -| server | string | Name of server (example: "freenode") -| tags | string | Tags in message (rarely used) -| message_without_tags | string | Message without tags -| nick | string | Nick -| host | string | Hostname -| command | string | IRC command (example: "PRIVMSG", "NOTICE", ...) -| channel | string | IRC channel -| arguments | string | Arguments of command (includes value of _channel_) -| text | string | Text (for example user message) -| pos_command | string | The index of _command_ in message ("-1" if _command_ was not found) -| pos_arguments | string | The index of _arguments_ in message ("-1" if _arguments_ was not found) -| pos_channel | string | The index of _channel_ in message ("-1" if _channel_ was not found) -| pos_text | string | The index of _text_ in message ("-1" if _text_ was not found) -|=== - -When the data is a pointer, the variable `tg_signal_data` can be used like this -to read a hdata property (in this example this is a pointer on a buffer): - ----- -${buffer[${tg_signal_data}].full_name} ----- - -[[trigger_data_hsignal]] -===== Hsignal - -The "hsignal" callback sets following variables in hashtable: - -[width="100%",cols="3m,2,14",options="header"] -|=== -| Variable | Type | Description -| tg_signal | string | Name of signal -|=== - -The hashtable contains all keys/values from hashtable received (type: -string/string). - -[[trigger_data_modifier]] -===== Modifier - -The "modifier" callback sets following variables in hashtable: - -[width="100%",cols="3m,2,14",options="header"] -|=== -| Variable | Type | Description -| tg_modifier | string | Name of modifier -| tg_modifier_data | string | Data sent with modifier -| tg_string | string | The string that can be modified -| tg_string_nocolor | string | The string without color codes -|=== - -For the _weechat_print_ modifier, variables using message tags are added (see -<<trigger_data_print,hook print>> below), and following variables: - -[width="100%",cols="3m,2,14",options="header"] -|=== -| Variable | Type | Description -| buffer | pointer | Buffer where message is printed -| tg_plugin | string | Plugin of buffer where message is printed -| tg_buffer | string | Full name of buffer where message is printed -| tg_prefix | string | Prefix of message printed -| tg_prefix_nocolor | string | Prefix without color codes -| tg_message | string | Message printed -| tg_message_nocolor | string | Message without color codes -|=== - -If the modifier contains an IRC message, the message is parsed and extra data is -added in hashtable (see <<trigger_data_signal,hook signal>>). - -[[trigger_data_print]] -===== Print - -The "print" callback sets following variables in hashtable: - -[width="100%",cols="3m,2,14",options="header"] -|=== -| Variable | Type | Description -| buffer | pointer | Buffer -| tg_date | string | Message date/time (format: `YYYY-MM-DD hh:mm:ss`) -| tg_displayed | string | "1" if displayed, "0" if line filtered -| tg_highlight | string | "1" if highlight, otherwise "0" -| tg_prefix | string | Prefix -| tg_prefix_nocolor | string | Prefix without color codes -| tg_message | string | Message -| tg_message_nocolor | string | Message without color codes -|=== - -Variables set using tags in message (they are set in modifier _weechat_print_ -too): - -[width="100%",cols="3m,2,14",options="header"] -|=== -| Variable | Type | Description -| tg_tags | string | Tags of message (with comma added at beginning/end of string) -| tg_tags_count | string | Number of tags in message -| tg_tag_nick | string | Nick (from tag "nick_xxx") -| tg_tag_prefix_nick | string | Color of nick in prefix (from tag "prefix_nick_ccc") -| tg_tag_host | string | User name and host, format: username@host (from tag "host_xxx") -| tg_tag_notify | string | Notify level (_none_, _message_, _private_, _highlight_) -| tg_notify | string | Notify level, if different from _none_ -| tg_msg_pv | string | "1" for a private message, otherwise "0" -|=== - -[[trigger_data_command]] -===== Command - -The "command" callback sets following variables in hashtable: - -[width="100%",cols="3m,2,14",options="header"] -|=== -| Variable | Type | Description -| buffer | pointer | Buffer -| tg_argvN | string | Argument #N -| tg_argv_eolN | string | From argument #N until end of arguments -|=== - -[[trigger_data_command_run]] -===== Command_run - -The "command_run" callback sets following variables in hashtable: - -[width="100%",cols="3m,2,14",options="header"] -|=== -| Variable | Type | Description -| buffer | pointer | Buffer -| tg_command | string | Command executed -|=== - -[[trigger_data_timer]] -===== Timer - -The "timer" callback sets following variables in hashtable: - -[width="100%",cols="3m,2,14",options="header"] -|=== -| Variable | Type | Description -| tg_remaining_calls | string | Number of remaining calls -| tg_date | string | Current date/time (format: `YYYY-MM-DD hh:mm:ss`) -|=== - -[[trigger_data_config]] -===== Config - -The "config" callback sets following variables in hashtable: - -[width="100%",cols="3m,2,14",options="header"] -|=== -| Variable | Type | Description -| tg_option | string | Option -| tg_value | string | Value -|=== - -[[trigger_data_focus]] -===== Focus - -The "focus" callback sets following variables in hashtable: - -[width="100%",cols="3m,2,14",options="header"] -|=== -| Variable | Type | Description -| window | pointer | Window -| buffer | pointer | Buffer -|=== - -The hashtable contains all keys/values from hashtable received (type: -string/string). - -[[trigger_examples]] -==== Examples - -[[trigger_example_url_color]] -===== Color for URLs - -Display URLs in green: - ----- -/trigger add url_color modifier weechat_print "${tg_notify}" "==\S+://\S+==${color:green}${re:0}${color:reset}==" ----- - -[NOTE] -The simple regex used to detect URL may not catch well all URLs, but it is -faster than a complex regex. - -[[trigger_example_auto_pong]] -===== Auto pong on ping queries - -When someone sends a "ping" in a private buffer, this trigger will auto-reply -with `pong`: - ----- -/trigger add pong print "" "${type} == private && ${tg_message} == ping" "" "pong" ----- - -[[trigger_example_responsive_layout]] -===== Responsive layout - -Following triggers can be used to customize things displayed when the size of -terminal is changed: - ----- -/trigger add resize_small signal signal_sigwinch "${info:term_width} < 100" "" "/bar hide nicklist" -/trigger add resize_big signal signal_sigwinch "${info:term_width} >= 100" "" "/bar show nicklist" ----- - -The triggers catch the signal "signal_sigwinch", which is sent by WeeChat when -signal SIGWINCH is received (when terminal size is changed). - -The condition with `${info:term_width}` checks the width of terminal (you can -also use `${info:term_height}` if needed). - -In the example, when the terminal becomes small, the nicklist is hidden. And the -bar is restored when the width is greater or equal to 100 chars. - -[[trigger_example_config_save]] -===== Automatic save of configuration - -You can automatically save configuration files (`*.conf`), for example each -hour: - ----- -/trigger add cfgsave timer 3600000;0;0 "" "" "/mute /save" ----- - -Arguments for the timer hook are: - -* _3600000_: 3600 * 1000 milliseconds, the callback is called each hour -* _0_: alignment on second (not aligned here) -* _0_: max number of calls (0 = no end for the timer) - -The command `/mute /save` will silently save configuration files (nothing -displayed on core buffer). - -[[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) - -Sections: - -[width="100%",cols="3m,6m,16",options="header"] -|=== -| Section | Control command | Description -| look | /set xfer.look.* | Look and feel -| color | /set xfer.color.* | Colors -| network | /set xfer.network.* | Network options -| file | /set xfer.file.* | Options for files sent/received -|=== - -Options: - -include::autogen/user/xfer_options.asciidoc[] - -[[xfer_commands]] -==== Commands - -include::autogen/user/xfer_commands.asciidoc[] - -[[support]] -== Support - -Before asking for support, be sure you've read documentation and FAQ provided -with WeeChat. - -For support with IRC, on server _chat.freenode.net_: - -* official channels (with developers): -** _#weechat_ (English) -** _#weechat-fr_ (French) -* non-official channels: -** _#weechat-de_ (German) - -For other ways of support, see: https://weechat.org/dev/support |