Please note: This README is work in progress. A more detailed documentation will follow.

weechat.el requires Emacs 24 and s.el. For Emacs versions below 24.3 you also need cl-lib. WeeChat version 0.4.0 or newer is recommended!

You can install weechat.el via package.el (melpa-stable (stable releases) or melpa (development snapshot)):

M-x package-install RET weechat RET

See NEWS.org for major changes in releases.

• Install dependencies via package.el:

  M-x package-install RET s RET
      

• If your Emacs is older than 24.3:

  M-x package-install RET cl-lib RET
      

• Download this directory to your system and add it to the load-path:

  (add-to-list 'load-path (expand-file-name "path/to/weechat.el/"))
      

• Load weechat.el

  (require 'weechat)
      

  (You can add this to your ~/.emacs.d/init.el or similar)

First, setup the relay server in weechat. Please refer to the manual.

To load and establish a connection:

(require 'weechat)
M-x weechat-connect RET

To show a channel in Emacs, do:

M-x weechat-monitor-buffer RET

Most colors in weechat.el come directly from WeeChat and are only translated into Emacs faces. There are a few notable exceptions such as weechat-highlight-face or weechat-nick-self-face.

If you are unsatisfied with the colors that WeeChat send then either change the corresponding color in WeeChat or customize weechat-color-list. Do not add or remove any values in the list! Simply change the value. Using rainbow-mode (from GNU ELPA) or list-colors-display can help finding good values.

The default configuration tries to match the WeeChat colors as close as possible. Example for colors that go better with the Emacs’ default theme are:

(setq weechat-color-list '(unspecified "black" "dim gray" "dark red" "red"
                                       "dark green" "green" "brown"
                                       "orange" "dark blue" "blue"
                                       "dark magenta" "magenta" "dark cyan"
                                       "royal blue" "dark gray" "gray"))

If you do not want any color then set weechat-debug-strip-formatting to t.

See documentation in SSL.org.

Weechat.el comes with module support. Modules can be loaded by simply calling load-library and removed by using unload-feature. The variable weechat-modules can be customized to set default loaded modules.

Available modules are:

This module provides support for buttons in chat windows. E.g., it turns URLs into clickable buttons. The module is default loaded. See weechat-modules.

It supports several types of buttons such as URLs, Channels, Emacs’ symbols, E-Mails, Manpages, Info links, and Nick names. However not all buttons are activated as default. See customization group weechat-button to enable and disable specific buttons.

You can use weechat-button-list to simply add your own button types.

This module provides support for nickname and command completion. It uses Emacs’ pcomplete framework and is default loaded.

If you want case-insensitive completion, set completion-ignore-case to t.

This module provides spelling support by using Emacs’ flyspell. You can customize the dictionary on a per channel/server basis by customizing weechat-spelling-dictionaries.

Weechat.el supports notifications for important messages, such as highlights or queries. The support is either based on notifications.el which is shipped with Emacs since version 24 and uses the Freedesktop notification spec. Another solution is based on Sauron.

To activate notifications you have to load the matching module. Either weechat-notifications for notifications.el or weechat-sauron for Sauron support.

To change the message types you want to receive notifications for customize weechat-notification-types.

Loading the weechat-notifications module uses notifications.el to display notifications. This uses the Freedesktop notification spec and should work fine on most Linux systems.

You can customize weechat-notifications-sound to play a sound on notification. Setting weechat-notifications-icon allows to change the notification icon.

The weechat-sauron module uses Sauron for notifications.

The weechat-tracking module provides tracking information in the mode line, similar to erc-track. It uses the Tracking library (available on marmalade or el-get).

This module uses Gnus’ smiley-region support to convert text smileys, such as :-), into a graphical representation. See the documentation of smiley.el on how to customize it.

The weechat-latex module provides a simple preview function for embedded LaTeX. It is based Org’s LaTeX preview functionality and many of Org’s LaTex customizations apply to it as well. Use weechat-latex-preview to generate previews and weechat-latex-remove to remove them.

There is also weechat-latex-auto-mode to automatically turn LaTeX fragments in every new message into a preview.

By using weechat-latex-preview-region or weechat-latex-preview-line the LaTeX previews can be limited to certain parts of the buffer.

The weechat-speedbar module provides Emacs’ Speedbar integration. After loading the module and opening the Speedbar there should be a Display mode called “WeeChat” available.

This modules allows (embedded) previews of image urls. After loading the module a button should appear next to urls to image files. By clicking the button images should be opened inline and by clicking the button again they should be removed.

By changing weechat-image-display-func the images can instead be opened inside the buffer weechat-image-buffer. The detection of image URLs can be influenced with weechat-image-url-regex and weechat-image-url-blacklist-regex.

Be careful when loading images of sources you do not trust. Change weechat-image-size-limit to prevent the display of large images.

Feel free to contact us via Github, Email, or IRC (#weechat.el on Freenode)

We appreciate every comment, suggestion, or nagging for missing features. Tell us your story!

Please add yourself to this list when you contribute code!

• Moritz Ulrich (Maintainer)
• Rüdiger Sonderfeld
• Aristid Breitkreuz