Add doc about 256 colors in user guide and FAQ

9 files changed, 568 insertions, 46 deletions

diff --git a/doc/de/weechat_faq.de.txt b/doc/de/weechat_faq.de.txt
index 46a652a55..b51d4381a 100644
--- a/doc/de/weechat_faq.de.txt
+++ b/doc/de/weechat_faq.de.txt
@@ -221,7 +221,7 @@ Hier findet man eine Auflistung von Skripten die sich mit URLs befassen: http://
 Ich möchte die Meldungen von Weechat in einer anderen Sprache ausgeben lassen, ohne WeeChat zu beenden. Ist dies möglich?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Ja, dazu kannst Du das Python-Skript shell.py verwenden (erhältlich auf der
+Ja, dazu kannst Du das Python-Skript 'shell.py' verwenden (erhältlich auf der
 Internetseite). Nach dem Laden des Skripts führe folgende Befehle aus:
 
 ----------------------------------------
@@ -234,6 +234,32 @@ Benutzer von ISO-Kodierungen können folgendes eingeben:
 `/shell setenv LANG=en_US`.
 
 
+// TRANSLATION MISSING
+[[256_colors]]
+How can I use 256 colors in WeeChat?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+256 colors are supported with WeeChat 0.3.4 or newer.
+
+First check that your 'TERM' environment variable is correct, recommended values
+are:
+
+* under screen: 'screen-256color'
+* outside screen: 'xterm-256color', 'rxvt-256color', 'putty-256color',...
+
+If your 'TERM' variable has wrong value and that WeeChat is already running,
+don't panic! You can change it without restarting, thanks to script 'shell.py':
+
+----------------------------------------
+/shell setenv TERM=screen-256color
+/upgrade
+----------------------------------------
+
+You can use command `/color` for easy setup of colors in WeeChat.
+
+Please read user's guide for more information about colors management.
+
+
 [[key_bindings]]
 Tastaturbelegung
 ----------------
diff --git a/doc/de/weechat_user.de.txt b/doc/de/weechat_user.de.txt
index 64d27fb58..9daf89d32 100644
--- a/doc/de/weechat_user.de.txt
+++ b/doc/de/weechat_user.de.txt
@@ -790,9 +790,10 @@ Dazu muss ein zweites "/" vorangestellt werden. Um den Befehl'/set' als Text zu
 //set
 ----------------------------------------
 
+// TRANSLATION MISSING
 [[command_line_colors]]
-Farben
-^^^^^^
+Color codes
+^^^^^^^^^^^
 
 Für einige Erweiterungen wie z.B. die IRC Erweiterung können Farbcodes und Attribute für den Text
 gesetzt werden. Dazu muss die Tastenkombination "Ctrl-C" gefolgt von einem der folgenden Zeichen
@@ -856,12 +857,62 @@ WeeChat Optionen (weechat.conf)
 
 include::autogen/user/weechat_options.txt[]
 
-[[curses_colors]]
-Farben für Curses GUI
-^^^^^^^^^^^^^^^^^^^^^
+[[weechat_commands]]
+WeeChat Befehle
+~~~~~~~~~~~~~~~
+
+include::autogen/user/weechat_commands.txt[]
+
+// TRANSLATION MISSING
+[[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="40%",cols="5,>2,>2",options="header"]
+|========================================
+| $TERM                                 | Colors | Pairs ^(1)^
+| "rxvt-unicode", "xterm",...           |     88 |         256
+| "rxvt-256color", "xterm-256color",... |    256 |       32767
+| "screen"                              |      8 |          64
+| "screen-256color"                     |    256 |       32767
+|========================================
+
+[NOTE]
+^(1)^ Even if your terminal supports more than 256 pairs, only 256 pairs can be
+used in WeeChat, because of a ncurses limitation.
+
+You can run `weechat-curses --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'
+* outside screen: 'xterm-256color', 'rxvt-256color', 'putty-256color',...
+
+If your 'TERM' variable has wrong value and that WeeChat is already running,
+don't panic! You can change it without restarting, thanks to script 'shell.py':
+
+----------------------------------------
+/shell setenv TERM=screen-256color
+/upgrade
+----------------------------------------
+
+// TRANSLATION MISSING
+[[colors_basic]]
+Basic colors
+^^^^^^^^^^^^
+
+Basic colors in WeeChat are:
 
-[width="50%",cols="^3m,8"]
+[width="50%",cols="^3m,8",options="header"]
 |========================================
+| Name         | Color
 | default      | Standard Terminalfarbe (transparent für Hintergrund)
 | black        | schwarz
 | darkgray     | dunkelgrau
@@ -880,11 +931,58 @@ Farben für Curses GUI
 | white        | weiß
 |========================================
 
-[[weechat_commands]]
-WeeChat Befehle
-~~~~~~~~~~~~~~~
+// TRANSLATION MISSING
+[[colors_palette]]
+Palette
+^^^^^^^
 
-include::autogen/user/weechat_commands.txt[]
+According to your terminal, 64 or 256 pairs are defined by WeeChat, a
+combination of foreground with background colors:
+
+* for 64 pairs: 8 foreground colors * 8 background colors (dark colors)
+* for 256 pairs: 16 foreground colors * 16 background colors (8 dark colors and
+  8 light colors)
+
+Use command `/color` to see default colors (on buffer you can press 'alt+c' to
+switch between WeeChat and terminal colors).
+
+You can override some color pairs (a pair is foreground + background) with
+command `/color`, which creates option in section 'palette' of file
+'weechat.conf'.
+
+For each color defined, you can specify:
+
+* foreground and background, using format "fg,bg": color for text and
+  background, by default it is color pair number on default background (-1)
+* alias: you can give a name to your color, for easy use in color options
+
+For example, to define pairs 225 to 240 with colors like blue, cyan, green,
+yellow, orange, red, pink, purple:
+
+----------------------------------------
+/color add 225 18,-1
+/color add 226 20,-1
+/color add 227 27,-1
+/color add 228 39,-1
+/color add 229 51,-1
+/color add 230 49,-1
+/color add 231 47,-1
+/color add 232 82,-1
+/color add 233 154,-1
+/color add 234 226,-1
+/color add 235 214,-1
+/color add 236 202,-1
+/color add 237 196,-1
+/color add 238 199,-1
+/color add 239 201,-1
+/color add 240 176,-1
+----------------------------------------
+
+See `/help color` for other examples.
+
+[IMPORTANT]
+Colors defined are overriding default WeeChat color pairs, so you should
+redefine pair only if you're not using this color in WeeChat.
 
 
 [[plugins]]
diff --git a/doc/en/weechat_faq.en.txt b/doc/en/weechat_faq.en.txt
index 9a91aef40..f2a8d1a87 100644
--- a/doc/en/weechat_faq.en.txt
+++ b/doc/en/weechat_faq.en.txt
@@ -209,7 +209,7 @@ List of scripts about URLs: http://www.weechat.org/scripts/stable/tag/url
 I want to change the language used by WeeChat for messages, but without exiting WeeChat, is it possible?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Yes, you have to use a python script, shell.py (available on WeeChat website)
+Yes, you have to use a python script, 'shell.py' (available on WeeChat website)
 and issue these commands when script is loaded:
 
 ----------------------------------------
@@ -221,6 +221,31 @@ To have english messages with UTF-8 encoding for terminal, for ISO users, you
 can issue: `/shell setenv LANG=en_US`.
 
 
+[[256_colors]]
+How can I use 256 colors in WeeChat?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+256 colors are supported with WeeChat 0.3.4 or newer.
+
+First check that your 'TERM' environment variable is correct, recommended values
+are:
+
+* under screen: 'screen-256color'
+* outside screen: 'xterm-256color', 'rxvt-256color', 'putty-256color',...
+
+If your 'TERM' variable has wrong value and that WeeChat is already running,
+don't panic! You can change it without restarting, thanks to script 'shell.py':
+
+----------------------------------------
+/shell setenv TERM=screen-256color
+/upgrade
+----------------------------------------
+
+You can use command `/color` for easy setup of colors in WeeChat.
+
+Please read user's guide for more information about colors management.
+
+
 [[key_bindings]]
 Key bindings
 ------------
diff --git a/doc/en/weechat_user.en.txt b/doc/en/weechat_user.en.txt
index f8c9e3f4d..e0f700c3f 100644
--- a/doc/en/weechat_user.en.txt
+++ b/doc/en/weechat_user.en.txt
@@ -792,8 +792,8 @@ For example, to send text '/set' on current buffer:
 ----------------------------------------
 
 [[command_line_colors]]
-Colors
-^^^^^^
+Color codes
+^^^^^^^^^^^
 
 For some plugins like IRC, you can use color codes and attributes, as
 follow (press Ctrl-C then following letter, with optional value):
@@ -856,12 +856,60 @@ WeeChat options (weechat.conf)
 
 include::autogen/user/weechat_options.txt[]
 
-[[curses_colors]]
-Colors for Curses GUI
-^^^^^^^^^^^^^^^^^^^^^
+[[weechat_commands]]
+WeeChat commands
+~~~~~~~~~~~~~~~~
+
+include::autogen/user/weechat_commands.txt[]
+
+[[colors]]
+Colors
+~~~~~~
 
-[width="50%",cols="^3m,8"]
+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="40%",cols="5,>2,>2",options="header"]
+|========================================
+| $TERM                                 | Colors | Pairs ^(1)^
+| "rxvt-unicode", "xterm",...           |     88 |         256
+| "rxvt-256color", "xterm-256color",... |    256 |       32767
+| "screen"                              |      8 |          64
+| "screen-256color"                     |    256 |       32767
 |========================================
+
+[NOTE]
+^(1)^ Even if your terminal supports more than 256 pairs, only 256 pairs can be
+used in WeeChat, because of a ncurses limitation.
+
+You can run `weechat-curses --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'
+* outside screen: 'xterm-256color', 'rxvt-256color', 'putty-256color',...
+
+If your 'TERM' variable has wrong value and that WeeChat is already running,
+don't panic! You can change it without restarting, thanks to script 'shell.py':
+
+----------------------------------------
+/shell setenv 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
@@ -880,11 +928,57 @@ Colors for Curses GUI
 | white        | white
 |========================================
 
-[[weechat_commands]]
-WeeChat commands
-~~~~~~~~~~~~~~~~
+[[colors_palette]]
+Palette
+^^^^^^^
 
-include::autogen/user/weechat_commands.txt[]
+According to your terminal, 64 or 256 pairs are defined by WeeChat, a
+combination of foreground with background colors:
+
+* for 64 pairs: 8 foreground colors * 8 background colors (dark colors)
+* for 256 pairs: 16 foreground colors * 16 background colors (8 dark colors and
+  8 light colors)
+
+Use command `/color` to see default colors (on buffer you can press 'alt+c' to
+switch between WeeChat and terminal colors).
+
+You can override some color pairs (a pair is foreground + background) with
+command `/color`, which creates option in section 'palette' of file
+'weechat.conf'.
+
+For each color defined, you can specify:
+
+* foreground and background, using format "fg,bg": color for text and
+  background, by default it is color pair number on default background (-1)
+* alias: you can give a name to your color, for easy use in color options
+
+For example, to define pairs 225 to 240 with colors like blue, cyan, green,
+yellow, orange, red, pink, purple:
+
+----------------------------------------
+/color add 225 18,-1
+/color add 226 20,-1
+/color add 227 27,-1
+/color add 228 39,-1
+/color add 229 51,-1
+/color add 230 49,-1
+/color add 231 47,-1
+/color add 232 82,-1
+/color add 233 154,-1
+/color add 234 226,-1
+/color add 235 214,-1
+/color add 236 202,-1
+/color add 237 196,-1
+/color add 238 199,-1
+/color add 239 201,-1
+/color add 240 176,-1
+----------------------------------------
+
+See `/help color` for other examples.
+
+[IMPORTANT]
+Colors defined are overriding default WeeChat color pairs, so you should
+redefine pair only if you're not using this color in WeeChat.
 
 
 [[plugins]]
diff --git a/doc/fr/weechat_faq.fr.txt b/doc/fr/weechat_faq.fr.txt
index 788473021..9b65a0e28 100644
--- a/doc/fr/weechat_faq.fr.txt
+++ b/doc/fr/weechat_faq.fr.txt
@@ -218,7 +218,7 @@ http://www.weechat.org/scripts/stable/tag/url
 Je souhaite changer la langue des messages affichés par WeeChat, mais sans quitter WeeChat, est-ce possible ?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Oui, il faut utiliser le script python shell.py (disponible sur le site de
+Oui, il faut utiliser le script python 'shell.py' (disponible sur le site de
 WeeChat) et taper ces commandes une fois le script chargé :
 
 ----------------------------------------
@@ -230,6 +230,34 @@ Pour avoir des messages anglais avec encodage UTF-8 pour le terminal, pour les
 utilisateurs en ISO, vous pouvez taper : `/shell setenv LANG=fr_FR`.
 
 
+[[256_colors]]
+Comment puis-je utiliser 256 couleurs sous WeeChat ?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Les 256 couleurs sont supportées avec WeeChat 0.3.4 ou plus récent.
+
+Premièrement vérifiez que votre variable d'environnement 'TERM' est correcte,
+les valeurs recommandées sont :
+
+* sous screen : 'screen-256color'
+* en dehors de screen : 'xterm-256color', 'rxvt-256color', 'putty-256color', ...
+
+Si votre variable 'TERM' a une valeur erronée et que WeeChat est déjà lancé,
+ne paniquez pas ! Vous pouvez la changer sans redémarrer, grâce au script
+'shell.py' :
+
+----------------------------------------
+/shell setenv TERM=screen-256color
+/upgrade
+----------------------------------------
+
+Vous pouvez utiliser la commande `/color` pour une configuration facile des
+couleurs dans WeeChat.
+
+Merci de lire le guide utilisateur pour plus d'information sur la gestion des
+couleurs.
+
+
 [[key_bindings]]
 Raccourcis clavier
 ------------------
diff --git a/doc/fr/weechat_user.fr.txt b/doc/fr/weechat_user.fr.txt
index 7c622116f..c6da4729c 100644
--- a/doc/fr/weechat_user.fr.txt
+++ b/doc/fr/weechat_user.fr.txt
@@ -811,8 +811,8 @@ doublant. Par exemple pour envoyer le texte '/set' sur le tampon courant :
 ----------------------------------------
 
 [[command_line_colors]]
-Couleurs
-^^^^^^^^
+Codes couleurs
+^^^^^^^^^^^^^^
 
 Pour certaines extensions comme IRC, il est possible d'utiliser des codes
 couleur et attributs comme suit (appuyer sur Ctrl-C puis sur la lettre qui
@@ -877,12 +877,62 @@ Options WeeChat (weechat.conf)
 
 include::autogen/user/weechat_options.txt[]
 
-[[curses_colors]]
-Couleurs pour l'interface Curses
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+[[weechat_commands]]
+Commandes WeeChat
+~~~~~~~~~~~~~~~~~
+
+include::autogen/user/weechat_commands.txt[]
+
+[[colors]]
+Couleurs
+~~~~~~~~
+
+WeeChat peut utiliser jusqu'à 256 paires de couleur pour afficher le texte dans
+les barres et la zone de discussion (votre terminal doit supporter 256 couleurs
+pour pouvoir les utiliser dans WeeChat).
 
-[width="50%",cols="^3m,8"]
+Selon la valeur de la variable d'environnement 'TERM', vous pouvez avoir les
+limites suivantes pour les couleurs dans WeeChat :
+
+[width="40%",cols="5,>2,>2",options="header"]
+|========================================
+| $TERM                                  | Couleurs | Paires ^(1)^
+| "rxvt-unicode", "xterm", ...           |       88 |          256
+| "rxvt-256color", "xterm-256color", ... |      256 |        32767
+| "screen"                               |        8 |           64
+| "screen-256color"                      |      256 |        32767
 |========================================
+
+[NOTE]
+^(1)^ Même si votre terminal supporte plus de 256 paires, seules 256 paires
+peuvent être utilisées dans WeeChat, en raison d'une limitation de ncurses.
+
+Vous pouvez lancer `weechat-curses --colors` ou utiliser la commande `/color`
+dans WeeChat pour afficher les limites de votre environnement.
+
+Quelques valeurs recommandées pour 'TERM' si vous voulez 256 couleurs :
+
+* sous screen : 'screen-256color'
+* en dehors de screen : 'xterm-256color', 'rxvt-256color', 'putty-256color', ...
+
+Si votre variable 'TERM' a une valeur erronée et que WeeChat est déjà lancé,
+ne paniquez pas ! Vous pouvez la changer sans redémarrer, grâce au script
+'shell.py' :
+
+----------------------------------------
+/shell setenv TERM=screen-256color
+/upgrade
+----------------------------------------
+
+[[colors_basic]]
+Couleurs de base
+^^^^^^^^^^^^^^^^
+
+Les couleurs de base dans WeeChat sont :
+
+[width="50%",cols="^3m,8",options="header"]
+|========================================
+| Nom          | Couleur
 | default      | couleur par défaut du terminal (transparent pour le fond)
 | black        | noir
 | darkgray     | gris foncé
@@ -901,11 +951,62 @@ Couleurs pour l'interface Curses
 | white        | white
 |========================================
 
-[[weechat_commands]]
-Commandes WeeChat
-~~~~~~~~~~~~~~~~~
+[[colors_palette]]
+Palette
+^^^^^^^
 
-include::autogen/user/weechat_commands.txt[]
+Selon votre terminal, 64 ou 256 paires sont définies par WeeChat, une
+combinaison des couleurs d'avant-plan avec le fond :
+
+* pour 64 paires : 8 couleurs d'avant-plan * 8 couleurs de fond (couleurs
+  sombres)
+* pour 256 paires : 16 couleurs d'avant-plan * 16 couleurs de fond (8 couleurs
+  sombres et 8 couleurs claires)
+
+Utilisez la commande `/color` pour voir les couleurs par défaut (sur le tampon
+vous pouvez appuyer sur 'alt+c' pour basculer entre les couleurs WeeChat et
+celles du terminal).
+
+Vous pouvez écraser des paires de couleur (une paire est un avant-plan + un
+fond) avec la commande `/color`, qui créé une option dans la section 'palette'
+du fichier 'weechat.conf'.
+
+Pour chaque couleur définie, vous pouvez spécifier :
+
+* avant-plan et fond, en utilisant le format "fg,bg" : couleur pour le texte et
+  le fond, par défaut c'est la couleur du numéro de paire sur le fond par
+  défaut (-1)
+* alias : vous pouvez donner un nom à la couleur, pour l'utiliser facilement
+  dans les options de couleurs
+
+Par exemple, pour définir les paires de 225 à 240 avec des couleurs comme le
+bleu, cyan, vert, jaune, orange, rouge, rose, pourpre :
+
+----------------------------------------
+/color add 225 18,-1
+/color add 226 20,-1
+/color add 227 27,-1
+/color add 228 39,-1
+/color add 229 51,-1
+/color add 230 49,-1
+/color add 231 47,-1
+/color add 232 82,-1
+/color add 233 154,-1
+/color add 234 226,-1
+/color add 235 214,-1
+/color add 236 202,-1
+/color add 237 196,-1
+/color add 238 199,-1
+/color add 239 201,-1
+/color add 240 176,-1
+----------------------------------------
+
+Voir `/help color` pour d'autres exemples.
+
+[IMPORTANT]
+Les couleurs définies écrasent les paires de couleur WeeChat par défaut, donc
+vous ne devriez redéfinir une paire seulement si vous n'utilisez pas cette
+couleur dans WeeChat.
 
 
 [[plugins]]
diff --git a/doc/it/weechat_faq.it.txt b/doc/it/weechat_faq.it.txt
index f3ca46204..563ea21c4 100644
--- a/doc/it/weechat_faq.it.txt
+++ b/doc/it/weechat_faq.it.txt
@@ -214,7 +214,7 @@ Elenco di script a proposito di URL: http://www.weechat.org/scripts/stable/tag/u
 Voglio cambiare la lingua utilizzata da WeeChat per i messaggi, ma senza uscire da WeeChat, è possibile?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Sì. è necessario uno script python, shell.py (disponibile sul sito di WeeChat)
+Sì. è necessario uno script python, 'shell.py' (disponibile sul sito di WeeChat)
 e digitare questi comandi quando viene caricato lo script:
 
 ----------------------------------------
@@ -226,6 +226,32 @@ Per avere i messaggi in inglese con la codifica UTF-8 per il terminale, per gli
 utenti ISO, digitare: `/shell setenv LANG=en_US`.
 
 
+// TRANSLATION MISSING
+[[256_colors]]
+How can I use 256 colors in WeeChat?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+256 colors are supported with WeeChat 0.3.4 or newer.
+
+First check that your 'TERM' environment variable is correct, recommended values
+are:
+
+* under screen: 'screen-256color'
+* outside screen: 'xterm-256color', 'rxvt-256color', 'putty-256color',...
+
+If your 'TERM' variable has wrong value and that WeeChat is already running,
+don't panic! You can change it without restarting, thanks to script 'shell.py':
+
+----------------------------------------
+/shell setenv TERM=screen-256color
+/upgrade
+----------------------------------------
+
+You can use command `/color` for easy setup of colors in WeeChat.
+
+Please read user's guide for more information about colors management.
+
+
 [[key_bindings]]
 Associazioni dei tasti
 ----------------------
diff --git a/doc/it/weechat_user.it.txt b/doc/it/weechat_user.it.txt
index c873c67e6..e63966a1d 100644
--- a/doc/it/weechat_user.it.txt
+++ b/doc/it/weechat_user.it.txt
@@ -805,9 +805,10 @@ poi un altro. Ad esempio, per inviare il testo '/set' sul buffer attivo:
 //set
 ----------------------------------------
 
+// TRANSLATION MISSING
 [[command_line_colors]]
-Colori
-^^^^^^
+Color codes
+^^^^^^^^^^^
 
 Per alcuni plugin come IRC, è possibile usare codici colori ed attributi,
 come segue (digitare Ctrl-C poi la lettera che segue, con il valore
@@ -872,12 +873,62 @@ Opzioni di WeeChat (weechat.conf)
 
 include::autogen/user/weechat_options.txt[]
 
-[[curses_colors]]
-I colori per l'interfaccia Curses
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+[[weechat_commands]]
+Comandi di WeeChat
+~~~~~~~~~~~~~~~~~~
+
+include::autogen/user/weechat_commands.txt[]
+
+// TRANSLATION MISSING
+[[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="40%",cols="5,>2,>2",options="header"]
+|========================================
+| $TERM                                 | Colors | Pairs ^(1)^
+| "rxvt-unicode", "xterm",...           |     88 |         256
+| "rxvt-256color", "xterm-256color",... |    256 |       32767
+| "screen"                              |      8 |          64
+| "screen-256color"                     |    256 |       32767
+|========================================
+
+[NOTE]
+^(1)^ Even if your terminal supports more than 256 pairs, only 256 pairs can be
+used in WeeChat, because of a ncurses limitation.
+
+You can run `weechat-curses --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'
+* outside screen: 'xterm-256color', 'rxvt-256color', 'putty-256color',...
+
+If your 'TERM' variable has wrong value and that WeeChat is already running,
+don't panic! You can change it without restarting, thanks to script 'shell.py':
+
+----------------------------------------
+/shell setenv TERM=screen-256color
+/upgrade
+----------------------------------------
+
+// TRANSLATION MISSING
+[[colors_basic]]
+Basic colors
+^^^^^^^^^^^^
+
+Basic colors in WeeChat are:
 
-[width="50%",cols="^3m,8"]
+[width="50%",cols="^3m,8",options="header"]
 |========================================
+| Name         | Color
 | default      | colore predefinito del terminale (trasparente per lo sfondo)
 | black        | nero
 | darkgray     | grigio scuro
@@ -894,13 +945,60 @@ I colori per l'interfaccia Curses
 | cyan         | azzurro scuro
 | lightcyan    | azzurro chiaro
 | white        | bianco
-|=======================================
+|========================================
 
-[[weechat_commands]]
-Comandi di WeeChat
-~~~~~~~~~~~~~~~~~~
+// TRANSLATION MISSING
+[[colors_palette]]
+Palette
+^^^^^^^
 
-include::autogen/user/weechat_commands.txt[]
+According to your terminal, 64 or 256 pairs are defined by WeeChat, a
+combination of foreground with background colors:
+
+* for 64 pairs: 8 foreground colors * 8 background colors (dark colors)
+* for 256 pairs: 16 foreground colors * 16 background colors (8 dark colors and
+  8 light colors)
+
+Use command `/color` to see default colors (on buffer you can press 'alt+c' to
+switch between WeeChat and terminal colors).
+
+You can override some color pairs (a pair is foreground + background) with
+command `/color`, which creates option in section 'palette' of file
+'weechat.conf'.
+
+For each color defined, you can specify:
+
+* foreground and background, using format "fg,bg": color for text and
+  background, by default it is color pair number on default background (-1)
+* alias: you can give a name to your color, for easy use in color options
+
+For example, to define pairs 225 to 240 with colors like blue, cyan, green,
+yellow, orange, red, pink, purple:
+
+----------------------------------------
+/color add 225 18,-1
+/color add 226 20,-1
+/color add 227 27,-1
+/color add 228 39,-1
+/color add 229 51,-1
+/color add 230 49,-1
+/color add 231 47,-1
+/color add 232 82,-1
+/color add 233 154,-1
+/color add 234 226,-1
+/color add 235 214,-1
+/color add 236 202,-1
+/color add 237 196,-1
+/color add 238 199,-1
+/color add 239 201,-1
+/color add 240 176,-1
+----------------------------------------
+
+See `/help color` for other examples.
+
+[IMPORTANT]
+Colors defined are overriding default WeeChat color pairs, so you should
+redefine pair only if you're not using this color in WeeChat.
 
 
 [[plugins]]
diff --git a/doc/pl/weechat_faq.pl.txt b/doc/pl/weechat_faq.pl.txt
index 42699207f..776d569ea 100644
--- a/doc/pl/weechat_faq.pl.txt
+++ b/doc/pl/weechat_faq.pl.txt
@@ -210,7 +210,7 @@ Lista skryptów do obsługi adresów URL: http://www.weechat.org/scripts/stable/
 Chcę zmienić język komunikatów wyświetlanych przez WeeChat, ale bez jego zamykania, czy jest to możliwe?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Tak, musisz użyć pythonowego skryptu shell.py (dostępny na stronie programu),
+Tak, musisz użyć pythonowego skryptu 'shell.py' (dostępny na stronie programu),
 oraz użyć tych komend po załadowaniu skryptu:
 
 ----------------------------------------
@@ -222,6 +222,32 @@ Aby otrzymać polskie komunikaty dla kodowania UTF-8 w terminalu, osóby
 używające ISO, moga wykonać: `/shell setenv LANG=pl_PL`.
 
 
+// TRANSLATION MISSING
+[[256_colors]]
+How can I use 256 colors in WeeChat?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+256 colors are supported with WeeChat 0.3.4 or newer.
+
+First check that your 'TERM' environment variable is correct, recommended values
+are:
+
+* under screen: 'screen-256color'
+* outside screen: 'xterm-256color', 'rxvt-256color', 'putty-256color',...
+
+If your 'TERM' variable has wrong value and that WeeChat is already running,
+don't panic! You can change it without restarting, thanks to script 'shell.py':
+
+----------------------------------------
+/shell setenv TERM=screen-256color
+/upgrade
+----------------------------------------
+
+You can use command `/color` for easy setup of colors in WeeChat.
+
+Please read user's guide for more information about colors management.
+
+
 [[key_bindings]]
 Przypisania klawiszy
 --------------------