How to use macros with the slrn newsreader

Macros and slrn

The slrn newsreader can be easily extended using S-Lang scripts that are most commonly called macros and can be recognised by their ".sl" suffix. This page aims to be an introduction to macros and slrn by describing:

Using the Macros Available with slrn: A description of how to utilise the macros that come with the slrn tarball.
Resources for writing your own macros: Several online resources that will enable the skilled and keen to get a start with writing their own macros.
The Macros of Thomas Schultz: Several macros written by Thomas Schultz described here and made avalable for download.

If you have a macro that you have developed yourself and wish it to be made available from this site please email Andrew Strong with the details.

Using the Macros Available with slrn

The slrn tarball contains a number of pre-written macros in the /macros directory and by default these are installed to /usr/local/share/slrn/slang although this path may very well differ on your system. For the purpose of demonstration I will show how to successfully use one of these macros with slrn, the color.sl macro. This macro implements a function called "edit_colors" that may be used for designing a color scheme interactively. It is called from the .slrnrc file as follows:

interpret "color.sl"
setkey article edit_colors "\eec"

Because this is a well written macro much of this information can be gained from opening the macro itself with your favourite editor and this is really mandatory before using any macro. When the file color.sl is opened you will see that the keybinding of "ESC e c" that I have suggested is drawn from the file itself. After pressing these keys you can now interactively select a color scheme by chosing an object, foreground color and background color.

The same principles hold true for any macro you choose to run with slrn, either those that came with slrn or those that you have sourced from elsewhere. Your own macros can be placed in a variety of locations and then sourced from the .slrnrc file using the interpret command. These locations are:

A path relative to $HOME (or $SLRNHOME if set).
An absolute path prefixed with an "/".
In you "macro_directory" if this string is set in .slrnrc.

This can be best illustrated in this brief extract from the slrn manual where the following example:

interpret "News/macros/my-macro.sl"
interpret "/usr/share/slrn/slang/util.sl"

could be more efficiently be rendered as:

set macro_directory "News/macros,/usr/share/slrn/slang"
interpret "my-macro.sl"
interpret "util.sl"

There are many, many slrn macros available on the Internet. An excellent starting point might be the links available on this web site or the macros that Thomas Schultz has made available. Perhaps you might also read on and see the information for creating your own macros?

Resources for writing your own macros

This page does not offer "hands-on" guidance on the writing of S-Lang macros, although hopefully one day it will. However below are some links that should at the very least furnish an excellent start:

README.macros: This plain text document comes as part of the slrn tarball in the /doc directory. Its purpose is "to provide some instructions on extending the newsreader in its macro language" and is a recommended starting point when considering writing your own macros.
S-Lang Library Documentation Page: This page contains a series of essential reference documents on the S-Lang Library and is required reading if you wish to develop your own macros.
Troy's Home Page : slrn Howto: Troy is the most prolific writer of quality macros for slrn in current times and it is highly recommended that some time be spent looking through his collection of about a dozen macros and observing his technique. And using his macros of course!

I would recommend as well having a look at the macros of Thomas Schultz which can be seen below.

The Macros of Thomas Schultz

In his time developing slrn Thomas Schultz put together some macros which are preserved on this web site for download:

One-Key Scoring: These are macros that allow you to create scorefile entries based on the current article via a single function call / keystroke. Two interfaces are available - the first is very simple and can be used to watch or ignore subthreads. The second is more complex, but also more versatile: It can put a score on subjects, "From:" lines or references. If you regularly use these functions, your scorefile will become quite large, so I recommend the perl script Cleanscore that can automatically remove expired entries. Note: As of slrn 0.9.7.0, these macros affect the currently visible article. There is now an option affect_article_at_cursor for those who consider this counter intuitive.
Temporary Scoring: This macro makes it possible to assign a "temporary score" on all articles that match a given regular expression in the subject, author or body. It will not affect your scorefile, so the scores are lost as soon as you exit the group. It can also "tag" matching headers, so they can be selected using the functions defined in nn.sl. This is done automatically if nn.sl is loaded before this file.
Improved Searching: This file is meant as a replacement for the file search.sl that comes with slrn. It also searches through the articles in the current newsgroup, but has nicer features: It leaves threads in their collapsed / uncollapsed status, optionally starts the search at the beginning of the buffer or wraps around the end of the article list.
Sorted Output of Header Lines: Some people like to view header lines in a special order. At your option, this macro set will sort header lines alphabetically, in a user-defined order or as given in the visible_headers slrnrc command. It can be automatically called whenever a new article is read.

Thanks again Thomas for making these macros available!