Re: [patch] Agent and download scoring etc.

[Mike McEwan <mike@lotusland.demon.co.uk>]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> Could you also send me a patch for the manual to document this
> much-wished-for feature?

Your wish...

I've also included another small update to `gnus-agent.el' to allow
the use of lists in a group's parameters when specifying `agent-predicate'.

-- 
Mike.

--- ChangeLog.orig	Sun Sep  6 20:01:14 1998
+++ ChangeLog	Sun Sep  6 20:07:09 1998
@@ -1,3 +1,8 @@
+1998-09-06  Mike McEwan  <mike@lotusland.demon.co.uk>
+
+	* gnus-agent.el (gnus-agent-fetch-group-1): Allow lists when
+	specifying `agent-predicate' in a group's parameters.
+
 Sat Sep  5 21:55:01 1998  Lars Magne Ingebrigtsen  <larsi@menja.ifi.uio.no>
 
 	* gnus.el: Pterodactyl Gnus v0.16 is released.
--- gnus-agent.el.orig	Sun Sep  6 20:01:14 1998
+++ gnus-agent.el	Sun Sep  6 20:03:24 1998
@@ -911,7 +911,7 @@
       (setq category (gnus-group-category group))
       (setq predicate
 	    (gnus-get-predicate 
-	     (or (gnus-group-get-parameter group 'agent-predicate)
+	     (or (gnus-group-get-parameter group 'agent-predicate t)
 		 (cadr category))))
       ;; Do we want to download everything, or nothing?
       (if (or (eq (caaddr predicate) 'gnus-agent-true)
--- ChangeLog.orig	1998/09/05 23:27:13
+++ ChangeLog	1998/09/06 19:12:16
@@ -1,3 +1,8 @@
+1998-09-06  Mike McEwan  <mike@lotusland.demon.co.uk>
+
+	* gnus.texi (Category Syntax): Added doc about agent categories
+	and download scoring.
+
 1998-09-05 17:36:14  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
 	* gnus.texi (Sorting Groups): Change.

--- gnus.texi.orig	1998/09/05 23:27:14
+++ gnus.texi	1998/09/06 19:40:41
@@ -11562,11 +11562,21 @@
 @item
 a score rule which (generally) gives you a finer granularity when
 deciding what articles to download.  (Note that this @dfn{download
-score} is wholly unrelated to normal scores.)
+score} is not necessarily related to normal scores.)
 @end enumerate
 
-A predicate consists of predicates with logical operators sprinkled in
-between.
+A predicate in its simplest form can be a single predicate such as
+@code{true} or @code{false}. These two will download every available
+article or nothing respectively. In the case of these two special
+predicates an additional score rule is superfluous.
+
+Predicates of @code{high} or @code{low} download articles in respect of
+their scores in relationship to @code{gnus-agent-high-score} and
+@code{gnus-agent-low-score} as descibed below.
+
+To gain even finer control of what is to be regarded eligible for
+download a predicate can consist of a number of predicates with logical
+operators sprinkled in between.
 
 Perhaps some examples are in order.
 
@@ -11602,7 +11612,7 @@
 
 @table @code
 @item short
-True iff the article is shorter than @code{gnus-agent-short-article}
+True if the article is shorter than @code{gnus-agent-short-article}
 lines; default 100.
 
 @item long
@@ -11610,15 +11620,15 @@
 lines; default 200.
 
 @item low
-True iff the article has a download score less than
+True if the article has a download score less than
 @code{gnus-agent-low-score}; default 0.
 
 @item high
-True iff the article has a download score greater than
+True if the article has a download score greater than
 @code{gnus-agent-high-score}; default 0.
 
 @item spam
-True iff the Gnus Agent guesses that the article is spam.  The
+True if the Gnus Agent guesses that the article is spam.  The
 heuristics may change over time, but at present it just computes a
 checksum and sees whether articles match.
 
@@ -11634,14 +11644,186 @@
 @code{gnus-headers} and @code{gnus-score} dynamic variables are bound to
 useful values.
 
+For example, you could decide that you don't want to download articles
+that were posted more than a certain number of days ago (e.g. posted
+more than @code{gnus-agent-expire-days} ago) you might write a function
+something along the lines of the following:
+
+@lisp
+(defun my-article-old-p ()
+  "Say whether an article is old."
+  (< (time-to-day (date-to-time (mail-header-date gnus-headers)))
+     (- (time-to-day (current-time)) gnus-agent-expire-days)))
+@end lisp
+
+with the predicate then defined as:
+
+@lisp
+(not my-article-old-p)
+@end lisp
+
+or you could append your predicate to the predefined
+@code{gnus-category-predicate-alist} in your @file{~/.gnus.el} or
+wherever.  (Note: this would have to be at a point *after*
+@code{gnus-agent} has been loaded via @code{(gnus-agentize)})   
+
+@lisp
+(defvar  gnus-category-predicate-alist
+  (append gnus-category-predicate-alist
+	 '((old . my-article-old-p))))
+@end lisp
+
+and simply specify your predicate as:
+
+@lisp
+(not old)
+@end lisp
+
+If/when using something like the above, be aware that there are many
+misconfigured systems/mailers out there and so an article's date is not
+always a reliable indication of when it was posted. Hell, some people
+just don't give a damm.
+
+
+The above predicates apply to *all* the groups which belong to the
+category. However, if you wish to have a specific predicate for an
+individual group within a category, or you're just too lazy to set up a
+new category, you can enter a group's individual predicate in it's group 
+parameters like so:
+
+@lisp
+(agent-predicate . short)
+@end lisp
+
+This is the group parameter equivalent of the agent category
+default. Note that when specifying a single word predicate like this,
+the @code{agent-predicate} specification must be in dotted pair
+notation.
+
+The equivalent of the longer example from above would be:
+
+@lisp
+(agent-predicate or high (and (not low) (not long)))
+@end lisp
+
+The outer parenthesis required in the category specification are not
+entered here as, not being in dotted pair notation, the value of the
+predicate is assumed to be a list. 
+ 
+
 Now, the syntax of the download score is the same as the syntax of
 normal score files, except that all elements that require actually
 seeing the article itself are verboten.  This means that only the
-following headers can be scored on: @code{From}, @code{Subject},
-@code{Date}, @code{Xref}, @code{Lines}, @code{Chars}, @code{Message-ID},
-and @code{References}.
+following headers can be scored on: @code{Subject}, @code{From},
+@code{Date}, @code{Message-ID}, @code{References}, @code{Chars},
+@code{Lines}, and @code{Xref}.
+
+As with predicates, the specification of the @code{download score rule}
+to use in respect of a group can be in either the category definition if
+it's to be applicable to all groups in therein, or a group's parameters
+if it's to be specific to that group.
+
+In both of these places the @code{download score rule} can take one of
+three forms:
+
+@table @code
+@enumerate
+@item 
+Score rule
+
+This has the same syntax as a normal gnus score file except only a
+subset of scoring keywords are available as mentioned above.
+
+example:
+
+@itemize @bullet
+@item 
+Category specification
 
+@lisp
+(("from"        
+       ("Lars Ingebrigtsen" 1000000 nil s))
+("lines"
+       (500 -100 nil <)))
+@end lisp
+
+@item 
+Group Parameter specification
+
+@lisp
+(agent-score ("from"        
+                   ("Lars Ingebrigtsen" 1000000 nil s))
+             ("lines"
+                   (500 -100 nil <)))
+@end lisp
+
+Again, note the omission of the outermost parenthesis here.
+@end itemize
+
+@item 
+Agent score file
 
+These score files must *only* contain the permitted scoring keywords
+stated above.
+
+example:
+
+@itemize @bullet
+@item 
+Category specification
+
+@lisp
+("~/News/agent.SCORE")
+@end lisp
+
+or perhaps
+
+@lisp
+("~/News/agent.SCORE" "~/News/agent.group.SCORE")
+@end lisp
+
+@item 
+Group Parameter specification
+
+@lisp
+(agent-score "~/News/agent.SCORE")
+@end lisp
+
+Additional score files can be specified as above. Need I say anything
+about parenthesis.
+@end itemize
+
+@item 
+Use @code{normal} score files
+
+If you dont want to maintain two sets of scoring rules for a group, and
+your desired @code{downloading} criteria for a group are the same as your
+@code{reading} criteria then you can tell the agent to refer to your
+@code{normal} score files when deciding what to download.
+
+These directives in either the category definition or a group's
+parameters will cause the agent to read in all the applicable score
+files for a group, *filtering out* those those sections that do not
+relate to one of the permitted subset of scoring keywords.
+
+@itemize @bullet
+@item 
+Category Specification
+
+@lisp
+file
+@end lisp
+
+@item 
+Group Parameter specification
+
+@lisp
+(agent-score . file)
+@end lisp
+@end itemize
+@end enumerate
+@end table
+ 
 @node The Category Buffer
 @subsubsection The Category Buffer