\input texinfo @c -*-texinfo-*-
@setfilename gnus
-@settitle Gnus 5.4.59 Manual
+@settitle Quassia Gnus 0.6 Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
@tex
@titlepage
-@title Gnus 5.4.59 Manual
+@title Quassia Gnus 0.6 Manual
@author by Lars Magne Ingebrigtsen
@page
spool or your mbox file. All at the same time, if you want to push your
luck.
-This manual corresponds to Gnus 5.4.59.
+This manual corresponds to Quassia Gnus 0.6.
@end ifinfo
@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.
The @code{gnus-select-method} variable says where Gnus should look for
news. This variable should be a list where the first element says
@dfn{how} and the second element says @dfn{where}. This method is your
-native method. All groups that are not fetched with this method are
+native method. All groups not fetched with this method are
foreign groups.
For instance, if the @samp{news.somewhere.edu} @sc{nntp} server is where
@code{NNTPSERVER} environment variable. If that variable isn't set,
Gnus will see whether @code{gnus-nntpserver-file}
(@file{/etc/nntpserver} by default) has any opinions on the matter. If
-that fails as well, Gnus will try to use the machine that is
-running Emacs as an @sc{nntp} server. That's a long shot, though.
+that fails as well, Gnus will try to use the machine running Emacs as an @sc{nntp} server. That's a long shot, though.
@vindex gnus-nntp-server
If @code{gnus-nntp-server} is set, this variable will override
also save you some time at startup. Even if this variable is
@code{nil}, you can always subscribe to the new groups just by pressing
@kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
-is @code{t} by default. If you set this variable to @code{always}, then
-Gnus will query the backends for new groups even when you do the @kbd{g}
-command (@pxref{Scanning New Messages}).
+is @code{ask-server} by default. If you set this variable to
+@code{always}, then Gnus will query the backends for new groups even
+when you do the @kbd{g} command (@pxref{Scanning New Messages}).
@menu
* Checking New Groups:: Determining what groups are new.
@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
@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
@c @head
The active file can be rather Huge, so if you have a slow network, you
can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
-reading the active file. This variable is @code{t} by default.
+reading the active file. This variable is @code{some} by default.
Gnus will try to make do by getting information just on the groups that
you actually subscribe to.
@item gnus-load-hook
@vindex gnus-load-hook
-A hook that is run while Gnus is being loaded. Note that this hook will
+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 that is 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
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)
(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
-will only move to groups that are of the same level (or lower). In
+will only move to groups of the same level (or lower). In
particular, going from the last article in one group to the next group
will go to the next group of the same level (or lower). This might be
handy if you want to read the most important groups before you read the
use this level as the ``work'' level.
@vindex gnus-activate-level
-Gnus will normally just activate groups that are 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
@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.
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}.
(@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)
@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
If the group parameter has an element that looks like @code{(auto-expire
-. t)}, all articles that are read will be marked as expirable. For an
+. t)}, all articles read will be marked as expirable. For an
alternative approach, @pxref{Expiring Mail}.
@item total-expire
@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
@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
@section Listing Groups
@cindex group listing
-These commands all list various slices of the groups that are available.
+These commands all list various slices of the groups available.
@table @kbd
@item A A
@kindex A A (Group)
@findex gnus-group-list-active
-List absolutely all groups that are in the active file(s) of the
+List absolutely all groups in the active file(s) of the
server(s) you are connected to (@code{gnus-group-list-active}). This
might very well take quite a while. It might actually be a better idea
to do a @kbd{A M} to list all matching, and just give @samp{.} as the
@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
@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
@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)
@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.
@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
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
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.
@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
@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
@item gnus-summary-selected-face
@vindex gnus-summary-selected-face
-This is the face (or @dfn{font} as some people call it) that is used to
+This is the face (or @dfn{font} as some people call it) used to
highlight the current article in the summary buffer.
@item gnus-summary-highlight
@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)
@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
@node Choosing Variables
@subsection Choosing Variables
-Some variables that are relevant for moving and selecting articles:
+Some variables relevant for moving and selecting articles:
@table @code
@item gnus-auto-extend-newsgroup
@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)
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
Marking articles as @dfn{expirable} (or have them marked as such
automatically) doesn't make much sense in normal groups---a user doesn't
control expiring of news articles, but in mail groups, for instance,
-articles that are marked as @dfn{expirable} can be deleted by Gnus at
+articles marked as @dfn{expirable} can be deleted by Gnus at
any time.
@end table
@item
@vindex gnus-cached-mark
-Articles that are 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
-Articles that are ``saved'' (in some manner or other; not necessarily
+Articles ``saved'' (in some manner or other; not necessarily
religiously) are marked with an @samp{S} in the second column
(@code{gnus-saved-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 ?
@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
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
-Clear all readedness-marks from the current article
-(@code{gnus-summary-clear-mark-forward}).
-
@item M e
@itemx E
@kindex M e (Summary)
@kindex / u (Summary)
@kindex x (Summary)
@findex gnus-summary-limit-to-unread
-Limit the summary buffer to articles that are not marked as read
+Limit the summary buffer to articles not marked as read
(@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
-buffer to articles that are strictly unread. This means that ticked and
+buffer to articles strictly unread. This means that ticked and
dormant articles will also be excluded.
@item / m
@item / t
@kindex / t (Summary)
@findex gnus-summary-limit-to-age
-Ask for a number and then limit the summary buffer to articles that are
-older than (or equal to) that number of days
+Ask for a number and then limit the summary buffer to articles older than (or equal to) that number of days
(@code{gnus-summary-limit-to-marks}). If given a prefix, limit to
-articles that are younger than that number of days.
+articles younger than that number of days.
@item / n
@kindex / n (Summary)
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.
@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 that are 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
'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
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
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
when doing thread commands. If this variable is @code{nil}, articles in
the same thread with different subjects will not be included in the
operation in question. If this variable is @code{fuzzy}, only articles
-that have subjects that are fuzzily equal will be included (@pxref{Fuzzy
+that have subjects fuzzily equal will be included (@pxref{Fuzzy
Matching}).
If you are using an unthreaded display for some strange reason or other,
you have to fiddle with the @code{gnus-article-sort-functions} variable.
It is very similar to the @code{gnus-thread-sort-functions}, except that
-is uses slightly different functions for article comparison. Available
+it uses slightly different functions for article comparison. Available
sorting predicate functions are @code{gnus-article-sort-by-number},
@code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject},
@code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}.
@code{nil} on read articles. The function is called with an article
data structure as the only parameter.
-If, for instance, you wish to pre-fetch only unread articles that are
-shorter than 100 lines, you could say something like:
+If, for instance, you wish to pre-fetch only unread articles shorter than 100 lines, you could say something like:
@lisp
(defun my-async-short-unread-p (data)
@vindex gnus-cache-directory
@vindex gnus-use-cache
To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
-all articles that are ticked or marked as dormant will then be copied
+all articles ticked or marked as dormant will then be copied
over to your local cache (@code{gnus-cache-directory}). Whether this
cache is flat or hierarchal is controlled by the
@code{gnus-use-long-file-name} variable, as usual.
variables. Both are lists of symbols. The first is @code{(ticked
dormant)} by default, meaning that ticked and dormant articles will be
put in the cache. The latter is @code{(read)} by default, meaning that
-articles that are marked as read are removed from the cache. Possibly
+articles marked as read are removed from the cache. Possibly
symbols in these two lists are @code{ticked}, @code{dormant},
@code{unread} and @code{read}.
@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,
name.
Here's an example function to clean up file names somewhat. If you have
-lots of mail groups that are called things like
+lots of mail groups called things like
@samp{nnml:mail.whatever}, you may want to chop off the beginning of
these group names before creating the file name to save to. The
following will do just that:
@lisp
(setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
-(setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
+(setq gnus-default-article-saver 'gnus-summary-save-in-file) ; no encoding
@end lisp
Then just save with @kbd{o}. You'd then read this hierarchy with
@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
@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
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
@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
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
@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)
@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)
@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)
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
@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
@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
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
[Paa]
@end example
+If you're using horizontal trees, it might be nice to display the trees
+side-by-side with the summary buffer. You could add something like the
+following to your @file{.gnus.el} file:
+
+@lisp
+(setq gnus-use-trees t
+ gnus-generate-tree-function 'gnus-generate-horizontal-tree
+ gnus-tree-minimize-window nil)
+(gnus-add-configuration
+ '(article
+ (vertical 1.0
+ (horizontal 0.25
+ (summary 0.75 point)
+ (tree 1.0))
+ (article 1.0))))
+@end lisp
+
+@xref{Windows Configuration}.
+
@node Mail Group Commands
@section Mail Group Commands
@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}).
@findex gnus-summary-expire-articles-now
Delete all the expirable articles in the group
(@code{gnus-summary-expire-articles-now}). This means that @strong{all}
-articles that are eligible for expiry in the current group will
+articles eligible for expiry in the current group will
disappear forever into that big @file{/dev/null} in the sky.
@item B DEL
(setq gnus-visible-headers "^From:\\|^Subject:")
@end lisp
-This variable can also be a list of regexps to match headers that are to
+This variable can also be a list of regexps to match headers to
remain visible.
@item gnus-ignored-headers
(setq gnus-ignored-headers "^References:\\|^Xref:")
@end lisp
-This variable can also be a list of regexps to match headers that are to
+This variable can also be a list of regexps to match headers to
be removed.
Note that if @code{gnus-visible-headers} is non-@code{nil}, this
@end lisp
Any headers that are to remain visible, but are not listed in this
-variable, will be displayed in random order after all the headers that
-are listed in this variable.
+variable, will be displayed in random order after all the headers listed in this variable.
@findex gnus-article-hide-boring-headers
@vindex gnus-article-display-hook
* 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
@node Mail and Post
@section Mail and Post
-Here's a list of variables that are relevant to both mailing and
+Here's a list of variables relevant to both mailing and
posting:
@table @code
@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)
@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
-@node Select Methods
-@chapter Select Methods
-@cindex foreign groups
-@cindex select methods
+@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.
-A @dfn{foreign group} is a group that is not read by the usual (or
-default) means. It could be, for instance, a group from a different
-@sc{nntp} server, it could be a virtual group, or it could be your own
-personal mail group.
+Rejected articles will also be put in this draft group (@pxref{Rejected
+Articles}).
-A foreign group (or any group, really) is specified by a @dfn{name} and
-a @dfn{select method}. To take the latter first, a select method is a
+@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
+@cindex foreign groups
+@cindex select methods
+
+A @dfn{foreign group} is a group not read by the usual (or
+default) means. It could be, for instance, a group from a different
+@sc{nntp} server, it could be a virtual group, or it could be your own
+personal mail group.
+
+A foreign group (or any group, really) is specified by a @dfn{name} and
+a @dfn{select method}. To take the latter first, a select method is a
list where the first element says what backend to use (e.g. @code{nntp},
@code{nnspool}, @code{nnml}) and the second element is the @dfn{server
name}. There may be additional elements in the select method, where the
* 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
server, that would be too much work, so Gnus offers a way of naming
select methods, which is what you do in the server buffer.
-To enter the server buffer, user the @kbd{^}
+To enter the server buffer, use the @kbd{^}
(@code{gnus-group-enter-server-mode}) command in the group buffer.
@menu
@code{nnmh} is a mail backend that reads a spool-like structure. Say
you have two structures that you wish to access: One is your private
mail spool, and the other is a public one. Here's the possible spec for
-you private mail:
+your private mail:
@lisp
(nnmh "private" (nnmh-directory "~/private/mail/"))
is run after a connection has been made. It can be used to send
commands to the @sc{nntp} server after it has been contacted. By
default it sends the command @code{MODE READER} to the server with the
-@code{nntp-send-mode-reader} function.
+@code{nntp-send-mode-reader} function. This function should always be
+present in this hook.
@item nntp-authinfo-function
@vindex nntp-authinfo-function
The default value is
@lisp
- '(("nntpd 1\\.5\\.11t"
- (remove-hook 'nntp-server-opened-hook nntp-send-mode-reader)))
+'(("nntpd 1\\.5\\.11t"
+ (remove-hook 'nntp-server-opened-hook 'nntp-send-mode-reader)))
@end lisp
This ensures that Gnus doesn't send the @code{MODE READER} command to
@vindex nntp-xover-commands
@cindex nov
@cindex XOVER
-List of strings that are used as commands to fetch @sc{nov} lines from a
+List of strings used as commands to fetch @sc{nov} lines from a
server. The default value of this variable is @code{("XOVER"
"XOVERVIEW")}.
@code{XOVER} request is split into several request. Note that if your
network is fast, setting this variable to a really small number means
that fetching will probably be slower. If this variable is @code{nil},
-@code{nntp} will never split requests.
+@code{nntp} will never split requests. The default is 5.
@item nntp-prepare-server-hook
@vindex nntp-prepare-server-hook
@var{FIELD} and @var{VALUE} can also be lisp symbols, in that case they
are expanded as specified by the variable
@code{nnmail-split-abbrev-alist}. This is an alist of cons cells, where
-the car of a cell contains the key, and the cdr contains the associated
+the @code{car} of a cell contains the key, and the @code{cdr} contains the associated
value.
@vindex nnmail-split-fancy-syntax-table
You do not have to mark articles as expirable by hand. Groups that
match the regular expression @code{gnus-auto-expirable-newsgroups} will
have all articles that you read marked as expirable automatically. All
-articles that are marked as expirable have an @samp{E} in the first
+articles marked as expirable have an @samp{E} in the first
column in the summary buffer.
By default, if you have auto expiry switched on, Gnus will mark all the
@end lisp
Note that making a group auto-expirable doesn't mean that all read
-articles are expired---only the articles that are marked as expirable
+articles are expired---only the articles marked as expirable
will be expired. Also note that using the @kbd{d} command won't make
groups expirable---only semi-automatic marking of articles as read will
mark the articles as expirable in auto-expirable groups.
it, you might treat it as a newsgroup. The files have to have numerical
names, of course.
-This might be an opportune moment to mention @code{ange-ftp}, that most
-wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
-didn't think much about it---a backend to read directories. Big deal.
+This might be an opportune moment to mention @code{ange-ftp} (and its
+successor @code{efs}), that most wonderful of all wonderful Emacs
+packages. When I wrote @code{nndir}, I didn't think much about it---a
+backend to read directories. Big deal.
@code{ange-ftp} changes that picture dramatically. For instance, if you
enter the @code{ange-ftp} file name
@file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name,
-@code{ange-ftp} or @code{efs} will actually allow you to read this directory over at
-@samp{sina} as a newsgroup. Distributed news ahoy!
+@code{ange-ftp} or @code{efs} will actually allow you to read this
+directory over at @samp{sina} as a newsgroup. Distributed news ahoy!
@code{nndir} will use @sc{nov} files if they are present.
@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
@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
sequence of articles. Sorting on date might be an option here
(@pxref{Selecting a Group}).
-One limitation, however---all groups that are included in a virtual
+One limitation, however---all groups included in a virtual
group have to be alive (i.e., subscribed or unsubscribed). Killed or
zombie groups can't be component groups for @code{nnvirtual} groups.
and the other is an additional @file{.newsrc} file to store information
on what groups have been searched through to find component articles.
-Articles that are marked as read in the @code{nnkiboze} group will have
+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
Customize a score file in a visually pleasing manner
(@code{gnus-score-customize}).
-@item I C-i
-@kindex I C-i (Summary)
-@findex gnus-summary-raise-score
-Increase the score of the current article
-(@code{gnus-summary-raise-score}).
-
-@item L C-l
-@kindex L C-l (Summary)
-@findex gnus-summary-lower-score
-Lower the score of the current article
-(@code{gnus-summary-lower-score}).
@end table
The rest of these commands modify the local score file.
@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
@cindex score cache
All score files are normally cached to avoid excessive re-loading of
score files. However, if this might make you Emacs grow big and
-bloated, so this regexp can be used to weed out score files that are
-unlikely to be needed again. It would be a bad idea to deny caching of
+bloated, so this regexp can be used to weed out score files unlikely to be needed again. It would be a bad idea to deny caching of
@file{all.SCORE}, while it might be a good idea to not cache
@file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
variable is @samp{ADAPT$} by default, so no adaptive score files will
(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
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:
@cindex date
A more useful match type is @code{regexp}. With it, you can match the
date string using a regular expression. The date is normalized to
-ISO8601 compact format first---@samp{YYYYMMDDTHHMMSS}. If you want to
-match all articles that have been posted on April 1st in every year, you
-could use @samp{....0401.........} as a match string, for instance.
-(Note that the date is kept in its original time zone, so this will
-match articles that were posted when it was April 1st where the article
-was posted from. Time zones are such wholesome fun for the whole
-family, eh?)
+ISO8601 compact format first---@var{YYYYMMDD}@code{T}@var{HHMMSS}. If
+you want to match all articles that have been posted on April 1st in
+every year, you could use @samp{....0401.........} as a match string,
+for instance. (Note that the date is kept in its original time zone, so
+this will match articles that were posted when it was April 1st where
+the article was posted from. Time zones are such wholesome fun for the
+whole family, eh?)
@item Head, Body, All
These three match keys use the same match types as the @code{From} (etc)
@item Thread
This match key works along the same lines as the @code{Followup} match
-key. If you say that you want to score on a (sub-)thread that is
-started by an article with a @code{Message-ID} @var{X}, then you add a
+key. If you say that you want to score on a (sub-)thread started by an article with a @code{Message-ID} @var{X}, then you add a
@samp{thread} match. This will add a new @samp{thread} match for each
article that has @var{X} in its @code{References} header. (These new
@samp{thread} matches will use the @code{Message-ID}s of these matching
@end table
@end enumerate
+@cindex Score File Atoms
@item mark
The value of this entry should be a number. Any articles with a score
lower than this number will be marked as read.
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
@end lisp
This is the default value. If you have adaption on words enabled, every
-word that appears in subjects of articles that are marked with
+word that appears in subjects of articles marked with
@code{gnus-read-mark} will result in a score rule that increase the
score with 30 points.
@lisp
("references"
- ("<x6[0-9a-z]+\\.fsf@@.*eyesore.no>" 1000 nil r))
+ ("<x6[0-9a-z]+\\.fsf\\(_-_\\)?@@.*eyesore.no>"
+ 1000 nil r))
@end lisp
Whether it's the first two or first three characters that are ``yours''
@itemize @bullet
@item
-Articles that are heavily crossposted are probably junk.
+Articles heavily crossposted are probably junk.
@item
To lower a single inappropriate article, lower by @code{Message-ID}.
@item
(gnus-expunge "X")
@end lisp
-This will mark every article written by me as read, and remove them from
-the summary buffer. Very useful, you'll agree.
+This will mark every article written by me as read, and remove the
+marked articles from the summary buffer. Very useful, you'll agree.
Other programs use a totally different kill file syntax. If Gnus
encounters what looks like a @code{rn} kill file, it will take a stab at
@file{soc.motss.KILL}. The suffix appended to the group name to get
this file name is detailed by the @code{gnus-kill-file-name} variable.
The ``global'' kill file (not in the score file sense of ``global'', of
-course) is called just @file{KILL}.
+course) is just called @file{KILL}.
@vindex gnus-kill-save-kill-file
@item gnus-kill-save-kill-file
likewise and gives you a personalized prediction for each unread news
article. Think of GroupLens as a matchmaker. GroupLens watches how you
rate articles, and finds other people that rate articles the same way.
-Once it has found for you some people you agree with it tells you, in
-the form of a prediction, what they thought of the article. You can use
-this prediction to help you decide whether or not you want to read the
+Once it has found some people you agree with it tells you, in the form
+of a prediction, what they thought of the article. You can use this
+prediction to help you decide whether or not you want to read the
article.
@menu
To use GroupLens you must register a pseudonym with your local Better
Bit Bureau (BBB).
@samp{http://www.cs.umn.edu/Research/GroupLens/bbb.html} is the only
-better bit in town is at the moment.
+better bit in town at the moment.
Once you have registered you'll need to set a couple of variables.
@end table
-Thats the minimum of what you need to get up and running with GroupLens.
+That's the minimum of what you need to get up and running with GroupLens.
Once you've registered, GroupLens will start giving you scores for
articles based on the average of what other people think. But, to get
the real benefit of GroupLens you need to start rating articles
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
Plain-old numeric value.
@item confidence-plus-minus
-Prediction +/i confidence.
+Prediction +/- confidence.
@end table
@table @code
@item gnus-summary-grouplens-line-format
-The summary line format used in summary buffers that are GroupLens
-enhanced. It accepts the same specs as the normal summary line format
-(@pxref{Summary Buffer Lines}). The default is
-@samp{%U%R%z%l%I%(%[%4L: %-20,20n%]%) %s\n}.
+The summary line format used in GroupLens-enhanced summary buffers. It
+accepts the same specs as the normal summary line format (@pxref{Summary
+Buffer Lines}). The default is @samp{%U%R%z%l%I%(%[%4L: %-20,20n%]%)
+%s\n}.
@item grouplens-bbb-host
Host running the bbbd server. @samp{grouplens.cs.umn.edu} is the
Scoring on Subjects and From headers is nice enough, but what if you're
really interested in what a person has to say only when she's talking
-about a particular subject? Or what about if you really don't want to
+about a particular subject? Or what if you really don't want to
read what person A has to say when she's following up to person B, but
want to read what she says when she's following up to person C?
@itemx not
@itemx ¬
This logical operator only takes a single argument. It returns the
-inverse of the value of its argument.
+logical negation of the value of its argument.
@end table
There is an @dfn{indirection operator} that will make its arguments
apply to the ancestors of the current article being scored. For
instance, @code{1-} will make score rules apply to the parent of the
-current article. @code{2-} will make score fules apply to the
+current article. @code{2-} will make score rules apply to the
grandparent of the current article. Alternatively, you can write
-@code{^^}, where the number of @code{^}s (carets) say how far back into
+@code{^^}, where the number of @code{^}s (carets) says how far back into
the ancestry you want to go.
Finally, we have the match operators. These are the ones that do the
result of the operation will be. For instance, if one of the arguments
of an @code{&} evaluates to @code{false}, there's no point in evaluating
the rest of the arguments. This means that you should put slow matches
-(@samp{body}, @code{header}) last and quick matches (@samp{from},
+(@samp{body}, @samp{header}) last and quick matches (@samp{from},
@samp{subject}) first.
The indirection arguments (@code{1-} and so on) will make their
* Buttons:: Get tendonitis in ten easy steps!
* Daemons:: Gnus can do things behind your back.
* NoCeM:: How to avoid spam and other fatty foods.
-* Picons:: How to display pictures of what your reading.
* Undo:: Some actions can be undone.
* Moderation:: What to do if you're a moderator.
* XEmacs Enhancements:: There are more pictures and stuff under XEmacs.
Many functions, among them functions for moving, decoding and saving
articles, use what is known as the @dfn{Process/Prefix convention}.
-This is a method for figuring out what articles that the user wants the
+This is a method for figuring out what articles the user wants the
command to be performed on.
It goes like this:
active, all articles in the region will be worked upon.
If there is no numeric prefix, but some articles are marked with the
-process mark, perform the operation on the articles that are marked with
+process mark, perform the operation on the articles marked with
the process mark.
If there is neither a numeric prefix nor any articles marked with the
@section Formatting Variables
@cindex formatting variables
-Throughout this manual you've probably noticed lots of variables that
-are called things like @code{gnus-group-line-format} and
+Throughout this manual you've probably noticed lots of variables called things like @code{gnus-group-line-format} and
@code{gnus-summary-mode-line-format}. These control how Gnus is to
output lines in the various buffers. There's quite a lot of them.
Fortunately, they all use the same syntax, so there's not that much to
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
Text inside the @samp{%[} and @samp{%]} specifiers will have their
normal faces set using @code{gnus-face-0}, which is @code{bold} by
-default. If you say @samp{%1[} instead, you'll get @code{gnus-face-1}
-instead, and so on. Create as many faces as you wish. The same goes
-for the @code{mouse-face} specs---you can say @samp{%3(hello%)} to have
+default. If you say @samp{%1[}, you'll get @code{gnus-face-1} instead,
+and so on. Create as many faces as you wish. The same goes for the
+@code{mouse-face} specs---you can say @samp{%3(hello%)} to have
@samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
Here's an alternative recipe for the group buffer:
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
instead of the normal @code{1.0} top-level spec, each additional split
should have a frame parameter alist as the size spec.
@xref{Frame Parameters, , Frame Parameters, elisp, The GNU Emacs Lisp
-Reference Manual}.
+Reference Manual}. Under XEmacs, a frame property list will be
+accepted, too---for instance, @code{(height 5 width 15 left -1 top 1)}
+is such a plist.
Here's a list of all possible keys for
@code{gnus-buffer-configuration}:
@code{summary-faq}, @code{edit-group}, @code{edit-server},
@code{edit-score}, @code{post}, @code{reply}, @code{forward},
@code{reply-yank}, @code{mail-bounce}, @code{draft}, @code{pipe},
-@code{bug}, @code{compose-bounce}.
+@code{bug}, @code{compose-bounce}, and @code{score-trace}.
Note that the @code{message} key is used for both
@code{gnus-group-mail} and @code{gnus-summary-mail-other-window}. If
@end lisp
If this variable is @code{nil} (which is the default), the mode line
-strings won't be chopped off, and they won't be padded either.
-Note that the default is unlikely to be desirable, as even the
-percentage complete in the buffer may be crowded off the mode line;
-the user should configure this variable appropriately for their
-configuration.
+strings won't be chopped off, and they won't be padded either. Note
+that the default is unlikely to be desirable, as even the percentage
+complete in the buffer may be crowded off the mode line; the user should
+configure this variable appropriately for her configuration.
@node Highlighting and Menus
@cindex menus
@vindex gnus-visual
-The @code{gnus-visual} variable controls most of the prettifying Gnus
+The @code{gnus-visual} variable controls most of the Gnus-prettifying
aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy
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
(setq gnus-visual '(article-highlight menu))
@end lisp
-If you want only highlighting and no menus whatsoever, you'd say:
+If you want highlighting only and no menus whatsoever, you'd say:
@lisp
(setq gnus-visual '(highlight))
@end table
All the @code{buttons} variables are lists. The elements in these list
-is either a cons cell where the car contains a text to be displayed and
-the cdr contains a function symbol, or a simple string.
+are either cons cells where the @code{car} contains a text to be displayed and
+the @code{cdr} contains a function symbol, or a simple string.
@node Daemons
@findex gnus-demon-add-rescan
@findex gnus-demon-add-scan-timestamps
@findex gnus-demon-add-disconnection
-Some ready-made functions to do this has been created:
+Some ready-made functions to do this have been created:
@code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection},
@code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and
@code{gnus-demon-add-scanmail}. Just put those functions in your
unsubscribed groups (@pxref{Subscription Commands}).
+@node Undo
+@section Undo
+@cindex undo
+
+It is very useful to be able to undo actions one has done. In normal
+Emacs buffers, it's easy enough---you just push the @code{undo} button.
+In Gnus buffers, however, it isn't that simple.
+
+The things Gnus displays in its buffer is of no value whatsoever to
+Gnus---it's all just data designed to look nice to the user.
+Killing a group in the group buffer with @kbd{C-k} makes the line
+disappear, but that's just a side-effect of the real action---the
+removal of the group in question from the internal Gnus structures.
+Undoing something like that can't be done by the normal Emacs
+@code{undo} function.
+
+Gnus tries to remedy this somewhat by keeping track of what the user
+does and coming up with actions that would reverse the actions the user
+takes. When the user then presses the @code{undo} key, Gnus will run
+the code to reverse the previous action, or the previous actions.
+However, not all actions are easily reversible, so Gnus currently offers
+a few key functions to be undoable. These include killing groups,
+yanking groups, and changing the list of read articles of groups.
+That's it, really. More functions may be added in the future, but each
+added function means an increase in data to be stored, so Gnus will
+never be totally undoable.
+
+@findex gnus-undo-mode
+@vindex gnus-use-undo
+@findex gnus-undo
+The undoability is provided by the @code{gnus-undo-mode} minor mode. It
+is used if @code{gnus-use-undo} is non-@code{nil}, which is the
+default. The @kbd{M-C-_} key performs the @code{gnus-undo} command
+command, which should feel kinda like the normal Emacs @code{undo}
+command.
+
+
+@node Moderation
+@section Moderation
+@cindex moderation
+
+If you are a moderator, you can use the @file{gnus-mdrtn.el} package.
+It is not included in the standard Gnus package. Write a mail to
+@samp{larsi@@gnus.org} and state what group you moderate, and you'll
+get a copy.
+
+The moderation package is implemented as a minor mode for summary
+buffers. Put
+
+@lisp
+(add-hook 'gnus-summary-mode-hook 'gnus-moderate)
+@end lisp
+
+in your @file{.gnus.el} file.
+
+If you are the moderator of @samp{rec.zoofle}, this is how it's
+supposed to work:
+
+@enumerate
+@item
+You split your incoming mail by matching on
+@samp{Newsgroups:.*rec.zoofle}, which will put all the to-be-posted
+articles in some mail group---for instance, @samp{nnml:rec.zoofle}.
+
+@item
+You enter that group once in a while and post articles using the @kbd{e}
+(edit-and-post) or @kbd{s} (just send unedited) commands.
+
+@item
+If, while reading the @samp{rec.zoofle} newsgroup, you happen upon some
+articles that weren't approved by you, you can cancel them with the
+@kbd{c} command.
+@end enumerate
+
+To use moderation mode in these two groups, say:
+
+@lisp
+(setq gnus-moderated-list
+ "^nnml:rec.zoofle$\\|^rec.zoofle$")
+@end lisp
+
+
+@node XEmacs Enhancements
+@section XEmacs Enhancements
+@cindex XEmacs
+
+XEmacs is able to display pictures and stuff, so Gnus has taken
+advantage of that.
+
+@menu
+* Picons:: How to display pictures of what your reading.
+* Smileys:: Show all those happy faces the way they were meant to be shown.
+* Toolbar:: Click'n'drool.
+* XVarious:: Other XEmacsy Gnusey variables.
+@end menu
+
+
@node Picons
-@section Picons
+@subsection Picons
@iftex
@iflatex
@node Picon Basics
-@subsection Picon Basics
+@subsubsection Picon Basics
What are Picons? To quote directly from the Picons Web site:
@node Picon Requirements
-@subsection Picon Requirements
+@subsubsection Picon Requirements
-To use have Gnus display Picons for you, you must be running XEmacs
+To have Gnus display Picons for you, you must be running XEmacs
19.13 or greater since all other versions of Emacs aren't yet able to
display images.
@node Easy Picons
-@subsection Easy Picons
+@subsubsection Easy Picons
To enable displaying picons, simply put the following line in your
@file{~/.gnus} file and start Gnus.
@node Hard Picons
-@subsection Hard Picons
+@subsubsection Hard Picons
Gnus can display picons for you as you enter and leave groups and
articles. It knows how to interact with three sections of the picons
@table @code
@item gnus-article-display-picons
@findex gnus-article-display-picons
-Looks up and display the picons for the author and the author's domain
-in the @code{gnus-picons-display-where} buffer. Should be added to
-the @code{gnus-article-display-hook}.
+Looks up and displays the picons for the author and the author's domain
+in the @code{gnus-picons-display-where} buffer. Should be added to the
+@code{gnus-article-display-hook}.
@item gnus-group-display-picons
@findex gnus-article-display-picons
@end table
Note: You must append them to the hook, so make sure to specify 't'
-to the append flag of @code{add-hook}:
+for the append flag of @code{add-hook}:
@lisp
(add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
@node Picon Configuration
-@subsection Picon Configuration
+@subsubsection Picon Configuration
The following variables offer further control over how things are
done, where things are located, and other useless stuff you really
@item gnus-picons-user-directories
@vindex gnus-picons-user-directories
List of subdirectories to search in @code{gnus-picons-database} for user
-faces. @code{("local" "users" "usenix" "misc/MISC")} is the default.
+faces. @code{("local" "users" "usenix" "misc")} is the default.
@item gnus-picons-domain-directories
@vindex gnus-picons-domain-directories
@end table
+@node Smileys
+@subsection Smileys
+@cindex smileys
-@node Undo
-@section Undo
-@cindex undo
+@dfn{Smiley} is a package separate from Gnus, but since Gnus is
+currently the only package that uses Smiley, it is documented here.
-It is very useful to be able to undo actions one has done. In normal
-Emacs buffers, it's easy enough---you just push the @code{undo} button.
-In Gnus buffers, however, it isn't that simple.
+In short---to use Smiley in Gnus, put the following in your
+@file{.gnus.el} file:
-The things Gnus displays in its buffer is of no value whatsoever to
-Gnus---it's all just data that is designed to look nice to the user.
-Killing a group in the group buffer with @kbd{C-k} makes the line
-disappear, but that's just a side-effect of the real action---the
-removal of the group in question from the internal Gnus structures.
-Undoing something like that can't be done by the normal Emacs
-@code{undo} function.
-
-Gnus tries to remedy this somewhat by keeping track of what the user
-does and coming up with actions that would reverse the actions the user
-takes. When the user then presses the @code{undo} key, Gnus will run
-the code to reverse the previous action, or the previous actions.
-However, not all actions are easily reversible, so Gnus currently offers
-a few key functions to be undoable. These include killing groups,
-yanking groups, and changing the list of read articles of groups.
-That's it, really. More functions may be added in the future, but each
-added function means an increase in data to be stored, so Gnus will
-never be totally undoable.
-
-@findex gnus-undo-mode
-@vindex gnus-use-undo
-@findex gnus-undo
-The undoability is provided by the @code{gnus-undo-mode} minor mode. It
-is used if @code{gnus-use-undo} is non-@code{nil}, which is the
-default. The @kbd{M-C-_} key performs the @code{gnus-undo} command
-command, which should feel kinda like the normal Emacs @code{undo}
-command.
+@lisp
+(add-hook 'gnus-article-display-hook 'gnus-smiley-display t)
+@end lisp
+Smiley maps text smiley faces---@samp{:-)}, @samp{:-=}, @samp{:-(} and
+the like---to pictures and displays those instead of the text smiley
+faces. The conversion is controlled by a list of regexps that matches
+text and maps that to file names.
-@node Moderation
-@section Moderation
-@cindex moderation
+@vindex smiley-nosey-regexp-alist
+@vindex smiley-deformed-regexp-alist
+Smiley supplies two example conversion alists by default:
+@code{smiley-deformed-regexp-alist} (which matches @samp{:)}, @samp{:(}
+and so on), and @code{smiley-nosey-regexp-alist} (which matches
+@samp{:-)}, @samp{:-(} and so on).
-If you are a moderator, you can use the @file{gnus-mdrtn.el} package.
-It is not included in the standard Gnus package. Write a mail to
-@samp{larsi@@gnus.org} and state what group you moderate, and you'll
-get a copy.
+The alist used is specified by the @code{smiley-regexp-alist} variable,
+which defaults to the value of @code{smiley-deformed-regexp-alist}.
-The moderation package is implemented as a minor mode for summary
-buffers. Put
+Here's the default value of @code{smiley-smiley-regexp-alist}:
@lisp
-(add-hook 'gnus-summary-mode-hook 'gnus-moderate)
+(setq smiley-nosey-regexp-alist
+ '(("\\(:-+[<«]+\\)\\W" 1 "FaceAngry.xpm")
+ ("\\(:-+\\]+\\)\\W" 1 "FaceGoofy.xpm")
+ ("\\(:-+D\\)\\W" 1 "FaceGrinning.xpm")
+ ("\\(:-+[@}»]+\\)\\W" 1 "FaceHappy.xpm")
+ ("\\(:-*)+\\)\\W" 1 "FaceHappy.xpm")
+ ("\\(:-+[/\\\"]+\\)\\W" 1 "FaceIronic.xpm")
+ ("\\([8|]-+[|Oo%]\\)\\W" 1 "FaceKOed.xpm")
+ ("\\([:|]-+#+\\)\\W" 1 "FaceNyah.xpm")
+ ("\\(:-+[(@{]+\\)\\W" 1 "FaceSad.xpm")
+ ("\\(:-+[Oo\*]\\)\\W" 1 "FaceStartled.xpm")
+ ("\\(:-+|\\)\\W" 1 "FaceStraight.xpm")
+ ("\\(:-+p\\)\\W" 1 "FaceTalking.xpm")
+ ("\\(:-+d\\)\\W" 1 "FaceTasty.xpm")
+ ("\\(;-+[>)@}»]+\\)\\W" 1 "FaceWinking.xpm")
+ ("\\(:-+[Vvµ]\\)\\W" 1 "FaceWry.xpm")
+ ("\\(][:8B]-[)>]\\)\\W" 1 "FaceDevilish.xpm")
+ ("\\([:|]-+P\\)\\W" 1 "FaceYukky.xpm")))
@end lisp
-in your @file{.gnus.el} file.
+The first item in each element is the regexp to be matched; the second
+element is the regexp match group that is to be replaced by the picture;
+and the third element is the name of the file to be displayed.
-If you are the moderation of @samp{rec.zoofle}, this is how it's
-supposed to work:
+The following variables customize where Smiley will look for these
+files, as well as the color to be used and stuff:
-@enumerate
-@item
-You split your incoming mail by matching on
-@samp{Newsgroups:.*rec.zoofle}, which will put all the to-be-posted
-articles in some mail group---for instance, @samp{nnml:rec.zoofle}.
+@table @code
-@item
-You enter that group once in a while and post articles using the @kbd{e}
-(edit-and-post) or @kbd{s} (just send unedited) commands.
+@item smiley-data-directory
+@vindex smiley-data-directory
+Where Smiley will look for smiley faces files.
-@item
-If, while reading the @samp{rec.zoofle} newsgroup, you happen upon some
-articles that weren't approved by you, you can cancel them with the
-@kbd{c} command.
-@end enumerate
+@item smiley-flesh-color
+@vindex smiley-flesh-color
+Skin color. The default is @samp{yellow}, which is really racist.
-To use moderation mode in these two groups, say:
+@item smiley-features-color
+@vindex smiley-features-color
+Color of the features of the face. The default is @samp{black}.
-@lisp
-(setq gnus-moderated-list
- "^nnml:rec.zoofle$\\|^rec.zoofle$")
-@end lisp
+@item smiley-tongue-color
+@vindex smiley-tongue-color
+Color of the tongue. The default is @samp{red}.
+@item smiley-circle-color
+@vindex smiley-circle-color
+Color of the circle around the face. The default is @samp{black}.
-@node XEmacs Enhancements
-@section XEmacs Enhancements
-@cindex XEmacs
+@item smiley-mouse-face
+@vindex smiley-mouse-face
+Face used for mouse highlighting over the smiley face.
-XEmacs is able to display pictures and stuff, so Gnus has taken
-advantage of that. Relevant variables include:
+@end table
-@table @code
-@item gnus-xmas-glyph-directory
-@vindex gnus-xmas-glyph-directory
-This is where Gnus will look for pictures. Gnus will normally
-auto-detect this directory, but you may set it manually if you have an
-unusual directory structure.
-@item gnus-xmas-logo-color-alist
-@vindex gnus-xmas-logo-color-alist
-This is an alist where the key is a type symbol and the values are the
-foreground and background color of the splash page glyph.
+@node Toolbar
+@subsection Toolbar
-@item gnus-xmas-logo-color-style
-@vindex gnus-xmas-logo-color-style
-This is the key used to look up the color in the alist described above.
-Legal values include @code{flame}, @code{pine}, @code{moss},
-@code{irish}, @code{sky}, @code{tin}, @code{velvet}, @code{grape},
-@code{labia}, @code{berry}, @code{neutral}, and @code{september}.
+@table @code
@item gnus-use-toolbar
@vindex gnus-use-toolbar
@vindex gnus-summary-mail-toolbar
The toolbar in the summary buffer of mail groups.
+@end table
+
+
+@node XVarious
+@subsection Various XEmacs Variables
+
+@table @code
+@item gnus-xmas-glyph-directory
+@vindex gnus-xmas-glyph-directory
+This is where Gnus will look for pictures. Gnus will normally
+auto-detect this directory, but you may set it manually if you have an
+unusual directory structure.
+
+@item gnus-xmas-logo-color-alist
+@vindex gnus-xmas-logo-color-alist
+This is an alist where the key is a type symbol and the values are the
+foreground and background color of the splash page glyph.
+
+@item gnus-xmas-logo-color-style
+@vindex gnus-xmas-logo-color-style
+This is the key used to look up the color in the alist described above.
+Legal values include @code{flame}, @code{pine}, @code{moss},
+@code{irish}, @code{sky}, @code{tin}, @code{velvet}, @code{grape},
+@code{labia}, @code{berry}, @code{neutral}, and @code{september}.
+
@item gnus-xmas-modeline-glyph
@vindex gnus-xmas-modeline-glyph
A glyph displayed in all Gnus mode lines. It is a tiny gnu head by
@end table
+
+
@node Fuzzy Matching
@section Fuzzy Matching
@cindex fuzzy matching
The biggest problem I have with email spam is that it comes in under
false pretenses. I press @kbd{g} and Gnus merrily informs me that I
-have 10 new emails. I say ``Golly gee! Happy is me!'' and selects the
+have 10 new emails. I say ``Golly gee! Happy is me!'' and select the
mail group, only to find two pyramid schemes, seven advertisements
(``New! Miracle tonic for growing full, lustrouos hair on your toes!'')
and one mail asking me to repent and find some god.
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
variable is @code{nil}, there is no upper read bound. If it is
@code{t}, the backends won't try to read the articles piece by piece,
but read the entire articles. This makes sense with some versions of
-@code{ange-ftp}.
+@code{ange-ftp} or @code{efs}.
@item nnheader-head-chop-length
@vindex nnheader-head-chop-length
-This variable says how big a piece of each article to read when doing
-the operation described above.
+This variable (default 2048) says how big a piece of each article to
+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
@item gnus-shell-command-separator
@vindex gnus-shell-command-separator
-String used to separate to shell commands. The default is @samp{;}.
+String used to separate two shell commands. The default is @samp{;}.
@end table
On July 28th 1996 work on Red Gnus was begun, and it was released on
January 25th 1997 (after 84 releases) as ``Gnus 5.4''.
-If you happen upon a version of Gnus that has a name that is prefixed --
+If you happen upon a version of Gnus that has a prefixed name --
``(ding) Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'' --
don't panic. Don't let it know that you're frightened. Back away.
Slowly. Whatever you do, don't run. Walk away, calmly, until you're
to separate the newsreader from the backends, Gnus now offers a simple
interface for anybody who wants to write new backends for fetching mail
and news from different sources. I have added hooks for customizations
-everywhere I could imagine useful. By doing so, I'm inviting every one
-of you to explore and invent.
+everywhere I could imagine it being useful. By doing so, I'm inviting
+every one of you to explore and invent.
-May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
+May Gnus never be complete. @kbd{C-u 100 M-x all-hail-emacs} and
+@kbd{C-u 100 M-x all-hail-xemacs}.
@node Compatibility
All commands have kept their names. Some internal functions have changed
their names.
-The @code{gnus-uu} package has changed drastically. @pxref{Decoding
+The @code{gnus-uu} package has changed drastically. @xref{Decoding
Articles}.
One major compatibility question is the presence of several summary
-buffers. All variables that are relevant while reading a group are
+buffers. All variables relevant while reading a group are
buffer-local to the summary buffer they belong in. Although many
important variables have their values copied into their global
counterparts whenever a command is executed in the summary buffer, this
@end table
-If you ever notice Gnus acting non-compliantly with regards to the texts
+If you ever notice Gnus acting non-compliant with regards to the texts
mentioned above, don't hesitate to drop a note to Gnus Towers and let us
know.
@item
David Moore---rewrite of @file{nnvirtual.el} and many other things.
-@item
-Ricardo Nassif, Mark Borges, and Jost Krieger---proof-reading.
-
@item
Kevin Davidson---came up with the name @dfn{ding}, so blame him.
@end itemize
+This manual was proof-read by Adrian Aichner, with Ricardo Nassif, Mark
+Borges, and Jost Krieger proof-reading parts of the manual.
+
The following people have contributed many patches and suggestions:
Christopher Davis,
servers (@pxref{Browse Foreign Server}).
@item
-Gnus can fetch articles asynchronously on a second connection to the
+Gnus can fetch articles, asynchronously, on a second connection to the
server (@pxref{Asynchronous Fetching}).
@item
Picons (personal icons) can be displayed under XEmacs (@pxref{Picons}).
@item
-A @code{trn}-line tree buffer can be displayed (@pxref{Tree Display}).
+A @code{trn}-like tree buffer can be displayed (@pxref{Tree Display}).
@lisp
(setq gnus-use-trees t)
Groups}).
@item
-New group parameters have been introduced to set list-address and
+New group parameters have been introduced to set list-addresses and
expiry times (@pxref{Group Parameters}).
@item
@item
New variables for specifying what score and adapt files are to be
-considered home score and adapt files (@pxref{Home Score File}).
+considered home score and adapt files (@pxref{Home Score File}) have
+been added.
@item
@code{nndoc} was rewritten to be easily extendable (@pxref{Document
another have been added (@pxref{Changing Servers}).
@item
-A way to specify that ``uninteresting'' fields be suppressed when
-generating lines in buffers (@pxref{Advanced Formatting}).
+There's a way now to specify that ``uninteresting'' fields be suppressed
+when generating lines in buffers (@pxref{Advanced Formatting}).
@item
Several commands in the group buffer can be undone with @kbd{M-C-_}
@item body
@cindex body
-The rest of an article. Everything that is not in the head is in the
+The rest of an article. Everything not in the head is in the
body.
@item header
@item server
@cindex server
-A machine than one can connect to and get news (or mail) from.
+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
-A named select method. Since a select methods defines all there is to
-know about connecting to a (physical) server, taking the things as a
+A named select method. Since a select method defines all there is to
+know about connecting to a (physical) server, taking the thing as a
whole is a virtual server.
@item washing
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
@node Slow Terminal Connection
@subsection Slow Terminal Connection
-Let's say you use your home computer for dialing up the system that
-runs Emacs and Gnus. If your modem is slow, you want to reduce the
-amount of data that is sent over the wires as much as possible.
+Let's say you use your home computer for dialing up the system that runs
+Emacs and Gnus. If your modem is slow, you want to reduce (as much as
+possible) the amount of data sent over the wires.
@table @code
horizontal and vertical recentering.
@item gnus-visible-headers
-Cut down on the headers that are included in the articles to the
+Cut down on the headers included in the articles to the
minimum. You can, in fact, make do without them altogether---most of the
useful data is in the summary buffer, anyway. Set this variable to
@samp{^NEVVVVER} or @samp{From:}, or whatever you feel you need.
If you have a slow machine, or are just really impatient, there are a
few things you can do to make Gnus run faster.
-Set@code{gnus-check-new-newsgroups} and
+Set @code{gnus-check-new-newsgroups} and
@code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
time.
It is also important to remember that I have no memory whatsoever. If
-you send a bug report, and I send you a reply, and then you send back
-just ``No, it's not! Moron!'', I will have no idea what you are
+you send a bug report, and I send you a reply, and then you just send
+back ``No, it's not! Moron!'', I will have no idea what you are
insulting me about. Always over-explain everything. It's much easier
for all of us---if I don't have all the information I need, I will just
mail you and ask for more info, and everything takes more time.
will be defining (in some details) the interface between Gnus and its
backends (this is written in stone), the format of the score files
(ditto), data structures (some are less likely to change than others)
-and general method of operations.
+and general methods of operation.
@menu
* Gnus Utility Functions:: Common functions and variable to use.
@item gnus-get-info
@findex gnus-get-info
-Return the group info list for @var{group}.
+Returns the group info list for @var{group}.
@item gnus-add-current-to-buffer-list
@findex gnus-add-current-to-buffer-list
-Add the current buffer to the list of buffers to be killed on Gnus
+Adds the current buffer to the list of buffers to be killed on Gnus
exit.
@item gnus-continuum-version
@findex gnus-continuum-version
-Take a Gnus version string as a parameter and returns a floating point
+Takes a Gnus version string as a parameter and returns a floating point
number. Earlier versions will always get a lower number than later
versions.
@item gnus-group-read-only-p
@findex gnus-group-read-only-p
-Say whether @var{group} is read-only or not.
+Says whether @var{group} is read-only or not.
@item gnus-news-group-p
@findex gnus-news-group-p
-Say whether @var{group} came from a news backend.
+Says whether @var{group} came from a news backend.
@item gnus-ephemeral-group-p
@findex gnus-ephemeral-group-p
-Say whether @var{group} is ephemeral or not.
+Says whether @var{group} is ephemeral or not.
@item gnus-server-to-method
@findex gnus-server-to-method
-Return the select method corresponding to @var{server}.
+Returns the select method corresponding to @var{server}.
@item gnus-server-equal
@findex gnus-server-equal
-Say whether two virtual servers are equal.
+Says whether two virtual servers are equal.
@item gnus-group-native-p
@findex gnus-group-native-p
-Say whether @var{group} is native or not.
+Says whether @var{group} is native or not.
@item gnus-group-secondary-p
@findex gnus-group-secondary-p
-Say whether @var{group} is secondary or not.
+Says whether @var{group} is secondary or not.
@item gnus-group-foreign-p
@findex gnus-group-foreign-p
-Say whether @var{group} is foreign or not.
+Says whether @var{group} is foreign or not.
@item group-group-find-parameter
@findex group-group-find-parameter
-Return the parameter list of @var{group}. If given a second parameter,
-return the value of that parameter for @var{group}.
+Returns the parameter list of @var{group}. If given a second parameter,
+returns the value of that parameter for @var{group}.
@item gnus-group-set-parameter
@findex gnus-group-set-parameter
@item gnus-narrow-to-body
@findex gnus-narrow-to-body
-Narrow the current buffer to the body of the article.
+Narrows the current buffer to the body of the article.
@item gnus-check-backend-function
@findex gnus-check-backend-function
@item gnus-read-method
@findex gnus-read-method
-Prompt the user for a select method.
+Prompts the user for a select method.
@end table
The backends should be able to switch between several virtual servers.
The standard backends implement this by keeping an alist of virtual
-server environments that it pulls down/pushes up when needed.
+server environments that they pull down/push up when needed.
There are two groups of interface functions: @dfn{required functions},
which must be present, and @dfn{optional functions}, which Gnus will
-always check whether are present before attempting to call.
+always check for presence before attempting to call 'em.
All these functions are expected to return data in the buffer
@code{nntp-server-buffer} (@samp{ *nntpd*}), which is somewhat
return value.
Some backends could be said to be @dfn{server-forming} backends, and
-some might be said to not be. The latter are backends that generally
+some might be said not to be. The latter are backends that generally
only operate on one group at a time, and have no concept of ``server''
-- they have a group, and they deliver info on that group and nothing
more.
This might later be expanded to @code{various}, which will be a mixture
of HEADs and NOV lines, but this is currently not supported by Gnus.
-If @var{fetch-old} is non-@code{nil} it says to try to fetch "extra
-headers, in some meaning of the word. This is generally done by
+If @var{fetch-old} is non-@code{nil} it says to try fetching "extra
+headers", in some meaning of the word. This is generally done by
fetching (at most) @var{fetch-old} extra headers less than the smallest
-article number in @code{articles}, and fill in the gaps as well. The
+article number in @code{articles}, and filling the gaps as well. The
presence of this parameter can be ignored if the backend finds it
cumbersome to follow the request. If this is non-@code{nil} and not a
number, do maximum fetches.
field = <text except TAB>
@end example
-For a closer explanation what should be in those fields,
+For a closer look at what should be in those fields,
@pxref{Headers}.
@item (nnchoke-open-server SERVER &optional DEFINITIONS)
@var{server} is here the virtual server name. @var{definitions} is a
-list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
+list of @code{(VARIABLE VALUE)} pairs that define this virtual server.
If the server can't be opened, no error should be signaled. The backend
may then choose to refuse further attempts at connecting to this
If @var{server} is the current virtual server, and the connection to the
physical server is alive, then this function should return a
non-@code{nil} vlue. This function should under no circumstances
-attempt to reconnect to a server that is has lost connection to.
+attempt to reconnect to a server we have lost connection to.
There should be no data returned.
If @var{to-buffer} is non-@code{nil}, the result data should be returned
in this buffer instead of the normal data buffer. This is to make it
possible to avoid copying large amounts of data from one buffer to
-another, and Gnus mainly request articles to be inserted directly into
-its article buffer.
+another, while Gnus mainly requests articles to be inserted directly
+into its article buffer.
If it is at all possible, this function should return a cons cell where
-the car is the group name the article was fetched from, and the cdr is
+the @code{car} is the group name the article was fetched from, and the @code{cdr} is
the article number. This will enable Gnus to find out what the real
group and article numbers are when fetching articles by
@code{Message-ID}. If this isn't possible, @code{t} should be returned
-on successful article retrievement.
+on successful article retrieval.
@item (nnchoke-request-group GROUP &optional SERVER FAST)
The flag says whether the group is read-only (@samp{n}), is moderated
(@samp{m}), is dead (@samp{x}), is aliased to some other group
-(@samp{=other-group} or none of the above (@samp{y}).
+(@samp{=other-group}) or none of the above (@samp{y}).
@item (nnchoke-request-post &optional SERVER)
When the user issues commands for ``sending news'' (@kbd{F} in the
summary buffer, for instance), Gnus has to know whether the article the
-user is following up is news or mail. This function should return
+user is following up on is news or mail. This function should return
@code{news} if @var{article} in @var{group} is news, @code{mail} if it
is mail and @code{unknown} if the type can't be decided. (The
@var{article} parameter is necessary in @code{nnvirtual} groups which
@var{mark}. If the backend doesn't care, it must return the original
@var{mark}, and not @code{nil} or any other type of garbage.
-The only use for this that I can see is what @code{nnvirtual} does with
+The only use for this I can see is what @code{nnvirtual} does with
it---if a component group is auto-expirable, marking an article as read
in the virtual group should result in the article being marked as
expirable.
that there will be more requests issued shortly, so that allows some
optimizations.
-The function should return a cons where the car is the group name and
-the cdr is the article number that the article was entered as.
+The function should return a cons where the @code{car} is the group name and
+the @code{cdr} is the article number that the article was entered as.
There should be no data returned.
If @var{last} in @code{nil}, that means that there will be more calls to
this function in short order.
-The function should return a cons where the car is the group name and
-the cdr is the article number that the article was entered as.
+The function should return a cons where the @code{car} is the group name and
+the @code{cdr} is the article number that the article was entered as.
There should be no data returned.
@item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
This function should rename @var{group} into @var{new-name}. All
-articles that are in @var{group} should move to @var{new-name}.
+articles in @var{group} should move to @var{new-name}.
There should be no data returned.
error conditions---they should not raise errors when they aren't able to
perform a request. The first argument to this function is the backend
symbol, and the rest are interpreted as arguments to @code{format} if
-there are many of them, or just a string if there is one of them.
-This function always returns @code{nil}.
+there are multiple of them, or just a string if there is one of them.
+This function must always returns @code{nil}.
@lisp
(nnheader-report 'nnchoke "You did something totally bogus")
recently reported message for the backend in question. This function
takes one argument---the server symbol.
-Internally, these function access @var{backend}@code{-status-string}, so
-the @code{nnchoke} backend will have its error message stored in
-@code{nnchoke-status-string}.
+Internally, these functions access @var{backend}@code{-status-string},
+so the @code{nnchoke} backend will have its error message stored in
+@code{nnchoke-status-string}.
@node Writing New Backends
To inherit functions from other backends (and allow other backends to
inherit functions from the current backend), you should use the
following macros:
-following.
@table @code
nnml nnmh)
@end lisp
-@code{nndir} has here declared that it intends to inherit functions from
+@code{nndir} has declared here that it intends to inherit functions from
both @code{nnml} and @code{nnmh}.
@item defvoo
@item post-mail
This backend supports both mail and news.
@item none
-This is neither a post or mail backend---it's something completely
+This is neither a post nor mail backend---it's something completely
different.
@item respool
It supports respooling---or rather, it is able to modify its source
(nnmail-get-new-mail 'nnml 'nnml-save-nov nnml-directory group))
@end lisp
-It simply just calls @code{nnmail-get-new-mail} will a few parameters,
+It simply calls @code{nnmail-get-new-mail} with a few parameters,
and @code{nnmail} takes care of all the moving and splitting of the
mail.
one looong line, then that's ok.
The meaning of the various atoms are explained elsewhere in this
-manual.
+manual (@pxref{Score File Format}).
@node Headers
@subsection Headers
-Gnus uses internally a format for storing article headers that
+Internally Gnus uses a format for storing article headers that
corresponds to the @sc{nov} format in a mysterious fashion. One could
almost suspect that the author looked at the @sc{nov} specification and
just shamelessly @emph{stole} the entire thing, and one would be right.
@end example
is a perfectly valid range, although a pretty long-winded one. This is
-also legal:
+also valid:
@example
(1 . 5)
does this @code{defalias} thing with Gnus equivalents instead. Cleaner
all over.
-In the cases when the XEmacs function interface was obviously
-cleaner, I used it instead. For example @code{gnus-region-active-p}
-is an alias for @code{region-active-p} in XEmacs, whereas in Emacs
-it is a function.
+In the cases where the XEmacs function interface was obviously cleaner,
+I used it instead. For example @code{gnus-region-active-p} is an alias
+for @code{region-active-p} in XEmacs, whereas in Emacs it is a function.
Of course, I could have chosen XEmacs as my native platform and done
mapping functions the other way around. But I didn't. The performance
@node Active File Format
@subsubsection Active File Format
-The active file lists all groups that are available on the server in
+The active file lists all groups available on the server in
question. It also lists the highest and lowest current article numbers
in each group.
``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you
may have heard from other disreputable sources (like the Emacs author).
-The shift key is normally located near your pinky fingers, and are
+The shift keys are normally located near your pinky fingers, and are
normally used to get capital letters and stuff. You probably use it all
the time. The control key is normally marked ``CTRL'' or something like
that. The meta key is, funnily enough, never marked as such on any
-keyboards. The one I'm currently at has a key that's marked ``Alt'',
+keyboard. The one I'm currently at has a key that's marked ``Alt'',
which is the meta key on this keyboard. It's usually located somewhere
to the left hand side of the keyboard, usually on the bottom row.
-Now, us Emacs people doesn't say ``press the meta-control-m key'',
+Now, us Emacs people don't say ``press the meta-control-m key'',
because that's just too inconvenient. We say ``press the @kbd{M-C-m}
key''. @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the
prefix that means ``control''. So ``press @kbd{C-k}'' means ``press
and @code{eval}ed (which is lisp-ese for ``run'') the next time you
start Emacs. If you want to change the variable right away, simply say
@kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
-previous ``form'', which here is a simple @code{setq} statement.
+previous ``form'', which is a simple @code{setq} statement here.
Go ahead---just try it, if you're located at your Emacs. After you
@kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
projects / gnus / blobdiff