* Note: The information in this file is outdated.  According to
* <URL:http://www.cs.umn.edu/Research/GroupLens/>, the trial of the
* collaborative filtering system for Usenet is finished.
* Chris Siegler <siegler@visi.com> told me he had a working implementation
* of a BBB server.  Although it's currently not online, I'll keep GroupLens
* support in slrn for now.

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/slrnfeat.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.

SLRN may be used to access a secure server using SSL.  To do this, SSL
support must be enabled.

Compiling SLRN with SSL support
-------------------------------

To build slrn with SSL support, you must first obtain and install the
OpenSSL library from http://www.openssl.org.  Beware that some
countries may have import/export regulations concerning such software.
If you get arrested, do not call me!  Just as important, do not
contact me if you have trouble compiling OpenSSL --- I have nothing to
do with the development of OpenSSL.

After installing OpenSSL, configure slrn for SSL support, e.g.,

   ./configure --with-ssl

By default, OpenSSL will install itself in /usr/local/ssl.  If you
install it elsewhere, e.g., $HOME/ssl, then use:

   ./configure --with-ssl=$HOME/ssl

After compiling it, `slrn --version' should indicate SSL support.


Using SLRN with secure servers
------------------------------

As far as slrn is concerned, only those servers whose names are prefixed with
"snews://" are secure and require SSL.  So, to access a secure server such as
netscape's secnews.netscape.com, simply prefix the NNTP host name with
"snews://" and, if required, specify the port number.  For instance,

   slrn -h snews://secnews.netscape.com:563 --create

In your .slrnrc file, you may want to add a line such as:

   server "snews://secnews.netscape.com:563" ".newsrc-netscape"

to indicate that the file ".newsrc-netscape" should be used for this
server.


If the server requires authentication, you may also want to add a line such
as:

   nnrpaccess "snews://secnews.netscape.com:563" "username" "password"

That's it!

-*- mode: text; mode: fold; -*-
The purpose of this note is to provide some instructions on extending the
newsreader in its macro language.

{{{ Introduction

When slrn is started, it reads the .slrnrc user initialization file.
That file may contain one or more `interpret' commands causing the
newsreader to load the specified S-Lang scripts, e.g.,

    interpret ".slrn.sl"
    interpret "src/slrn/macros/search.sl"

Each script must obey the syntax of the S-Lang language.  See the
slang documentation from <http://www.jedsoft.org/slang/> more more
information about the syntax.

Several pre-written macros are included in the slrn distribution in
the macro subdirectory and many more are available from various pages all
over the web.

}}}
---------------------------------------------------------------------------
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");

    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
    performs a regular expression search for subjects.

	variable Last_Search_Str = "";
	define re_subject_search_forward ()
	{
	   variable str;

	   ERROR_BLOCK
	     {
	       () = header_up (1);
	     }

	   !if (header_down (1)) return;

	   str = read_mini ("Subject re-search fwd", Last_Search_Str, "");

	   !if (strlen (str))
	     return;

	   Last_Search_Str = str;
	   !if (re_fsearch_subject (str))
	     error ("Not found.");
	}

    To bind it to, e.g., `s' in the article keymap, use:

	definekey ("re_subject_search_forward", "s", "article");

    Some slrn keyboard functions require a ``prefix argument''.
    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");
	}

   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.

   Some of the built-in keyboard functions will prompt for a
   string.  For example, in article mode, pressing the `:' key will
   prompt for an filename.  The function `set_input_string' may be
   used to provide a response to such a prompt, e.g.,

      % The `:' command will prompt for a filename.
      set_input_string ("/tmp/decoded");
      call ("decode");

   For functions that prompt for a single character, such as

      Do you really want to quit? [Y]es No

   a similar intrinsic function, set_input_chars, may be used to
   provide the answer.

}}}
---------------------------------------------------------------------------
Hooks and Command Reference
---------------------------------------------------------------------------
The above examples used ``intrinsic'' functions such as `call',
`set_integer_variable', etc.  A description of all slrn intrinsic functions
that are available via the interpreter is included in slrnfuns.txt.  A
comprehensive list of all hooks into the newsreader is now also included in
that file.

The S-Lang language includes many other intrinsics, such as `strcmp' and
`is_substr' which are described in the file slangfun.txt that comes with
S-Lang itself.

This file concerns a setup of slrn that is suitable for multiple users.

The installation instructions given in this file provide information about
setting up slrn with defaults that are global to all users.  These defaults
include such information as the name of the organization and the hostname.
In addition, only one newsgroup description file is needed instead of one
per user.

The files that provide such "global" information are put in
  SYSCONFDIR/slrn.rc           : global initialization file and
  DATADIR/slrn/newsgroups.dsc  : newsgroup description file.
The values of SYSCONFDIR and DATADIR can be set when building slrn
(--sysconfdir and --datadir options of ./configure).

On my system, the global slrn.rc file simply contains the two lines:

   set hostname space.mit.edu
   set organization "Center for Space Research"

which will appear in the appropriate headers when a user posts a message. In
addition to specifying these quantities in the slrn.rc file, suitable
defaults may be compiled into the executable.  Simply edit the slrnfeat.h
file for this option.

Background:

  When slrn runsn it looks for a file that contains the description of all
  the news groups.  This is NOT the newsrc file.  Rather, it is a file that
  contains a one line summary of what each group is about.  This file can be
  quite large if there are many newsgroups.  For example, on my system, the
  newsgroup description file is 225 Kilobytes.  It is not desirable for each
  user to have their own private copy of this file, especially when there is
  more than one user of slrn on a given system.  Instead, the system
  administrator only has to keep a copy of it in a directory that slrn knows
  about.  Part of the installation process described in this file involves
  the creation of such a directory.

  slrn assumes that newsgroup description file will be called
  `newsgroups.dsc'.  The directory where this file is located get hardcoded
  into the binary. By default, it is /usr/local/share/slrn, but you can
  change this with the --datadir option when running ./configure.

  Now, you have to obtain the newsgroup description file. You can do that in
  at least two ways.  The easiest is to simply get the file `newsgroups.dsc'
  from space.mit.edu:/pub/davis/slrn.  The other method is just as easy but
  involves slrn to create such a file for you.  This is described below.

With this background, the steps presented below should be clear.

  0. Execute the steps outlines in README before continuing.

  1. Create the directory `/usr/local/share/slrn' (or equivalent; after a
     successful installation of slrn, it should already exist).

  2. Run slrn as follows:

         slrn -f SHAREDIR/slrn/newsgroups -d

     (Of course, make the proper substution of SHAREDIR).  This will create
     a file newsgroups.dsc in SHAREDIR/slrn.

     This step may take some time to complete for slow NNTP connections.

  3. If more that one person will be reading this file, make sure it is
     world readable, e.g.,

         chmod go+r SHAREDIR/newsgroups.dsc


That's it!!