Keyboard Shortcuts

In the first Weechat post I covered the shortcuts for handling buffers and IRC. The other ones I've found useful are below. I've purposely limited this to the most useful (as defined by me!) shortcuts. The Weechat manual has a full list of keyboard shortcuts and commands if you'd like more.

Shortcut	Command	Description
<Pgup>		Move up one page in the channel scrollback. Use <Alt><PgUp> if you want to scroll one line at a time.
<PgDn>		Move down one page in the channel scrollback. Use <Alt><PgDn> if you want to scroll one line at a time.
<Alt><Shift>b	/buflist toggle	Toggle the buflist (channel) bar on the left.
<Alt><Shift>n	/bar toggle nicklist	Toggle the nicklist bar on the right
<Alt>l	/window bare	Switch to bare display which removes all the bars. This is useful for cutting and pasting URLs from channels.

I really like the fact that Weechat uses the Function keys as they're so often under-utilised. If you're using a full sized keyboard rather than a laptop then they're pretty easy to reach:

Shortcut	Command	Description
<F1>	/bar scroll buflist * -100%	Scroll up one page in buffer list
<F2>	/bar scroll buflist * +100%	Scroll down one page in buffer list
<F5>	/buffer -1	Switch to previous buffer
<F6>	/buffer +1	Switch to next buffer
<F7>	/window -1	Switch to previous window
<F8>	/window +1	Switch to next window
<F11>	/bar scroll nicklist * -100%	Scroll up one page in nick list
<F12>	/bar scroll nicklist * +100%	Scroll down one page in nick list

Keys can be bound and there's also the ability to create command aliases. As a basic example I like an easier shortcut for toggling the buffer list:

# alt-b to toggle the buflist
/key bind meta-b /bar toggle buflist

Filtering IRC

On busy channels many of the activity highlights that appear are for users joining and leaving the channel rather than anyone chatting. Weechat can filter these out using the /filter capability so that you don't see these messages and won't get alerts:

/set irc.look.smart_filter on
/filter add irc_smart * irc_smart_filter *

# hide default channel information - not botherng with
# /set irc.look.display_join_message
#/filter add irc_join_names * irc_366,irc_332,irc_333,irc_329,irc_324 *

The second filter tells Weechat to ignore the messages when joining a channel, it's worth considering using this if you find them annoying.

Weechat Security

IRC is a microcosm of the Internet, a global village where interesting people abound - but also jokers and more serious malefactors lurk. Semi-anonymous chatting about hobbies and interests is great fun - but we should always bear in mind the risks of social engineering. Aside from being careful about the information we reveal it's best to limit the surface area that can be attacked.

The IRC protocol defaults to clients showing information about themselves and users having the ability to directly transfer files. To switch off file transfer and reduce the amount of information that the client shows set the following:

/set irc.ctcp.clientinfo ""
/set irc.ctcp.finger ""
/set irc.ctcp.source ""
/set irc.ctcp.time ""
/set irc.ctcp.userinfo ""
/set irc.ctcp.version ""
/set irc.ctcp.ping ""

/plugin unload xfer

Weechat is defined as a core system and a set of plugins that are loaded. It's worth switching off any plugins that aren't need. Some of the scripts used later require Python and Perl so these plugins remain switched on:

/plugin unload lua
/plugn unload tcl
/plugin unload ruby
/plugin unload javascript
/plugin unload guile
/plugin unload relay

# To disable exec, fifo, guile, javascript, lua, ruby, tcl, xfer
/set weechat.plugin.autoload "*,!exec,!fifo,!guile,!javascript,!lua,!ruby,!tcl,!xfer"

Remember to save settings at the end with /save.

Logging Chat

It's useful to have a log of chat so that you can refer back to it later. By default Weechat will log everything at the highest level of detail and store it in ~/.weechat/logs. To show the logging status of all current buffers do:

/logger list

The logging levels used by the IRC and Weechat plugins are:

1. User message, notice, private
2. Nick change
3. Server message
4. Join/part/quit messages
5. All messages

Like other plugins the logging settings are in the Settings buffer (/set): see my first blog post for a reminder on using it. To filter the view to just the logger ones do:

# change to the fset buffer
/set

# in the input bar type a space and type logger then <return>
<space>logger

Logging can be set to a different levels for each server. My recommendation is to stop the main Weechat programme logging as it's unnecessary. Then decide the levels required for each server - personally for work Slack and IRC I log channel chat and direct messages:

# don't log the core weechat application
/set logger.level.core.weechat 0

# log all channels and messages for work slack
/set logger.level.python.xxxx.slack.com 1

# log channels and messages to me
/set logger.level.irc 1

We can also alter the logging for specific channels - for example, if the channel is noisy we can set it to not log at all:

# don't log the ##news channel
/set logger.level.irc.freenode.##news 0

We can also alter the location and the file name that each of the logs uses. This involves setting the logger.file.path and then adding a mask for the filename with logger.file.mask. To see what variables are available for the mask in a particular buffer do:

/buffer localvar

My preference is to collect all logs together by year into a directory, and then different servers I'm on need to be logged with their name:

# location of logs - with year
/set logger.file.path "%h/logs/%Y/"
/set logger.file.mask "$plugin.$name.log"
# Put brackets around the Nickname so it's different from the message
/set logger.file.nick_suffix "]"
/set logger.file.nick_prefix "["

Scripts

Weechat has scripts that extend it's capabilities. Scripts are user contributed, whereas the Plugins we discussed earlier are part of core Weechat. There are lots of choices to explore and there's a dedicated buffer for them which is opened with:

/script

The buffer shows a list of scripts, these are the ones that are available from weechat.org/scripts. It's also possible to install scripts manually, which we'll do in another blog when we install the Wee-slack script.

For each script we have the name, date it was updated and a list of status options:

* i a H r N
| | | | | |
| | | | | obsolete (new version available)
| | | | running (loaded)
| | | held
| | autoloaded
| installed
popular script

To navigate the display either use the mouse or <PgDown>/<PgUp>. There are a lot of scripts so just like the Settings buffer it can be useful to filter the view:

# put a space in and then type to show the spell scripts
<space>spell

# to reset put a <space> in on its own
<space>

When we find a script we want to examine we can either do /script show <name> or we can move the cursor onto that scripts row and type <Alt>v so that Weechat show us the script's contents. Generally, this gives us some hints about how to use the script - many also have help after they're installed.

To install a script we do /script install <name>, or we can highlight and hit <Alt>i. Scripts install and load themselves into the local environment so we should be good to go.

If we're not happy with a script we can do /script unload <name> (or <Alt>u), and then /script remove <name> (or <Alt>r) to remove it entirely.

Autosort Channels

In the first post we clustered the channel buffers under each server we're connected to so that it's easier to see what we're connected to. At the moment the channels aren't sorted alphabetically under each server. The Weechat-autosort plugin solves this problem. See Figure 1 where I'm connected to two servers (Freenode and SDF) and the channels are clusters alphabetically for each one:

# open the script buffer
/script

# install the autorsort script
/script install autosort.py

# whether you have a server buffer or not. The default is merge_with_core
# but if you connect to multiple servers setting 'independent' will cluster
# the buffers under a server buffer
/set irc.look.server_buffer independent

# save the settings
/save

After it's installed and loaded do /help autosort to see the range of options. Autosort is a popular script with nicely written help. I use the default settings and haven't changed anything.

Spell Check Plugin

I often make spelling mistakes as I'm typing, Weechat provides a way to show any spelling mistakes we're making and to recommend correctly spelt words.

Weechat comes with a spelling plugin that uses GNU aspell to highlight spelling errors. In earlier versions of Weechat the commands were /aspell <something> and they are now /spell <something> - but it's the same otherwise. If you're using an earlier version of Weechat then replace every reference to spell that I show with aspell.

We're also going to use a couple of scripts to make it easier to select a recommendation.

To switch on spelling do:

/spell enable

We also need to tell Weechat which of Aspell's dictionaries to use. We can list the dictionaries with:

/spell listdict

Then to select a dictionary we do:

/set spell.check.default_dict "en_GB,en"

As an example using more than one dictionary: for English this means it will show me the British English spelling (e.g visualise) as well as the US English (e.g. visualize). It's also possible to have complex settings like different dictionaries for different channels.

Anything that you type into a buffer will be spell checked. For example, if you change into the main Weechat buffer and type a turtla swims in water it will highlight turtla in red to show you that it's mis-spelt. See Figure 2 lower down where you can see it's highlighting on the input bar.

There are two ways Weechat can give us suggestions to correct spelling mistakes:

1. Show suggestions on the status bar and we type in the correct version
2. Show suggestions in a menu and we select the one we want

The difference is that to have a menu and select the correct recommendation requires some scripts. For either option the first step is to tell Weechat to make recommendations:

# pick a number for how many suggestions you want
/set spell.check.suggestions 3

To have the suggestions show on the status bar we need to change it's configuration. All the bars (like the status bar and menu bar) can be configured and formatted. The format can be very long, so to avoid typing the whole thing out we'll use the append option:

# open up the set buffer
/set

# filter it to showing the status.bar.items
<space> weechat.bar.status.items

# tell Weechat we want to append
/fset -append

Weechat will put the whole of option into the input bar where you can scroll through and change it. We want to add ,[spell_suggest] somewhere: this is the variable spell_suggest inside square brackets so the suggestions are easy to use.

For me this means the final version is:

# new version with [aspell_suggest] on the end - split over some lines to make it easier to see
/set weechat.bar.status.items "[time],[buffer_last_number],[buffer_plugin],
buffer_number+:+buffer_name+(buffer_modes)+{buffer_nick_list_count}+buffer_zoom+buffer_filter,
scroll,[lag],[hotlist],completion,[spell_suggest]"

# if it's messed up reset to the default value with
/fset -reset

# save the new setting
/save

With this new setting it will show three spelling suggestions on the Status bar as we're typing.

To add the ability to select the correct spelling from a menu of suggestions we need to add two scripts, first 'menu.pl' and then 'spell_menu.pl'. To install the menu capability do:

/script install menu.pl

The menu script puts a menu at the top of the screen, as we have the mouse enabled you can click on the menu items to open them up. Alternatively, open it with the /menu command. We can also select the menus items with the arrow keys. To close a menu without taking an option use <Ctrl>-x.

It's worth playing around with /menu and reading /menu help to see if it's something to use generally. It makes many Weechat commands easy to access.

In my case to save as many terminal lines as possible I set the menu not to show:

# stop the menu being there all the time
/set plugins.var.perl.menu.main_menu_hidden yes

# note that setting this does not work as it gets reset by
# the script. Use the one above
/set weechat.bar.main_menu.hidden yes

# if you don't want the menu at the top to pop-up at all
# set this - but you then won't know that <ctrl>+x shuts
# the menu if you don't want any of the recommendations
/set plugins.var.perl.menu.active_help no

The next step is to install the spell_menu.pl script with:

/script install spell_menu.pl

Now when we type a word incorrectly it's highlighted and we can hit <Tab> to pop-up a menu of suggestions. To select one of the suggestions either type the number, or use the right and left arrow keys to select it. If we're not happy with any of the suggestions then <Ctrl>x will close the menu.

To see more of the options do /spell_menu help which accesses the internal help for the script.

Handling URLs

When sharing links in browser Slack you can just click on them - so we need a way to do this with Weechat.

The first way to handle this is that the terminal emulator may have support for handling URLs: in Gnome terminal you can right click a URL or use <Shift> to highlight a URL. This works some of the time, but if the URL is over more than one line then it can't recognise it's a URL and you can't select it. Switch to a bare display with <Alt>-l or /window bare and it will remove all the bars and just show the chat area so you can easily select the URL.

If this doesn't work for you, then the other option is the URL Grab (urlgrab) Python script. Urlgrab provides a special buffer and commands to select URLs in a buffer.

Color Nicks

Colours in text-based UI's are complex because they depend on the terminal environment supporting them. For example, a local terminal such as gnome-terminal or using ssh/tmux may require different configuration to achieve 256 colours.

To see the colours and TERM environment that Weechat is aware of do:

/color

This will open up the Color buffer that shows the colours that Weechat is using. At the top of the buffer it shows the $TERM and colours available. In my configuration it shows xterm-256color and consequently COLORS are 256. Read the Weechat User Guide - Colors to start down the rabbit hole of enabling 256 colours!

Press e for further information that is pretty useful. It will show you the aliases that colours have been given and the Nick colors being used.

Colours can be given aliases, so the basic colours are shown with their names (e.g. red, blue). However, all of them are given numbers by default in the terminal. To see all the colours Weechat thinks the terminal supports with their numbers press <Alt>-c in the Color buffer.

The terminal colour display only shows for 10 seconds. When playing with colours it's useful to have a complete print of them to see the colours that are distinctive - to see what your terminal supports use this one liner in a bash shell:

for COLOR in {1..255}; do echo -en "\e[38;5;${COLOR}m${COLOR} "; done; echo;

This will print out all the colours, but bear in mind that you can also set the background colour to something different: for example I prefer a dark background with light text, but for when I'm mentioned I flip the background to be orange and it shows the text in a dark colour. It's a particular aesthetic (read that as pretty ugly!) but clearly shows when someone's mentioned me.

To set colours on Nicks we do:

# Nick are coloured
/set irc.look.color_nicks_in_nicklist on

# Use a different color for offline Nicks
/set weechat.look.color_nick_offline yes

# if it's the same person talking don't repeat their name as a prefix either
# use a space or a return symbol to show it's still them speaking
# /set weechat.look.prefix_same_nick "⤷"
/set weechat.look.prefix_same_nick " "

We can set the colours that are used in the Nicks using any of the 256 colours available:

# this is a single line command split over multiple lines to show it
/set weechat.color.chat_nick_colors "1,2,3,4,6,7,9,10,11,12,13,14,22,23,24,
25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,
50,51,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,182,
183,184,244,225,226,227

This is a set that has a good level of distinctiveness between the colours being used. It's also possible to set colour highlights for whenever your Nick is mentioned:

# Using solarized terminal which has a dark background.
# This sets background of the highlight to be dark and the star means the text is bolded.
# The text itself is highlighted in orange/pink.
/set weechat.color.chat_highlight *16
/set weechat.color.chat_highlight_bg 9

Colorize Lines

We can also colour each Nicks text in the text area to be the same colour as their Nickname is coloured - this helps to show conversations.

/script install colorize_lines.pl

With this installed all lines of chat are automatically given colors. The settings are in plugins.var.perl.colorize_lines, the only one I set is:

# whether a line where you have been mentioned is highlighted
plugins.var.perl.colorize_lines.hightlight on

The colors used for the highlight are set in weechat.color.chat_highlight and weechat.color.chat_highlight_bg which we set above. The colour for your own text is set in weechat.color.chat_nick_self by default - this is white.

Configuration Checkpoint

We've run through quite a few settings in the last two posts. This is the complete configuration from the two posts:

# filter out join/part/quit/nick messages from inactive users
/filter add irc_smart * irc_smart_filter *
/set irc.look.smart_filter on

# switch of things we don't need and provide less information
/set weechat.plugin.autoload "*,!exec,!fifo,!guile,!javascript,!lua,!ruby,!tcl,!xfer"
/set irc.ctcp.clientinfo ""
/set irc.ctcp.finger ""
/set irc.ctcp.source ""
/set irc.ctcp.time ""
/set irc.ctcp.userinfo ""
/set irc.ctcp.version ""
/set irc.ctcp.ping ""

# close a buffer when you leave
/set irc.look.part_closes_buffer on

# show servers as individual buffers
/set irc.look.server_buffer independent

# Nicks are coloured
/set irc.look.color_nicks_in_nicklist on

## remember to define Freenode with /server command ##
# make sure SSL is on for Freenode
/set irc.server.freenode.ssl "on"
# nicknames to use for Freenode
/set irc.server.freenode.nicks "XXX,XXX"
# preferred nickname to use on Freenode
/set irc.server.freenode.username "XXX"
# set your real name
/set irc.server.freenode.realname ""

# securely store Nick password - see first blog post
/set irc.server.freenode.sasl_password "${sec.data.freenode_password}"
/set irc.server.freenode.sasl_username "mynick"

# default username for IRC
/set irc.server_default.username "name you want to use"
# variants of your nickname to use
/set irc.server_default.nicks "name,name1,name2,name3,name4"


# don't log the core weechat application
/set logger.level.core.weechat 0
# log all channels and messages for work slack
# /set logger.level.python.xxxx.slack.com 1
# log channels and messages to me
/set logger.level.irc 1
# location of logs - with year
/set logger.file.path "%h/logs/%Y/"
/set logger.file.mask "$plugin.$name.log"
# Put brackets around the Nickname so it's different from the message
/set logger.file.nick_suffix "]"
/set logger.file.nick_prefix "["

## remember to install the colorize_lines.pl script ##
# Colorize lines
# whether a line where you have been mentioned is highlighted
/set plugins.var.perl.colorize_lines.hightlight on

## remember to install the menu.pl and spell_menu.pl scripts ##
# menus for spelling
/set plugins.var.perl.menu.main_menu_hidden yes
# if you don't want the menu at the top to pop-up at all set this - but you
# then won't know that <ctrl>+x shuts the menu if you don't want any of the
# recommendations
/set plugins.var.perl.menu.active_help no

# set the spell check dictionary
/set spell.check.default_dict "en_GB"
/set spell.check.suggestions 3

# top bar can resize to fit text - very useful for buffers like settings
# that have a lot of help at the top
/set weechat.bar.title.size 0

# add spelling suggestions to the bar
# to show this I've split it over three lines - cut-n-paste it as one line
/set weechat.bar.status.items "[time],[buffer_last_number],[buffer_plugin],
buffer_number+:+buffer_name+(buffer_modes)+{buffer_nick_list_count}+buffer_zoom+buffer_filter,
scroll,[lag],[hotlist],completion,[spell_suggest]"

# increase colours available to use in Nicks
# this is a single line command split over multiple lines to show it
/set weechat.color.chat_nick_colors "1,2,3,4,6,7,9,10,11,12,13,14,22,23,24,
25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,
50,51,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,182,
183,184,244,225,226,227

# using solarized terminal setting background of the highlight to be dark
# and the star means the text is bolded. The text itself is highlighted in
# orange/pink
/set weechat.color.chat_highlight *16
/set weechat.color.chat_highlight_bg 9

# Use a different color for offline Nicks
/set weechat.look.color_nick_offline yes

# don't keep repeating the Nick if it's the same person talking
/set weechat.look.prefix_same_nick " "

# use the mouse
/set weechat.look.mouse on

# shortcut to use /<N> to jump buffers
# this setting is split over two lines for illustration - cut-n-paste it as one
# line for it to work properly
/trigger add numberjump modifier "2000|input_text_for_buffer"
"${tg_string} =~ ^/[0-9]+$" "=/([0-9]+)=/buffer *${re:1}=" ""

# alt-b to toggle the buflist
/key bind meta-b /bar toggle buflist

Resources

• Optimizing Weechat log usage

  Jeaye gives tips on what to log and how to reduce logging useless data.

• Logrotate Weechat logs

  Jelly shows how to use logrotate to rotate and compress your IRC logs. Get it from the WayBack Machine.

• Using aspell in WeeChat IRC client

  Qeole gives an overview of installing Weechat's Aspell capability.

• Learning how to type / spell (in weechat)

  Eric Rich's post on how to use Aspell in Weechat.

• A simple solarized Weechat setup v2.0

  Ben Oliver's post on setting up Weechat nicely if you have a Solarized terminal.

Summary

The final configuration is show in Figure 4 which can be clicked on to show a bigger image. The only critical element of configuration that's missing is notifications, which we'll solve in the last post. Having set-up the main scripts and learnt the most useful keyboard shortcuts every day experience of IRC in Weechat should be good. Next time we'll move onto learning about Wee-slack so that we can use Slack from within Weechat.