X-Git-Url: http://cgit.sxemacs.org/?p=gnus;a=blobdiff_plain;f=texi%2Fgnus.texi;h=ec316b939c13f74267eb596f3c368485dba5a030;hp=8264e714ec9db544b2e9ae08154ccac851e50c16;hb=9eb9d4904cd4cf0d9317355ebcb430390833babc;hpb=40c3c84356b403e9c4eb89758009b53c8c180180

diff --git a/texi/gnus.texi b/texi/gnus.texi
index 8264e714e..ec316b939 100644
--- a/texi/gnus.texi
+++ b/texi/gnus.texi
@@ -1,7 +1,7 @@
 \input texinfo                  @c -*-texinfo-*-
 
 @setfilename gnus
-@settitle Gnus 5.4.67 Manual
+@settitle Quassia Gnus 0.6 Manual
 @synindex fn cp
 @synindex vr cp
 @synindex pg cp
@@ -309,7 +309,7 @@ into another language, under the above conditions for modified versions.
 @tex
 
 @titlepage
-@title Gnus 5.4.67 Manual
+@title Quassia Gnus 0.6 Manual
 
 @author by Lars Magne Ingebrigtsen
 @page
@@ -345,7 +345,7 @@ can be gotten by any nefarious means you can think of---@sc{nntp}, local
 spool or your mbox file.  All at the same time, if you want to push your
 luck.
 
-This manual corresponds to Gnus 5.4.67.
+This manual corresponds to Quassia Gnus 0.6.
 
 @end ifinfo
 
@@ -408,7 +408,8 @@ If you want to start Gnus in a different frame, you can use the command
 @kbd{M-x gnus-other-frame} instead.
 
 If things do not go smoothly at startup, you have to twiddle some
-variables. 
+variables in your @file{~/.gnus} file.  This file is similar to
+@file{~/.emacs}, but is read when gnus starts.
 
 @menu
 * Finding the News::    Choosing a method for getting news.
@@ -677,11 +678,12 @@ zombies later (with @kbd{A z}) and either kill them all off properly
 
 @item gnus-subscribe-randomly
 @vindex gnus-subscribe-randomly
-Subscribe all new groups randomly.
+Subscribe all new groups in arbitrary order.  This really means that all
+new groups will be added at ``the top'' of the grop buffer.
 
 @item gnus-subscribe-alphabetically
 @vindex gnus-subscribe-alphabetically
-Subscribe all new groups alphabetically.
+Subscribe all new groups in alphabetical order.
 
 @item gnus-subscribe-hierarchically
 @vindex gnus-subscribe-hierarchically
@@ -696,7 +698,8 @@ up.  Or something like that.
 @item gnus-subscribe-interactively
 @vindex gnus-subscribe-interactively
 Subscribe new groups interactively.  This means that Gnus will ask
-you about @strong{all} new groups.
+you about @strong{all} new groups.  The groups you choose to subscribe
+to will be subscribed hierarchically.
 
 @item gnus-subscribe-killed
 @vindex gnus-subscribe-killed
@@ -984,13 +987,17 @@ A hook run while Gnus is being loaded.  Note that this hook will
 normally be run just once in each Emacs session, no matter how many
 times you start Gnus.
 
+@item gnus-before-startup-hook
+@vindex gnus-before-startup-hook
+A hook run after starting up Gnus successfully.
+
 @item gnus-startup-hook
 @vindex gnus-startup-hook
-A hook run after starting up Gnus successfully.
+A hook run as the very last thing after starting up Gnus
 
 @item gnus-started-hook
 @vindex gnus-started-hook
-A hook run as the very last thing after starting up Gnus
+A hook that is run as the very last thing after starting up Gnus
 successfully.
 
 @item gnus-check-bogus-newsgroups
@@ -1408,9 +1415,9 @@ minimum amount of fuzz (@code{gnus-group-quick-select-group}).  No
 scoring/killing will be performed, there will be no highlights and no
 expunging.  This might be useful if you're in a real hurry and have to
 enter some humongous group.  If you give a 0 prefix to this command
-(i.e., @kbd{0 M-RET}), Gnus won't even generate the summary buffer.
-This might be useful if you want to toggle threading before entering the
-group.
+(i.e., @kbd{0 M-RET}), Gnus won't even generate the summary buffer,
+which is useful if you want to toggle threading before generating the
+summary buffer (@pxref{Summary Generation Commands}).
 
 @item M-SPACE
 @kindex M-SPACE (Group)
@@ -1629,7 +1636,7 @@ Two closely related variables are @code{gnus-level-default-subscribed}
 (default 3) and @code{gnus-level-default-unsubscribed} (default 6),
 which are the levels that new groups will be put on if they are
 (un)subscribed.  These two variables should, of course, be inside the
-relevant legal ranges.
+relevant valid ranges.
 
 @vindex gnus-keep-same-level
 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
@@ -1656,10 +1663,10 @@ give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
 use this level as the ``work'' level.
 
 @vindex gnus-activate-level
-Gnus will normally just activate groups on level
-@code{gnus-activate-level} or less.  If you don't want to activate
-unsubscribed groups, for instance, you might set this variable to
-5.  The default is 6.
+Gnus will normally just activate (i. e., query the server about) groups
+on level @code{gnus-activate-level} or less.  If you don't want to
+activate unsubscribed groups, for instance, you might set this variable
+to 5.  The default is 6.
 
 
 @node Group Score
@@ -1776,7 +1783,7 @@ to subscribe to @sc{nntp} groups, @pxref{Browse Foreign Server}.
 @findex gnus-group-rename-group
 @cindex renaming groups
 Rename the current group to something else
-(@code{gnus-group-rename-group}).  This is legal only on some
+(@code{gnus-group-rename-group}).  This is valid only on some
 groups---mail groups mostly.  This command might very well be quite slow
 on some backends.
 
@@ -1871,7 +1878,7 @@ this command without a prefix, Gnus will guess at the file type.
 Make an ephemeral group based on a web search
 (@code{gnus-group-make-web-group}).  If you give a prefix to this
 command, make a solid group instead.  You will be prompted for the
-search engine type and the search string.  Legal search engine types
+search engine type and the search string.  Valid search engine types
 include @code{dejanews}, @code{altavista} and @code{reference}.
 @xref{Web Searches}.
 
@@ -1882,7 +1889,8 @@ This function will delete the current group
 (@code{gnus-group-delete-group}).  If given a prefix, this function will
 actually delete all the articles in the group, and forcibly remove the
 group itself from the face of the Earth.  Use a prefix only if you are
-absolutely sure of what you are doing.
+absolutely sure of what you are doing.  This command can't be used on
+read-only groups (like @code{nntp} group), though.
 
 @item G V
 @kindex G V (Group)
@@ -1975,8 +1983,9 @@ If this symbol is present in the group parameter list and set to
 @code{t}, newly composed messages will be @code{Gcc}'d to the current
 group. If it is present and set to @code{none}, no @code{Gcc:} header
 will be generated, if it is present and a string, this string will be
-inserted literally as a @code{gcc} header (this symbol takes precedence over
-any default @code{Gcc} rules as described later).
+inserted literally as a @code{gcc} header (this symbol takes precedence
+over any default @code{Gcc} rules as described later).  @xref{Archived
+Messages}
 
 @item auto-expire
 @cindex auto-expire
@@ -2004,14 +2013,14 @@ the symbols @code{never} or @code{immediate}.
 @item score-file
 @cindex score file group parameter
 Elements that look like @code{(score-file . "file")} will make
-@file{file} into the current score file for the group in question.  This
-means that all score commands you issue will end up in that file. 
+@file{file} into the current adaptive score file for the group in
+question.  All adaptive score entries will be put into this file.
 
 @item adapt-file
 @cindex adapt file group parameter
 Elements that look like @code{(adapt-file . "file")} will make
-@file{file} into the current adaptive score file for the group in
-question.  All adaptive score entries will be put into this file.
+@file{file} into the current adaptive file for the group in question.
+All adaptive score entries will be put into this file.
 
 @item admin-address
 When unsubscribing from a mailing list you should never send the
@@ -2021,7 +2030,7 @@ put the admin address somewhere convenient.
 
 @item display
 Elements that look like @code{(display . MODE)} say which articles to
-display on entering the group.  Legal values are:
+display on entering the group.  Valid values are:
 
 @table @code
 @item all
@@ -2524,7 +2533,7 @@ really neat, I think.
 @vindex gnus-topic-line-format
 The topic lines themselves are created according to the
 @code{gnus-topic-line-format} variable (@pxref{Formatting Variables}).
-Legal elements are:
+Valid elements are:
 
 @table @samp
 @item i
@@ -2781,7 +2790,7 @@ allowed---@code{visible} and @code{invisible}.
 @cindex topic parameters
 
 All groups in a topic will inherit group parameters from the parent (and
-ancestor) topic parameters.  All legal group parameters are legal topic
+ancestor) topic parameters.  All valid group parameters are valid topic
 parameters (@pxref{Group Parameters}).  
 
 Group parameters (of course) override topic parameters, and topic
@@ -2848,8 +2857,8 @@ Enter the server buffer (@code{gnus-group-enter-server-mode}).
 @item a
 @kindex a (Group)
 @findex gnus-group-post-news
-Post an article to a group (@code{gnus-group-post-news}).  The current
-group name will be used as the default.
+Post an article to a group (@code{gnus-group-post-news}).  If given a
+prefix, the current group name will be used as the default.
 
 @item m
 @kindex m (Group)
@@ -3165,8 +3174,8 @@ Article number.
 @item S
 Subject string.
 @item s
-Subject if the article is the root or the previous article had a
-different subject, @code{gnus-summary-same-subject} otherwise.
+Subject if the article is the root of the thread or the previous article
+had a different subject, @code{gnus-summary-same-subject} otherwise.
 (@code{gnus-summary-same-subject} defaults to @samp{}.)
 @item F
 Full @code{From} header.
@@ -3204,7 +3213,7 @@ Unread.
 @item R
 Replied.
 @item i
-Score as a number.
+Score as a number (@pxref{Scoring}).
 @item z
 @vindex gnus-summary-zcore-fuzz
 Zcore, @samp{+} if above the default level and @samp{-} if below the
@@ -3233,6 +3242,8 @@ An @samp{=} (@code{gnus-not-empty-thread-mark}) will be displayed if the
 article has any children.
 @item P
 The line number.
+@item O
+Download mark.
 @item u
 User defined specifier.  The next character in the format string should
 be a letter.  Gnus will call the function
@@ -3245,7 +3256,7 @@ into the summary just like information from any other summary specifier.
 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
 have to be handled with care.  For reasons of efficiency, Gnus will
 compute what column these characters will end up in, and ``hard-code''
-that.  This means that it is illegal to have these specs after a
+that.  This means that it is invalid to have these specs after a
 variable-length spec.  Well, you might not be arrested, but your summary
 buffer will look strange, which is bad enough.
 
@@ -3277,7 +3288,8 @@ Gnus version.
 @item U
 Number of unread articles in this group.
 @item e
-Number of unselected articles in this group.
+Number of unread articles in this group that aren't displayed in the
+summary buffer.
 @item Z
 A string with the number of unread and unselected articles represented
 either as @samp{<%U(+%e) more>} if there are both unread and unselected
@@ -3289,13 +3301,13 @@ shortened to @samp{r.a.anime}.
 @item S
 Subject of the current article.
 @item u
-User-defined spec.
+User-defined spec (@pxref{User-Defined Specs}).
 @item s
-Name of the current score file.
+Name of the current score file (@pxref{Scoring}).
 @item d
-Number of dormant articles.
+Number of dormant articles (@pxref{Unread Articles}).
 @item t
-Number of ticked articles.
+Number of ticked articles (@pxref{Unread Articles}).
 @item r
 Number of articles that have been marked as read in this session. 
 @item E
@@ -3370,8 +3382,8 @@ Go to the previous summary line of an unread article
 @kindex j (Summary)
 @kindex G j (Summary)
 @findex gnus-summary-goto-article
-Ask for an article number and then go to that article
-(@code{gnus-summary-goto-article}). 
+Ask for an article number or @code{Message-ID}, and then go to that
+article (@code{gnus-summary-goto-article}).
 
 @item G g
 @kindex G g (Summary)
@@ -3518,13 +3530,16 @@ Go to the article with the highest score
 @findex gnus-summary-goto-last-article
 Go to the previous article read (@code{gnus-summary-goto-last-article}).
 
-@item G p
-@kindex G p (Summary)
+@item G o
+@kindex G o (Summary)
 @findex gnus-summary-pop-article
+@cindex history
+@cindex article history
 Pop an article off the summary history and go to this article
 (@code{gnus-summary-pop-article}).  This command differs from the
 command above in that you can pop as many previous articles off the
-history as you like.
+history as you like.  For a somewhat related issue (if you use this
+command a lot), @pxref{Article Backlog}.
 @end table
 
 
@@ -3731,9 +3746,9 @@ This command understands the process/prefix convention
 @item S O m
 @kindex S O m (Summary)
 @findex gnus-uu-digest-mail-forward
-Digest the current series and forward the result using mail
-(@code{gnus-uu-digest-mail-forward}).  This command uses the
-process/prefix convention (@pxref{Process/Prefix}). 
+Digest the current series (@pxref{Decoding Articles}) and forward the
+result using mail (@code{gnus-uu-digest-mail-forward}).  This command
+uses the process/prefix convention (@pxref{Process/Prefix}).
 
 @item S M-c
 @kindex S M-c (Summary)
@@ -3931,7 +3946,8 @@ Articles}).
 Marked as dormant (@code{gnus-dormant-mark}).  
 
 @dfn{Dormant articles} will only appear in the summary buffer if there
-are followups to it.
+are followups to it.  If you want to see them even if they don't have
+followups, you can use the @kbd{/ D} command (@pxref{Limiting}).
 
 @item SPACE
 @vindex gnus-unread-mark
@@ -4042,8 +4058,8 @@ answered) will be marked with an @samp{A} in the second column
 
 @item 
 @vindex gnus-cached-mark
-Articles stored in the article cache will be marked with an
-@samp{*} in the second column (@code{gnus-cached-mark}).
+Articles stored in the article cache will be marked with an @samp{*} in
+the second column (@code{gnus-cached-mark}).  @xref{Article Caching}
 
 @item 
 @vindex gnus-saved-mark
@@ -4084,12 +4100,23 @@ you'll only see the cache mark and not the replied mark.
 All the marking commands understand the numeric prefix.
 
 @table @kbd
+@item M c
+@itemx M-u
+@kindex M c (Summary)
+@kindex M-u (Summary)
+@findex gnus-summary-clear-mark-forward
+@cindex mark as unread
+Clear all readedness-marks from the current article
+(@code{gnus-summary-clear-mark-forward}).  In other words, mark the
+article as unread.
+
 @item M t
 @itemx !
 @kindex ! (Summary)
 @kindex M t (Summary)
 @findex gnus-summary-tick-article-forward
 Tick the current article (@code{gnus-summary-tick-article-forward}).
+@xref{Article Caching} 
 
 @item M ?
 @itemx ?
@@ -4097,7 +4124,7 @@ Tick the current article (@code{gnus-summary-tick-article-forward}).
 @kindex M ? (Summary)
 @findex gnus-summary-mark-as-dormant
 Mark the current article as dormant
-(@code{gnus-summary-mark-as-dormant}).
+(@code{gnus-summary-mark-as-dormant}).  @xref{Article Caching} 
 
 @item M d
 @itemx d
@@ -4160,15 +4187,6 @@ Mark all articles between point and mark as read
 Kill all articles with scores below the default score (or below the
 numeric prefix) (@code{gnus-summary-kill-below}).
 
-@item M c
-@itemx M-u
-@kindex M c (Summary)
-@kindex M-u (Summary)
-@findex gnus-summary-clear-mark-forward
-@cindex mark as unread
-Clear all readedness-marks from the current article
-(@code{gnus-summary-clear-mark-forward}).
-
 @item M e
 @itemx E
 @kindex M e (Summary)
@@ -4434,6 +4452,43 @@ Gnus threads articles by default.  @dfn{To thread} is to put responses
 to articles directly after the articles they respond to---in a
 hierarchical fashion.
 
+Threading is done by looking at the @code{References} headers of the
+articles.  In a perfect world, this would be enough to build pretty
+trees, but unfortunately, the @code{References} header is often broken
+or simply missing.  Weird news propagration excarcerbates the problem,
+so one has to employ other heuristics to get pleasing results.  A
+plethora of approaches exists, as detailed in horrible detail in
+@pxref{Customizing Threading}. 
+
+First, a quick overview of the concepts:
+
+@table @dfn
+@item root
+The top-most article in a thread; the first article in the thread.
+
+@item thread
+A tree-like article structure.
+
+@item sub-thread
+A small(er) section of this tree-like structure.
+
+@item loose threads
+Threads often lose their roots due to article expiry, or due to the root
+already having been read in a previous session, and not displayed in the
+summary buffer.  We then typicall have many sub-threads that really
+belong to one thread, but are without connecting roots.  These are
+called loose threads.
+
+@item thread gathering
+An attempt to gather loose threads into bigger threads.
+
+@item sparse threads
+A thread where the missing articles have been ``guessed'' at, and are
+displayed as empty lines in the summary buffer.
+
+@end table
+
+
 @menu
 * Customizing Threading::     Variables you can change to affect the threading.
 * Thread Commands::           Thread based commands in the summary buffer.
@@ -4443,45 +4498,76 @@ hierarchical fashion.
 @node Customizing Threading
 @subsection Customizing Threading
 @cindex customizing threading
+
+@menu
+* Loose Threads::        How Gnus gathers loose threads into bigger threads.
+* Filling In Threads::   Making the threads displayed look fuller.
+* More Threading::       Even more variables for fiddling with threads.
+* Low-Level Threading::  You thought it was over... but you were wrong!
+@end menu
+
+
+@node Loose Threads
+@subsubsection Loose Threads
 @cindex <
 @cindex >
+@cindex loose threads
 
 @table @code
+@item gnus-summary-make-false-root
+@vindex gnus-summary-make-false-root
+If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
+and create a dummy root at the top.  (Wait a minute.  Root at the top?
+Yup.)  Loose subtrees occur when the real root has expired, or you've
+read or killed the root in a previous session.
 
-@item gnus-show-threads
-@vindex gnus-show-threads
-If this variable is @code{nil}, no threading will be done, and all of
-the rest of the variables here will have no effect.  Turning threading
-off will speed group selection up a bit, but it is sure to make reading
-slower and more awkward.
+When there is no real root of a thread, Gnus will have to fudge
+something.  This variable says what fudging method Gnus should use.
+There are four possible values:
 
-@item gnus-fetch-old-headers
-@vindex gnus-fetch-old-headers
-If non-@code{nil}, Gnus will attempt to build old threads by fetching
-more old headers---headers to articles marked as read.  If you
-would like to display as few summary lines as possible, but still
-connect as many loose threads as possible, you should set this variable
-to @code{some} or a number.  If you set it to a number, no more than
-that number of extra old headers will be fetched.  In either case,
-fetching old headers only works if the backend you are using carries
-overview files---this would normally be @code{nntp}, @code{nnspool} and
-@code{nnml}.  Also remember that if the root of the thread has been
-expired by the server, there's not much Gnus can do about that.
+@iftex
+@iflatex
+\gnusfigure{The Summary Buffer}{390}{
+\put(0,0){\epsfig{figure=tmp/summary-adopt.ps,width=7.5cm}}
+\put(445,0){\makebox(0,0)[br]{\epsfig{figure=tmp/summary-empty.ps,width=7.5cm}}}
+\put(0,400){\makebox(0,0)[tl]{\epsfig{figure=tmp/summary-none.ps,width=7.5cm}}}
+\put(445,400){\makebox(0,0)[tr]{\epsfig{figure=tmp/summary-dummy.ps,width=7.5cm}}}
+}
+@end iflatex
+@end iftex
 
-@item gnus-build-sparse-threads
-@vindex gnus-build-sparse-threads
-Fetching old headers can be slow.  A low-rent similar effect can be
-gotten by setting this variable to @code{some}.  Gnus will then look at
-the complete @code{References} headers of all articles and try to string
-together articles that belong in the same thread.  This will leave
-@dfn{gaps} in the threading display where Gnus guesses that an article
-is missing from the thread.  (These gaps appear like normal summary
-lines.  If you select a gap, Gnus will try to fetch the article in
-question.)  If this variable is @code{t}, Gnus will display all these
-``gaps'' without regard for whether they are useful for completing the
-thread or not.  Finally, if this variable is @code{more}, Gnus won't cut
-off sparse leaf nodes that don't lead anywhere.  This variable is
-@code{nil} by default.
+@cindex adopting articles
+
+@table @code
+
+@item adopt
+Gnus will make the first of the orphaned articles the parent.  This
+parent will adopt all the other articles.  The adopted articles will be
+marked as such by pointy brackets (@samp{<>}) instead of the standard
+square brackets (@samp{[]}).  This is the default method.
+
+@item dummy
+@vindex gnus-summary-dummy-line-format
+Gnus will create a dummy summary line that will pretend to be the
+parent.  This dummy line does not correspond to any real article, so
+selecting it will just select the first real article after the dummy
+article.  @code{gnus-summary-dummy-line-format} is used to specify the
+format of the dummy roots.  It accepts only one format spec:  @samp{S},
+which is the subject of the article.  @xref{Formatting Variables}.
+
+@item empty
+Gnus won't actually make any article the parent, but simply leave the
+subject field of all orphans except the first empty.  (Actually, it will
+use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
+Buffer Format}).)
+
+@item none
+Don't make any article parent at all.  Just gather the threads and
+display them after one another.
+
+@item nil
+Don't gather loose threads.
+@end table
 
 @item gnus-summary-gather-subject-limit
 @vindex gnus-summary-gather-subject-limit
@@ -4575,60 +4661,54 @@ something like:
       'gnus-gather-threads-by-references)
 @end lisp
 
-@item gnus-summary-make-false-root
-@vindex gnus-summary-make-false-root
-If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
-and create a dummy root at the top.  (Wait a minute.  Root at the top?
-Yup.)  Loose subtrees occur when the real root has expired, or you've
-read or killed the root in a previous session.
-
-When there is no real root of a thread, Gnus will have to fudge
-something.  This variable says what fudging method Gnus should use.
-There are four possible values:
+@end table
 
-@iftex
-@iflatex
-\gnusfigure{The Summary Buffer}{390}{
-\put(0,0){\epsfig{figure=tmp/summary-adopt.ps,width=7.5cm}}
-\put(445,0){\makebox(0,0)[br]{\epsfig{figure=tmp/summary-empty.ps,width=7.5cm}}}
-\put(0,400){\makebox(0,0)[tl]{\epsfig{figure=tmp/summary-none.ps,width=7.5cm}}}
-\put(445,400){\makebox(0,0)[tr]{\epsfig{figure=tmp/summary-dummy.ps,width=7.5cm}}}
-}
-@end iflatex
-@end iftex
 
-@cindex adopting articles
+@node Filling In Threads
+@subsubsection Filling In Threads
 
 @table @code
+@item gnus-fetch-old-headers
+@vindex gnus-fetch-old-headers
+If non-@code{nil}, Gnus will attempt to build old threads by fetching
+more old headers---headers to articles marked as read.  If you
+would like to display as few summary lines as possible, but still
+connect as many loose threads as possible, you should set this variable
+to @code{some} or a number.  If you set it to a number, no more than
+that number of extra old headers will be fetched.  In either case,
+fetching old headers only works if the backend you are using carries
+overview files---this would normally be @code{nntp}, @code{nnspool} and
+@code{nnml}.  Also remember that if the root of the thread has been
+expired by the server, there's not much Gnus can do about that.
 
-@item adopt
-Gnus will make the first of the orphaned articles the parent.  This
-parent will adopt all the other articles.  The adopted articles will be
-marked as such by pointy brackets (@samp{<>}) instead of the standard
-square brackets (@samp{[]}).  This is the default method.
+@item gnus-build-sparse-threads
+@vindex gnus-build-sparse-threads
+Fetching old headers can be slow.  A low-rent similar effect can be
+gotten by setting this variable to @code{some}.  Gnus will then look at
+the complete @code{References} headers of all articles and try to string
+together articles that belong in the same thread.  This will leave
+@dfn{gaps} in the threading display where Gnus guesses that an article
+is missing from the thread.  (These gaps appear like normal summary
+lines.  If you select a gap, Gnus will try to fetch the article in
+question.)  If this variable is @code{t}, Gnus will display all these
+``gaps'' without regard for whether they are useful for completing the
+thread or not.  Finally, if this variable is @code{more}, Gnus won't cut
+off sparse leaf nodes that don't lead anywhere.  This variable is
+@code{nil} by default.
 
-@item dummy
-@vindex gnus-summary-dummy-line-format
-Gnus will create a dummy summary line that will pretend to be the
-parent.  This dummy line does not correspond to any real article, so
-selecting it will just select the first real article after the dummy
-article.  @code{gnus-summary-dummy-line-format} is used to specify the
-format of the dummy roots.  It accepts only one format spec:  @samp{S},
-which is the subject of the article.  @xref{Formatting Variables}.
+@end table
 
-@item empty
-Gnus won't actually make any article the parent, but simply leave the
-subject field of all orphans except the first empty.  (Actually, it will
-use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
-Buffer Format}).)
 
-@item none
-Don't make any article parent at all.  Just gather the threads and
-display them after one another.
+@node More Threading
+@subsubsection More Threading
 
-@item nil
-Don't gather loose threads.
-@end table
+@table @code
+@item gnus-show-threads
+@vindex gnus-show-threads
+If this variable is @code{nil}, no threading will be done, and all of
+the rest of the variables here will have no effect.  Turning threading
+off will speed group selection up a bit, but it is sure to make reading
+slower and more awkward.
 
 @item gnus-thread-hide-subtree
 @vindex gnus-thread-hide-subtree
@@ -4659,6 +4739,14 @@ in a new thread.
 This is a number that says how much each sub-thread should be indented.
 The default is 4.
 
+@end table
+
+
+@node Low-Level Threading
+@subsubsection Low-Level Threading
+
+@table @code
+
 @item gnus-parse-headers-hook
 @vindex gnus-parse-headers-hook
 Hook run before parsing any headers.  The default value is
@@ -4666,6 +4754,28 @@ Hook run before parsing any headers.  The default value is
 slightly decoded in a hackish way.  This is likely to change in the
 future when Gnus becomes @sc{MIME}ified.
 
+@item gnus-alter-header-function
+@vindex gnus-alter-header-function
+If non-@code{nil}, this function will be called to allow alteration of
+article header structures.  The function is called with one parameter,
+the article header vector, which it may alter in any way.  For instance,
+if you have a mail-to-news gateway which alters the @code{Message-ID}s
+in systematic ways (by adding prefixes and such), you can use this
+variable to un-scramble the @code{Message-ID}s so that they are more
+meaningful.  Here's one example:
+
+@lisp
+(setq gnus-alter-header-function 'my-alter-message-id)
+
+(defun my-alter-message-id (header)
+  (let ((id (mail-header-id header)))
+    (when (string-match
+           "\\(<[^<>@@]*\\)\\.?cygnus\\..*@@\\([^<>@@]*>\\)" id)
+      (mail-header-set-id
+       (concat (match-string 1 id) "@@" (match-string 2 id))
+       header))))
+@end lisp
+
 @end table
 
 
@@ -5019,10 +5129,13 @@ symbols in these two lists are @code{ticked}, @code{dormant},
 @findex gnus-jog-cache
 So where does the massive article-fetching and storing come into the
 picture?  The @code{gnus-jog-cache} command will go through all
-subscribed newsgroups, request all unread articles, and store them in
-the cache.  You should only ever, ever ever ever, use this command if 1)
-your connection to the @sc{nntp} server is really, really, really slow
-and 2) you have a really, really, really huge disk.  Seriously.
+subscribed newsgroups, request all unread articles, score them, and
+store them in the cache.  You should only ever, ever ever ever, use this
+command if 1) your connection to the @sc{nntp} server is really, really,
+really slow and 2) you have a really, really, really huge disk.
+Seriously.  One way to cut down on the number of articles downloaded is
+to score unwanted articles down and have them marked as read.  They will
+not then be downloaded by this command.
 
 @vindex gnus-uncacheable-groups
 It is likely that you do not want caching on some groups.  For instance,
@@ -5386,12 +5499,15 @@ encoded in some way or other.  Gnus can decode them for you.
 
 @menu 
 * Uuencoded Articles::    Uudecode articles.
-* Shared Articles::       Unshar articles.
+* Shell Archives::        Unshar articles.
 * PostScript Files::      Split PostScript.
+* Other Files::           Plain save and binhex.
 * Decoding Variables::    Variables for a happy decoding.
 * Viewing Files::         You want to look at the result of the decoding?
 @end menu
 
+@cindex series
+@cindex article series
 All these functions use the process/prefix convention
 (@pxref{Process/Prefix}) for finding out what articles to work on, with
 the extension that a ``single article'' means ``a single series''.  Gnus
@@ -5439,7 +5555,8 @@ Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
 @kindex X v U (Summary)
 @findex gnus-uu-decode-uu-and-save-view
 Uudecodes, views and saves the current series
-(@code{gnus-uu-decode-uu-and-save-view}). 
+(@code{gnus-uu-decode-uu-and-save-view}).
+
 @end table
 
 Remember that these all react to the presence of articles marked with
@@ -5463,11 +5580,16 @@ you have just viewed the file in question.  This feature can't be turned
 off.
 
 
-@node Shared Articles
-@subsection Shared Articles
+@node Shell Archives
+@subsection Shell Archives
 @cindex unshar
+@cindex shell archives
 @cindex shared articles
 
+Shell archives (``shar files'') used to be a popular way to distribute
+sources, but it isn't used all that much today.  In any case, we have
+some commands to deal with these:
+
 @table @kbd
 
 @item X s
@@ -5524,6 +5646,24 @@ View and save the current PostScript series
 @end table
 
 
+@node Other Files
+@subsection Other Files
+
+@table @kbd
+@item X o
+@kindex X o (Summary)
+@findex gnus-uu-decode-save
+Save the current series
+(@code{gnus-uu-decode-save}).
+
+@item X b
+@kindex X b (Summary)
+@findex gnus-uu-decode-binhex
+Unbinhex the current series (@code{gnus-uu-decode-binhex}).  This
+doesn't really work yet.
+@end table
+
+
 @node Decoding Variables
 @subsection Decoding Variables
 
@@ -5993,7 +6133,7 @@ is hidden.
 Gnus adds buttons to show where the cited text has been hidden, and to
 allow toggle hiding the text.  The format of the variable is specified
 by this format-like variable (@pxref{Formatting Variables}).  These
-specs are legal:
+specs are valid:
 
 @table @samp
 @item b
@@ -6054,6 +6194,13 @@ Remove page breaks from the current article
 @c @icon{gnus-summary-caesar-message}
 Do a Caesar rotate (rot13) on the article buffer
 (@code{gnus-summary-caesar-message}). 
+Unreadable articles that tell you to read them with Caesar rotate or rot13.
+(Typically offensive jokes and such.)
+
+It's commonly called ``rot13'' because each letter is rotated 13
+positions in the alphabet, e. g. @samp{B} (letter #2) -> @sam{O} (letter
+#15).  It is sometimes referred to as ``Caesar rotate'' because Caesar
+is rumoured to have employed this form of, uh, somewhat weak encryption.
 
 @item W t
 @kindex W t (Summary)
@@ -6091,12 +6238,17 @@ when filling.
 @item W c
 @kindex W c (Summary)
 @findex gnus-article-remove-cr
-Remove CR (@code{gnus-article-remove-cr}).
+Remove CR (i. e., @samp{^M}s on the end of the lines)
+(@code{gnus-article-remove-cr}).
 
 @item W q
 @kindex W q (Summary)
 @findex gnus-article-de-quoted-unreadable
 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
+Quoted-Printable is one common @sc{mime} encoding employed when sending
+non-ASCII (i. e., 8-bit) articles.  It typically makes strings like
+@samp{déjà vu} look like @samp{d=E9j=E0 vu}, which doesn't look very
+readable to me.
 
 @item W f
 @kindex W f (Summary)
@@ -6131,7 +6283,8 @@ last.
 @item W b
 @kindex W b (Summary)
 @findex gnus-article-add-buttons
-Add clickable buttons to the article (@code{gnus-article-add-buttons}). 
+Add clickable buttons to the article (@code{gnus-article-add-buttons}).
+@xref{Article Buttons}
 
 @item W B
 @kindex W B (Summary)
@@ -6179,7 +6332,8 @@ body (@code{gnus-article-strip-leading-space}).
 
 People often include references to other stuff in articles, and it would
 be nice if Gnus could just fetch whatever it is that people talk about
-with the minimum of fuzz.
+with the minimum of fuzz when you hit @kbd{RET} or use the middle mouse
+button on these references.
 
 Gnus adds @dfn{buttons} to certain standard references by default:
 Well-formed URLs, mail addresses and Message-IDs.  This is controlled by
@@ -6354,7 +6508,17 @@ in question is not a signature.
 @end enumerate
 
 This variable can also be a list where the elements may be of the types
-listed above.  
+listed above.  Here's an example:
+
+@lisp
+(setq gnus-signature-limit
+      '(200.0 "^---*Forwarded article"))
+@end lisp
+
+This means that if there are more than 200 lines after the signature
+separator, or the text after the signature separator is matched by
+the regular expression @samp{^---*Forwarded article}, then it isn't a
+signature after all.
 
 
 @node Article Commands
@@ -6653,7 +6817,7 @@ A hook called in all tree mode buffers.
 @item gnus-tree-mode-line-format
 @vindex gnus-tree-mode-line-format
 A format string for the mode bar in the tree mode buffers.  The default
-is @samp{Gnus: %%b [%A] %Z}.  For a list of legal specs, @pxref{Summary
+is @samp{Gnus: %%b [%A] %Z}.  For a list of valid specs, @pxref{Summary
 Buffer Mode Line}. 
 
 @item gnus-selected-tree-face
@@ -6669,7 +6833,7 @@ is @samp{%(%[%3,3n%]%)}, which displays the first three characters of
 the name of the poster.  It is vital that all nodes are of the same
 length, so you @emph{must} use @samp{%4,4n}-like specifiers.
 
-Legal specs are:
+Valid specs are:
 
 @table @samp
 @item n
@@ -6777,7 +6941,7 @@ following to your @file{.gnus.el} file:
 @cindex mail group commands
 
 Some commands only make sense in mail groups.  If these commands are
-illegal in the current group, they will raise hell and let you know.
+invalid in the current group, they will raise a hell and let you know.
 
 All these commands (except the expiry and edit commands) use the
 process/prefix convention (@pxref{Process/Prefix}).
@@ -7663,9 +7827,8 @@ to make Gnus try to post using the foreign server.
 * Posting Server::       What server should you post via?
 * Mail and Post::        Mailing and posting at the same time.
 * Archived Messages::    Where Gnus stores the messages you've sent.
-@c * Posting Styles::       An easier way to configure some key elements.
-@c * Drafts::               Postponing messages and rejected messages.
-@c * Rejected Articles::    What happens if the server doesn't like your article?
+* Drafts::               Postponing messages and rejected messages.
+* Rejected Articles::    What happens if the server doesn't like your article?
 @end menu
 
 Also see @pxref{Canceling and Superseding} for information on how to
@@ -7989,36 +8152,36 @@ but the latter is the preferred method.
 @c           (signature . "~/.mail-signature"))))
 @c @end lisp
 
-@c @node Drafts
-@c @section Drafts
-@c @cindex drafts
-@c 
-@c If you are writing a message (mail or news) and suddenly remember that
-@c you have a steak in the oven (or some pesto in the food processor, you
-@c craazy vegetarians), you'll probably wish there was a method to save the
-@c message you are writing so that you can continue editing it some other
-@c day, and send it when you feel its finished.
-@c 
-@c Well, don't worry about it.  Whenever you start composing a message of
-@c some sort using the Gnus mail and post commands, the buffer you get will
-@c automatically associate to an article in a special @dfn{draft} group.
-@c If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the
-@c article will be saved there.  (Auto-save files also go to the draft
-@c group.) 
-@c 
-@c @cindex nndraft
-@c @vindex gnus-draft-group-directory
-@c The draft group is a special group (which is implemented as an
-@c @code{nndraft} group, if you absolutely have to know) called
-@c @samp{nndraft:drafts}.  The variable @code{gnus-draft-group-directory}
-@c controls both the name of the group and the location---the leaf element
-@c in the path will be used as the name of the group.  What makes this
-@c group special is that you can't tick any articles in it or mark any
-@c articles as read---all articles in the group are permanently unread.
-@c 
-@c If the group doesn't exist, it will be created and you'll be subscribed
-@c to it.
-@c 
+@node Drafts
+@section Drafts
+@cindex drafts
+
+If you are writing a message (mail or news) and suddenly remember that
+you have a steak in the oven (or some pesto in the food processor, you
+craaazy vegetarians), you'll probably wish there was a method to save
+the message you are writing so that you can continue editing it some
+other day, and send it when you feel its finished.
+
+Well, don't worry about it.  Whenever you start composing a message of
+some sort using the Gnus mail and post commands, the buffer you get will
+automatically associate to an article in a special @dfn{draft} group.
+If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the
+article will be saved there.  (Auto-save files also go to the draft
+group.) 
+
+@cindex nndraft
+@vindex nndraft-directory
+The draft group is a special group (which is implemented as an
+@code{nndraft} group, if you absolutely have to know) called
+@samp{nndraft:drafts}.  The variable @code{nndraft-directory} says where
+@code{nndraft} is to store its files.  What makes this group special is
+that you can't tick any articles in it or mark any articles as
+read---all articles in the group are permanently unread.
+
+If the group doesn't exist, it will be created and you'll be subscribed
+to it.  The only way to make it disappear from the Group buffer is to
+unsubscribe it. 
+
 @c @findex gnus-dissociate-buffer-from-draft
 @c @kindex C-c M-d (Mail)
 @c @kindex C-c M-d (Post)
@@ -8037,42 +8200,49 @@ but the latter is the preferred method.
 @c @vindex gnus-use-draft
 @c To leave association with the draft group off by default, set
 @c @code{gnus-use-draft} to @code{nil}.  It is @code{t} by default. 
-@c 
-@c @findex gnus-summary-send-draft
-@c @kindex S D c (Summary)
-@c When you want to continue editing the article, you simply enter the
-@c draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
-@c that.  You will be placed in a buffer where you left off.
-@c 
-@c Rejected articles will also be put in this draft group (@pxref{Rejected
-@c Articles}).
-@c 
-@c @findex gnus-summary-send-all-drafts
-@c If you have lots of rejected messages you want to post (or mail) without
-@c doing further editing, you can use the @kbd{S D a} command
-@c (@code{gnus-summary-send-all-drafts}).  This command understands the
-@c process/prefix convention (@pxref{Process/Prefix}).  
-@c 
-@c 
-@c @node Rejected Articles
-@c @section Rejected Articles
-@c @cindex rejected articles
-@c 
-@c Sometimes a news server will reject an article.  Perhaps the server
-@c doesn't like your face.  Perhaps it just feels miserable.  Perhaps
-@c @emph{there be demons}.  Perhaps you have included too much cited text.
-@c Perhaps the disk is full.  Perhaps the server is down.
-@c 
-@c These situations are, of course, totally beyond the control of Gnus.
-@c (Gnus, of course, loves the way you look, always feels great, has angels
-@c fluttering around inside of it, doesn't care about how much cited text
-@c you include, never runs full and never goes down.)  So Gnus saves these
-@c articles until some later time when the server feels better.
-@c 
-@c The rejected articles will automatically be put in a special draft group
-@c (@pxref{Drafts}).  When the server comes back up again, you'd then
-@c typically enter that group and send all the articles off.
-@c 
+
+@findex gnus-draft-edit-message
+@kindex D e (Draft)
+When you want to continue editing the article, you simply enter the
+draft group and push @kbd{D e} (@code{gnus-draft-edit-message}) to do
+that.  You will be placed in a buffer where you left off.
+
+Rejected articles will also be put in this draft group (@pxref{Rejected
+Articles}).
+
+@findex gnus-draft-send-all-messages
+@findex gnus-draft-send-message
+If you have lots of rejected messages you want to post (or mail) without
+doing further editing, you can use the @kbd{D s} command
+(@code{gnus-draft-send-message}).  This command understands the
+process/prefix convention (@pxref{Process/Prefix}).  The @kbd{D S}
+command (@code{gnus-draft-send-all-messages}) will ship off all messages
+in the buffer.
+
+If you have some messages that you wish not to send, you can use the
+@kbd{D t} (@code{gnus-draft-toggle-sending}) command to mark the message
+as unsendable.  This is a toggling command.
+
+
+@node Rejected Articles
+@section Rejected Articles
+@cindex rejected articles
+
+Sometimes a news server will reject an article.  Perhaps the server
+doesn't like your face.  Perhaps it just feels miserable.  Perhaps
+@emph{there be demons}.  Perhaps you have included too much cited text.
+Perhaps the disk is full.  Perhaps the server is down.
+
+These situations are, of course, totally beyond the control of Gnus.
+(Gnus, of course, loves the way you look, always feels great, has angels
+fluttering around inside of it, doesn't care about how much cited text
+you include, never runs full and never goes down.)  So Gnus saves these
+articles until some later time when the server feels better.
+
+The rejected articles will automatically be put in a special draft group
+(@pxref{Drafts}).  When the server comes back up again, you'd then
+typically enter that group and send all the articles off.
+
 
 @node Select Methods
 @chapter Select Methods
@@ -8111,6 +8281,7 @@ The different methods all have their peculiarities, of course.
 * Getting Mail::          Reading your personal mail with Gnus.
 * Other Sources::         Reading directories, files, SOUP packets.
 * Combined Groups::       Combining groups into one group.
+* Gnus Unplugged::        Reading news and mail offline.
 @end menu
 
 
@@ -10014,7 +10185,7 @@ This should be one of @code{mbox}, @code{babyl}, @code{digest},
 @item nndoc-post-type
 @vindex nndoc-post-type
 This variable says whether Gnus is to consider the group a news group or
-a mail group.  There are two legal values:  @code{mail} (the default)
+a mail group.  There are two valid values:  @code{mail} (the default)
 and @code{news}.
 @end table
 
@@ -10142,7 +10313,7 @@ is of @code{mmdf} type, and so on.  These type predicates should return
 @code{nil} if the document is not of the correct type; @code{t} if it is
 of the correct type; and a number if the document might be of the
 correct type.  A high number means high probability; a low number means
-low probability with @samp{0} being the lowest legal number.
+low probability with @samp{0} being the lowest valid number.
 
 
 @node SOUP
@@ -10690,6 +10861,522 @@ Articles marked as read in the @code{nnkiboze} group will have
 their @sc{nov} lines removed from the @sc{nov} file.
 
 
+@node Gnus Unplugged
+@section Gnus Unplugged
+@cindex offline
+@cindex unplugged
+@cindex Agent
+@cindex Gnus Agent
+@cindex Gnus Unplugged
+
+In olden times (ca. February '88), people used to run their newsreaders
+on big machines with permanent connections to the net.  News transport
+was dealt with by news servers, and all the newsreaders had to do was to
+read news.  Believe it or not.
+
+Nowadays most people read news and mail at home, and use some sort of
+modem to connect to the net.  To avoid running up huge phone bills, it
+would be nice to have a way to slurp down all the news and mail, hang up
+the phone, read for several hours, and then upload any responses you
+have to make.  And then you repeat the procedure.
+
+Of course, you can use news servers for doing this as well.  I've used
+@code{inn} together with @code{slurp}, @code{pop} and @code{sendmail}
+for some years, but doing that's a bore.  Moving the news server
+functionality up to the newsreader makes sense if you're the only person
+reading news on a machine.
+
+Using Gnus as an ``offline'' newsreader is quite simple.
+
+@itemize @bullet
+@item
+First, set ut Gnus as you would do if you were running it on a machine
+that has full connection to the net.  Go ahead.  I'll still be waiting
+here.
+
+@item
+Then, put the following magical incantation at the end of your
+@file{.gnus.el} file:
+
+@lisp
+(gnus-agentize)
+@end lisp
+@end itemize
+
+That's it.  Gnus is now an ``offline'' newsreader.
+
+Of course, to use it as such, you have to learn a few new commands.
+
+@menu
+* Agent Basics::           How it all is supposed to work.
+* Agent Categories::       How to tell the Gnus Agent what to download.
+* Agent Commands::         New commands for all the buffers.
+* Outgoing Messages::      What happens when you post/mail something?
+* Agent Variables::        Customizing is fun.
+* Example Setup::          An example @file{.gnus.el} file for offline people.
+@end menu
+
+
+@node Agent Basics
+@subsection Agent Basics
+
+First, let's get some terminilogy out of the way.
+
+The Gnus Agent is said to be @dfn{unplugged} when you have severed the
+connection to the net (and notified the Agent that this is the case).
+When the connection to the net is up again (and Gnus knows this), the
+Agent is @dfn{plugged}.
+
+The @dfn{local} machine is the one you're running on, and which isn't
+connected to the net continously.
+
+@dfn{Downloading} means fetching things from the net to your local
+machine.  @dfn{Uploading} is doing the opposite.
+
+Let's take a typical Gnus session using the Agent.
+
+@itemize @bullet
+
+@item
+You start Gnus with @code{gnus-unplugged}.  This brings up the Gnus
+Agent in a disconnected state.  You can read all the news that you have
+already fetched while in this mode.
+
+@item
+You then decide to see whether any new news has arrived.  You connect
+your machine to the net (using PPP or whatever), and then hit @kbd{J j}
+to make Gnus become @dfn{plugged}.
+
+@item
+You can then read the new news immediately, or you can download the news
+onto your local machine.  If you want to do the latter, you press @kbd{J
+s} to fetch all the eligible articles in all the groups.  (To let Gnus
+know which articles you want to download, @pxref{Agent Categories}.)
+
+@item
+After fetching the articles, you press @kbd{J j} to make Gnus become
+unplugged again, and you shut down the PPP thing (or whatever).  And
+then you read the news offline.
+
+@item
+And then you go to step 2.
+@end itemize
+
+Here are some things you should do the first time (or so) that you use
+the Agent.
+
+@itemize @bullet
+
+@item
+Decide which servers should be covered by the Agent.  If you have a mail
+backend, it would probably be nonsensical to have it covered by the
+Agent.  Go to the server buffer (@kbd{^} in the group buffer) and press
+@kbd{J a} the server (or servers) that you wish to have covered by the
+Agent (@pxref{Server Agent Commands}).  This will typically be only the
+primary select method, which is listed on the bottom in the buffer.
+
+@item
+Decide on download policy.  @xref{Agent Categories}
+
+@item
+Uhm... that's it.
+@end itemize
+
+
+@node Agent Categories
+@subsection Agent Categories
+
+On of the main reasons to integrate the news transport layer into the
+newsreader is to allow greater control over what articles to download.
+There's not much point in downloading huge amounts of articles, just to
+find out that you're not interested in reading any of them.  It's better
+to be somewhat more conservative in choosing what to download, and then
+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. 
+Gnus has its own buffer for creating and managing categories.
+
+@menu
+* Category Syntax::       What a category looks like.
+* The Category Buffer::   A buffer for maintaining categories.
+* Category Variables::    Customize'r'Us.
+@end menu
+
+
+@node Category Syntax
+@subsubsection Category Syntax
+
+A category consists of two things.
+
+@enumerate
+@item
+A predicate which (generally) gives a rough outline of which articles
+are eligible for downloading; and
+
+@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.)
+@end enumerate
+
+A predicate consists of predicates with logical operators sprinkled in
+between.
+
+Perhaps some examples are in order.
+
+Here's a simple predicate.  (It's the default predicate, in fact, used
+for all groups that don't belong to any other category.)
+
+@lisp
+short
+@end lisp
+
+Quite simple, eh?  This predicate is true if and only if the article is
+short (for some value of ``short'').
+
+Here's a more complex predicate:
+
+@lisp
+(or high
+    (and
+     (not low)
+     (not long)))
+@end lisp
+
+This means that an article should be downloaded if it has a high score,
+or if the score is not low and the article is not long.  You get the
+drift.
+
+The available logical operators are @code{or}, @code{and} and
+@code{not}.  (If you prefer, you can use the more ``C''-ish operators
+@samp{|}, @code{&} and @code{!} instead.)
+
+The following predicates are pre-defined, but if none of these fit what
+you want to do, you can write your own.
+
+@table @code
+@item short
+True iff the article is shorter than @code{gnus-agent-short-article}
+lines; default 100.
+
+@item long
+True iff the article is longer than @code{gnus-agent-long-article}
+lines; default 200.
+
+@item low
+True iff 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
+@code{gnus-agent-high-score}; default 0.
+
+@item spam
+True iff the Gnus Agent guesses that the article is spam.  The
+heuristics may change over time, but at present it just computes a
+checksum and see whether articles match.
+
+@item true
+Always true.
+
+@item false
+Always false.
+@end table
+
+If you want to create your own predicate function, here's what you have
+to know:  The functions are called with no parameters, but the
+@code{gnus-headers} and @code{gnus-score} dynamic variables are bound to
+useful values.
+
+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 is 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}.
+
+
+@node The Category Buffer
+@subsubsection The Category Buffer
+
+You'd normally do all category maintenance from the category buffer.
+When you enter it for the first time (with the @kbd{J c} command from
+the group buffer), you'll only see the @code{default} category.
+
+The following commands are available in this buffer:
+
+@table @kbd
+@item q
+@kindex q (Category)
+@findex gnus-category-exit
+Return to the group buffer (@code{gnus-category-exit}).
+
+@item k
+@kindex k (Category)
+@findex gnus-category-kill
+Kill the current category (@code{gnus-category-kill}).
+
+@item c
+@kindex c (Category)
+@findex gnus-category-copy
+Copy the current category (@code{gnus-category-copy}).
+
+@item a
+@kindex a (Category)
+@findex gnus-category-add
+Add a new category (@code{gnus-category-add}).
+
+@item p
+@kindex p (Category)
+@findex gnus-category-edit-predicate
+Edit the predicate of the current category
+(@code{gnus-category-edit-predicate}).
+
+@item g
+@kindex g (Category)
+@findex gnus-category-edit-groups
+Edit the list of groups belonging to the current category
+(@code{gnus-category-edit-groups}).
+
+@item s
+@kindex s (Category)
+@findex gnus-category-edit-score
+Edit the download score rule of the current category
+(@code{gnus-category-edit-score}).
+
+@item l
+@kindex l (Category)
+@findex gnus-category-list
+List all the categories (@code{gnus-category-list}).
+@end table
+
+
+@node Category Variables
+@subsubsection Category Variables
+
+@table @code
+@item gnus-category-mode-hook
+@vindex gnus-category-mode-hook
+Hook run in category buffers.
+
+@item gnus-category-line-format
+@vindex gnus-category-line-format
+Format of the lines in the category buffer (@pxref{Formatting
+Variables}).  Legal elements are:
+
+@table @samp
+@item c
+The name of the category.
+
+@item g
+The number of groups in the category.
+@end table
+
+@item gnus-category-mode-line-format
+@vindex gnus-category-mode-line-format
+Format of the category mode line.
+
+@item gnus-agent-short-article 
+@vindex gnus-agent-short-article 
+Articles that have fewer lines than this are short.  Default 100.
+
+@item gnus-agent-long-article 
+@vindex gnus-agent-long-article 
+Articles that have more lines than this are long.  Default 200.
+
+@item gnus-agent-low-score 
+@vindex gnus-agent-low-score 
+Articles that have a score lower than this have a low score.  Default
+0. 
+
+@item gnus-agent-high-score 
+@vindex gnus-agent-high-score 
+Articles that have a score higher than this have a high score.  Default
+0. 
+
+@end table
+
+
+@node Agent Commands
+@subsection Agent Commands
+
+All the Gnus Agent commands is on the @kbd{J} submap.  The @kbd{J j}
+(@code{gnus-agent-toggle-plugged} command works in all modes, and
+toggles the plugged/unplugged state of the Gnus Agent.
+
+
+@menu
+* Group Agent Commands::
+* Summary Agent Commands::
+* Server Agent Commands::
+@end menu
+
+
+@node Group Agent Commands
+@subsubsection Group Agent Commands
+
+@table @kbd
+@item J u 
+@kindex J u (Agent Group)
+@findex gnus-agent-fetch-group
+Fetch all eligible articles in the current group
+(@code{gnus-agent-fetch-group}).
+
+@item J c
+@kindex J c (Agent Group)
+@findex gnus-enter-category-buffer
+Enter the Agent category buffer (@code{gnus-enter-category-buffer}).
+
+@item J s
+@kindex J s (Agent Group)
+@findex gnus-agent-fetch-session
+Fetch all eligible articles in all groups
+(@code{gnus-agent-fetch-session}).
+
+@item J S
+@kindex J S (Agent Group)
+@findex gnus-group-send-drafts
+Send all sendable messages in the draft group
+(@code{gnus-agent-fetch-session}).  @xref{Drafts}
+
+@item J a
+@kindex J a (Agent Group)
+@findex gnus-agent-add-group
+Add the current group to an Agent category
+(@code{gnus-agent-add-group}).
+
+@end table
+
+
+@node Summary Agent Commands
+@subsubsection Summary Agent Commands
+
+@table @kbd
+@item J #
+@kindex J # (Agent Summary)
+@findex gnus-agent-mark-article
+Mark the article for downloading (@code{gnus-agent-mark-article}).
+
+@item J M-#
+@kindex J M-# (Agent Summary)
+@findex gnus-agent-unmark-article
+Remove the downloading mark from the article
+(@code{gnus-agent-unmark-article}).
+
+@item @@
+@kindex @@ (Agent Summary)
+@findex gnus-agent-toggle-mark
+Toggle whether to download the article (@code{gnus-agent-toggle-mark}).
+
+@item J c
+@kindex J c (Agent Summary)
+@findex gnus-agent-catchup
+Mark all undownloaded articles as read (@code{gnus-agent-catchup}).
+
+@end table
+
+
+@node Server Agent Commands
+@subsubsection Server Agent Commands
+
+@table @kbd
+@item J a
+@kindex J a (Agent Server)
+@findex gnus-agent-add-server
+Add the current server to the list of servers covered by the Gnus Agent
+(@code{gnus-agent-add-server}).
+
+@item J r
+@kindex J r (Agent Server)
+@findex gnus-agent-remove-server
+Remove the current server from the list of servers covered by the Gnus
+Agent (@code{gnus-agent-remove-server}).
+
+@end table
+
+
+@node Outgoing Messages
+@subsection Outgoing Messages
+
+When Gnus is unplugged, all outgoing messages (both mail and news) are
+stored in the draft groups (@pxref{Drafts}).  You can view them there
+after posting, and edit them at will.
+
+When Gnus is plugged again, you can send the messages either from the
+draft group with the special commands available there, or you can use
+the @kbd{J S} command in the group buffer to send all the sendable
+messages in the draft group.
+
+
+
+@node Agent Variables
+@subsection Agent Variables
+
+@table @code
+@item gnus-agent-directory
+@vindex gnus-agent-directory
+Where the Gnus Agent will store its files.  The default is
+@file{~/News/agent/}.
+
+@item gnus-agent-plugged-hook
+@vindex gnus-agent-plugged-hook
+Hook run when connecting to the network.
+
+@item gnus-agent-unplugged-hook
+@vindex gnus-agent-unplugged-hook
+Hook run when disconnecting from the network.
+
+@end table
+
+
+@node Example Setup
+@subsection Example Setup
+
+If you don't want to read this manual, and you have a fairly standard
+setup, you may be able to use something like the following as your
+@file{.gnus.el} file to get started.
+
+@lisp
+;;; Define how Gnus is to fetch news.  We do this over NNTP
+;;; from your ISP's server.
+(setq gnus-select-method '(nntp "nntp.your-isp.com"))
+
+;;; Define how Gnus is to read your mail.  We read mail from
+;;; your ISP's POP server.
+(setenv "MAILSERVER" "pop.your-isp.com")
+(setq nnmail-spool-file "po:username")
+
+;;; Say how Gnus is to store the mail.  We use nnml groups.
+(setq gnus-secondary-select-methods '((nnml "")))
+
+;;; Make Gnus into an offline newsreader.
+(gnus-agentize)
+@end lisp
+
+That should be it, basically.  Put that in your @file{~/.gnus.el} file,
+edit to suit your needs, start up PPP (or whatever), and type @kbd{M-x
+gnus}.
+
+If this is the first time you've run Gnus, you will be subscribed
+automatically to a few default newsgroups.  You'll probably want to
+subscribe to more groups, and to do that, you have to query the
+@sc{nntp} server for a complete list of groups with the @kbd{A A}
+command.  This usually takes quite a while, but you only have to do it
+once.
+
+After reading and parsing a while, you'll be presented with a list of
+groups.  Subscribe to the ones you want to read with the @kbd{u}
+command.  @kbd{l} to make all the killed groups disappear after you've
+subscribe to all the groups you want to read.  (@kbd{A k} will bring
+back all the killed groups.)
+
+You can now read the groups at once, or you can download the articles
+with the @kbd{J s} command.  And then read the rest of this manual to
+find out which of the other gazillion things you want to customize.
+
+
 @node Scoring
 @chapter Scoring
 @cindex scoring
@@ -10883,7 +11570,7 @@ Score on the head.
 @end table
 
 @item
-The third key is the match type.  Which match types are legal depends on
+The third key is the match type.  Which match types are valid depends on
 what headers you are scoring on.
 
 @table @code
@@ -11156,7 +11843,7 @@ Anyway, if you'd like to dig into it yourself, here's an example:
  (files "/hom/larsi/News/gnu.SCORE")
  (exclude-files "all.SCORE")
  (local (gnus-newsgroup-auto-expire t)
-        (gnus-summary-make-false-root 'empty))
+        (gnus-summary-make-false-root empty))
  (eval (ding)))
 @end lisp
 
@@ -11165,7 +11852,7 @@ approach, see @pxref{Advanced Scoring}.
 
 Even though this looks much like lisp code, nothing here is actually
 @code{eval}ed.  The lisp reader is used to read this form, though, so it
-has to be legal syntactically, if not semantically.
+has to be valid syntactically, if not semantically.
 
 Six keys are supported by this alist:
 
@@ -11372,7 +12059,7 @@ The value of this entry should be a list of @code{(VAR VALUE)} pairs.
 Each @var{var} will be made buffer-local to the current summary buffer,
 and set to the value specified.  This is a convenient, if somewhat
 strange, way of setting variables in some groups if you don't like hooks
-much.
+much.  Note that the @var{value} won't be evaluated.
 @end table
 
 
@@ -12098,7 +12785,7 @@ In either case, GroupLens gives you a few choices for how you would like
 to see your predictions displayed.  The display of predictions is
 controlled by the @code{grouplens-prediction-display} variable.
 
-The following are legal values for that variable.
+The following are valid values for that variable.
 
 @table @code
 @item prediction-spot
@@ -12551,7 +13238,7 @@ Padding, limiting, cutting off parts and suppressing certain values can
 be achieved by using @dfn{tilde modifiers}.  A typical tilde spec might
 look like @samp{%~(cut 3)~(ignore "0")y}.
 
-These are the legal modifiers:
+These are the valid modifiers:
 
 @table @code
 @item pad
@@ -12759,7 +13446,7 @@ For each split, there @emph{must} be one element that has the 100% tag.
 The splitting is never accurate, and this buffer will eat any leftover
 lines from the splits.
 
-To be slightly more formal, here's a definition of what a legal split
+To be slightly more formal, here's a definition of what a valid split
 may look like:
 
 @example
@@ -12972,7 +13659,7 @@ colors or fonts.  This will also inhibit loading the @file{gnus-vis.el}
 file.
 
 This variable can be a list of visual properties that are enabled.  The
-following elements are legal, and are all included by default:
+following elements are valid, and are all included by default:
 
 @table @code
 @item group-highlight
@@ -13621,7 +14308,6 @@ The name of the buffer that @code{picons} points to.  Defaults to
 
 @end table
 
-
 @node Smileys
 @subsection Smileys
 @cindex smileys
@@ -13766,6 +14452,8 @@ default.
 @end table
 
 
+
+
 @node Fuzzy Matching
 @section Fuzzy Matching
 @cindex fuzzy matching
@@ -13813,7 +14501,7 @@ This is annoying.
 The way to deal with this is having Gnus split out all spam into a
 @samp{spam} mail group (@pxref{Splitting Mail}).
 
-First, pick one (1) legal mail address that you can be reached at, and
+First, pick one (1) valid mail address that you can be reached at, and
 put it in your @code{From} header of all your news articles.  (I've
 chosen @samp{larsi@@trym.ifi.uio.no}, but for many addresses on the form
 @samp{larsi+usenet@@ifi.uio.no} will be a better choice.  Ask your
@@ -13934,10 +14622,10 @@ read when doing the operation described above.
 @item nnheader-file-name-translation-alist 
 @vindex nnheader-file-name-translation-alist 
 @cindex file names
-@cindex illegal characters in file names
+@cindex invalid characters in file names
 @cindex characters in file names
 This is an alist that says how to translate characters in file names.
-For instance, if @samp{:} is illegal as a file character in file names
+For instance, if @samp{:} is invalid as a file character in file names
 on your system (you OS/2 user you), you could say something like:
 
 @lisp
@@ -15191,7 +15879,7 @@ A machine one can connect to and get news (or mail) from.
 @item select method
 @cindex select method
 A structure that specifies the backend, the server and the virtual
-server parameters.
+server settings.
 
 @item virtual server
 @cindex virtual server
@@ -15221,6 +15909,30 @@ group buffer are solid groups.
 These are article placeholders shown in the summary buffer when
 @code{gnus-build-sparse-threads} has been switched on.
 
+@item threading
+@cindex threading
+To put responses to articles directly after the articles they respond
+to---in a hierarchical fashion.
+
+@item root
+@cindex root
+@cindex thread root
+The first article in a thread is the root.  It is the ancestor of all
+articles in the thread.
+
+@item parent
+@cindex parent
+An article that has responses.
+
+@item child
+@cindex child
+An article that responds to a different article---its parent.
+
+@item digest
+@cindex digest
+A collection of messages in one file.  The most common digest format is
+specified by RFC1153.
+
 @end table
 
 
@@ -16478,7 +17190,7 @@ are equal.  In fact, any non-descending list is a range:
 @end example
 
 is a perfectly valid range, although a pretty long-winded one.  This is
-also legal:
+also valid:
 
 @example
 (1 . 5)