README for simple adaptive scoring with slrn
============================================

NOTE: You need slrn >= 0.9.7.3 for these macros.

This is a collection of macros that enable slrn to create score file
entries based on your reading behaviour.

You can define rules to, for example, automagically score threads up that you
have read, or to hide followups to articles that you've deleted.

The basic principle is simple: As soon as you leave a group, the
macros look what you have done with the articles in the group (e.g. read,
deleted, replied to, etc.). Based on rules you have previously
defined, they extract a header from each of them and create a score
pattern for it. 

To use the macros, you have to perform some steps:

- Modify adsc.sl according to your configuration
  (see included comments)

- Put adsc.sl and adscfuncs.sl somewhere

- Put "interpret <path to adsc.sl>" into your .slrnrc

- Put "include <path given in ADSC_SCOREFILE>" into your score file
  (which is ~/News/Score by default)
  
- Create/modify your "startup_hook" to include the rule definitions:
  (see below for examples)

    Syntax: 
        
      adsc_create_rule( type, score, group, header, expire )

        - TYPE: To which type of articles does this rule apply
        
                ADSC_READ        To all read articles
                ADSC_DELETED     To all deleted articles
                ADSC_UNREAD      To all unread articles
                ADSC_REPLIED     To all replied articles
                ADSC_FOLLOWEDUP  To all articles you have followed up to
        
        - SCORE: The score matched articles get
                 (positive or negative)
                 
        - GROUP: In which groups the rule is to be used
                 - Globs like "comp.os.*" are possible
                 - Special meaning of NULL: Use the rule in all groups
                   but apply the generated scores only within the same group
                   as the articles that generated them.
        
        - HEADER: On which header the score is to be based on
                  - Special value "THREAD": Puts the value of
                    "Message-ID" into a "References" pattern, so
                    all followups to the article are matched
                    
        - EXPIRE: How many days the generated scores are to be valid                    
                    
                    
    Examples: 

           Give the authors of read articles a bonus of 1 in all groups
           for ten days:
   
               adsc_create_rule( ADSC_READ, 1, "*", "From", 10 );

           Give the threads started by read articles a bonus of 2 in 
           the current group for ten days:

               adsc_create_rule( ADSC_READ, 2, NULL, "Thread", 10 );

           Give the authors of deleted articles a malus of 3 in 
           the current group for ten days:

               adsc_create_rule( ADSC_DELETED, -3, NULL, "From", 10 );

           Give the threads started by deleted articles a malus of 3 in 
           the current group for ten days:

               adsc_create_rule( ADSC_DELETED, -3, NULL, "Thread", 10 );
   
           Give the treads started by articles you have reacted on a bonus
           of 20 in the current group:
   
              adsc_create_rule( ADSC_FOLLOWEDUP, 20, NULL, "Thread", 20 );
              adsc_create_rule( ADSC_REPLIED, 20, NULL, "Thread", 20 );
       
  - Run "cleanscore" (see slrn/contrib directory) on the
    ADSC_SCOREFILE regularly to remove obsoleted entries 
    
  - Read news :)

Note that the score file may grow rapidly even if you use only a
few rules. Depending on your equipment, this may slow down the
entering of a group considerably. Nevertheless, I've found it worth
the extra time slrn needs for applying the score rules.

Comments are welcome!  
  
Robin Sommer  
<rsommer@cs.uni-sb.de>