doc: move section "Key bindings" at top level, add section title "Configuration" (user's guide)

1 files changed, 538 insertions, 529 deletions

diff --git a/doc/en/weechat_user.en.adoc b/doc/en/weechat_user.en.adoc
index d435972a2..bd9c412a0 100644
--- a/doc/en/weechat_user.en.adoc
+++ b/doc/en/weechat_user.en.adoc
@@ -631,6 +631,53 @@ Some environment variables are used by WeeChat if they are defined:
 | WEECHAT_EXTRA_LIBDIR | An extra directory to load plugins (from the "plugins" directory in this path).
 |===
 
+[[colors_support]]
+=== Colors support
+
+WeeChat can use up to 32767 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="75%",cols="8,>3,>3",options="header"]
+|===
+| $TERM                                  | Colors | Pairs
+| "rxvt-unicode", "xterm", ...           |     88 | 32767
+| "rxvt-256color", "xterm-256color", ... |    256 | 32767
+| "screen"                               |      8 |    64
+| "screen-256color"                      |    256 | 32767
+| "tmux"                                 |      8 |    64
+| "tmux-256color"                        |    256 | 32767
+|===
+
+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
+----
+
 [[files_and_directories]]
 === Files and directories
 
@@ -959,151 +1006,6 @@ kbd:[!]
 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 32767 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="75%",cols="8,>3,>3",options="header"]
-|===
-| $TERM                                  | Colors | Pairs
-| "rxvt-unicode", "xterm", ...           |     88 | 32767
-| "rxvt-256color", "xterm-256color", ... |    256 | 32767
-| "screen"                               |      8 |    64
-| "screen-256color"                      |    256 | 32767
-| "tmux"                                 |      8 |    64
-| "tmux-256color"                        |    256 | 32767
-|===
-
-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="75%",cols="1m,4",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
-----
-
 [[buffers_and_windows]]
 === Buffers and windows
 
@@ -1426,233 +1328,6 @@ By default WeeChat and its default plugins interpret these variables:
 [NOTE]
 External plugins and scripts can define and use other local variables.
 
-[[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. The default bar _buflist_ has type `root`. +
-  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 default bars _title_, _status_,
-  _input_ and _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/libera.#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/libera] 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/libera] 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 terminal is > 100:
-
-----
-/set weechat.bar.nicklist.conditions "${nicklist} && ${info:term_width} > 100"
-----
-
-Same condition, but always display nicklist on buffer _&bitlbee_
-(even if terminal is small):
-
-----
-/set weechat.bar.nicklist.conditions "${nicklist} && (${info:term_width} > 100 || ${buffer.full_name} == irc.bitlbee.&bitlbee)"
-----
-
 [[bare_display]]
 === Bare display
 
@@ -1740,155 +1415,17 @@ The screen will look like that in bare display:
 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
-
-[[setup_notify_levels]]
-==== Setup 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="75%",cols="2m,7",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 "libera":
-
-----
-/set weechat.notify.irc.libera message
-----
-
-Set notify level _highlight_ on channel "#weechat" only:
-
-----
-/set weechat.notify.irc.libera.#weechat highlight
-----
-
-The notify level for a buffer can be set with command `/buffer`:
-
-----
-/buffer notify highlight
-----
-
-[[max_hotlist_level_nicks]]
-==== Max hotlist level for nicks
-
-It is possible to set max hotlist level for some nicks, per buffer, or per group
-of buffers (like IRC servers).
-
-The buffer property "hotlist_max_level_nicks" can be set with a list of nicks
-and for each nick the max hotlist level to trigger, possible levels are:
-
-* -1: no hotlist changes for nick
-* 0: low priority (like join/part messages)
-* 1: message
-* 2: private message
-* 3: highlight (in fact useless, since it's already the default max for all messages)
-
-For example to disable highlights from "joe" and "mike" on current buffer:
-
-----
-/buffer set hotlist_max_level_nicks_add joe:2,mike:2
-----
-
-[NOTE]
-The buffer property "hotlist_max_level_nicks" is not saved in configuration. +
-You can easily save it with the script _buffer_autoset.py_: you can install it
-with `+/script install buffer_autoset.py+` and get help with
-`+/help buffer_autoset+`.
-
-[[highlights]]
-=== Highlights
-
-[[highlights_words]]
-==== Add words to highlight
-
-By default, WeeChat highlights messages from other users containing your nick,
-therefore the highlight depends on the buffer (the nick can be different from
-one buffer to another).
-
-You can add other words to highlight with the option
-<<option_weechat.look.highlight,weechat.look.highlight>>, for example to
-highlight your nick and "word1", "word2" and all words beginning with "test":
-
-----
-/set weechat.look.highlight word1,word2,test*
-----
-
-If you need a more specific rule for the word, you can use regular expressions
-with the option <<option_weechat.look.highlight_regex,weechat.look.highlight_regex>>,
-for example to highlight words "flashcode", "flashcöde" and "flashy":
-
-----
-/set weechat.look.highlight_regex flashc[oö]de|flashy
-----
-
-The delimiters around words to highlight can be customized with the option
-<<option_weechat.look.word_chars_highlight,weechat.look.word_chars_highlight>>.
-
-[[highlights_tags]]
-==== Add tags to highlight
-
-Lines displayed can contain "tags", which give some info about the origin of
-message or the message itself. +
-You can display tags with the command `/debug tags` (same command to hide them).
-
-You can add specific tags to highlight with the option
-<<option_weechat.look.highlight_tags,weechat.look.highlight_tags>>.
-Tags are separated by commas, and multiple tags can be separated by `+++` to do
-a logical "and" between them.
-
-For example to highlight all messages from nick "FlashCode" and all notices
-from nicks beginning with "toto":
-
-----
-/set weechat.look.highlight_tags "nick_flashcode,irc_notice+nick_toto*"
-----
-
-[[highlights_regex_buffer]]
-==== Set extra highlights on buffer
-
-You can force highlight using a regular expression with the buffer property
-"highlight_regex".
-
-For example to force the highlight on all messages in the current buffer:
-
-----
-/buffer set highlight_regex .*
-----
-
-[NOTE]
-The buffer property "highlight_regex" is not saved in configuration. +
-You can easily save it with the script _buffer_autoset.py_: you can install it
-with `+/script install buffer_autoset.py+` and get help with
-`+/help buffer_autoset+`.
-
 [[key_bindings]]
-=== Default key bindings
+== Key bindings
+
+WeeChat provides a lot of default key bindings, listed in the following chapters. +
+They can be changed and new ones can be added with the <<command_weechat_key,/key>> command.
 
 [[key_bindings_cmdline]]
-==== Command line
+=== Command line
 
 [[key_bindings_cmdline_cursor_movement]]
-===== Cursor movement
+==== Cursor movement
 
 [width="100%",cols="^.^3,.^8,.^5",options="header"]
 |===
@@ -1908,7 +1445,7 @@ with `+/script install buffer_autoset.py+` and get help with
 |===
 
 [[key_bindings_cmdline_editing]]
-===== Editing
+==== Editing
 
 [width="100%",cols="^.^3,.^8,.^5",options="header"]
 |===
@@ -1936,7 +1473,7 @@ with `+/script install buffer_autoset.py+` and get help with
 |===
 
 [[key_bindings_cmdline_color_codes]]
-===== Color codes
+==== Color codes
 
 [width="100%",cols="^.^3,.^8,.^5",options="header"]
 |===
@@ -1950,7 +1487,7 @@ with `+/script install buffer_autoset.py+` and get help with
 |===
 
 [[key_bindings_cmdline_history]]
-===== Command history
+==== Command history
 
 [width="100%",cols="^.^3,.^8,.^5",options="header"]
 |===
@@ -1962,7 +1499,7 @@ with `+/script install buffer_autoset.py+` and get help with
 |===
 
 [[key_bindings_buffers]]
-==== Buffers
+=== Buffers
 
 [width="100%",cols="^.^3,.^8,.^5",options="header"]
 |===
@@ -2000,7 +1537,7 @@ with `+/script install buffer_autoset.py+` and get help with
 |===
 
 [[key_bindings_windows]]
-==== Windows
+=== Windows
 
 [width="100%",cols="^.^3,.^8,.^5",options="header"]
 |===
@@ -2019,7 +1556,7 @@ with `+/script install buffer_autoset.py+` and get help with
 |===
 
 [[key_bindings_bars]]
-==== Bars
+=== Bars
 
 [width="100%",cols="^.^3,.^8,.^5",options="header"]
 |===
@@ -2043,7 +1580,7 @@ with `+/script install buffer_autoset.py+` and get help with
 |===
 
 [[key_bindings_hotlist]]
-==== Hotlist
+=== Hotlist
 
 [width="100%",cols="^.^3,.^8,.^5",options="header"]
 |===
@@ -2056,7 +1593,7 @@ with `+/script install buffer_autoset.py+` and get help with
 |===
 
 [[key_bindings_toggle_keys]]
-==== Toggle keys
+=== Toggle keys
 
 [width="100%",cols="^.^3,.^8,.^5",options="header"]
 |===
@@ -2068,7 +1605,7 @@ with `+/script install buffer_autoset.py+` and get help with
 |===
 
 [[key_bindings_search_context]]
-==== Search context
+=== Search context
 
 These keys are used in context "search" (when kbd:[Ctrl+r] is pressed to search
 text in buffer).
@@ -2088,7 +1625,7 @@ text in buffer).
 |===
 
 [[key_bindings_cursor_context]]
-==== Cursor context
+=== Cursor context
 
 These keys are used in context "cursor" (free movement of cursor on screen).
 
@@ -2117,7 +1654,7 @@ These keys are used in context "cursor" (free movement of cursor on screen).
 |===
 
 [[key_bindings_mouse]]
-==== Mouse
+=== Mouse
 
 These mouse actions are possible only if mouse is enabled with key kbd:[Alt+m]
 (command: `+/mouse toggle+`).
@@ -2170,7 +1707,7 @@ These mouse actions are possible only if mouse is enabled with key kbd:[Alt+m]
 ^(1)^ kbd:[▲] and kbd:[▼] are wheel up and down.
 
 [[key_bindings_fset_buffer]]
-==== Fset buffer
+=== Fset buffer
 
 These keys and actions are used on the fset buffer (see <<fset_plugin,Fset plugin>>).
 
@@ -2216,7 +1753,7 @@ These keys and actions are used on the fset buffer (see <<fset_plugin,Fset plugi
 ^(1)^ The action must be entered as input on the command line, followed by kbd:[Enter].
 
 [[key_bindings_script_buffer]]
-==== Script buffer
+=== Script buffer
 
 These keys and actions are used on the script buffer (see <<scripts_plugins,Script plugin>>).
 
@@ -2239,6 +1776,251 @@ These keys and actions are used on the script buffer (see <<scripts_plugins,Scri
 [NOTE]
 ^(1)^ The action must be entered as input on the command line, followed by kbd:[Enter].
 
+[[configuration]]
+== Configuration
+
+[[colors]]
+=== Colors
+
+[[colors_basic]]
+==== Basic colors
+
+Basic colors in WeeChat are:
+
+[width="75%",cols="1m,4",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
+----
+
+[[notify_levels]]
+=== Notify levels
+
+[[setup_notify_levels]]
+==== Setup 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="75%",cols="2m,7",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 "libera":
+
+----
+/set weechat.notify.irc.libera message
+----
+
+Set notify level _highlight_ on channel "#weechat" only:
+
+----
+/set weechat.notify.irc.libera.#weechat highlight
+----
+
+The notify level for a buffer can be set with command `/buffer`:
+
+----
+/buffer notify highlight
+----
+
+[[max_hotlist_level_nicks]]
+==== Max hotlist level for nicks
+
+It is possible to set max hotlist level for some nicks, per buffer, or per group
+of buffers (like IRC servers).
+
+The buffer property "hotlist_max_level_nicks" can be set with a list of nicks
+and for each nick the max hotlist level to trigger, possible levels are:
+
+* -1: no hotlist changes for nick
+* 0: low priority (like join/part messages)
+* 1: message
+* 2: private message
+* 3: highlight (in fact useless, since it's already the default max for all messages)
+
+For example to disable highlights from "joe" and "mike" on current buffer:
+
+----
+/buffer set hotlist_max_level_nicks_add joe:2,mike:2
+----
+
+[NOTE]
+The buffer property "hotlist_max_level_nicks" is not saved in configuration. +
+You can easily save it with the script _buffer_autoset.py_: you can install it
+with `+/script install buffer_autoset.py+` and get help with
+`+/help buffer_autoset+`.
+
+[[highlights]]
+=== Highlights
+
+[[highlights_words]]
+==== Add words to highlight
+
+By default, WeeChat highlights messages from other users containing your nick,
+therefore the highlight depends on the buffer (the nick can be different from
+one buffer to another).
+
+You can add other words to highlight with the option
+<<option_weechat.look.highlight,weechat.look.highlight>>, for example to
+highlight your nick and "word1", "word2" and all words beginning with "test":
+
+----
+/set weechat.look.highlight word1,word2,test*
+----
+
+If you need a more specific rule for the word, you can use regular expressions
+with the option <<option_weechat.look.highlight_regex,weechat.look.highlight_regex>>,
+for example to highlight words "flashcode", "flashcöde" and "flashy":
+
+----
+/set weechat.look.highlight_regex flashc[oö]de|flashy
+----
+
+The delimiters around words to highlight can be customized with the option
+<<option_weechat.look.word_chars_highlight,weechat.look.word_chars_highlight>>.
+
+[[highlights_tags]]
+==== Add tags to highlight
+
+Lines displayed can contain "tags", which give some info about the origin of
+message or the message itself. +
+You can display tags with the command `/debug tags` (same command to hide them).
+
+You can add specific tags to highlight with the option
+<<option_weechat.look.highlight_tags,weechat.look.highlight_tags>>.
+Tags are separated by commas, and multiple tags can be separated by `+++` to do
+a logical "and" between them.
+
+For example to highlight all messages from nick "FlashCode" and all notices
+from nicks beginning with "toto":
+
+----
+/set weechat.look.highlight_tags "nick_flashcode,irc_notice+nick_toto*"
+----
+
+[[highlights_regex_buffer]]
+==== Set extra highlights on buffer
+
+You can force highlight using a regular expression with the buffer property
+"highlight_regex".
+
+For example to force the highlight on all messages in the current buffer:
+
+----
+/buffer set highlight_regex .*
+----
+
+[NOTE]
+The buffer property "highlight_regex" is not saved in configuration. +
+You can easily save it with the script _buffer_autoset.py_: you can install it
+with `+/script install buffer_autoset.py+` and get help with
+`+/help buffer_autoset+`.
+
 [[mouse]]
 === Mouse support
 
@@ -2358,6 +2140,233 @@ any gesture made using left button.
 You can find an event name with command `+/input grab_mouse+` then doing event
 with mouse. This will insert event name on command line.
 
+[[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. The default bar _buflist_ has type `root`. +
+  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 default bars _title_, _status_,
+  _input_ and _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/libera.#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/libera] 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/libera] 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 terminal is > 100:
+
+----
+/set weechat.bar.nicklist.conditions "${nicklist} && ${info:term_width} > 100"
+----
+
+Same condition, but always display nicklist on buffer _&bitlbee_
+(even if terminal is small):
+
+----
+/set weechat.bar.nicklist.conditions "${nicklist} && (${info:term_width} > 100 || ${buffer.full_name} == irc.bitlbee.&bitlbee)"
+----
+
 [[secured_data]]
 === Secured data