slrn is an NNTP based news reader.
VMS users: READ VMSNOTES.TXT !!!
OS/2 users: Use the makefile called Makefile.os2
(See also INSTALL for more installation tips--- especially for a multiuser
system)
(Note: For VMS, use either VMSMAKE.COM or DESCRIPT.MMS. In addition, names
like .jnewsrc should be read as jnews.rc, etc...)
To build slrn, build the S-Lang library first. S-Lang is available from
space.mit.edu. slrn uses S-Lang for most of the dirty work such as keymaps,
terminal i/o, and screen management. Once S-Lang has been compiled, compile
slrn. Under Unix, this is accomplished by running the configure script via:
./configure
[edit src/features.h and src/Makefile]
make
make install
Notes:
* It may be necessary to edit the Makefile in src/Makefile.
* Be sure to look at src/sysconf.h after running the configure script
but BEFORE running make.
* If you want support for a local news spool or for inews, edit
src/features.h.
* The executable will be created in src/objs.
Once slrn has been created, you will need to creat a .jnewsrc file in your
$HOME directory. The simplist way to do this is to simply do:
cp $HOME/.newsrc $HOME/.jnewsrc
[Actually, slrn will do this for you automatically. If no newsrc file is
specified, and .newsrc exists, it will create .jnewsrc from .newsrc]
slrn will use a different name for this file while it is under development.
Finally, make sure the environment variable NNTPSERVER is set to point to
your news server (e.g., setenv NNTPSERVER nntp.where-ever.com). This is
only necessary when using NNTP.
[ If you do not already have a .newsrc file, it will be necessary to create
one. To do so, at the unix prompt, type:
slrn -f .jnewsrc -create
This starts the newsreader and retrieves all active newsgroups from the
news server. The act of retrieving all groups can be quite slow for
slow connections. Fortunately, this only happens when the create flag
is used.
From within the news reader, you may subscribe to
desired groups. Press the `L' (capital-L!!) key to list all groups
matching a specified pattern, e.g., comp.*unix*.
Use the `s' key to subscribe.
]
For run-time configuration of slrn such as new keybindings, change in
location of local spool directories, etc. copy the file `slrn.rc' to your
home directory and rename it `.slrnrc' (Unix-- VMS and OS/2 use a different
name). Edit this file to change the keybindings and to associate different
newsrc files with different servers, etc...
To post articles, slrn will look for the following environment variables for
an editor:
SLANG_EDITOR
EDITOR
VISUAL
If it fails, it will resort to vi. `SLANG_EDITOR' is the most versatile
since one can define it to include a command line. For example, if JED is
your editor, use:
setenv SLANG_EDITOR 'jed %s -g %d -tmp'
That's it, type: slrn
Also, try: slrn --help
[If you have a color terminal, use `./slrn -C'. You may need to change
the colors by setting them in your .slrnrc file. If you run under
X Windows, you may consider getting a good color Xterm such as rxvt.
(color_xterm itself is somewhat buggy so I recommend rxvt. See
http://space.mit.edu/~davis for pointers to rxvt.]
After connecting to the server and getting news for the subscribed groups in
you .jnewsrc file, slrn will enter full screen mode listing the newsgroups
that you have subscribed to. Use the UP/DOWN (^P/^N) arrow keys to move
from one group to another. To read news from that group, press the SPACE
bar or simply hit RETURN.
slrn will display the headers for unread articles after getting the required
headers for the group from the server. Use the UP/DOWN arrow keys to move
from one to the other. To delete the current header (i.e., mark as read),
hit the `d' key. `u' will undelete the article. To read the article under
the cursor, press RETURN or SPACE. The screen will split into two windows--
a small one for the headers and a large one for the article. Press SPACE to
scroll through the article and `b' to page backwards. The `t' key may be
used to toggle hiding of selected headers.
The `f' key may be used to followup on the article. `q' will return to the
list of newsgroups. Also, one may use the `n' key to go to thye next unread
article. If there are no more unread articles, pressing `n' will also take
you to the next group. Press the arrow keys to choose one.
At the group level, a new message may be posted by using the `p' key.
Enjoy. However, since this slrn is still in its infancy and is still under
development, please send me your comments regarding the user interface.
I follow the news.software.readers newsgroup. Feel free to post questions
there. Before posting, read the files FAQ, KILL_FAQ, score.txt. Finally
look at the sample slrn.rc file.
davis@space.mit.edu
The GroupLens support should work on most Unix systems. It may even
work for OS/2 or VMS.
For information about GroupLens, see
http://www.cs.umn.edu/Research/GroupLens/trial.html
Edit src/features.h to enable support for GroupLens,
The next step is to create a file called .grplens in your home
directory. This file must contain lines such as:
PSEUDONYM your-pseudonym
BBBHOST grouplens.cs.umn.edu
BBBPORT 9000
comp.os.linux.misc
.
.
rec.food.recipes
rec.arts.movies.current-films
The last lines in the file consist of newsgroup names. See
http://www.cs.umn.edu/Research/GroupLens/trial.html for information
about which groups are supported.
The PSEUDONYM line must contain a registered pseudonym. To register a
pseudonym, see http://www.cs.umn.edu/Research/GroupLens/trial.html for
a registering link.
Once you have created your .grplens file with a registered pseudonym,
you need to add the line
set use_grouplens 1
to your .slrnrc file. After doing that, simply run slrn. When you
enter a supported newsgroup, slrn will retrieve rating for the
newsgroup from the GroupLens server and display the ratings in the
header summary window. The display format is set via the DISPLAYTYPE
line in your .grplens file. Again, see the GroupLens web page for
supported DISPLAYTYPE or look at the documentation in the GroupLens
library directory.
To rate articles that you have read, simply press `0' followed by an
integer `1' through `5' where `1' is a low rating and `5' is a high
rating. After leaving the newsgroup, slrn will send your ratings back
to the GroupLens server. Note: Only those newsgroups that the
GroupLens server supports which are also listed in your .grplens file
may be rated.
The header display in a group for which GroupLens ratings have been
requested, will include a ratings field. The ratings field will
either consist of one or more `*' characters, or a `?'. The `?' means
that there is no GroupLens information for the article for which the
header refers. Articles for which GroupLens information is available
will contain one or more `*' characters on the header lines to
indicate a rating of 1 to 5.
This version of slrn 0.8.8.2 can run under OS/2 as well as Unix or VMS. The
compiled binary, with everything you need to get it running, can be found on
ftp.cdrom.com and ftp-os2.nmsu.edu as slrn0882.zip, in the os2/network/tcpip
directory. There are still a couple of restrictions in this version relative
to the Unix version, but it's working well enough to use. There are also
some additional setup requirements beyond those for slrn itself.
To use this version of slrn:
1) Optionally, place this version of emx.dll somewhere on your LIBPATH. You
must have version 0.9b of the library (which this package includes) in order
to avoid nagging error messages and subtle bugs. You can also place this in
your slrn directory along with slrn.exe, if you wish.
2) Optionally, place slrn.exe somewhere on your PATH.
3) Set two environment variables, either in your CONFIG.SYS or else by
hand before starting slrn:
set NNTPSERVER=your.server.name
set LOGNAME=youruserid
slrn will complain and refuse to run if NNTPSERVER isn't set, and will default
to root (a Bad Idea, but an artifact of the emx library) if LOGNAME isn't set.
The latter will produce a complaint in a later release, so go ahead and set it
now.
4) Edit slrn.rc. There are comments at the top for the entries you must change
for your system, and you may wish to change others as well.
5) Place slrn.rc in a directory by itself. Run slrn from this directory. The
first time you do anything that saves a file, the directory you specified in
slrn.rc will be created; it's best to make that a subdirectory of this one. If
you wish to use a signature file, place it in this directory as well and call
it signatur.txt, or else change the location in the slrn.rc file.
6) Enjoy!
The OS/2 version of slrn will use the full extent of the OS/2 command window
it's run in. You can do "mode co80,50", and it will use all 50 lines. You can
also specify a wider window and it will use the extra width. (If you use a wide
window, please take care that your postings don't exceed 80 characters per
line. The net will thank you.)
This version will also always use the colors specified in the slrn.rc file; you
don't have to use the -C command line switch to enable them. You might wish to
play with the colors; the default settings are pretty, but hard for me to read
(but then, I'm partially colorblind, too.) Because color capability is assumed,
mono statements in the slrn.rc file are processed but have no effect.
Mailing a reply to a message, or forwarding a message, works now. You must
modify the sendmail.cf file supplied with the binary distribution to give it
the name of the host that processes your outgoing SMTP mail, your fully-
qualified domain name (to set your email address with), and the directory
that sendmail is to use to queue the outgoing message. Use the e.exe editor
supplied with OS/2, or another editor that does not mangle tabs, to edit
this file, or else sendmail will act very strangely. The EPM editor is NOT
suitable for this task. Alternatively, if you have a working sendmail.cf for
another application, you can tell slrn to use that by changing the path name
on the sendmail_command line in slrn.rc.
You may use the U key to start a Web browser (by default, WebExplorer, which
is assumed to be installed on your PATH) to browse the first URL encountered
in the current posting. Be careful when doing this: WebExplorer is known to
be less than stable, and running two copies at the same time locked up my
system a few times while playing with this. The supplied slrn.rc uses the
command "start explore %s", which will cause WebExplorer to run at the same
time as slrn. If you wish to make sure you only run one copy at a time, you
can remove the word "start" from the line, which will suspend slrn until you
exit the browser.
slrn now does base64 decoding of MIME messages itself, so I don't have to go
get the OS/2 version of metamail and make it work. Yay!
The following are known bugs and restrictions of the OS/2 version in this
release:
Bad Things happen if you don't change the defaults in slrn.rc to fit your
machine. Don't skip this step. I plan to squash those bugs, but my defaults
may not fit your situation.
The program does not depend on running on an HPFS file system, but the
suggested default file name when saving a file is almost never suitable for
FAT file systems. I'll try to come up with a more sensible default name to
remove this one. Other files are FAT-friendly, though. (This wasn't entirely
true in the 0.8.6 OS/2 version; the newsgroups description file defaulted to
jnews.rc.dsc. If you have this file, you'll need to rename it to ds-jnews.rc.)
The error message "Unable to find a fully qualified hostname." means that slrn
was unable to figure out the host name of your PC, or that it found one but
it wasn't a valid fully-qualified domain name (it didn't contain at least one
".", or contained a "(" or "@"). The best approach to fixing this is to make
sure that the HOSTNAME environment variable contains the host name part of
your machine's name (for example, my PC at home is yakko.nwpros.com, so I put
set HOSTNAME=yakko
in my CONFIG.SYS file) and that your TCP/IP settings have the name of your
domain (in my case, nwpros.com) in the settings notebook. (The location of
this setting varies depending on which dialer you use, or if you have Warp
Connect installed.)
Please drop me email if you discover other bugs; I'll try to squash them and
pass the fixes along. Good luck with slrn for OS/2!
Jay Maynard, jmaynard@nwpros.com
The purpose of this note is to provide some instructions on extending
the newsreader in its macro language.
The present implementation does not provide many hooks into the
newsreader. More capabilities will be added in subsequent releases.
When slrn is started, it reads the .slrnrc user initialization file.
That file may contain the `interpret' command which causes the
newsreader to load a specified S-Lang script, e.g.,
interpret ".slrn.sl"
The script file must obey the syntax of the S-Lang language. See
slang/doc/slang.tex for information about the syntax. This
distribution includes a file called `slrn.sl' which contains examples
of functions described in this document.
This macro file can define hooks that the newsreader will call, new
functions with keybindings, etc...
---------------------------------------------------------------------------
Defining Key Macros
---------------------------------------------------------------------------
Although one is able to bind keys to specific functions via lines
of the form
setkey group "refresh_groups" "G"
in the .slrnrc file, it is not possible to defined more
complicated actions in this manner. However, macros can be
defined by using a S-Lang script. For example, the
`refresh_groups' internal function refreshes the newsgroups but it
does not cause the cursor to move to the top of the newsgroup
list. On the other hand, the internal function `bob' moves to the
top of the list but it does not refresh the groups. One can
define a S-Lang function to perform both actions:
define refresh_groups_bob ()
{
call ("refresh_groups");
call ("bob");
}
and bind it to a key:
definekey ("refresh_groups_bob", "g", "group");
Note: It is not yet possible to write this as:
define refresh_groups_bob ()
{
refresh_groups ();
bob ();
}
This restriction will be lifted in the future.
The `definekey' function takes 3 arguments:
function to execute
keybinding
keymap name ("article" or "group")
Here is another macro that may be used in article mode. It marks
as read all articles not given the `*' mark, removes the `*' marks,
``expunges'' all articles marked as read, moves to the top of the
list, and selects the first article:
define nn_like_function ()
{
call ("catchup_all");
set_prefix_argument (1);
call ("toggle_header_tag"); % If used with prefix, it untags all
call ("art_xpunge"); % remove read articles
call ("art_header_bob"); % goto top of list
call ("scroll_dn"); % read article
}
To bind it to, e.g., `+' in the article keymap, use:
definekey ("nn_like_function", "+", "article");
Note the use of the `set_prefix_argument' function. This is
necessary so that the `toggle_header_tag' will remove all header tags.
Many people find the use of prefix arguments somewhat strange.
For example, instead of typing `ESC 1 ESC p' to reconstruct a thread,
one can simply use the function:
define my_recreate_thread ()
{
set_prefix_argument (1);
call ("get_parent_header");
}
Finally, here is a function that pipes the current article to a
command called `most' (a paging program similar to more/less):
define pipe_to_most ()
{
pipe_article ("most");
}
definekey ("pipe_to_most", "&", "article");
Here it has been bound to the `&' key. Most likely one will want
to pipe the article to a shell script for further processing.
---------------------------------------------------------------------------
Hooks
---------------------------------------------------------------------------
Currently, the newsreader
recognizes the following hooks:
startup_hook
This hook is called right after the newsreader is initialized
and immediately before checking for news. This hook allows
the user to set variables on a server by server basis.
Here is an example:
define startup_hook ()
{
!if (strcmp (server_name (), "uhog"))
{
set_integer_variable ("lines_per_update", 20);
set_integer_variable ("read_active", 0);
}
}
It simply sets the `lines_per_update' variable to 20 and turns
off reading of the active file if the servername is `uhog' (it
is a slow server).
group_mode_hook
This hook is called after checking for news and immediately
before entering the main keyboard loop.
article_mode_hook
This hook is called immediately before going into article mode.
One can set variables based on the group name. For example,
define article_mode_hook ()
{
variable sorting_method = 7;
variable author_display = 2;
variable signature_file = ".signature";
if (is_substr (current_newsgroup (), "binaries")
or is_substr (current_newsgroup (), "pictures"))
{
sorting_method = 3;
author_display = 0;
}
if (strncmp (current_newsgroup (), "comp.", 5))
signature_file = ".nerd-signature";
set_integer_variable ("sorting_method", sorting_method);
set_integer_variable ("author_display", author_display);
set_string_variable ("signature", signature_file);
}
changes the `sorting_method' and `author_display' variables to
something more appropriate for newgroups which contain encoded
articles.
header_number_hook
If defined, this function will be called after selecting a header
via a header number.
---------------------------------------------------------------------------
Command Reference
---------------------------------------------------------------------------
The above examples used ``intrinsic'' functions such as `call',
`set_integer_variable', etc. This section describes all slrn
intrinsic functions that are available via the interpreter. The code
S-Lang langauge includes many others such as `strcmp' and `is_substr'
which are not described here.
---------------------------------------------------------------------------
call
Prototype: Void call (String fun);
This function is used to execute an interactive slrn internal
function. Such functions are used with `setkey' statements in the
.slrnrc startup files.
See Also: definekey, undefinekey, set_prefix_argument
---------------------------------------------------------------------------
collapse_threads
Prototype: Void collapse_threads ();
This function will collapse all threads in the current newsgroup.
See also: uncollapse_threads
---------------------------------------------------------------------------
current_newsgroup
Prototype: String current_newsgroup ();
This function returns the name of the current newsgroup.
See Also: server_name
---------------------------------------------------------------------------
definekey
Prototype: definekey (String fun, String key, String km);
This function is used to bind a key sequence specified by `key' to
a function `fun' in the keymap `km'. Here `fun' can be any
predefined slang function that takes 0 arguments and returns void.
The parameter `km' must be either "article" or "group".
See Also: undefinekey, call, set_prefix_argument
---------------------------------------------------------------------------
error
Prototype: Void error (String s);
This function generates a S-Lang error and displays a message given
by `s'.
See Also: message
---------------------------------------------------------------------------
get_header_flags
Prototype: Integer get_header_flags ();
This functions returns the flags for the current header. This
integer is a bitmapped value whose bits are defined by the following
constants:
HEADER_READ : set if header is marked as read
HEADER_TAGGED : set if header has `*' tag
HEADER_HIGH_SCORE : set if header has high score
HEADER_LOW_SCORE : set if header has low score
See also: set_header_flags
---------------------------------------------------------------------------
get_select_box_response
Prototype: Integer get_select_box_response (title, item_1, ..., n_items);
This function pops a selection box and queries the user for a
response. An integer is returned which indicates the user's choice.
For example:
variable rsp = get_select_box_response (
"Pick a number:",
"one", "two", "three", "four",
4);
message (Sprintf ("You chose %d", rsp, 1));
See also: read_mini, message
---------------------------------------------------------------------------
get_variable_value
Prototype: Value get_variable_value (String v);
This function returns the value of an internal variable specified
by `v'. Here `v' must be one of the variable names that can be
used in .slrnrc `set' commands. The type of the object returned will
depend upon the type of the object `v' represents.
See Also: set_integer_variable, set_string_variable
---------------------------------------------------------------------------
goto_num_tagged_header
Prototype: Void goto_num_tagged_header (Integer n);
This function causes the header with numerical tag `n' to become the
current header.
See also: header_down, get_header_flags, call
---------------------------------------------------------------------------
header_down
Prototype: Integer header_down (Integer n);
The function moves the current position down `n' headers. It
returns the number that was actually moved.
See also: header_up
---------------------------------------------------------------------------
header_up
Prototype: header_up ();
The function moves the current position up `n' headers. It
returns the number that was actually moved.
See also: header_down
---------------------------------------------------------------------------
make_home_filename
Prototype: String make_home_filename (name);
This function returns the complete filename associated with a file
called `name' located in the user's home directory.
See Also: read_mini
---------------------------------------------------------------------------
message
Prototype: Void message (String m);
The `message' function displays the string `m'.
See Also: error, get_select_box_response
---------------------------------------------------------------------------
next_tagged_header
Prototype: next_tagged_header ();
This function moves the current header position to the next `*'
tagged header.
See also: prev_tagged_header, goto_num_tagged_header, header_up, header_down
---------------------------------------------------------------------------
pipe_article
Prototype: Void pipe_article (String cmd);
This function may be used to pipe the current article to the command
given by the `cmd' argument.
See Also: `read_mini'
---------------------------------------------------------------------------
prev_tagged_header
Prototype: prev_tagged_header ();
This function moves the current header position to the previous `*'
tagged header.
See also: next_tagged_header, goto_num_tagged_header, header_up, header_down
---------------------------------------------------------------------------
quit
Prototype: Void quit (Integer exit_status);
This function will cause the newsreader to exit with exit status
specified by `exit_status'.
See Also: call
---------------------------------------------------------------------------
re_bsearch_author
Prototype: Integer re_bsearch_author (String regexp);
Search backward for header whose author matches regular expression
`regexp'. If successful, it returns 1 and the current header is set
to the matching header. It returns 0 upon failure.
See also: re_fsearch_author, re_fsearch_subject
---------------------------------------------------------------------------
re_bsearch_subject
Prototype: Integer re_bsearch_subject (String regexp);
Search backward for header whose subject matches regular expression
`regexp'. If successful, it returns 1 and the current header is set
to the matching header. It returns 0 upon failure.
See also: re_fsearch_author, re_bsearch_subject
---------------------------------------------------------------------------
re_fsearch_author
Prototype: Integer re_bsearch_author (String regexp);
Search forward for header whose author matches regular expression
`regexp'. If successful, it returns 1 and the current header is set
to the matching header. It returns 0 upon failure.
See also: re_bsearch_author, re_fsearch_subject
---------------------------------------------------------------------------
re_fsearch_subject
Prototype: Integer re_fsearch_subject (String regexp);
Search forward for header whose subject matches regular expression
`regexp'. If successful, it returns 1 and the current header is set
to the matching header. It returns 0 upon failure.
See also: re_fsearch_author, re_bsearch_subject
---------------------------------------------------------------------------
re_search_article
Prototype: Integer re_search_article (String pat);
This function searches forward in the article associated with the
currently selected header for a string matching the regular
expression given by the parameter `pat'. It returns 0 if no
matching line is found. Otherwise, it returns 1 and the matching
line will be left on the stack as a string.
See also: search_article
---------------------------------------------------------------------------
read_mini
Prototype: String read_mini (String p, String init);
This function will prompt the user for a string value using prompt
`p'. The second parameter is used to specify the default value.
See Also:
---------------------------------------------------------------------------
search_article
Prototype: Integre search_article (String str);
This function searches forward in the article associated with the
currently selected header for the string given by the parameter
`str'. It returns 0 if no matching line is found. Otherwise, it
returns 1 and the matching line will be left on the stack as a
string.
See also: re_search_article
---------------------------------------------------------------------------
server_name
Prototype: String server_name ();
The `server_name' function returns the name of the current server.
See Also: current_newsgroup
---------------------------------------------------------------------------
set_header_flags
Prototype: Void set_header_flags (Integer flags);
This function may be used to set the flags associated with the
currently selected header. See the description for the
`get_header_flags' function for more information.
See also: get_header_flags
---------------------------------------------------------------------------
set_integer_variable
Prototype: Void set_integer_variable (String name, Integer v);
This function may be used to set the value of the internal integer
variable specified by `name' to value `v'. `name' must be an integer
variable name allowed in .slrnrc `set' commands.
See Also: set_string_variable, get_variable_value
---------------------------------------------------------------------------
set_prefix_argument
Prototype: Void set_prefix_argument (Integer val);
The `set_prefix_argument' function may be used to set the prefix
argument to `val'. It is mainly used immediately before `calling'
internal functions which take prefix arguments.
See Also: `call'
---------------------------------------------------------------------------
set_string_variable
Prototype: Void set_string_variable (String name, String v);
This function may be used to set the value of the internal string
variable specified by `name' to value `v'. `name' must be a string
variable name allowed in .slrnrc `set' commands.
See Also: set_integer_variable, get_variable_value
---------------------------------------------------------------------------
uncollapse_threads
Prototype: Void uncollapse_threads ();
This function uncollapses all threads. This is usually necessary
if one wants to use the header movement functions to access hidden
headers.
See also: collapse_threads
---------------------------------------------------------------------------
undefinekey
Prototype: Void undefinekey (String key, String map);
This function undefineds a key sequence specified by `key' from
keymap `map'.
See Also: definekey
---------------------------------------------------------------------------
update
Prototype: update ();
This function may be used to force the display to be updated.
See also: message
---------------------------------------------------------------------------
See VMSNOTES.TXT about potential problems with building slrn on VMS.
After building slrn, you must do:
$ slrn :== $device:[directory.of.slrn]slrn.exe
$ define/job nntpserver news.server.name
$ slrn -create -f jnews.rc
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.