+2003-03-19 Jesper Harder <harder@ifa.au.dk>
+
+ * mm-util.el (mm-mule-charset-to-mime-charset): Test if
+ sort-coding-systems is defined.
+
2003-03-18 Paul Jarc <prj@po.cwru.edu>
* nnmaildir.el (nnmaildir-open-server,
(defun mm-mule-charset-to-mime-charset (charset)
"Return the MIME charset corresponding to the given Mule CHARSET."
- (if (fboundp 'find-coding-systems-for-charsets)
+ (if (and (fboundp 'find-coding-systems-for-charsets)
+ (fboundp 'sort-coding-systems))
(let (mime)
(dolist (cs (sort-coding-systems
(copy-sequence
+2003-03-18 Kevin Greiner <kgreiner@xpediantsolutions.com>
+
+ * gnus.texi (Gnus Unplugged): Refer to new agent Group/Topic
+ parameters.
+ (Category Syntax): New description.
+ (Category Buffer): New command.
+ (Category Variables): New variables.
+ (Agent as Cache): Expanded description.
+ (Agent Expiry): Expanded description.
+ (Agent Variables): Fixed and new descriptions.
+
+ * infohack.el (batch-makeinfo): Provide local implementation of
+ subst-char-in-region as the built-in implementation is unreliable
+ on Windows XP (Intermittent failure results in build looping
+ forever).
+
2003-03-18 Paul Jarc <prj@po.cwru.edu>
* gnus.texi (Maildir): Replace create-directory with
\e$B$9!#\e(B
@item
-\e$B%@%&%s%m!<%IJ}?K$r7hDj$7$^$9!#\e(B@xref{Agent Categories}.
+@c TRANSLATEME
+\e$B%@%&%s%m!<%IJ}?K$r7hDj$7$^$9!#\e(BIt's fairly simple once you decide whether
+you are going to use agent categories, topic parameters, and/or group
+parameters to implement your policy. If you're new to gnus, it
+is probably best to start with a category @xref{Agent Categories}.
+
+Both topic parameters (@xref{Topic Parameters}) and agent
+categories (@xref{Agent Categories}) provide for setting a policy that
+applies to multiple groups. Which you use is entirely up to you. Topic
+parameters do override categories so, if you mix the two, you'll have to
+take that into account. If you have a few groups that deviate from your
+policy, you can use @xref{Group Parameters} to configure them.
@item
\e$B$($($H\e(B@dots{}\e$B!"0J>e$G$9!#\e(B
\e$B$Y$-$G$"$j!"$=$N5-;v$,LLGr$$$HJ,$+$C$?;~E@$G!"%@%&%s%m!<%I$9$k$?$a$N0u$r\e(B
\e$B<jF0$GIU$1$k$Y$-$J$N$G$9!#\e(B
-\e$B2?$r%@%&%s%m!<%I$9$k$+$r@)8f$9$k<g$JJ}K!$O!"J,N`\e(B (@dfn{category}) \e$B$r:n@.\e(B
-\e$B$7$F!"$=$7$F$=$NJ,N`$K$$$/$D$+\e(B (\e$B$"$k$$$OA4It\e(B) \e$B$N%0%k!<%W$r3d$jEv$F$^$9!#\e(B
-\e$BB>$NJ,N`$KB0$5$J$$%0%k!<%W$O\e(B @code{\e$B=i4|\e(B} \e$BJ,N`$KB0$7$^$9!#\e(BGnus \e$B$OJ,N`$N:n\e(B
-\e$B@.$H4IM}$N$?$a$NFH<+$N%P%C%U%!!<$r;}$C$F$$$^$9!#\e(B
+\e$B2?$r%@%&%s%m!<%I$9$k$+$r@)8f$9$k$?$a$N$h$jM-8z$JJ}K!$N0l$D$O!"J,\e(B
+\e$BN`\e(B (@dfn{category}) \e$B$r:n@.$7$F!"$=$7$F$=$NJ,N`$K$$$/$D$+\e(B (\e$B$"$k$$$OA4\e(B
+\e$BIt\e(B) \e$B$N%0%k!<%W$r3d$jEv$F$k$3$H$G$9!#B>$NJ,N`$KB0$5$J$$%0%k!<%W\e(B
+\e$B$O\e(B @code{\e$B=i4|\e(B} \e$BJ,N`$KB0$7$^$9!#\e(BGnus \e$B$OJ,N`$N:n@.$H4IM}$N$?$a$NFH<+$N%P%C\e(B
+\e$B%U%!!<$r;}$C$F$$$^$9!#\e(B
+
+@c TRANSLATEME
+If you prefer, you can also use group parameters (@pxref{Group
+Parameters}) and topic parameters (@pxref{Topic Parameters}) for an
+alternative approach to controlling the agent. The only real
+difference is that categories are specific to the agent (so there is
+less to learn) while group and topic parameters include the kitchen
+sink.
+
+Since you can set agent parameters in several different places we have
+a rule to decide which source to believe. This rule specifies that
+the parameter sources are checked in the following order: group
+parameters, topic parameters, agent category, and finally customizable
+variables. So you can mix all of these sources to produce a wide range
+of behavior, just don't blame me if you don't remember where you put
+your settings.
@menu
* Category Syntax:: \e$BJ,N`$H$O$I$s$J$b$N$+\e(B
@node Category Syntax
@subsubsection \e$BJ,N`$NJ8K!\e(B
-\e$BJ,N`$OFs$D$N$b$N$+$i$J$j$^$9!#\e(B
+@c TRANSLATEME
+\e$BJ,N`$O\e(B ** \e$B$N$b$N$+$i$J$j$^$9!#\e(B
+A category consists of a name, the list of groups belonging to the
+category, and a number of optional parameters that override the
+customizable variables. The complete list of agent parameters are
+listed below.
-@enumerate
-@item
+@table @code
+@item gnus-agent-cat-name
+The name of the category.
+
+@item gnus-agent-cat-groups
+The list of groups that are in this category.
+
+@item gnus-agent-cat-predicate
(\e$BDL>o\e(B) \e$B$I$N5-;v$r%@%&%s%m!<%I$9$k$N$,E,Ev$+$H$$$&Bg$^$+$JNX3T$rM?$($k=R\e(B
\e$B8l!#$=$7$F\e(B
-@item
+@item gnus-agent-cat-score-file
(\e$BDL>o\e(B) \e$B$I$N5-;v$r%@%&%s%m!<%I$9$k$+$r7h$a$k$H$-$N$h$j$-$a$N:Y$+$$%9%3%"\e(B
\e$B5,B'!#\e(B(\e$B$3$N%@%&%s%m!<%I%9%3%"\e(B (@dfn{download score}) \e$B$ODL>o$N%9%3%"$H$O\e(B
\e$BI,$:$7$b4X78$,L5$$$3$H$KCm0U$7$F$/$@$5$$!#\e(B)
-@end enumerate
+
+@c TRANSLATEME
+@item gnus-agent-cat-enable-expiration
+a boolean indicating whether the agent should expire old articles in
+this group. Most groups should be expired to conserve disk space. In
+fact, its probably safe to say that the gnus.* hierarchy contains the
+only groups that should not be expired.
+
+@item gnus-agent-cat-days-until-old
+an integer indicating the number of days that the agent should wait
+before deciding that a read article is safe to expire.
+
+@item gnus-agent-cat-low-score
+an integer that overrides the value of @code{gnus-agent-low-score}.
+
+@item gnus-agent-cat-high-score
+an integer that overrides the value of @code{gnus-agent-high-score}.
+
+@item gnus-agent-cat-length-when-short
+an integer that overrides the value of
+@code{gnus-agent-short-article}.
+
+@item gnus-agent-cat-length-when-long
+an integer that overrides the value of @code{gnus-agent-long-article}.
+@end table
+
+The name of a category can not be changed once the category has been
+created.
+
+Each category maintains a list of groups that are exclusive members of
+that category. The exclusivity rule is automatically enforced, add a
+group to a new category and it is automatically removed from its old
+category.
\e$B=R8l$N0lHVC1=c$J7A<0$O\e(B @code{true} \e$B$d\e(B @code{false} \e$B$N$h$&$JC1FH$N=R8l$+\e(B
\e$B$i$J$j$^$9!#$3$l$i$NFs$D$O$=$l$>$l!"A4$F$N2DG=$J5-;v$r%@%&%s%m!<%I$9$k$+!"\e(B
\e$B0J2<$N=R8l$O$"$i$+$8$aDj5A$5$l$F$$$^$9$,!"$3$l$i$N$I$l$b$"$J$?$N$d$j$?$$\e(B
\e$B$3$H$K0lCW$7$J$1$l$P!"<+J,$GFH<+$N$b$N$r=q$/$3$H$b$G$-$^$9!#\e(B
+@c TRANSLATEME
+When evaluating each of these predicates, the named constant will be
+bound to the value determined by calling
+@code{gnus-agent-find-parameter} on the appropriate parameter. For
+example, gnus-agent-short-article will be bound to
+@code{(gnus-agent-find-parameter group 'agent-short-article)}. This
+means that you can specify a predicate in your category then tune that
+predicate to individual groups.
+
@table @code
@item short
\e$B5-;v$,\e(B @code{gnus-agent-short-article} \e$B9T$h$jC;$+$1$l$P??!#=i4|@_DjCM\e(B
(agent-predicate . short)
@end lisp
-\e$B$3$l$O\e(B agent \e$BJ,N`$N=i4|CM$HEy2A$J$b$N$G$9!#$3$N$h$&$J0l8l$N=R8l$r;XDj$7\e(B
-\e$B$F$$$k$H$-$O!"\e(B@code{agent-predicate} \e$B;X<($O%I%C%HBP5-K!$G$"$kI,MW$,$"$k\e(B
-\e$B$3$H$KCm0U$7$F$/$@$5$$!#\e(B
+\e$B$3$l$O\e(B agent \e$BJ,N`$N%G%#%U%)%k%H$HEy2A$J%0%k!<%W\e(B/\e$B%H%T%C%/%Q%i%a!<%?$G$9!#\e(B
+\e$B$3$N$h$&$J0l8l$N=R8l$r;XDj$7$F$$$k$H$-$O!"\e(B@code{agent-predicate} \e$B;X<($O\e(B
+\e$B%I%C%HBP5-K!$G$"$kI,MW$,$"$k$3$H$KCm0U$7$F$/$@$5$$!#\e(B
\e$B>e$N$b$N$HEy2A$JD9$$J}$NNc$O\e(B:
@end lisp
@item
-\e$B%0%k!<%W%Q%i%a!<%?;XDj\e(B
+\e$B%0%k!<%W\e(B/\e$B%H%T%C%/%Q%i%a!<%?;XDj\e(B
@lisp
(agent-score ("from"
@findex gnus-category-exit
\e$B%0%k!<%W%P%C%U%!!<$KLa$k\e(B (@code{gnus-category-exit})\e$B!#\e(B
+@c TRANSLATEME
+@item e
+@kindex e (Category)
+@findex gnus-category-customize-category
+Use a customization buffer to set all of the selected category's
+parameters at one time (@code{gnus-category-customize-category}).
+
@item k
@kindex k (\e$BJ,N`\e(B)
@findex gnus-category-kill
@item gnus-agent-high-score
@vindex gnus-agent-high-score
\e$B$3$NCM$h$jBg$-$$%9%3%"$r;}$D5-;v$O9b%9%3%"$G$"$k!#=i4|@_DjCM$O\e(B 0\e$B!#\e(B
+
+@c TRANSLATEME
+@item gnus-agent-expire-days
+@vindex gnus-agent-expire-days
+The number of days that a @samp{read} article must stay in the agent's
+local disk before becoming eligible for expiration (While the name is
+the same, this doesn't mean expiring the article on the server. It
+just means deleting the local copy of the article). What is also
+important to understand is that the counter starts with the time the
+article was written to the local disk and not the time the article was
+read.
+Default 7.
+
+@item gnus-agent-enable-expiration
+@vindex gnus-agent-enable-expiration
+Determines whether articles in a group are, by default, expired or
+retained indefinitely. The default is @code{ENABLE} which means that
+you'll have to disable expiration when desired. On the other hand,
+you could set this to @code{DISABLE}. In that case, you would then
+have to enable expiration in selected groups.
@end table
@node Agent Commands
\e$B$s$,!"$9$G$K%(!<%8%'%s%H$K%@%&%s%m!<%I$7$?5-;v$,$"$k$J$i$P!"\e(Bgnus \e$B$O%5!<\e(B
\e$B%P!<$+$i:F$S5-;v$r%@%&%s%m!<%I$;$:$K!"<j85$K3JG<$5$l$?%3%T!<$r;H$$$^$9!#\e(B
-\e$B$3$NF0:n$O\e(B @code{gnus-agent-cache} \e$B$G@)8f$5$l$^\e(B
-\e$B$9\e(B (@pxref{Agent Variables})\e$B!#\e(B
+@c TRANSLATEME
+If you so desire, you can configure the agent (see @code{gnus-agent-cache}
+@pxref{Agent Variables}) to always download headers and articles while
+plugged. Gnus will almost certainly be slower, but it will be kept
+synchronized with the server. That last point probably won't make any
+sense if you are using a nntp or nnimap backend.
@node Agent Expiry
@subsection \e$B%(!<%8%'%s%H4|8B@Z$l>C5n\e(B
@vindex gnus-agent-expire-days
@findex gnus-agent-expire
@kindex M-x gnus-agent-expire
+@kindex M-x gnus-agent-expire-group
+@findex gnus-agent-expire-group
@cindex Agent expiry
@cindex Gnus Agent expiry
@cindex expiry
-@code{nnagent} \e$B$O4|8B@Z$l>C5n$r07$$$^$;$s!#$=$NBe$o$j$K!"FCJL\e(B
-\e$B$J\e(B @code{gnus-agent-expire} \e$BL?Na$,\e(B @code{gnus-agent-expire-days} \e$BF|$h$j\e(B
-\e$B$b8E$$4{FI5-;v$rA4$F>C5n$7$^$9!#$3$l$O$"$J$?$,%G%#%9%/MFNL$r;H$$@Z$j$=$&\e(B
-\e$B$@$H;W$C$?$H$-$K$$$D$G$b<B9T$9$k$3$H$,$G$-$^$9!#$3$l$OFC$KB.$/$b$J$/8zN(\e(B
-\e$BE*$G$b$J$/!"0lC6;O$a$F$7$^$C$?$i\e(B (@kbd{C-g} \e$B$d$=$NB>$G\e(B) \e$BCfCG$9$k$3$H$b$"\e(B
-\e$B$^$jNI$$$3$H$G$O$"$j$^$;$s!#\e(B
+\e$B%(!<%8%'%s%H%P%C%/%(%s%I\e(B @code{nnagent} \e$B$O4|8B@Z$l>C5n$r07$$$^$;$s!#$($(\e(B
+\e$B$H!">/$J$/$H$bB>$N%P%C%/%(%s%I$N$h$&$K$=$l$r07$$$^$;$s!#$=$NBe$o$j$K!"FC\e(B
+\e$BJL$J\e(B @code{gnus-agent-expire} \e$B$H\e(B @code{gnus-agent-expire-group} \e$BL?Na\e(B
+\e$B$,\e(B @code{gnus-agent-expire-days} \e$B$NF|?t$h$j$b8E$$4{FI5-;v$r$9$Y$F>C5n$7\e(B
+\e$B$^$9!#$3$l$i$O$"$J$?$,%G%#%9%/MFNL$r;H$$@Z$j$=$&$@$H;W$C$?$H$-$K$$$D$G$b\e(B
+\e$B<B9T$9$k$3$H$,$G$-$^$9!#$I$A$i$bFC$KB.$/$b$J$/8zN(E*$G$b$J$/!"$=$l$i$N0l\e(B
+\e$B$D$r$$$C$?$s;O$a$F$7$^$C$?$i\e(B (@kbd{C-g} \e$B$d$=$NB>$G\e(B) \e$BCfCG$9$k$3$H$b$"$^$j\e(B
+\e$BNI$$$3$H$G$O$"$j$^$;$s!#\e(B
\e$BNc$($P\e(B @code{gnus-request-expire-articles} \e$B$N$h$&$JB>$N4X?t$O!"%(!<%8%'\e(B
\e$B%s%H$r%0%k!<%W$KF14|$5$;$k$?$a$K\e(B @code{gnus-agent-expire} \e$B$r<B9T$9$k$+$b\e(B
\e$B$7$l$J$$$3$H$KCm0U$7$F2<$5$$!#\e(B
-@code{gnus-agent-expire-days} \e$B$O@55,I=8=\e(B/\e$BF|?t$N%Z%"$N%j%9%H$G$"$C$F$b9=\e(B
-\e$B$$$^$;$s!#@55,I=8=$O%0%k!<%WL>$K%^%C%A$7!"0[$J$k%0%k!<%W$G0[$J$k4|8B@Z$l\e(B
-\e$B>C5n$r9T$J$&$3$H$r2DG=$K$7$^$9!#\e(B
-
-@lisp
-(setq gnus-agent-expire-days
- '(("alt\\." 7)
- (".*binary" 1)
- ("." 21)))
-@end lisp
-
-\e$B$b$7%j%9%H$N7A<0$r;H$&>l9g$O!":G8e$NMWAG$O%G%#%U%)%k%H$N%a%=%C%I!"$9$J$o\e(B
-\e$B$A$9$Y$F$N%0%k!<%W$K%^%C%A$9$k$b$N$K$7$J$1$l$P$J$j$^$;$s!#@55,I=8=$K4X$7\e(B
-\e$B$F!"$5$i$K$=$l$O%0%k!<%WL>$N@hF,$+$i%^%C%A$7$J$1$l$P$J$j$^$;$s!#\e(B
+\e$B%(!<%8%'%s%H%Q%i%a!<%?\e(B @code{agent-enable-expiration} \e$B$O!"A*Br$7$?%0%k!<\e(B
+\e$B%W$G$N4|8B@Z$l>C5n$rM^@)$9$k$?$a$K;H$o$l$k$+$b$7$l$^$;$s!#\e(B
@vindex gnus-agent-expire-all
-@code{gnus-agent-expire-all} \e$B$,\e(B @code{nil} \e$B$G$J$1$l$P!"$3$NL?Na$OA4$F$N\e(B
-\e$B5-;v\e(B --- \e$BL$FI!"4{FI!"2D;k!"J]N15-;v$r>C5n$7$^$9!#$b$7\e(B @code{nil} (\e$B$3$l$,\e(B
-\e$B=i4|@_DjCM\e(B) \e$B$G$"$l$P!"4{FI5-;v$N$_$,>C5n$NBP>]$H$J$j!"L$FI!"2D;k!"J]N15-\e(B
-\e$B;v$O$5$i$KL54|8B$KJ];}$7$^$9!#\e(B
+@code{gnus-agent-expire-all} \e$B$,\e(B @code{nil} \e$B$G$J$1$l$P!"%(!<%8%'%s%H$N4|\e(B
+\e$B8B@Z$l>C5n%3%^%s%I72$O$9$Y$F$N5-;v\e(B --- \e$BL$FI!"4{FI!"2D;k!"J]N15-;v$r>C5n\e(B
+\e$B$7$^$9!#$b$7\e(B @code{nil} (\e$B$3$l$,=i4|@_DjCM\e(B) \e$B$G$"$l$P!"4{FI5-;v$N$_$,>C5n\e(B
+\e$B$NBP>]$H$J$j!"L$FI!"2D;k!"J]N15-;v$O$5$i$KL54|8B$KJ];}$7$^$9!#\e(B
\e$B4|8B@Z$l>C5n$5$l$F$$$k$O$:$J$N$K;D$C$F$$$k5-;v$r8+$D$1$?$J$i$P!"$?$V$s$$\e(B
\e$B$/$D$+$N\e(B gnus \e$B%(!<%8%'%s%H%U%!%$%k$,2u$l$F$$$^$9!#\e(B
-@code{gnus-agent-regenerate} \e$B$O!"5/$3$j$&$kLdBj$r=$I|$9$k$?$a$NFCJL$J%3\e(B
-\e$B%^%s%I$G$9!#\e(B
+@code{gnus-agent-regenerate} \e$B$H\e(B @code{gnus-agent-regenerate-group} \e$B$O!"\e(B
+\e$B5/$3$j$&$kLdBj$r=$I|$9$k$?$a$NFCJL$J%3%^%s%I$G$9!#\e(B
@node Agent Regeneration
@subsection \e$B%(!<%8%'%s%H$r:n$jD>$9\e(B
\e$B%k$N%G!<%?9=B$$r=$I|$9$k$3$H$G$9!#\e(B
\e$BNc$($P!"5-;v$r%(!<%8%'%s%H$K%@%&%s%m!<%I$7$F$$$k4V$K%5!<%P!<$X$N@\B3$,@Z\e(B
-\e$B$l$F$7$^$&>l9g!"%m!<%+%k$N%G!<%?9=B$$O@\B3$,@Z$l$kA0$K%@%&%s%m!<%I$5$l$?\e(B
-\e$B5-;v$N$3$H$rCN$j$^$;$s!#\e(B@code{gnus-agent-regenerate} \e$B$^$?\e(B
+\e$B$l$F$7$^$&>l9g!"%m!<%+%k$N%G!<%?9=B$$O@\B3$,@Z$l$kA0$K5-;v$,<sHxNI$/%@%&\e(B
+\e$B%s%m!<%I$5$l$?$+$I$&$+$rCN$j$^$;$s!#\e(B@code{gnus-agent-regenerate} \e$B$^$?\e(B
\e$B$O\e(B @code{gnus-agent-regenerate-group} \e$B$r<B9T$9$k$H!"$=$N$h$&$J5-;v$rFs2s\e(B
\e$B%@%&%s%m!<%I$7$J$/$F$b:Q$`$h$&$K%G!<%?9=B$$r99?7$7$^$9!#\e(B
@item gnus-agent-mark-unread-after-downloaded
@vindex gnus-agent-mark-unread-after-downloaded
@code{gnus-agent-mark-unread-after-downloaded} \e$B$,\e(B \e$BHs\e(B-@code{nil} \e$B$@$C$?$i!"\e(B
-\e$B%@%&%s%m!<%I$7$?8e$G5-;v$KL$FI$N0u$rIU$1$^$9!#%G%#%U%)%k%H$O\e(B @code{t} \e$B$G\e(B
-\e$B$9!#\e(B
+\e$B%@%&%s%m!<%I$7$?8e$G5-;v$KL$FI$N0u$rIU$1$^$9!#$3$l$ODL>o!"?7$7$/%@%&%s%m!<\e(B
+\e$B%I$5$l$?5-;v$rL@3N$KL$FI$K$9$k$?$a$N0BA4$J9T0Y$G$9!#%G%#%U%)%k%H\e(B
+\e$B$O\e(B @code{t} \e$B$G$9!#\e(B
@item gnus-agent-consider-all-articles
@vindex gnus-agent-consider-all-articles
\e$B9g$K!"CY$l;~4V$r:G>.$K$7$^$9\e(B (\e$B%0%k!<%W$N>uBV$r99?7$9$k$?$a\e(B
\e$B$K\e(B @code{gnus-agent-regenerate-group} \e$B$r<B9T$9$kI,MW$,$"$k$+$b$7$l$^$;\e(B
\e$B$s!#$G$b!"@\B3$,@Z$l$kA0$K2r@O$5$l$?$9$Y$F$N5-;v$O!"\e(Bunplugged \e$B$N4|4V$KMx\e(B
-\e$BMQ$9$k$3$H$,$G$-$k$G$7$g$&!#\e(B)\e$B!#\e(B
+\e$BMQ$9$k$3$H$,$G$-$k$G$7$g$&!#\e(B)\e$B!#7+$jJV$7$KAx6x$9$k$3$H$ODA$7$$$N$G!"%G%#\e(B
+\e$B%U%)%k%H$O\e(B 10M \e$B$G$9\e(B
@item gnus-server-unopen-status
@vindex gnus-server-unopen-status
\e$B%s%H$,IT3h@-2=$5$l$k$H!"\e(Bgnus \e$B$O$$$D$bC1$K%5!<%P!<$H$N@\B3$r@d$A$^$9!#$3\e(B
\e$B$NJQ?t$NB>$NA*Br;h$K$O\e(B @code{denied} \e$B$H\e(B @code{offline} \e$B$,$"$j!"%(!<%8%'\e(B
\e$B%s%H$,;H$o$l$k>l9g$O8e<T$@$1$,M-8z$G$9!#\e(B
+
+@c TRANSLATEME
+@item gnus-auto-goto-ignores
+@vindex gnus-auto-goto-ignores
+Another variable that isn't a Agent variable, yet so closely related
+that most will look for it here, this variable tells the summary
+buffer how to maneuver around undownloaded (only headers stored in the
+agent) and unfetched (neither article nor headers stored) articles.
+
+The legal values are @code{nil} (maneuver to any article),
+@code{undownloaded} (maneuvering while unplugged ignores articles that
+have not been fetched), @code{always-undownloaded} (maneuvering always
+ignores articles that have not been fetched), @code{unfetched}
+(maneuvering ignores articles whose headers have not been fetched).
@end table
@node Example Setup
@code{gnus-secondary-select-methods} are agentized.
@item
-Decide on download policy. @xref{Agent Categories}.
+
+Decide on download policy. It's fairly simple once you decide whether
+you are going to use agent categories, topic parameters, and/or group
+parameters to implement your policy. If you're new to gnus, it
+is probably best to start with a category @xref{Agent Categories}.
+
+Both topic parameters (@xref{Topic Parameters}) and agent
+categories (@xref{Agent Categories}) provide for setting a policy that
+applies to multiple groups. Which you use is entirely up to you. Topic
+parameters do override categories so, if you mix the two, you'll have to
+take that into account. If you have a few groups that deviate from your
+policy, you can use @xref{Group Parameters} to configure them.
@item
Uhm@dots{} that's it.
mark the articles for downloading manually if it should turn out that
you're interested in the articles anyway.
-The main way to control what is to be downloaded is to create a
-@dfn{category} and then assign some (or all) groups to this category.
-Groups that do not belong in any other category belong to the
-@code{default} category. Gnus has its own buffer for creating and
-managing categories.
+One of the more effective methods for controlling what is to be
+downloaded is to create a @dfn{category} and then assign some (or all)
+groups to this category. Groups that do not belong in any other
+category belong to the @code{default} category. Gnus has its own
+buffer for creating and managing categories.
+
+If you prefer, you can also use group parameters (@pxref{Group
+Parameters}) and topic parameters (@pxref{Topic Parameters}) for an
+alternative approach to controlling the agent. The only real
+difference is that categories are specific to the agent (so there is
+less to learn) while group and topic parameters include the kitchen
+sink.
+
+Since you can set agent parameters in several different places we have
+a rule to decide which source to believe. This rule specifies that
+the parameter sources are checked in the following order: group
+parameters, topic parameters, agent category, and finally customizable
+variables. So you can mix all of these sources to produce a wide range
+of behavior, just don't blame me if you don't remember where you put
+your settings.
@menu
* Category Syntax:: What a category looks like.
@node Category Syntax
@subsubsection Category Syntax
-A category consists of two things.
+A category consists of a name, the list of groups belonging to the
+category, and a number of optional parameters that override the
+customizable variables. The complete list of agent parameters are
+listed below.
-@enumerate
-@item
+@table @code
+@item gnus-agent-cat-name
+The name of the category.
+
+@item gnus-agent-cat-groups
+The list of groups that are in this category.
+
+@item gnus-agent-cat-predicate
A predicate which (generally) gives a rough outline of which articles
are eligible for downloading; and
-@item
+@item gnus-agent-cat-score-file
a score rule which (generally) gives you a finer granularity when
deciding what articles to download. (Note that this @dfn{download
score} is not necessarily related to normal scores.)
-@end enumerate
+
+@item gnus-agent-cat-enable-expiration
+a boolean indicating whether the agent should expire old articles in
+this group. Most groups should be expired to conserve disk space. In
+fact, its probably safe to say that the gnus.* hierarchy contains the
+only groups that should not be expired.
+
+@item gnus-agent-cat-days-until-old
+an integer indicating the number of days that the agent should wait
+before deciding that a read article is safe to expire.
+
+@item gnus-agent-cat-low-score
+an integer that overrides the value of @code{gnus-agent-low-score}.
+
+@item gnus-agent-cat-high-score
+an integer that overrides the value of @code{gnus-agent-high-score}.
+
+@item gnus-agent-cat-length-when-short
+an integer that overrides the value of
+@code{gnus-agent-short-article}.
+
+@item gnus-agent-cat-length-when-long
+an integer that overrides the value of @code{gnus-agent-long-article}.
+@end table
+
+The name of a category can not be changed once the category has been
+created.
+
+Each category maintains a list of groups that are exclusive members of
+that category. The exclusivity rule is automatically enforced, add a
+group to a new category and it is automatically removed from its old
+category.
A predicate in its simplest form can be a single predicate such as
@code{true} or @code{false}. These two will download every available
The following predicates are pre-defined, but if none of these fit what
you want to do, you can write your own.
+When evaluating each of these predicates, the named constant will be
+bound to the value determined by calling
+@code{gnus-agent-find-parameter} on the appropriate parameter. For
+example, gnus-agent-short-article will be bound to
+@code{(gnus-agent-find-parameter group 'agent-short-article)}. This
+means that you can specify a predicate in your category then tune that
+predicate to individual groups.
+
@table @code
@item short
True iff the article is shorter than @code{gnus-agent-short-article}
(agent-predicate . short)
@end lisp
-This is the group parameter equivalent of the agent category default.
+This is the group/topic 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.
@end lisp
@item
-Group Parameter specification
+Group/Topic Parameter specification
@lisp
(agent-score ("from"
@findex gnus-category-exit
Return to the group buffer (@code{gnus-category-exit}).
+@item e
+@kindex e (Category)
+@findex gnus-category-customize-category
+Use a customization buffer to set all of the selected category's
+parameters at one time (@code{gnus-category-customize-category}).
+
@item k
@kindex k (Category)
@findex gnus-category-kill
Articles that have a score higher than this have a high score. Default
0.
+@item gnus-agent-expire-days
+@vindex gnus-agent-expire-days
+The number of days that a @samp{read} article must stay in the agent's
+local disk before becoming eligible for expiration (While the name is
+the same, this doesn't mean expiring the article on the server. It
+just means deleting the local copy of the article). What is also
+important to understand is that the counter starts with the time the
+article was written to the local disk and not the time the article was
+read.
+Default 7.
+
+@item gnus-agent-enable-expiration
+@vindex gnus-agent-enable-expiration
+Determines whether articles in a group are, by default, expired or
+retained indefinitely. The default is @code{ENABLE} which means that
+you'll have to disable expiration when desired. On the other hand,
+you could set this to @code{DISABLE}. In that case, you would then
+have to enable expiration in selected groups.
+
@end table
article into the Agent, Gnus will not download the article from the
server again but use the locally stored copy instead.
-This behaviour can be controlled by @code{gnus-agent-cache}
-(@pxref{Agent Variables}).
+If you so desire, you can configure the agent (see @code{gnus-agent-cache}
+@pxref{Agent Variables}) to always download headers and articles while
+plugged. Gnus will almost certainly be slower, but it will be kept
+synchronized with the server. That last point probably won't make any
+sense if you are using a nntp or nnimap backend.
@node Agent Expiry
@subsection Agent Expiry
@vindex gnus-agent-expire-days
@findex gnus-agent-expire
@kindex M-x gnus-agent-expire
+@kindex M-x gnus-agent-expire-group
+@findex gnus-agent-expire-group
@cindex Agent expiry
@cindex Gnus Agent expiry
@cindex expiry
-@code{nnagent} doesn't handle expiry. Instead, there's a special
-@code{gnus-agent-expire} command that will expire all read articles that
-are older than @code{gnus-agent-expire-days} days. It can be run
-whenever you feel that you're running out of space. It's not
-particularly fast or efficient, and it's not a particularly good idea to
-interrupt it (with @kbd{C-g} or anything else) once you've started it.
+The Agent backend, @code{nnagent}, doesn't handle expiry. Well, at
+least it doesn't handle it like other backends. Instead, there are
+special @code{gnus-agent-expire} and @code{gnus-agent-expire-group}
+commands that will expire all read articles that are older than
+@code{gnus-agent-expire-days} days. They can be run whenever you feel
+that you're running out of space. Neither are particularly fast or
+efficient, and it's not a particularly good idea to interrupt them (with
+@kbd{C-g} or anything else) once you've started one of them.
Note that other functions, e.g. @code{gnus-request-expire-articles},
might run @code{gnus-agent-expire} for you to keep the agent
synchronized with the group.
-@code{gnus-agent-expire-days} can also be a list of regexp/day pairs.
-The regexps will be matched against group names to allow differing
-expiry in different groups.
-
-@lisp
-(setq gnus-agent-expire-days
- '(("alt\\." 7)
- (".*binary" 1)
- ("." 21)))
-@end lisp
-
-If you use the list form, the last element must always be the default
-method---it must always match all groups. Also, for a regexp to match,
-it must match from the beginning of the group's name.
+The agent parameter @code{agent-enable-expiration} may be used to
+prevent expiration in selected groups.
@vindex gnus-agent-expire-all
-If @code{gnus-agent-expire-all} is non-@code{nil}, this command will
-expire all articles---unread, read, ticked and dormant. If @code{nil}
-(which is the default), only read articles are eligible for expiry, and
-unread, ticked and dormant articles will be kept indefinitely.
+If @code{gnus-agent-expire-all} is non-@code{nil}, the agent
+expiration commands will expire all articles---unread, read, ticked
+and dormant. If @code{nil} (which is the default), only read articles
+are eligible for expiry, and unread, ticked and dormant articles will
+be kept indefinitely.
If you find that some articles eligible for expiry are never expired,
-perhaps some Gnus Agent files are corrupted. There's a special
-@code{gnus-agent-regenerate} command to fix possible problems.
+perhaps some Gnus Agent files are corrupted. There's are special
+commands, @code{gnus-agent-regenerate} and
+@code{gnus-agent-regenerate-group}, to fix possible problems.
@node Agent Regeneration
@subsection Agent Regeneration
For example, if your connection to your server is lost while
downloaded articles into the agent, the local data structures will not
-know about articles downloaded prior to the connection failure.
-Running @code{gnus-agent-regenerate} or
+know about articles successfully downloaded prior to the connection
+failure. Running @code{gnus-agent-regenerate} or
@code{gnus-agent-regenerate-group} will update the data structures
such that you don't need to download these articles a second time.
@item gnus-agent-fetched-hook
@vindex gnus-agent-fetched-hook
-Hook run when after finishing fetching articles.
+Hook run when finished fetching articles.
@item gnus-agent-cache
@vindex gnus-agent-cache
@item gnus-agent-mark-unread-after-downloaded
@vindex gnus-agent-mark-unread-after-downloaded
If @code{gnus-agent-mark-unread-after-downloaded} is non-@code{nil},
-mark articles as unread after downloading. The default is t.
+mark articles as unread after downloading. This is usually a safe
+thing to do as the newly downloaded article has obviously not been
+read. The default is t.
@item gnus-agent-consider-all-articles
@vindex gnus-agent-consider-all-articles
connection be lost while fetching (You may need to run
@code{gnus-agent-regenerate-group} to update the group's state.
However, all articles parsed prior to loosing the connection will be
-available while unplugged).
+available while unplugged). The default is 10M so it is unusual to
+see any cycling.
@item gnus-server-unopen-status
@vindex gnus-server-unopen-status
for this variable include @code{denied} and @code{offline} the latter
is only valid if the Agent is used.
+@item gnus-auto-goto-ignores
+@vindex gnus-auto-goto-ignores
+Another variable that isn't a Agent variable, yet so closely related
+that most will look for it here, this variable tells the summary
+buffer how to maneuver around undownloaded (only headers stored in the
+agent) and unfetched (neither article nor headers stored) articles.
+
+The legal values are @code{nil} (maneuver to any article),
+@code{undownloaded} (maneuvering while unplugged ignores articles that
+have not been fetched), @code{always-undownloaded} (maneuvering always
+ignores articles that have not been fetched), @code{unfetched}
+(maneuvering ignores articles whose headers have not been fetched).
+
@end table
@code{gnus-agent-fetch-selected-article} to
@code{gnus-select-article-hook}.
-@item If I read an article while plugged, and the article already exists in the Agent, will it get downloaded once more?
+@item If I read an article while plugged, and the article already exists in
+the Agent, will it get downloaded once more?
@strong{No}, unless @code{gnus-agent-cache} is @code{nil}.
(Info-split))
(save-buffer)))
+(eval-and-compile
+ (when (string-match "windows-nt\\|os/2\\|emx\\|cygwin"
+ (symbol-name system-type))
+ (defun subst-char-in-region (START END FROMCHAR TOCHAR &optional NOUNDO)
+ "From START to END, replace FROMCHAR with TOCHAR each time it occurs.
+If optional arg NOUNDO is non-nil, don't record this change for undo
+and don't mark the buffer as really changed.
+Both characters must have the same length of multi-byte form."
+ (let ((original-buffer-undo-list buffer-undo-list)
+ (modified (buffer-modified-p)))
+ (if NOUNDO
+ (setq buffer-undo-list t))
+ (goto-char START)
+ (let ((from (char-to-string FROMCHAR))
+ (to (char-to-string TOCHAR)))
+ (while (search-forward from END t)
+ (replace-match to t t)))
+ (if NOUNDO
+ (progn (setq buffer-undo-list original-buffer-undo-list)
+ (set-buffer-modidifed-p modified)))))))
+
(defun batch-makeinfo ()
"Emacs makeinfo in batch mode."
(infohack-texi-format (car command-line-args-left)
projects / elisp / gnus.git- / commitdiff