@top The Gnus Newsreader
You can read news (and mail) from within Emacs by using Gnus. The news
-can be gotten by any nefarious means you can think of - @sc{nntp}, local
+can be gotten by any nefarious means you can think of---@sc{nntp}, local
spool or your mbox file. All at the same time, if you want to push your
luck.
* Customization:: Tailoring Gnus to your needs.
* Troubleshooting:: What you might try if things do not work.
* The End:: Farewell and goodbye.
-* Appendix:: Technical stuff for technical people.
+* Appendices:: Technical stuff, Emacs intro, FAQ
* Index:: Variable, function and concept index.
* Key Index:: Key Index.
@end menu
In any case, after spending all that energy with coming up with a new
and spiffy name, we decided that the name was @emph{too} spiffy, so we
renamamed it back again to "Gnus". But in mixed case. "Gnus" vs.
-@sc{gnus}. New vs. old.
+"@sc{gnus}". New vs. old.
Incidentally, the next Gnus generation will be called "September Gnus",
and won't be released until February. Confused? You will be.
Gnus offer no real solutions to these questions, but I would very much
like to see Gnus being used as a testing ground for new methods of
-reading and fetching news. Expanding on Umeda-san's wise decision to
+reading and fetching news. Expanding on Umeda-san's wise decision 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 can imagine useful. By doing so, I'm inviting every one of
+and news from different sources. I have added hooks for customizations
+everywhere I can imagine useful. By doing so, I'm inviting every one of
you to explore and invent new ways of reading news.
May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
@section Conformity
No rebels without a clue here, ma'am. We conform to all standards known
-to man. Except, of course, where we disagree with the standards and/or
-conventions.
+to (wo)man. Except for those standards and/or conventions we disagree
+with, of course.
@table @strong
@item RFC 822
-There are no known breaches to this standard.
+There are no known breaches of this standard.
@item RFC 1036
-There are no known breaches to this standard, either.
+There are no known breaches of this standard, either.
@item Usenet Seal of Approval
Gnus hasn't been formally through the Seal process, but I have read
-through the Seal text, and I think that Gnus would pass.
+through the Seal text and I think Gnus would pass.
@item Son-of-RFC 1036
We do have some breaches to this one.
those for posting articles. I would not have known that if it wasn't
for the @code{X-Newsreader} header.
@item References
-Gnus does line breaking on this header. I infer from RFC1036 that being
-conservative in what you output is not creating 5000-character lines, so
-it seems like a good idea to me. However, this standard-to-be says that
-whitespace in the @code{References} header is to be preserved, so... It
-doesn't matter one way or the other to Gnus, so if somebody tells me
-what The Way is, I'll change it. Or not.
+Gnus breaks lines if this header is long. I infer from RFC1036 that
+being conservative in what you output is not creating 5000-character
+lines, so it seems like a good idea to me. However, this standard-to-be
+says that whitespace in the @code{References} header is to be preserved,
+so... It doesn't matter one way or the other to Gnus, so if somebody
+tells me what The Way is, I'll change it. Or not.
@end table
@end table
XEmacs.
@item
-The same with current-article marking -- XEmacs puts an underline under
-the entire article while Emacs and Mule are nicer and kinder.
+The same with current-article marking---XEmacs puts an underline under
+the entire summary line while Emacs and Mule are nicer and kinder.
@item
-XEmacs features more graphics -- a logo and a toolbar.
+XEmacs features more graphics---a logo and a toolbar.
@item
Citation highlighting us better under Emacs and Mule than under XEmacs.
endurance, what with my "oh, that's a neat idea <type type>, yup, I'll
release it right away <ship off> no wait, that doesn't work at all <type
type>, yup, I'll ship that one off right away <ship off> no, wait, that
-absolutely does not work" policy for releases. Microsoft - bah. I'm
-@emph{much} worse.
+absolutely does not work" policy for releases. Micro$oft---bah.
+Amateurs. I'm @emph{much} worse. (Or is that "worser"? "much worser"?
+"worsest"?)
I would like to take this opportunity to thank the Academy for... oops,
wrong show.
Of course, GNUS was written by Masanobu UMEDA.
@item
Many excellent functions, especially dealing with scoring and
-highlighting (as well as the soon-to-come @sc{soup} support) was written
+highlighting (as well as the @sc{soup} support) was written
by Per Abrahamsen.
@item
Innumerable bug fixes were written by Sudish Joseph.
@item
I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
@item
-nnfolder has been much enhanced by Scott Byer.
+@code{nnfolder} has been much enhanced by Scott Byer.
@item
The orphan scoring was written by Peter Mutsaers.
@item
GNU XEmacs support has been added by Fabrice Popineau.
@item
-Various bits and pieces, especially dealing with .newsrc files, was
+POP mail support was written by Ken Raeburn.
+@item
+Various bits and pieces, especially dealing with .newsrc files, were
suggested and added by Hallvard B Furuseth.
@item
-Brian Edmonds has written @code{gnus-bbdb}, as well as other bits and
-pieces.
+Brian Edmonds has written @code{gnus-bbdb}.
@item
Ricardo Nassif did the proof-reading.
@item
Kevin Davidson came up with the name @dfn{ding}, so blame him.
@item
-Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel Quinlan, Frank
-D. Cringle, Geoffrey T. Dairiki and Andrew Eskilsson have all
-contributed code and suggestions.
+Peter Arius, Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel
+Quinlan, Frank D. Cringle, Geoffrey T. Dairiki and Andrew Eskilsson have
+all contributed code and suggestions.
@end itemize
@item
You can read a number of different mail formats (@pxref{Reading Mail}).
All the mail backends implement a convenient mail expiry scheme
-(@code{Expiring Old Mail Articles}).
+(@pxref{Expiring Old Mail Articles}).
@item
Gnus can use various strategies for gathering threads that have lost
-their roots (thereby gathering loose sub-threads in one thread) or it
+their roots (thereby gathering loose sub-threads into one thread) or it
can go back and retrieve enough headers to build a complete thread
(@pxref{Customizing Threading}).
them as well.
@item
-Gnus can do partial group updates - you do not have to retrieve the
+Gnus can do partial group updates---you do not have to retrieve the
entire active file just to check for new articles in a few groups
(@pxref{The Active File}).
@item
You can score articles according to any number of criteria
-(@pxref{Scoring}). You can even get Gnus to score articles for you
-(@pxref{Adaptive Scoring}).
+(@pxref{Scoring}). You can even get Gnus to find out how to score
+articles for you (@pxref{Adaptive Scoring}).
@item
Gnus maintains a dribble buffer that is auto-saved the normal Emacs
glitches (@pxref{Finding the Parent}).
@item
-Gnus can fetch FAQs to and descriptions of groups (@pxref{Group
-Information}).
+Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
@item
Digests (and other files) can be used as the basis for groups
Articles can be highlighted and customized (@pxref{Customizing
Articles}).
+@item
+URLs and other external references can be buttonized (@pxref{Article
+Buttons}).
+
@item
All Gnus buffers can be customized in a difficult fashion
(@pxref{Windows Configuration}).
@itemize @bullet
@item
-Native @sc{mime} support is something that should be done. I was hoping
-I could steal code from @code{Mew}, the @sc{mime} mail reader for Emacs,
-but I'm not quite sure what the status of that project is. Gnus might
-support @sc{mime} quite soon, and it might not.
-
+Native @sc{mime} support is something that should be done.
@item
@code{trn}-like trees.
@item
NoCeM support.
@item
Frame configuration.
-@item
-Re-sending bounced mail and rejected articles.
@item
Floating point group levels and group bubbling.
-@item
-@file{/etc/nntpserver} usage.
@item
Automatic re-scan of incoming mail.
@item
@item
Gather thread by filling in missing Message-IDs.
@item
-Slave Gnusii to enable several Gnusii to run at once.
-@item
PGP support.
@item
Allow posting through mail-to-news gateways.
@item
-Allow renaming mail groups in a simple fashion.
-@item
Speed up massive group massacres.
@item
@code{jka-compr} isn't fully supported.
@item
Really do unbinhexing.
@item
-Fetching by Message-ID should work in mail groups.
-@item
Listing of all active groups.
@item
XEmacs toolbar.
@item
Do the X-Receipt-To thing.
@item
-Hierarchal group buffers.
-@item
Don't kill summary buffers upon exit from the groups.
@item
Allow adaption on secondary marks.
And much, much, much more. There is more to come than has already been
implemented. (But that's always true, isn't it?)
-You can probably sneak a look at the actual up-to-the-second todo list
-by snooping @code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>}.
+@code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>} is where the actual
+up-to-the-second todo list is located, so if you're really curious, you
+could point your Web browser over that-a-way.
@node Terminology
@chapter Terminology
@table @dfn
@item news
@cindex news
-This is what you are supposed to use this thing for - reading news.
+This is what you are supposed to use this thing for---reading news.
News is generally fetched from a nearby @sc{nntp} server, and is
generally publicly available to everybody. If you post news, the entire
world is likely to read just what you have written, and they'll all
are reading.
@item backend
Gnus gets fed articles from a number of backends, both news and mail
-backends. Gnus does not handle the underlying media, so to speak - this
+backends. Gnus does not handle the underlying media, so to speak---this
is all done by the backends.
@item native
Gnus will always use one method (and backend) as the @dfn{native}, or
put.
@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 that is not in the head is in the
body.
@item header
@cindex header
@kindex M-x gnus
If your system administrator has set things up properly, starting Gnus
-and reading news is extremely easy - you just type @kbd{M-x gnus}.
+and reading news is extremely easy---you just type @kbd{M-x gnus}.
If things do not go smoothly at startup, you have to twiddle some
variables.
* Slave Gnusii:: You can have more than one Gnus active at a time.
* Fetching a Group:: Starting Gnus just to read a group.
* New Groups:: What is Gnus supposed to do with new groups?
-* Startup Files:: Those pesky startup files - @file{.newsrc}.
+* Startup Files:: Those pesky startup files---@file{.newsrc}.
* Auto Save:: Recovering from a crash.
* The Active File:: Reading the active file over a slow line Takes Time.
* Startup Variables:: Other variables you might change.
@vindex gnus-nntpserver-file
@cindex NNTPSERVER
-@cindex nntp server
+@cindex @sc{nntp} server
If this variable is not set, Gnus will take a look at the
@code{NNTPSERVER} environment variable. If that variable isn't set,
Gnus will see whether @code{gnus-nntpserver-file} (default
given the wrong address) or the server has just momentarily taken ill
for some reason or other.
-If Gnus says "nntp server on <your server> can't be opened. Continue?",
+If Gnus says "nntp server on <your server> can't be opened. Continue?",
you do not want to continue unless you have some foreign groups that you
want to read. Even if you don't, Gnus will let you continue, but you'll
find it difficult to actually do anything in the group buffer. But,
@node Slave Gnusii
-@section Slave Gnusii
+@section Slave Gnusiï
@cindex slave
You might want to run more than one Emacs with more than one Gnus at the
same time. If you are using different @file{.newsrc} files (eg., if you
-are using the two different Gnusii to read from two different servers),
+are using the two different Gnusiï to read from two different servers),
that is no problem whatsoever. You just do it.
-The problem appears when you want to run two Gnusii that uses the same
-@code{.newsrc} file.
+The problem appears when you want to run two Gnusiï that use the same
+@code{.newsrc} file.
To work around that problem some, we here at the Think-Tank at the Gnus
-Towers have come up with a new concept: @dfn{Master} and @dfn{servants}.
-(We have applied for a patent on this concept, and have taken out a
-copyright on those words. If you wish to use those words in conjunction
-with each other, you have to send ¢1 per usage to me. Usage of the
-patent (@dfn{Master/Slave Relationships In Computer Applications}) will
-be much more expensive, of course.)
+Towers have come up with a new concept: @dfn{Masters} and
+@dfn{servants}. (We have applied for a patent on this concept, and have
+taken out a copyright on those words. If you wish to use those words in
+conjunction with each other, you have to send $1 per usage instance to
+me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
+Applications}) will be much more expensive, of course.)
Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
-however you do it). Each subsequent slave Gnusii should be started with
+however you do it). Each subsequent slave Gnusiï should be started with
@kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
-files, but some slave files that contains only information on what
+files, but some slave files that contains information only on what
groups have been read in the slave session. When a master Gnus starts,
it will read (and delete) these slave files, incorporating all
information from all of them. (The slave files will be read in the
-sequence they were created, so the latest changes will have presedence.)
+sequence they were created, so the latest changes will have precedence.)
Information from the slave files has, of course, presedence over the
information in the normal (i. e., master) @code{.newsrc} file.
@vindex gnus-subscribe-interactively
Subscribe new groups interactively. This means that Gnus will ask
you about @strong{all} new groups.
+
@item gnus-subscribe-zombies
@vindex gnus-subscribe-zombies
-Make all new groups zombies. You can browse the zombies later and
-either kill them all off properly, or subscribe to them. This is the
-default.
+Make all new groups zombies. You can browse the zombies later (with
+@kbd{A z}) and either kill them all off properly, or subscribe to them.
+This is the default.
@end table
@vindex gnus-subscribe-hierarchical-interactive
you could set @code{gnus-check-new-newsgroups} to @code{nil}. This will
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}).
+@kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
+is @code{t} by default.
Gnus normally determines whether a group is new or not by comparing the
list of groups from the active file(s) with the lists of subscribed and
files, while @code{gnus-save-quick-newsrc-hook} is called just before
saving the @file{.newsrc.eld} file, and
@code{gnus-save-standard-newsrc-hook} is called just before saving the
-@file{.newsrc} file. The latter two are commonly used to tern version
-control on or off.
+@file{.newsrc} file. The latter two are commonly used to turn version
+control on or off. Version control is off by default when saving.
@node Auto Save
@section Auto Save
this file.
If Gnus detects this file at startup, it will ask the user whether to
-read it. The auto save file is deleted whenever the real startup file is
+read it. The auto save file is deleted whenever the real startup file is
saved.
@vindex gnus-use-dribble-file
If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
-maintain a dribble buffer.
+maintain a dribble buffer. The default is @code{t}.
@vindex gnus-dribble-directory
Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
@vindex gnus-read-active-file
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.
+reading the active file. This variable is @code{t} by default.
Gnus will try to make do by just getting information 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
-normally be run just once in a single Emacs session, no matter how many
+normally be run just once in each Emacs session, no matter how many
times you start Gnus.
@item gnus-startup-hook
* Group Buffer Format:: Information listed and how you can change it.
* Group Maneuvering:: Commands for moving in the group buffer.
* Selecting a Group:: Actually reading news.
-* Group Subscribing:: Unsubscribing, killing, subscribing.
+* Subscription Commands:: Unsubscribing, killing, subscribing.
* Group Levels:: Levels? What are those, then?
+* Group Score:: A mechanism for finding out what groups you like.
* Marking Groups:: You can mark groups for later processing.
* Foreign Groups:: How to create foreign groups.
* Group Parameters:: Each group may have different parameters set.
* Listing Groups:: Gnus can list various subsets of the groups.
+* Sorting Groups:: Re-arrange the group order.
* Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
* Browse Foreign Server:: You can browse a server. See what if has to offer.
* Exiting Gnus:: Stop reading news and get some work done.
@code{gnus-group-line-format} variable. This variable works along the
lines of a @code{format} specification, which is pretty much the same as
a @code{printf} specifications, for those of you who use (feh!) C.
-
-In addition to the normal "padding" specs that @code{format} supports
-(eg. @samp{%7d}), specifications like @samp{%7,12s} are allowed. A spec
-of this type means that the field will be at least 7 characters long,
-and never more that 12 characters long.
+@xref{Formatting Variables}.
The default value that produced those lines above is
@samp{"%M%S%5y: %(%g%)\n"}.
There should always be a colon on the line; the cursor always moves to
-the colon after performing an operation. Nothing else is required - not
+the colon after performing an operation. Nothing else is required---not
even the group name. All displayed text is just window dressing, and is
never examined by Gnus. Gnus stores all real information it needs using
text properties.
@cindex *
All the "number-of" specs will be filled with an asterisk (@samp{*}) if
-no info is available - for instance, if it is a non-activated foreign
+no info is available---for instance, if it is a non-activated foreign
group, or a bogus (or semi-bogus) native group.
@vindex gnus-group-mode-line-format
@vindex gnus-group-goto-unread
If @code{gnus-group-goto-unread} is @code{nil}, all the movement
commands will move to the next group, not the next unread group. Even
-the commands that say they move to the next unread group.
+the commands that say they move to the next unread group. The default
+is @code{t}.
@node Selecting a Group
@section Selecting a Group
@findex gnus-group-select-group
Select the current group and switch to the summary buffer
(@code{gnus-group-select-group}). Takes the same arguments as
-@code{gnus-group-read-group} - the only difference is that this command
+@code{gnus-group-read-group}---the only difference is that this command
does not display the first unread article automatically upon group
entry.
@vindex gnus-large-newsgroup
The @code{gnus-large-newsgroup} variable says what Gnus should consider
-to be a big group. If the group has more unread articles than this,
-Gnus will query the user before entering the group. The user can then
-specify how many articles should be fetched from the server. If the
-user specifies a negative number (@samp{-n}), the @samp{n} oldest
-articles will be fetched. If it is positive, the @samp{n} articles that
-have arrived most recently will be fetched.
+to be a big group. This is 200 by default. If the group has more
+unread articles than this, Gnus will query the user before entering the
+group. The user can then specify how many articles should be fetched
+from the server. If the user specifies a negative number (@samp{-n}),
+the @samp{n} oldest articles will be fetched. If it is positive, the
+@samp{n} articles that have arrived most recently will be fetched.
@vindex gnus-select-group-hook
@vindex gnus-auto-select-first
-If @code{gnus-auto-select-first} is non-@code{nil}, the first unread
-article in the group will be displayed when you enter the group. If you
-want to prevent automatic selection in some group (say, in a binary
-group with Huge articles) you can set this variable to @code{nil} in
-@code{gnus-select-group-hook}, which is called when a group is selected.
+@code{gnus-auto-select-first} control whether any articles are selected
+automatically when entering a group.
+
+@table @code
+@item nil
+Don't select any articles when entering the group. Just display the
+full summary buffer.
+
+@item t
+Select the first unread article when entering the group.
+
+@item best
+Select the most high-scored article in the group when entering the
+group.
+@end table
+
+If you want to prevent automatic selection in some group (say, in a
+binary group with Huge articles) you can set this variable to @code{nil}
+in @code{gnus-select-group-hook}, which is called when a group is
+selected.
@findex gnus-thread-sort-by-total-score
@findex gnus-thread-sort-by-date
functions might be @code{max}, @code{min}, or squared means, or whatever
tickles you fancy.
-@node Group Subscribing
-@section Group Subscribing
+
+@node Subscription Commands
+@section Subscription Commands
@cindex subscribing
@table @kbd
Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
@end table
+Also @xref{Group Levels}.
+
@node Group Levels
@section Group Levels
@cindex group level
@vindex gnus-level-unsubscribed
@vindex gnus-level-subscribed
Gnus considers groups on between levels 1 and
-@code{gnus-level-subscribed} (inclusive) to be subscribed,
+@code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed,
@code{gnus-level-subscribed} (exclusive) and
-@code{gnus-level-unsubscribed} (inclusive) to be unsubscribed,
-@code{gnus-level-zombie} to be zombies (walking dead) and
-@code{gnus-level-killed} to be killed, completely dead. Gnus treats
-subscribed and unsubscribed groups exactly the same, but zombie and
-killed groups have no information on what articles you have read, etc,
-stored. This distinction between dead and living groups isn't done
-because it is nice or clever, it is done purely for reasons of
-efficiency.
+@code{gnus-level-unsubscribed} (inclusive) (default 7) to be
+unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
+(default 8) and @code{gnus-level-killed} to be killed (default 9),
+completely dead. Gnus treats subscribed and unsubscribed groups exactly
+the same, but zombie and killed groups have no information on what
+articles you have read, etc, stored. This distinction between dead and
+living groups isn't done because it is nice or clever, it is done purely
+for reasons of efficiency.
It is recommended that you keep all your mail groups (if any) on quite
low levels (eg. 1 or 2).
@vindex gnus-level-default-unsubscribed
@vindex gnus-level-default-subscribed
Two closely related variables are @code{gnus-level-default-subscribed}
-and @code{gnus-level-default-unsubscribed}, 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.
+(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.
@vindex gnus-keep-same-level
If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
use this level as the "work" level.
+
+@node Group Score
+@section Group Score
+@cindex group score
+
+You would normally keep important groups on high levels, but that scheme
+is somewhat restrictive. Don't you wish you could have Gnus sort the
+group buffer according to how often you read groups, perhaps? Within
+reason?
+
+This is what @dfn{group score} is for. You can assign a score to each
+group. You can then sort the group buffer based on this score.
+Alternatively, you can sort on score and then level. (Taken together,
+the level and the score is called the @dfn{rank} of the group. A group
+that is on level 4 and has a score of 1 has a higher rank than a group
+on level 5 that has a score of 300. (The level is the most significant
+part and the score is the least significant part.)
+
+@findex gnus-summary-bubble-group
+If you want groups you read often to get higher scores than groups you
+read seldom you can add the @code{gnus-summary-bubble-group} function to
+the @code{gnus-summary-exit-hook} hook. This will result (after
+sorting) in a bubbling sort of action. If you want to see that in
+action after each summary exit, you can add
+@code{gnus-group-sort-groups-by-rank} or
+@code{gnus-group-sort-groups-by-score} to the same hook, but that will
+slow things down somewhat.
+
+
@node Marking Groups
@section Marking Groups
@cindex marking groups
-If you want to perform some action on several groups, and they appear
+If you want to perform some command on several groups, and they appear
subsequently in the group buffer, you would normally just give a
numerical prefix to the command. Most group commands will then do your
bidding on those groups.
However, if the groups are not in sequential order, you can still
-perform an action on several groups. You simply mark the groups first,
-and then execute the command.
+perform a command on several groups. You simply mark the groups first
+with the process mark and then execute the command.
@table @kbd
+
@item #
@kindex # (Group)
-@item M m
+@itemx M m
@kindex M m (Group)
@findex gnus-group-mark-group
Set the mark on the current group (@code{gnus-group-mark-group}).
+
@item M-#
@kindex M-# (Group)
-@item < u
+@itemx < u
@kindex M u (Group)
@findex gnus-group-unmark-group
Remove the mark from the current group
(@code{gnus-group-unmark-group}).
+
@item M w
@kindex M w (Group)
@findex gnus-group-mark-region
Mark all groups between point and mark (@code{gnus-group-mark-region}).
+
+@item M r
+@kindex M r (Group)
+@findex gnus-group-mark-regexp
+Mark all groups that match some regular expression
+(@code{gnus-group-mark-regexp}).
@end table
+Also @xref{Process/Prefix}.
+
+
@node Foreign Groups
@section Foreign Groups
@cindex foreign groups
name}. There may be additional elements in the select method, where the
value may have special meaning for the backend in question.
-One could say that a select method defines a @dfn{virtual server} - so
+One could say that a select method defines a @dfn{virtual server}---so
we do just that (@pxref{The Server Buffer}).
The @dfn{name} of the group is the name the backend will recognize the
@samp{some.where.edu} will have the name @samp{soc.motss} and select
method @code{(nntp "some.where.edu")}. Gnus will call this group, in
all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
-nntp backend just knows this group as @samp{soc.motss}.
+@code{nntp} backend just knows this group as @samp{soc.motss}.
Here are some commands for making and editing general foreign groups,
and some commands to ease the creation of some special-purpose groups:
@kindex G f (Group)
@findex gnus-group-make-doc-group
Make a group based on some file or other
-(@code{gnus-group-make-doc-group}). You will be prompted for a file
-name and a file type. Currently supported types are @code{babyl},
-@code{mbox} and @code{digest}.
+(@code{gnus-group-make-doc-group}). If you give a prefix to this
+command, you will be prompted for a file name and a file type.
+Currently supported types are @code{babyl}, @code{mbox}, @code{digest},
+@code{mmfd}, and @code{forward}. If you run this command without a
+prefix, Gnus will guess at the file type.
@item G DEL
@kindex G DEL (Group)
@findex gnus-group-delete-group
This function will delete the current group
(@code{gnus-group-delete-group}). If given a prefix, this function will
-actuallt delete all the articles in the group, and forcibly remove the
+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
sure of what you are doing.
* nnvirtual:: Combining articles from many groups.
* nnkiboze:: Looking through parts of the newsfeed for articles.
* nndir:: You can read a directory as if it was a newsgroup.
-* nneething:: Dired? Who needs dired?
+* nneething:: Dired? Who needs dired?
* nndoc:: Single files can be the basis of a group.
+* SOUP:: Reading @sc{SOUP} packets "offline".
* Reading Mail:: Reading your personal mail with Gnus.
@end menu
If the @code{gnus-activate-foreign-newsgroups} is a positive number,
Gnus will check all foreign groups with this level or lower at startup.
This might take quite a while, especially if you subscribe to lots of
-groups from different @sc{nntp} servers. It is @code{nil} by default,
-which means that you won't be told whether there are new articles in
-these groups. How many unread articles there are will be determined
-when, or if, you decide to enter them. You can also activate any group
-with @kbd{M-g} to see how many unread articles there are.
+groups from different @sc{nntp} servers.
@node nntp
@subsection nntp
@node nnspool
@subsection nnspool
-@cindex nnspool
+@cindex @code{nnspool}
@cindex news spool
Subscribing to a foreign group from the local spool is extremely easy,
anything else) as the address.
If you have access to a local spool, you should probably use that as the
-native select method (@pxref{Finding the News}).
+native select method (@pxref{Finding the News}). It is normally faster
+than using an @code{nntp} select method, but might not be. It depends.
+You just have to try to find out what's best at your site.
@table @code
@item nnspool-inews-program
@item nnspool-spool-directory
@vindex nnspool-spool-directory
-Where nnspool looks for the articles. This is normally
+Where @code{nnspool} looks for the articles. This is normally
@file{/usr/spool/news/}.
@item nnspool-nov-directory
@vindex nnspool-nov-directory
-Where nnspool will look for @sc{nov} files. This is normally
+Where @code{nnspool} will look for @sc{nov} files. This is normally
@file{/usr/spool/news/over.view/}.
@item nnspool-lib-dir
@item nnspool-newsgroups-file
@vindex nnspool-newsgroups-file
-The path of the group description file.
+The path of the group descriptions file.
@item nnspool-history-file
@vindex nnspool-history-file
@node nnvirtual
@subsection nnvirtual
-@cindex nnvirtual
+@cindex @code{nnvirtual}
@cindex virtual groups
An @dfn{nnvirtual group} is really nothing more than a collection of
All marks in the virtual group will stick to the articles in the
component groups. So if you tick an article in a virtual group, the
article will also be ticked in the component group from whence it came.
-(And vice versa - marks from the component groups will also be shown in
+(And vice versa---marks from the component groups will also be shown in
the virtual group.)
-Here's an example nnvirtual method that collects all Andrea Dworkin
+Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
newsgroups into one, big, happy newsgroup:
@lisp
"^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
@end example
-This should work kinda smoothly - all articles from both groups should
+This should work kinda smoothly---all articles from both groups should
end up in this one, and there should be no duplicates. Threading (and
the rest) will still work as usual, but there might be problems with the
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 that are included in a virtual
group has to be alive (i.e., subscribed or unsubscribed). Killed or
-zombie groups can't be component groups for nnvirtual groups.
+zombie groups can't be component groups for @code{nnvirtual} groups.
+
@node nnkiboze
@subsection nnkiboze
-@cindex nnkiboze
+@cindex @code{nnkiboze}
@cindex kibozing
-@dfn{Kibozing} is defined by OED as "grepping through (parts of) the
-news feed". nnkiboze is a backend that will do this for you. Oh joy!
-Now you can grind any @sc{nntp} server down to a halt with useless
+@dfn{Kibozing} is defined by @sc{oed} as "grepping through (parts of)
+the news feed". @code{nnkiboze} is a backend that will do this for you. Oh
+joy! Now you can grind any @sc{nntp} server down to a halt with useless
requests! Oh happiness!
-The address field of the nnkiboze method is, as with nnvirtual, a regexp
-to match groups to be "included" in the nnkiboze group. There most
-similarities between nnkiboze and nnvirtual ends.
+The address field of the @code{nnkiboze} method is, as with
+@code{nnvirtual}, a regexp to match groups to be "included" in the
+@code{nnkiboze} group. There most similarities between @code{nnkiboze}
+and @code{nnvirtual} ends.
-In addition to this regexp detailing component groups, an nnkiboze group
+In addition to this regexp detailing component groups, an @code{nnkiboze} group
must have a score file to say what articles that are to be included in
the group (@pxref{Scoring}).
@kindex M-x nnkiboze-generate-groups
@findex nnkiboze-generate-groups
You must run @kbd{M-x nnkiboze-generate-groups} after creating the
-nnkiboze groups you want to have. This command will take time. Lots of
+@code{nnkiboze} groups you want to have. This command will take time. Lots of
time. Oodles and oodles of time. Gnus has to fetch the headers from
all the articles in all the components groups and run them through the
scoring process to determine if there are any articles in the groups
-that are to be part of the nnkiboze groups.
+that are to be part of the @code{nnkiboze} groups.
Please limit the number of component groups by using restrictive
regexps. Otherwise your sysadmin may become annoyed with you, and the
@sc{nntp} site may throw you off and never let you back in again.
Stranger things have happened.
-nnkiboze component groups do not have to be alive - they can be dead,
+@code{nnkiboze} component groups do not have to be alive---they can be dead,
and they can be foreign. No restrictions.
@vindex nnkiboze-directory
-The generation of an nnkiboze group means writing two files in
+The generation of an @code{nnkiboze} group means writing two files in
@code{nnkiboze-directory}, which is @file{~/News/} by default. One
contains the @sc{nov} header lines for all the articles in the group,
and the other is an additional @file{.newsrc} file to store information
on what groups that have been searched through to find component
articles.
-Articles that are marked as read in the nnkiboze group will have their
+Articles that are marked as read in the @code{nnkiboze} group will have their
@sc{nov} lines removed from the @sc{nov} file.
@node nndir
@subsection nndir
-@cindex nndir
+@cindex @code{nndir}
@cindex directory groups
If you have a directory that has lots of articles in separate files in
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.
+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 @file{"/ftp@@sina.tcamc.uh.edu:/pub/emacs/ding-list/"} as the the
@code{nndir} will use @sc{nov} files if they are present.
-@code{nndir} is a "read-only" backend - you can't delete or expire
+@code{nndir} is a "read-only" backend---you can't delete or expire
articles with this method. You can use @code{nnmh} or @code{nnml} for
whatever you use @code{nndir} for, so you could switch to any of those
methods if you feel the need to have a non-read-only @code{nndir}.
@node nneething
@subsection nneething
-@cindex nneething
+@cindex @code{nneething}
From the @code{nndir} backend (which reads a single spool-like
directory), it's just a hop and a skip to @code{nneething}, which
-pretends that any random directory is a newsgroup. Strange, but true.
+pretends that any random directory is a newsgroup. Strange, but true.
When @code{nneething} is presented with a directory, it will scan this
-directory and assign article numbers to each file. When you enter such a
-group, @code{nneething} must create "headers" that Gnus can use. After
+directory and assign article numbers to each file. When you enter such a
+group, @code{nneething} must create "headers" that Gnus can use. After
all, Gnus is a newsreader, in case you're forgetting. @code{nneething}
-does this in a two-step process. First, it snoops each file in question.
+does this in a two-step process. First, it snoops each file in question.
If the file looks like an article (i.e., the first few lines look like
-headers), it will use this as the head. If this is just some random file
+headers), it will use this as the head. If this is just some random file
without a head (eg. a C source file), @code{nneething} will cobble up a
-header out of thin air. It will use file ownership, name and date and do
+header out of thin air. It will use file ownership, name and date and do
whatever it can with these elements.
All this should happen automatically for you, and you will be presented
-with something that looks very much like a newsgroup. Totally like a
-newsgroup, to be precise. If you select an article, it will be displayed
+with something that looks very much like a newsgroup. Totally like a
+newsgroup, to be precise. If you select an article, it will be displayed
in the article buffer, just as usual.
If you select a line that represents a directory, Gnus will pop you into
-a new summary buffer for this @code{nneething} group. And so on. You can
+a new summary buffer for this @code{nneething} group. And so on. You can
traverse the entire disk this way, if you feel like, but remember that
Gnus is not dired, really, and does not intend to be, either.
-There are two overall modes to this action - ephemeral or solid. When
+There are two overall modes to this action---ephemeral or solid. When
doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
will not store information on what files you have read, and what files
-are new, and so on. If you create a solid @code{nneething} group the
+are new, and so on. If you create a solid @code{nneething} group the
normal way with @kbd{G m}, Gnus will store a mapping table between
article numbers and file names, and you can treat this group like any
-other groups. When you activate a solid @code{nneething} group, you will
+other groups. When you activate a solid @code{nneething} group, you will
be told how many unread articles it contains, etc., etc.
Some variables:
@item nneething-exclude-files
@vindex nneething-exclude-files
-All files that match this regexp will be ignored. Nice to use to exclude
+All files that match this regexp will be ignored. Nice to use to exclude
auto-save files and the like, which is what it does by default.
@item nneething-map-file
@node nndoc
@subsection nndoc
-@cindex nndoc
+@cindex @code{nndoc}
@cindex documentation group
@cindex help group
-nndoc is a cute little thing that will let you read a single file as a
-newsgroup. Currently supported file types are @code{babyl}, @code{mbox}
-and @code{digest}.
+@code{nndoc} is a cute little thing that will let you read a single file
+as a newsgroup. Currently supported file types are @code{babyl} (the
+RMAIL file type), @code{mbox} (standard Unix mbox files), @code{digest}
+(various digests, MIME and otherwise), @code{mmfd} (the MMFD mail box
+format), and @code{forward} (a single forwarded mail). You can also use
+the special "file type" @code{guess}, which means that @code{nndoc} will
+try to guess what file type it is looking at.
-nndoc will not try to change the file or insert any extra headers into
-it - it will simply, like, let you use the file as the basis for a
+@code{nndoc} will not try to change the file or insert any extra headers into
+it---it will simply, like, let you use the file as the basis for a
group. And that's it.
+If you have some old archived articles that you want to insert into your
+new & spiffy Gnus mail backend, @code{nndoc} can probably help you with
+that. Say you have an old @file{RMAIL} file with mail that you now want
+to split into your new @code{nnml} groups. You look at that file using
+@code{nndoc}, set the process mark on all the articles in the buffer
+(@kbd{M P b}, for instance), and then respool (@kbd{B r}) using
+@code{nnml}. If all goes well, all the mail in the @file{RMAIL} file is
+now also stored in lots of @code{nnml} directories, and you can delete
+that pesky @file{RMAIL} file. If you have the guts!
+
Virtual server variables:
@table @code
@item nndoc-article-type
@vindex nndoc-article-type
-This should be one of @code{mbox}, @code{babyl} or @code{digest}.
+This should be one of @code{mbox}, @code{babyl}, @code{digest},
+@code{mmfd}, @code{forward}, or @code{guess}.
+@end table
+
+
+@node SOUP
+@subsection @sc{soup}
+@cindex @sc{SOUP}
+@cindex offline
+
+In the PC world people often talk about "offline" newsreaders. These
+are thingies that are combined reader/news transport monstrosities.
+With built-in modem programs. Yecchh!
+
+Of course, us Unix Weenie types of human beans use things like
+@code{uucp} and, like, @code{nntpd} and set up proper news and mail
+transport things like Ghod inteded. And then we just use normal
+newsreaders.
+
+However, it can sometimes be convenient to do something a that's a bit
+easier on the brain if you have a very slow modem, and you're not really
+that interested in doing things properly.
+
+A file format called @sc{soup} has been developed for transporting news
+and mail from servers to home machines and back again. It can be a bit
+fiddly.
+
+@enumerate
+
+@item
+You log in on the server and create a @sc{soup} packet. You can either
+use a dedicated @sc{soup} thingie, or you can use Gnus to create the
+packet with the @kbd{O s} command.
+
+@item
+You transfer the packet home. Rail, boat, car or modem will do fine.
+
+@item
+You put the packet in your home directory.
+
+@item
+You fire up Gnus using the @code{nnsoup} backend as the native server.
+
+@item
+You read articles and mail and answer and followup to the things you
+want.
+
+@item
+You do the @kbd{G S r} command to pack these replies into a @sc{soup}
+packet.
+
+@item
+You transfer this packet to the server.
+
+@item
+You use Gnus to mail this packet out with the @kbd{G S s} command.
+
+@item
+You then repeat until you die.
+
+@end enumerate
+
+So you basically have a bipartite system---you use @code{nnsoup} for
+reading and Gnus for packing/sending these @sc{soup} packets.
+
+@menu
+* SOUP Commands:: Commands for creating and sending @sc{soup} packets
+* nnsoup:: A backend for reading @sc{soup} packets.
+* SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
+@end menu
+
+
+@node SOUP Commands
+@subsubsection @sc{soup} Commands
+
+@table @kbd
+@item G s b
+@kindex G s b (Group)
+@findex gnus-group-brew-soup
+Pack all unread articles in the current group
+(@code{gnus-group-brew-soup}). This command understands the
+process/prefix convention.
+
+@item G s w
+@kindex G s w (Group)
+@findex gnus-soup-save-areas
+Save all data files (@code{gnus-soup-save-areas}).
+
+@item G s s
+@kindex G s s (Group)
+@findex gnus-soup-send-replies
+Send all replies from the replies packet
+(@code{gnus-soup-send-replies}).
+
+@item G s p
+@kindex G s p (Group)
+@findex gnus-soup-pack-packet
+Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
+
+@item G s r
+@kindex G s r (Group)
+@findex nnsoup-pack-replies
+Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
+
+@item O s
+@kindex O s (Summary)
+@findex gnus-soup-add-article
+This summary-mode command adds the current article to a @sc{soup} packet
+(@code{gnus-soup-add-article}). It understands the process/prefix
+convention.
+
+@end table
+
+
+There are a few variables to customize where Gnus will put all these
+thingies:
+
+@table @code
+
+@item gnus-soup-directory
+@vindex gnus-soup-directory
+Directory where Gnus will save intermediate files while composing
+@sc{soup} packets. The default is @file{~/SoupBrew/}.
+
+@item gnus-soup-replies-directory
+@vindex gnus-soup-replies-directory
+This is what Gnus will use as a temporary directory while sending our
+reply packets. The default is @file{~/SoupBrew/SoupReplies/}.
+
+@item gnus-soup-prefix-file
+@vindex gnus-soup-prefix-file
+Name of the file where Gnus stores the last used prefix. The default is
+@samp{"gnus-prefix"}.
+
+@item gnus-soup-packer
+@vindex gnus-soup-packer
+A format string command for packing a @sc{soup} packet. The default is
+@samp{ "tar cf - %s | gzip > $HOME/Soupout%d.tgz"}.
+
+@item gnus-soup-unpacker
+@vindex gnus-soup-unpacker
+Format string command for unpacking a @sc{soup} packet. The default is
+@samp{"gunzip -c %s | tar xvf -"}.
+
+@item gnus-soup-packet-directory
+@vindex gnus-soup-packet-directory
+Wehre Gnus will look for reply packets. The default is @file{~/}.
+
+@item gnus-soup-packet-regexp
+@vindex gnus-soup-packet-regexp
+Regular expression matching @sc{soup} reply packets in
+@code{gnus-soup-packet-directory}.
+
@end table
+
+
+@node nnsoup
+@subsubsection nnsoup
+@cindex @code{nnsoup}
+
+@code{nnsoup} is the backend for reading @sc{soup} packets. It will
+read incoming packets, unpack them, and put them in a directory where
+you can read them at leisure.
+
+These are the variables you can use to customize its behavior:
+
+@table @code
+
+@item nnsoup-directory
+@vindex nnsoup-directory
+@code{nnsoup} will move all incoming @sc{soup} packets to this directory
+and unpack them there. The default is @file{~/SOUP/}.
+
+@item nnsoup-replies-directory
+@vindex nnsoup-replies-directory
+All replies will stored in this directory before being packed into a
+reply packet. The default is @file{~/SOUP/replies/"}.
+
+@item nnsoup-replies-format-type
+@vindex nnsoup-replies-format-type
+The @sc{soup} format of the replies packets. The default is @samp{?n}
+(rnews), and I don't think you should touch that variable. I probaly
+shouldn't even have documented it. Drats! Too late!
+
+@item nnsoup-replies-index-type
+@vindex nnsoup-replies-index-type
+The index type of the replies packet. The is @samp{?n}, which means
+"none". Don't fiddle with this one either!
+
+@item nnsoup-active-file
+@vindex nnsoup-active-file
+Where @code{nnsoup} stores lots of information. This is not an "active
+file" in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
+this file or mess it up in any way, you're dead. The default is
+@file{~/SOUP/active}.
+
+@item nnsoup-packer
+@vindex nnsoup-packer
+Format string command for packing a reply @sc{soup} packet. The default
+is @samp{"tar cf - %s | gzip > $HOME/Soupin%d.tgz"}.
+
+@item nnsoup-unpacker
+@vindex nnsoup-unpacker
+Format string command for unpacking incoming @sc{soup} packets. The
+default is @samp{"gunzip -c %s | tar xvf -"}.
+
+@item nnsoup-packet-directory
+@vindex nnsoup-packet-directory
+Where @code{nnsoup} will look for incoming packets. The default is
+@file{~/}.
+
+@item nnsoup-packet-regexp
+@vindex nnsoup-packet-regexp
+Regular expression matching incoming @sc{soup} packets. The default is
+@samp{Soupout}.
+
+@end table
+
+
+@node SOUP Replies
+@subsubsection SOUP Replies
+
+Just using @code{nnsoup} won't mean that your postings and mailings end
+up in @sc{soup} reply packets automagically. You have to work a bit
+more for that to happen.
+
+@findex nnsoup-set-variables
+The @code{nnsoup-set-variables} command will set the appropriate
+variables to ensure that all your followups and replies end up in the
+@sc{soup} system.
+
+In specific, this is what it does:
+
+@lisp
+(setq gnus-inews-article-function 'nnsoup-request-post)
+(setq send-mail-function 'nnsoup-request-mail)
+@end lisp
+
+And that's it, really. If you only want news to go into the @sc{soup}
+system you just use the first line. If you only want mail to be
+@sc{soup}ed you use the second.
+
@node Reading Mail
@subsection Reading Mail
@cindex reading mail
@cindex mail
-Reading mail with a newsreader - isn't that just plain WeIrD? But of
+Reading mail with a newsreader---isn't that just plain WeIrD? But of
course.
Gnus will read the mail spool when you activate a mail group. The mail
programs, if you want to.
@vindex nnmail-spool-file
+@cindex POP mail
@code{nnmail-spool-file} says where to look for new mail. If this
variable is @code{nil}, the mail backends will never attempt to fetch
-mail by themselves. It is quite likely that Gnus supports POP-mail.
-Set this variable to begin with the string @samp{po:}, and everything
-should go smoothly, even though I have never tested this.
+mail by themselves. If you are using a POP mail server and your name is
+@samp{"larsi"}, you should set this variable to @samp{"po:larsi"}. If
+your name is not @samp{"larsi"}, you should probably modify that
+slightly, but you may have guessed that already, you smart & handsome
+devil! You can also set this variable to @code{pop}, and Gnus will try
+to figure out the POP mail string by itself.
+
+When you use a mail backend, Gnus will slurp all your mail from your
+inbox and plonk it down in your home directory. Gnus doesn't move any
+mail if you're not using a mail backend---you have to do a lot of magic
+invocations first. At the time when you have finished drawing the
+pentagram, lightened the candles, and sacrificed the goat, you really
+shouldn't be too suprised when Gnus moves your mail.
@vindex nnmail-use-procmail
If @code{nnmail-use-procmail} is non-@code{nil}, the mail backends will
@vindex nnmail-movemail-program
@code{nnmail-movemail-program} is executed to move mail from the user's
-inbox to her home directory. The default is @samp{"movemail"}.
+inbox to her home directory. The default is @samp{"movemail"}.
@vindex nnmail-delete-incoming
If @code{nnmail-delete-incoming} is non-@code{nil}, the mail backends
will delete the temporary incoming file after splitting mail into the
proper groups. This is @code{nil} by default for reasons of security.
+@vindex nnmail-use-long-file-names
+If @code{nnmail-use-long-file-names} is non-@code{nil} the mail backends
+will use long file and directory names. Groups like @samp{mail.misc}
+will end up in directories like @file{mail.misc/}. If it is @code{nil},
+the same group will end up in @file{mail/misc/}.
+
@vindex nnmail-message-id-cache-length
@vindex nnmail-message-id-cache-file
@vindex nnmail-delete-duplicates
@cindex duplicate mails
If you are a member of a couple of mailing list, you will sometime
-receive two copies of the same mail. This can be quite annoying, so
-@code{nnmail} checks for and discards any duplicates it might find. To
+receive two copies of the same mail. This can be quite annoying, so
+@code{nnmail} checks for and discards any duplicates it might find. To
do this, it keeps a cache of old @code{Message-ID}s -
@code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
-default. The approximate maximum number of @code{Message-ID}s stored
+default. The approximate maximum number of @code{Message-ID}s stored
there is controlled by the @code{nnmail-message-id-cache-length}
variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
stored.) If all this sounds scary to you, you can set
with Gnus, and that she has @code{nnmail-delete-duplicates} set to
@code{t}, you can send her as many insults as you like, just by using a
@code{Message-ID} of a mail that you know that she's already received.
-Think of all the fun! She'll never see any of it! Whee!
+Think of all the fun! She'll never see any of it! Whee!
Gnus gives you all the opportunity you could possibly want for shooting
yourself in the foot. Let's say you create a group that will contain
mails that haven't been matched by any of the other regexps.
If you like to tinker with this yourself, you can set this variable to a
-function of your choice. This function will be called without any
+function of your choice. This function will be called without any
arguments in a buffer narrowed to the headers of an incoming mail
-message. The function should return a list of groups names that it
+message. The function should return a list of groups names that it
thinks should carry this mail message.
+Note that the mail backends are free to maul the poor, innocent
+incoming headers all they want to. They all add @code{Lines} headers;
+some add @code{X-Gnus-Group} headers; most rename the Unix mbox
+@code{From<SPC>} line to something else.
+
@vindex nnmail-crosspost
The mail backends all support cross-posting. If several regexps match,
the mail will be "cross-posted" to all those groups.
@code{nnmail-crosspost} says whether to use this mechanism or not. Note
that no articles are crossposted to the general (@samp{""}) group.
+
+
@node Fancy Mail Splitting
@subsubsection Fancy Mail Splitting
@cindex mail splitting
@code{nnmail-resplit-incoming} to @code{t}.
@vindex nnmail-keep-last-article
-If you use @code{procmail} to split things directory into an nnmh
+If you use @code{procmail} to split things directory into an @code{nnmh}
directory (which you shouldn't do), you should set
@code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
-ever expiring the final article in a mail newsgroup. This is quite,
+ever expiring the final article in a mail newsgroup. This is quite,
quite important.
@node nnmbox
@subsubsection nnmbox
-@cindex nnmbox
+@cindex @code{nnmbox}
@cindex unix mail box
@vindex nnmbox-active-file
@node nnbabyl
@subsubsection nnbabyl
-@cindex nnbabyl
+@cindex @code{nnbabyl}
@cindex rmail mbox
@vindex nnbabyl-active-file
@node nnml
@subsubsection nnml
-@cindex nnml
+@cindex @code{nnml}
@cindex mail @sc{nov} spool
The @dfn{nnml} spool mail format isn't compatible with any other known
@item nnml-newsgroups-file
@vindex nnml-newsgroups-file
-The @code{nnml} group description file.
+The @code{nnml} group descriptions file. @xref{Newsgroups File
+Format}.
@item nnml-get-new-mail
@vindex nnml-get-new-mail
@node nnmh
@subsubsection nnmh
-@cindex nnmh
+@cindex @code{nnmh}
@cindex mh-e mail spool
@code{nnmh} is just like @code{nnml}, except that is doesn't generate
sure that the articles in the folder is actually what Gnus think they
are. It will check date stamps, and stat everything in sight, so
setting this to @code{t} will mean a serious slow-down. If you never
-use anything by Gnus to read the nnmh articles, you do not have to set
+use anything by Gnus to read the @code{nnmh} articles, you do not have to set
this variable to @code{t}.
@end table
@node nnfolder
@subsubsection nnfolder
-@cindex nnfolder
+@cindex @code{nnfolder}
@cindex mbox folders
@code{nnfolder} is a backend for storing each mail group in a separate
@item nnfolder-newsgroups-file
@vindex nnfolder-newsgroups-file
-The name of the group description file.
+The name of the group descriptions file. @xref{Newsgroups File Format}.
@item nnfolder-get-new-mail
@vindex nnfolder-get-new-mail
If non-@code{nil}, @code{nnfolder} will read incoming mail.
@end table
+
@node Group Parameters
@section Group Parameters
@cindex group parameters
In fact, the vast majority of groups will normally only have the first
three elements, which saves quite a lot of cons cells.
-The group parameters stores information local to a particular group:
+The group parameters store information local to a particular group:
@table @code
@item to-address
If the group parameter list contains an element that looks like
@samp{(to-address . "some@@where.com")}, that address will be used by
the backend when doing followups and posts. This is primarily useful in
-mail groups that represent mailing lists. You just set this address to
-whatever the list address is.
+mail groups that represent close mailing lists. You just set this
+address to whatever the list address is.
This trick will actually work whether the group is foreign or not.
Let's say there's a group on the server that is called @samp{fa.4ad-l}.
This is a real newsgroup, but the server has gotten the articles from a
mail-to-news gateway. Posting directly to this group is therefore
-impossible - you have to send mail to the mailing list address instead.
+impossible---you have to send mail to the mailing list address instead.
+Also @xref{Mail & Post}.
+
+@item to-list
+@cindex to-list
+If the group parameter list has an element that looks like
+@samp{(to-list . "some@@where.com")}, that address will be used when
+doing a @kbd{a} in any group. It is totally ignored when doing a
+followup---except that if it is present in a news group, you'll get mail
+group semantics when doing @kbd{f}.
@item to-group
@cindex to-group
-IF the group parameter list contains an element like @code{(to-group
-. "some.group.name")}, all posts will be sent to that groups.
+If the group parameter list contains an element like @code{(to-group
+. "some.group.name")}, all posts will be sent to that group.
+
+@item topic
+@cindex topic
+If the group parameter list contains an element like @code{(topic
+. "some-topic")}, the group will become a member of the topic in
+question (@pxref{Group Topics}).
@item auto-expire
@cindex auto-expire
@item A k
@kindex A k (Group)
@findex gnus-group-list-killed
-List all killed groups (@code{gnus-group-list-killed}).
+List all killed groups (@code{gnus-group-list-killed}). If given a
+prefix argument, really list all groups that are available, but aren't
+currently (un)subscribed. This could entail reading the active file
+from the server.
@item A z
@kindex A z (Group)
@end table
+@vindex gnus-permanently-visible-groups
+@cindex visible group paramenter
+Groups that match the @code{gnus-permanently-visible-groups} regexp will
+always be shown, whether they have unread articles or not. You can also
+add the @code{visible} element to the group parameters in question to
+get the same effect.
+
+@node Sorting Groups
+@section Sorting Groups
+@cindex sorting groups
+
+@kindex C-c C-s (Group)
+@findex gnus-group-sort-groups
+@vindex gnus-group-sort-function
+The @kbd{C-c C-s} (@code{gnus-group-srot-groups}) command sorts the
+group buffer according to the function(s) given by the
+@code{gnus-group-sort-function} variable. Available sorting functions
+include:
+
+@table @code
+
+@item gnus-group-sort-by-alphabet
+@findex gnus-group-sort-by-alphabet
+Sort the group names alphabetically. This is the default.
+
+@item gnus-group-sort-by-level
+@findex gnus-group-sort-by-level
+Sort by group level.
+
+@item gnus-group-sort-by-score
+@findex gnus-group-sort-by-score
+Sort by group score.
+
+@item gnus-group-sort-by-rank
+@findex gnus-group-sort-by-rank
+Sort by group score and then the group level. The level and the score
+are, when taken together, the group's @dfn{rank}.
+
+@item gnus-group-sort-by-unread
+@findex gnus-group-sort-by-unread
+Sort by number of unread articles.
+
+@item gnus-group-sort-by-method
+@findex gnus-group-sort-by-method
+Sort by alphabetically on the select method.
+
+
+@end table
+
+@code{gnus-group-sort-function} can also be a list of sorting
+functions. In that case, the most significant sort key function must be
+the last one.
+
+
+There are also a number of commands for sorting directly according to
+some sorting criteria:
+
+@table @kbd
+@item G S a
+@kindex G S a (Group)
+@findex gnus-group-sort-groups-by-alphabet
+Sort the group buffer alphabetically by group name
+(@code{gnus-group-sort-groups-by-alphabet}).
+
+@item G S u
+@kindex G S u (Group)
+@findex gnus-group-sort-groups-by-unread
+Sort the group buffer by the number of unread articles
+(@code{gnus-group-sort-groups-by-unread}).
+
+@item G S l
+@kindex G S l (Group)
+@findex gnus-group-sort-groups-by-level
+Sort the group buffer by group level
+(@code{gnus-group-sort-groups-by-level}).
+
+@item G S v
+@kindex G S v (Group)
+@findex gnus-group-sort-groups-by-score
+Sort the group buffer by group score
+(@code{gnus-group-sort-groups-by-score}).
+
+@item G S r
+@kindex G S r (Group)
+@findex gnus-group-sort-groups-by-rank
+Sort the group buffer by group level
+(@code{gnus-group-sort-groups-by-rank}).
+
+@item G S m
+@kindex G S m (Group)
+@findex gnus-group-sort-groups-by-method
+Sort the group buffer alphabetically by backend name
+(@code{gnus-group-sort-groups-by-method}).
+
+@end table
+
+When given a prefix, all these commands will sort in reverse order.
+
+
+
@node Group Maintenance
@section Group Maintenance
@cindex bogus groups
@findex gnus-group-check-bogus-groups
Find bogus groups and delete them
(@code{gnus-group-check-bogus-groups}).
+
@item F
@kindex F (Group)
@findex gnus-find-new-newsgroups
Find new groups and process them (@code{gnus-find-new-newsgroups}).
+
@item C-c C-x
@kindex C-c C-x (Group)
@findex gnus-group-expire-articles
Run all articles in all groups through the expiry process
(@code{gnus-group-expire-all-groups}).
-@item C-c C-s
-@kindex C-c C-s (Group)
-@findex gnus-group-sort-groups
-@vindex gnus-group-sort-function
-Sort the groups according to the function given by the
-@code{gnus-group-sort-function} variable
-(@code{gnus-group-sort-groups}). Available sorting functions include:
-
-@table @code
-
-@item gnus-group-sort-by-level
-@findex gnus-group-sort-by-level
-Sort by group level.
-
-@item gnus-group-sort-by-unread
-@findex gnus-group-sort-by-unread
-Sort by number of unread articles.
-
-@item gnus-group-sort-by-alphabet
-@findex gnus-group-sort-by-alphabet
-Sort the group names alphabetically. This is the default.
-
-@item gnus-group-sort-by-method
-@findex gnus-group-sort-by-method
-Sort by alphabetically on the select method.
-
@end table
-@code{gnus-group-sort-function} can also be a list of sorting
-functions. In that case, the most significant sort key function must be
-the last one.
-@end table
@node Browse Foreign Server
@section Browse Foreign Server
@cindex topics
If you read lots and lots of groups, it might be convenient to group
-them according to topics. You put your Emacs groups over here, your sex
-groups over there, and the rest (what, two groups or so?) you put in
-some misc section that you never bother with anyway.
+them hierarchically according to topics. You put your Emacs groups over
+here, your sex groups over there, and the rest (what, two groups or so?)
+you put in some misc section that you never bother with anyway. You can
+even group the Emacs sex groups as a sub-topic to either the Emacs
+groups or the sex groups---or both! Go wild!
+
+@findex gnus-topic-mode
+@kindex t (Group)
+To get this @emph{fab} functionality you simply turn on (ooh!) the
+@code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This
+is a toggling command.)
-To get this @emph{fab} functionality, you set
-@code{gnus-group-prepare-function} to @code{gnus-group-prepare-topics}.
Go ahead, just try it. I'll still be here when you get back. La de
-dum... Nice tune, that... la la la... What, you're back? Yes, and now
+dum... Nice tune, that... la la la... What, you're back? Yes, and now
press @kbd{l}. There. All your groups are now listed under
@samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
bothered?
+If you want this permanently enabled, you should add that minor mode to
+the hook for the group mode:
+
+@lisp
+(add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
+@end lisp
+
+There are, in general, two methods for dividing the groups into topics.
+You can either sniff around some variables, or you can use some handy
+commands.
+
+@menu
+* Topic Variables:: How to customize the topics the Lisp Way.
+* Topic Commands:: Interactive E-Z commands.
+* Topic Topology:: A map of the world.
+@end menu
+
+
+@node Topic Variables
+@subsection Topic Variables
+@cindex topic variables
+
@vindex gnus-group-topics
-To get an even more exciting division, you have to fiddle with
-@code{gnus-group-topics}. That is an alist where each entry looks like
-this:
+
+@code{gnus-group-topics} is the main variable that specifies what topics
+each group belong to. That is an alist where each entry looks like
+this:
@lisp
(TOPIC REGEXP SHOW)
@end lisp
-As you've already guessed (only geniouses read manuals anyway), all
+As you've already guessed (only geniï read manuals anyway), all
groups that match @var{regexp} gets put into a section called
@var{topic}. If @var{show} is non-@code{nil}, it overrides
@code{gnus-group-topic-topics-only}. In specific, if @var{show} is
Whoo, this is complicated. If @code{gnus-group-topic-topics-only} is
@code{nil}, all groups and topics will be listed, as you would expect.
If this variable is non-@code{nil}, only the topics will be listed, and
-the groups will not be listed. This makes the group buffer much shorter,
+the groups will not be listed. This makes the group buffer much shorter,
I'm sure you'll agree. This is all modified on a topic-by-topic basis
by the @var{show} parameter. It makes perfect sense, really.
-@vindex gnus-group-topic-face
-Topics are shown with @code{gnus-group-topic-face}.
+@vindex gnus-topic-unique
+If @code{gnus-topic-unique} is non-@code{nil}, each group will be member
+of (tops) one topic each. If this is @code{nil}, each group might end
+up being a member of several topics.
+
+You can also put a @code{topic} in the group parameters (@pxref{Group
+Parameters}).
Now, if you select a topic, if will fold/unfold that topic, which is
really neat, I think.
("The Rest" "." nil))
@end lisp
+@vindex gnus-topic-line-format
+The topic lines themselves are created according to the
+@code{gnus-topic-line-format} variable. @xref{Formatting Variables}.
+Elements allowed are:
+
+@table @samp
+@item i
+Indentation.
+@item n
+Topic name.
+@item v
+Visibility.
+@item l
+Level.
+@item g
+Number of groups in the topic.
+@item a
+Number of unread articles in the topic.
+@end table
+
+
+@node Topic Commands
+@subsection Topic Commands
+@cindex topic commands
+
+When the topic minor mode is turned on, a new @kbd{T} submap will be
+available. In addition, a few of the standard keys change their
+definitions slightly.
+
+@table @kbd
+
+@item T n
+@kindex T n (Group)
+@findex gnus-topic-create-topic
+Create a new topic (@code{gnus-topic-create-subtopic}). You will be
+prompted for a topic name and the name of the parent topic.
+
+@item T m
+@kindex T m (Group)
+@findex gnus-topic-move-group
+Move the current group to some other topic
+(@code{gnus-topic-move-group}). This command understands the
+process/prefix convention (@pxref{Process/Prefix}).
+
+@item T c
+@kindex T c (Group)
+@findex gnus-topic-copy-group
+Copy the current group to some other topic
+(@code{gnus-topic-copy-group}). This command understands the
+process/prefix convention (@pxref{Process/Prefix}).
+
+@item T M
+@kindex T M (Group)
+@findex gnus-topic-move-matching
+Move all groups that match some regular expression to a topic
+(@code{gnus-topic-move-matching}).
+
+@item T C
+@kindex T C (Group)
+@findex gnus-topic-copy-matching
+Copy all groups that match some regular expression to a topic
+(@code{gnus-topic-copy-matching}).
+
+@item RET
+@kindex RET (Group)
+@findex gnus-topic-select-group
+@itemx SPACE
+Either select a group or fold a topic (@code{gnus-topic-select-group}).
+When you perform this command on a group, you'll enter the group, as
+usual. When done on a topic line, the topic will be folded (if it was
+visible) or unfolded (if it was folded already). So it's basically a
+toggling command on topics. In addition, if you give a numerical
+prefix, group on that level (and lower) will be displayed.
+
+@item C-k
+@kindex C-k (Group)
+@findex gnus-topic-kill-group
+Kill a group or topic (@code{gnus-topic-kill-group}).
+
+@item C-y
+@kindex C-y (Group)
+@findex gnus-topic-yank-group
+Yank the previosuly killed group or topic (@code{gnus-topic-yank-group}).
+Note that all topics will be yanked before all groups.
+
+@item T r
+@kindex T r (Group)
+@findex gnus-topic-rename
+Rename a topic (@code{gnus-topic-rename}).
+
+@item T DEL
+@kindex T DEL (Group)
+@findex gnus-topic-delete
+Delete an empty topic (@code{gnus-topic-delete}).
+
+@end table
+
+
+@node Topic Topology
+@subsection Topic Topology
+@cindex topic topology
+@cindex topology
+
+So, let's have a look at an example group buffer:
+
+@example
+Gnus
+ Emacs -- I wuw it!
+ 3: comp.emacs
+ 2: alt.religion.emacs
+ Naughty Emacs
+ 452: alt.sex.emacs
+ 0: comp.talk.emacs.recovery
+ Misc
+ 8: comp.binaries.fractals
+ 13: comp.sources.unix
+@end example
+
+So, here we have one top-level topic, two topics under that, and one
+sub-topic under one of the sub-topics. (There is always just one (1)
+top-level topic). This topology can be expressed as follows:
+
+@lisp
+(("Gnus" visible)
+ (("Emacs -- I wuw it!" visible)
+ (("Naughty Emacs" visible)))
+ (("Misc" visible)))
+@end lisp
+
+This is in fact how the variable @code{gnus-topic-topology} would look
+for the display above. That variable is saved in the @file{.newsrc.eld}
+file, and shouldn't be messed with manually---unless you really want
+to. Since this variable is read from the @file{.newsrc.eld} file,
+setting it in any other startup files will have no effect.
+
+This topology shows what topics are sub-topics of what topics (right),
+and which topics are visible. Two settings are currently
+allowed---@code{visible} and @code{invisible}.
+
+@vindex gnus-topic-hide-subtopics
+If @code{gnus-topic-hide-subtopics} is non-@code{nil} (which it is by
+default), sub-topics will be folded along with any groups that belong to
+the topic. If this variable is @code{nil}, all topics will always be
+visible, even though the parent topics are folded.
+
@node Misc Group Stuff
@section Misc Group Stuff
@item g
@kindex g (Group)
@findex gnus-group-get-new-news
-Check server for new articles. If the numerical prefix is used, this
-command will check only groups of level @var{arg} and lower
+Check the server(s) for new articles. If the numerical prefix is used,
+this command will check only groups of level @var{arg} and lower
(@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
command will force a total rereading of the active file(s) from the
-backend(s).
+backend(s).
@item M-g
@kindex M-g (Group)
@kindex s (Group)
@findex gnus-group-save-newsrc
Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
-(@code{gnus-group-save-newsrc}).
+(@code{gnus-group-save-newsrc}). If given a prefix, force saving the
+file(s) whether Gnus thinks it is necessary or not.
@item Z
@kindex Z (Group)
@findex gnus-group-clear-dribble
@item a
@kindex a (Group)
@findex gnus-group-post-news
-Post an article to a group (@code{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.
@item m
@kindex m (Group)
@findex gnus-group-mail
* Threading:: How threads are made.
* Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
* Article Caching:: You may store articles in a cache.
+* Article Backlog:: Having already read articles hang around.
* Exiting the Summary Buffer:: Returning to the Group buffer.
* Process/Prefix:: A convention used by many treatment commands.
* Saving Articles:: Ways of customizing article saving.
variable as a function for getting the name and address parts of a
@code{From} header. Two pre-defined function exist:
@code{gnus-extract-address-components}, which is the default, quite
-fast, and too simplistic solution, and
+fast, and too simplistic solution; and
@code{mail-extract-address-components}, which works very nicely, but is
slower.
@vindex gnus-summary-same-subject
@code{gnus-summary-same-subject} is a string indicating that the current
article has the same subject as the previous. This string will be used
-with those specs that require it.
+with those specs that require it. The default is @samp{""}.
@node Summary Buffer Lines
@subsection Summary Buffer Lines
@item n
The name (from the @code{From} header).
@item a
-The name (from the @code{From} header). This differs from the @code{n}
+The name (from the @code{From} header). This differs from the @code{n}
spec in that it uses @code{gnus-extract-address-components}, which is
slower, but may be more thorough.
@item A
-The address (from the @code{From} header). This works the same way as
+The address (from the @code{From} header). This works the same way as
the @code{a} spec.
@item L
Number of lines in the article.
@item D
@code{Date}.
@item M
-@code{Message-Id}.
+@code{Message-ID}.
@item r
@code{References}.
@item t
into the summary just like information from any other summary specifier.
@end table
-Text between @samp{%(} and @samp{%)} will be highlighted with
-@code{gnus-mouse-face} when the mouse point is placed inside the area.
-There can only be one such area.
-
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"
articles, and just as @samp{<%U more>} if there are just unread articles
and no unselected ones.
@item g
-Shortish group name. For instance, @samp{rec.arts.anime} will be
+Shortish group name. For instance, @samp{rec.arts.anime} will be
shortened to @samp{r.a.anime}.
@item S
Subject of the current article.
@menu
* Mail:: Mailing & replying.
* Post:: Posting and following up.
+* Posting Server:: What server should you post via?
* Mail & Post:: Mailing and posting at the same time.
+* Posting Styles:: An easier way to configure some key elements.
* Drafts:: Postponing messages and rejected messages.
* Rejected Articles:: What happens if the server doesn't like your article?
@end menu
Commands for composing a mail message:
@table @kbd
+
@item S r
@itemx r
@kindex S r (Summary)
@findex gnus-summary-reply
Mail a reply to the author of the current article
(@code{gnus-summary-reply}).
+
@item S R
@itemx R
@kindex R (Summary)
Mail a reply to the author of the current article and include the
original message (@code{gnus-summary-reply-with-original}). This
command uses the process/prefix convention.
+
@item S o m
@kindex S o m (Summary)
@findex gnus-summary-mail-forward
Forward the current article to some other person
(@code{gnus-summary-mail-forward}).
+
@item S o p
@kindex S o p (Summary)
@findex gnus-summary-post-forward
Forward the current article to a newsgroup
(@code{gnus-summary-post-forward}).
+
@item S m
@itemx m
@kindex m (Summary)
@findex gnus-summary-mail-other-window
Send a mail to some other person
(@code{gnus-summary-mail-other-window}).
+
@item S D b
@kindex S D b (Summary)
@findex gnus-summary-resend-bounced-mail
the bounced mail is a reply to some other mail, Gnus will try to fetch
that mail and display it for easy perusal of its headers. This might
very well fail, though.
+
+@item S D r
+@kindex S D r (Summary)
+@findex gnus-summary-resend-message
+Not to be confused with the previous command,
+@code{gnus-summary-resend-message} will prompt you for an address to
+send the current message off to, and then send it to that place. The
+headers of the message won't be altered---but lots of headers that say
+@samp{Resent-To}, @samp{Resent-From} and so on will be added. This
+means that you actually send a mail to someone that has a @samp{To}
+header that (proabbly) points to yourself. This will confuse people.
+So, natcherly you'll only do that if you're really eVIl.
+
+This command is mainly used if you have several accounts and want to
+ship a mail to a different account of yours. (If you're both
+@samp{root} and @samp{postmaster} and get a mail for @samp{postmaster}
+to the @samp{root} account, you may want to resend it to
+@samp{postmaster}. Ordnung muss sein!
+
@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}).
+
@item S O p
@kindex S O p (Summary)
@findex gnus-uu-digest-post-forward
The @code{Newsgroups} header is illegal in this list, while @code{To} is
required, and @code{X-Mailer} can be added if you so should want.
+@findex gnus-forward-start-separator
+@item gnus-forward-start-separator
+Delimiter inserted before forwarded messages.
+
+@findex gnus-forward-end-separator
+@item gnus-forward-end-separator
+Delimiter inserted after forwarded messages.
+
+@findex gnus-signature-before-forwarded-message
+@item gnus-signature-before-forwarded-message
+If this variable is @code{t}, which it is by default, your personal
+signature will be inserted before the forwarded message. If not, the
+forwarded message will be inserted first in the new mail.
+
@end table
@kindex C-c C-c (Mail)
@end table
In addition, you can enter conses into this list. The car of this cons
-should be a symbol who's name is the name of the header, and the cdr can
-either a string to be entered verbatim as the value of this header, or
-it can be a function to be called. This function should return a string
-to be inserted. For instance, if you want to insert @samp{Mime-Version:
-1.0}, you should enter @code{(Mime-Version . "1.0")} into the list. If
-you want to insert a funny quote, you could enter something like
-@code{(X-Yow . yow)} into the list. The function @code{yow} will then
-be called without any arguments.
+should be a symbol. This symbol's name is the name of the header, and
+the cdr can either be a string to be entered verbatim as the value of
+this header, or it can be a function to be called. This function should
+return a string to be inserted. For instance, if you want to insert
+@samp{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
+into the list. If you want to insert a funny quote, you could enter
+something like @code{(X-Yow . yow)} into the list. The function
+@code{yow} will then be called without any arguments.
The list contains a cons where the car of the cons is @code{optional},
the cdr of this cons will only be inserted if it is non-@code{nil}.
Other variables for customizing outgoing articles:
@table @code
-@item gnus-post-method
-@vindex gnus-post-method
-If non-@code{nil}, Gnus will use this method instead of the default
-select method when posting.
-
@item nntp-news-default-headers
@vindex nntp-news-default-headers
If non-@code{nil}, this variable will override
post buffer has been initialized, and can be used for inserting a
signature. Nice if you use different signatures in different groups.
-@item gnus-post-prepapare-hook
-@vindex gnus-post-prepapare-hook
-This hook is called after a post buffer has been prepared. If you want
+@item gnus-post-prepare-hook
+@vindex gnus-post-prepare-hook
+This hook is called after a post buffer has been prepared. If you want
to insert a signature at this point, you could put
@code{gnus-inews-insert-signature} into this hook.
In article <zngay8jrql@@eyesore.no> Lars Mars <lars@@eyesore.no> writes:
@end example
-Having the @code{Message-Id} in this line is probably overkill, so I
+Having the @code{Message-ID} in this line is probably overkill, so I
would suggest this hook instead:
@lisp
@item gnus-prepare-article-hook
@vindex gnus-prepare-article-hook
-This hook is called before the headers have been prepared. By default
-it inserts the signature specified by @code{gnus-signature-file}.
+This hook is called before the headers have been prepared.
@item gnus-inews-article-function
@vindex gnus-inews-article-function
@item new-text
Check whether there is any new text in the messages.
@item signature
-Check the length of the signature
+Check the length of the signature.
@item approved
Check whether the article has an @code{Approved} header, which is
something only moderators should include.
@end table
+@node Posting Server
+@subsection Posting Server
+
+When you press those magical @kbd{C-c C-c} keys to ship off your latest
+(extremely intelligent, of course) article, where does it go?
+
+Thank you for asking. I hate you.
+
+@vindex gnus-post-method
+
+It can be quite complicated. Normally, Gnus will use the same native
+server. However. If your native server doesn't allow posting, just
+reading, you probably want to use some other server to post your
+(extremely intelligent and fabulously interesting) articles. You can
+then set the @code{gnus-post-method} to some other method:
+
+@lisp
+(setq gnus-post-method '(nnspool ""))
+@end lisp
+
+Now, if you've done this, and then this server rejects your article, or
+this server is down, what do you do then? To override this variable you
+can use a prefix to the @kbd{C-c C-c} command to force using the
+"current" server for posting.
+
+
@node Mail & Post
@subsection Mail & Post
signature will be appended to all outgoing post. Most people find it
more convenient to use @code{mail-signature}, which (sort of) does the
same, but inserts the signature into the buffer before you start editing
-the post (or mail). So - if you have both of these variables set, you
+the post (or mail). So---if you have both of these variables set, you
will get two signatures. Note that @code{mail-signature} does not work
the same way as @code{gnus-signature-file}, which is a bit confusing.
If @code{mail-signature} is @code{t}, it will insert
@item mail-yank-ignored-headers
@vindex mail-yank-ignored-headers
When you yank a message, you do not want to quote any headers, so
-@code{(setq mail-yank-ignored-headers ":")}.
+@code{(setq mail-yank-ignored-headers "^")}.
@item user-mail-address
@vindex user-mail-address
@code{gnus-local-domain} are @code{nil}, Gnus will use
@code{user-mail-address} as the address part of the @code{From} header.
+@item gnus-local-domain
+@vindex gnus-local-domain
+@cindex domain
+The local doman name excluding the host name. If your host is called
+@samp{"narfi.ifi.uio.no"}, then this variable should be
+@samp{"ifi.uio.no"}.
+
+@item gnus-local-domain
+@vindex gnus-local-domain
+@cindex domain
+The local doman name excluding the host name. If your host is called
+@samp{"narfi.ifi.uio.no"}, then this variable should be
+@samp{"ifi.uio.no"}.
+
@item gnus-user-from-line
@vindex gnus-user-from-line
Your full, complete e-mail address with name. This variable overrides
Here are two example values of this variable: @samp{"larsi@@ifi.uio.no
(Lars Magne Ingebrigtsen)"} and @samp{"Lars Magne Ingebrigtsen
-<larsi@@ifi.uio.no>"}. The latter version is recommended in news (and is
+<larsi@@ifi.uio.no>"}. The latter version is recommended in news (and is
probably illegal in mail), but the name has to be quoted if it contains
-non-alpha-numerical characters - @samp{"\"Lars M. Ingebrigtsen\"
+non-alpha-numerical characters---@samp{"\"Lars M. Ingebrigtsen\"
<larsi@@ifi.uio.no>"}.
@item mail-default-headers
copy to the author of the article you are following up. If
non-@code{nil} and not @code{ask}, Gnus will send a mail with a copy of
all follow-ups to the authors of the articles you follow up. It's nice
-in one way - you make sure that the person you are responding to gets
+in one way---you make sure that the person you are responding to gets
your response. Other people loathe this method and will hate you dearly
for it, because it means that they will first get a mail, and then have
to read the same article later when they read the news. It is
@vindex gnus-outgoing-message-group
All outgoing messages will be put in this group. If you want to store
all your outgoing mail and articles in the group @samp{nnml:archive},
-you set this variable to that value. This variable can also be a list of
+you set this variable to that value. This variable can also be a list of
group names.
If you want to have greater control over what group to put each
current newsgroup name and then returns a suitable group name (or list
of names).
+@item gnus-mailing-list-groups
+@findex gnus-mailing-list-groups
+@cindex mailing lists
+
+If your newsserver offer groups that are really mailing lists that are
+gatewayed to the @sc{nntp} server, you can read those groups without
+problems, but you can't post/followup to them without some difficulty.
+One solution is to add a @code{to-address} to the group parameters
+(@pxref{Group Parameters}). An easier thing to do is set the
+@code{gnus-mailing-list-groups} to a regexp that match the groups that
+really are mailing lists. Then, at least, followups to the mailing
+lists will work most of the time. Posting to these groups (@kbd{a}) is
+still a pain, though.
+
+
@end table
You may want to do spell-checking on messages that you send out. Or, if
@code{gnus-inews-insert-mime-headers} to @code{gnus-inews-article-hook}.
+@node Posting Styles
+@subsection Posting Styles
+@cindex posting styles
+@cindex styles
+
+All them variables, they make my head swim.
+
+So what if you want a different @code{Organization} and signature based
+on what groups you post to? And you post both from your home machine
+and your work machine, and you want different @code{From} lines, and so
+on?
+
+@vindex gnus-posting-styles
+One way to do stuff like that is to write clever hooks that change the
+variables you need to have changed. That's a bit boring, so somebody
+came up with the bright idea of letting the user specify these things in
+a handy alist. Here's an example of a @code{gnus-posting-styles}
+variable:
+
+@lisp
+((".*" (signature . "Peace and happiness") (organization . "What me?"))
+ ("^comp" (signature . "Death to everybody"))
+ ("comp.emacs.i-love-it" (organization . "Emacs is it")))
+@end lisp
+
+As you might surmise from this example, this alist consists of several
+@dfn{styles}. Each style will be applicable if the first element
+"matches", in some form or other. The entire alist will be iterated
+over, from the beginning towards the end, and each match will be
+applied, which means that attributes in later styles that match override
+the same attributes in earlier matching styles. So
+@samp{comp.programming.literate} will have the @samp{Death to everybody}
+signature and the @samp{What me?} @code{Organization} header.
+
+The first element in each style is called the @code{match}. If it's a
+string, then Gnus will try to regexp match it against the group name.
+If it's a function symbol, that function will be called with no
+arguments. If it's a variable symbol, then the variable will be
+referenced. If it's a list, then that list will be @code{eval}ed. In
+any case, if this returns a non-@code{nil} value, then the style is said
+to @dfn{match}.
+
+Each style may contain a random amount of @dfn{attributes}. Each
+attribute consists of a @var{(name . value)} pair. The attribute name
+can be one of @code{signature}, @code{organization} or @code{from}.
+The attribute name can also be a string. In that case, this will be
+used as a header name, and the value will be inserted in the headers of
+the article.
+
+The attribute value can be a string (used verbatim), a function (the
+return value will be used), a variable (its value will be used) or a
+list (it will be @code{eval}ed and the return value will be used).
+
+So here's a new example:
+
+@lisp
+(setq gnus-posting-styles
+ '((".*"
+ (signature . "~/.signature")
+ (from . "user@@foo (user)")
+ ("X-Home-Page" . (getenv "WWW_HOME"))
+ (organization . "People's Front Against MWM"))
+ ("^rec.humor"
+ (signature . my-funny-signature-randomizer))
+ ((equal (system-name) "gnarly")
+ (signature . my-quote-randomizer))
+ (posting-from-work-p
+ (signature . "~/.work-signature")
+ (from . "user@@bar.foo (user)")
+ (organization . "Important Work, Inc"))
+ ("^nn.+:"
+ (signature . "~/.mail-signature"))))
+@end lisp
+
+
+
@node Drafts
@subsection Drafts
@cindex drafts
(unfinished) message in a special draft group (which is implemented as
an @code{nndir} group, if you absolutely have to know) called
@samp{nndir:drafts}. The variable @code{gnus-draft-group-directory}
-controls both the name of the group and the location -- the leaf element
+controls both the name of the group and the location---the leaf element
in the path will be used as the name of the group.
-If the group doesn't exist, it will be created and subscribed to.
+If the group doesn't exist, it will be created and you'll be subscribed
+to it.
@findex gnus-summary-send-draft
-@kindex S D c
-When you want to continue editing, you simply enter the draft group and
-push @kbd{S D c} (@code{gnus-summary-send-draft}) to do that. You will
-be placed in a buffer where you left off.
+@kindex S D c (Summary)
+When you want to continue editing the article, you simply enter the
+draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
+that. You will be placed in a buffer where you left off.
Rejected articles will also be put in this draft group (@pxref{Rejected
Articles}).
If you have lots of rejected messages you want to post (or mail) without
doing further editing, you can use the @kbd{S D a} command
(@code{gnus-summary-send-all-drafts}). This command understands the
-process/prefix convention.
+process/prefix convention (@pxref{Process/Prefix}).
@node 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 there
-be demons. Perhaps you have included too much cited text. Perhaps the
-disk is full. Perhaps the server is down.
+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 in it, doesn't care about how much cited text you
-include, never runs full and never goes down.) So what Gnus does is
-saves these articles until some later time when the server feels better.
+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
Find the article you wish to cancel (you can only cancel your own
articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
c} (@code{gnus-summary-cancel-article}). Your article will be
-canceled - machines all over the world will be deleting your article.
+canceled---machines all over the world will be deleting your article.
Be aware, however, that not all sites honor cancels, so your article may
live on here and there, while most sites will delete the article in
@vindex gnus-delete-supersedes-headers
You probably want to delete some of the old headers before sending the
-superseding article - @code{Path} and @code{Date} are probably
+superseding article---@code{Path} and @code{Date} are probably
incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
match the lines you want removed. The default is
@samp{"^Path:\\|^Date"}.
@item M C-c
@kindex M C-c (Summary)
@findex gnus-summary-catchup-all
-Mark all articles in the group as read - even the ticked and dormant
+Mark all articles in the group as read---even the ticked and dormant
articles (@code{gnus-summary-catchup-all}).
@item M H
@kindex M H (Summary)
The @code{gnus-summary-goto-unread} variable controls what action should
be taken after setting a mark. If non-@code{nil}, point will move to
the next/previous unread article. If @code{nil}, point will just move
-one line up or down.
+one line up or down. The default is @code{t}.
@node Setting Process Marks
@table @kbd
-@item M N u
+@item / /
+@kindex / / (Summary)
+@findex gnus-summary-limit-to-subject
+Limit the summary buffer to articles that match some subject
+(@code{gnus-summary-limit-to-subject}).
+
+@item / u
@itemx x
-@kindex M N u (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
buffer to articles that are strictly unread. This means that ticked and
dormant articles will also be excluded.
-@item M N m
-@kindex M N m (Summary)
+@item / m
+@kindex / m (Summary)
@findex gnus-summary-limit-to-marks
Ask for a mark and then limit to all articles that have not been marked
with that mark (@code{gnus-summary-limit-to-marks}).
-@item M N n
-@kindex M N n (Summary)
-@findex
+@item / n
+@kindex / n (Summary)
+@findex gnus-summary-limit-to-articles
Limit the summary buffer to the current article
(@code{gnus-summary-limit-to-articles}). Uses the process/prefix
convention (@pxref{Process/Prefix}).
-@item M N w
-@kindex M N w (Summary)
+@item / w
+@kindex / w (Summary)
@findex gnus-summary-pop-limit
Pop the previous limit off the stack and restore it
(@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
the stack.
-@item M N s
+@item / s
@itemx /
-@kindex M N s (Summary)
+@kindex / s (Summary)
@kindex / (Summary)
@findex gnus-summary-limit-to-subject
Limit the summary buffer to articles that have a subject that matches a
regexp (@code{gnus-summary-limit-to-subject}).
-@item M N v
-@kindex M N v (Summary)
+@item / v
+@kindex / v (Summary)
@findex gnus-summary-limit-to-score
Limit the summary buffer to articles that have a score at or above some
score (@code{gnus-summary-limit-to-score}).
-@item M S
+@item / E
+@itemx M S
@kindex M S (Summary)
-@findex gnus-summary-show-all-expunged
-Display all expunged articles (@code{gnus-summary-show-all-expunged}).
+@kindex / E (Summary)
+@findex gnus-summary-limit-include-expunged
+Display all expunged articles
+(@code{gnus-summary-limit-include-expunged}).
-@item M N D
-@kindex M N D (Summary)
+@item / D
+@kindex / D (Summary)
@findex gnus-summary-limit-include-dormant
Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
-@item M N d
-@kindex M N d (Summary)
+@item / d
+@kindex / d (Summary)
@findex gnus-summary-limit-exclude-dormant
Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
-@item M N c
-@kindex M N c (Summary)
+@item / c
+@kindex / c (Summary)
@findex gnus-summary-limit-exclude-childless-dormant
Hide all dormant articles that have no children
(@code{gnus-summary-limit-exclude-childless-dormant}).
@cindex article threading
Gnus threads articles by default. @dfn{To thread} is to put replies to
-articles directly after the articles they reply to - in a hierarchical
+articles directly after the articles they reply to---in a hierarchical
fashion.
@menu
@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
+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
+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.
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
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.
+
@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
@cindex asynchronous article fetching
If you read your news from an @sc{nntp} server that's far away, the
-network latencies may make reading articles a chore. You have to wait
+network latencies may make reading articles a chore. You have to wait
for a while after pressing @kbd{n} to go to the next article before the
-article appears. Why can't Gnus just go ahead and fetch the article
+article appears. Why can't Gnus just go ahead and fetch the article
while you are reading the previous one? Why not, indeed.
First, some caveats. There are some pitfalls to using asynchronous
Gnus will fetch more articles than you will read. This will mean that
the link between your machine and the @sc{nntp} server will become more
loaded than if you didn't use article pre-fetch. The server itself will
-also become more loaded - both with the extra article requests, and the
+also become more loaded---both with the extra article requests, and the
extra connection.
-Ok, so now you know that you shouldn't really use this thing... unless
+Ok, so now you know that you shouldn't really use this thing... unless
you really want to.
@vindex gnus-asynchronous
since @code{nnvirtual} assigns random article numbers to its articles.
+@node Article Backlog
+@section Article Backlog
+@cindex backlog
+@cindex article backlog
+
+If you have a slow connection, but the idea of using caching seems
+unappealing to you (and it is, really), you can help the situation some
+by switching on the @dfn{backlog}. This is where Gnus will buffer
+already read articles so that it doesn't have to re-fetch articles
+you've already read. This only helps if you are in the habit of
+re-selecting articles you've recently read, of course. If you never do
+that, turning the backlog on will slow Gnus down a little bit, and
+increase memory usage some.
+
+@vindex gnus-keep-backlog
+If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store
+at most @var{n} old articles in a buffer for later re-fetching. If this
+variable is non-@code{nil} and is not a number, Gnus will store
+@emph{all} read articles, which means that your Emacs will group without
+bound before exploding and taking your machine down with you. I put
+that in there just to keep y'all on your toes.
+
+This variable is @code{nil} by default.
+
+
@node Exiting the Summary Buffer
@section Exiting the Summary Buffer
@cindex summary exit
The data on the current group will be updated (which articles you have
read, which articles you have replied to, etc.) when you exit the
summary buffer. If the @code{gnus-use-cross-reference} variable is
-@code{t}, articles that are cross-referenced to this group and are
-marked as read, will also be marked as read in the other subscribed
-groups they were cross-posted to. If this variable is neither
-@code{nil} nor @code{t}, the article will be marked as read in both
-subscribed and unsubscribed groups.
+@code{t} (which is the default), articles that are cross-referenced to
+this group and are marked as read, will also be marked as read in the
+other subscribed groups they were cross-posted to. If this variable is
+neither @code{nil} nor @code{t}, the article will be marked as read in
+both subscribed and unsubscribed groups.
Marking cross-posted articles as read ensures that you'll never have to
read the same article more than once. Unless, of course, somebody has
C'est la vie.
+
@node Process/Prefix
@section Process/Prefix
@cindex process/prefix convention
negative, perform the operation on the previous N articles, starting
with the current one.
+If @code{transient-mark-mode} in non-@code{nil} and the region is
+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
the process mark.
Quite simple, really, but it needs to be made clear so that surprises
are avoided.
+@vindex gnus-summary-goto-unread
+One thing that seems to shock & horrify lots of people is that, for
+instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}.
+Since each @kbd{d} (which marks the current article as read) by default
+goes to the next unread article after marking, this means that @kbd{3 d}
+will mark the next three unread articles as read, no matter what the
+summary buffer looks like. Set @code{gnus-summary-goto-unread} to
+@code{nil} for a more straightforward action.
+
@node Saving Articles
@section Saving Articles
@cindex saving articles
If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
unwanted headers before saving the article.
+@vindex gnus-saved-headers
+If the preceeding variable is @code{nil}, all headers that match the
+@code{gnus-saved-headers} regexp will be kept, while the rest will be
+deleted before saving.
+
@table @kbd
@item O o
@item O p
@kindex O p (Summary)
@findex gnus-summary-pipe-output
-Save the current article in a pipe. Uhm, like, what I mean is - Pipe
+Save the current article in a pipe. Uhm, like, what I mean is---Pipe
the current article to a process (@code{gnus-summary-pipe-output}).
@end table
All of these functions, except for the last one, will save the article
in the @code{gnus-article-save-directory}, which is initialized from the
-@samp{SAVEDIR} environment variable.
+@samp{SAVEDIR} environment variable. This is @file{~/News/} by
+default.
As you can see above, the functions use different functions to find a
suitable name of a file to save the article in. Below is a list of
Generates file names that look like @samp{~/News/alt.andrea-dworkin}.
@end table
+@vindex gnus-split-methods
+You can have Gnus suggest where to save articles by plonking regexp into
+the @code{gnus-split-methods} alist. For instance, if you would like to
+save articles related to Gnus in the file @file{gnus-stuff}, and articles
+related to VM in @code{vm-stuff}, you could set this variable to something
+like:
+
+@lisp
+(("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
+ ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff")
+ (my-choosing-function "../other-dir/my-stuff")
+ ((equal gnus-newsgroup-name "mail.misc") "mail-stuff"))
+@end lisp
+
+We see that this is a list where each element is a list that has two
+elements---the @dfn{match} and the @dfn{file}. The match can either be
+a string (in which case it is used as a regexp to match on the article
+head); it can be a symbol (which will be called as a function); or it
+can be a list (which will be @code{eval}ed). If any of these actions
+have a non-@code{nil} result, the @dfn{file} will be used as a default
+prompt.
+
@vindex gnus-use-long-file-name
Finally, you have the @code{gnus-use-long-file-name} variable. If it is
@code{nil}, all the preceding functions will replace all periods
-(@samp{.}) in the group names with slashes (@samp{/}) - which means that
+(@samp{.}) in the group names with slashes (@samp{/})---which means that
the functions will generate hierarchies of directories instead of having
all the files in the toplevel directory
(@samp{~/News/alt/andrea-dworkin} instead of
-@samp{~/News/alt.andrea-dworkin}.)
+@samp{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default
+on most systems. However, for historical reasons, this is @code{nil} on
+Xenix and usg-unix-v machines by default.
This function also affects kill and score file names. If this variable
is a list, and the list contains the element @code{not-score}, long file
(setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
@end lisp
-Then just save with @kbd{o}. You'd then read this hierarchy with
-ephemeral @code{nneething} groups - @kbd{G D} in the group buffer, and
-the toplevel directory as the argument (@file{~/News/}). Then just walk
+Then just save with @kbd{o}. You'd then read this hierarchy with
+ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
+the toplevel directory as the argument (@file{~/News/}). Then just walk
around to the groups/directories with @code{nneething}.
Non-@code{nil} means that @code{gnus-uu}, when asked to save without
decoding, will save in digests. If this variable is @code{nil},
@code{gnus-uu} will just save everything in a file without any
-embellishments. The digesting almost conforms to RFC1153 - no easy way
+embellishments. The digesting almost conforms to RFC1153---no easy way
to specify any meaningful volume and issue numbers were found, so I
simply dropped them.
Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
thread. This may not be smart, as no other decoder I have seen are able
to follow threads when collecting uuencoded articles. (Well, I have
-seen one package that does that - @code{gnus-uu}, but somehow, I don't
+seen one package that does that---@code{gnus-uu}, but somehow, I don't
think that counts...) Default is @code{nil}.
@item gnus-uu-post-separate-description
@table @kbd
@item W H a
-@kindex W H a
+@kindex W H a (Summary)
@findex gnus-article-highlight
Highlight the current article (@code{gnus-article-highlight}).
@item W H h
-@kindex W H h
+@kindex W H h (Summary)
@findex gnus-article-highlight-headers
@vindex gnus-header-face-alist
Highlight the headers (@code{gnus-article-highlight-headers}). The
match made will be used.
@item W H c
-@kindex W H c
+@kindex W H c (Summary)
@findex gnus-article-highlight-citation
Highlight cited text (@code{gnus-article-highlight-citation}).
@item W H s
-@kindex W H s
+@kindex W H s (Summary)
@vindex gnus-signature-separator
@findex gnus-article-highlight-signature
Highlight the signature (@code{gnus-article-highlight-signature}).
@vindex gnus-article-x-face-command
@vindex gnus-article-x-face-too-ugly
Look for and display any X-Face headers
-(@code{gnus-article-display-x-face}). The command executed by this
-function is given by the @code{gnus-article-x-face-command} variable. If
+(@code{gnus-article-display-x-face}). The command executed by this
+function is given by the @code{gnus-article-x-face-command} variable. If
this variable is a string, this string will be executed in a sub-shell.
If it is a function, this function will be called with the face as the
-argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
+argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
matches the @code{From} header, the face will not be shown.
@item W b
You can also ask the @sc{nntp} server for an arbitrary article, no
matter what group it belongs to. @kbd{M-^}
(@code{gnus-summary-refer-article}) will ask you for a
-@code{Message-Id}, which is one of those long thingies that look
+@code{Message-ID}, which is one of those long thingies that look
something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
it all exactly right. No fuzzy searches, I'm afraid.
@vindex gnus-refer-article-method
If the group you are reading is located on a backend that does not
-support fetching by @code{Message-Id} very well (like @code{nnspool}),
+support fetching by @code{Message-ID} very well (like @code{nnspool}),
you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
would, perhaps, be best if the @sc{nntp} server you consult is the same
as the one that keeps the spool you are reading from updated, but that's
@kindex B M-C-e (Summary)
@findex gnus-summary-expire-articles-now
Expunge all the expirable articles in the group
-(@code{gnus-summary-expire-articles-now}). This means that @strong{all}
+(@code{gnus-summary-expire-articles-now}). This means that @strong{all}
articles that are eligeble for expiry in the current group will
disappear forever into that big @file{/dev/null} in the sky.
* Really Various Summary Commands:: Those pesky non-conformant commands.
@end menu
+@vindex gnus-summary-generate-hook
+@code{gnus-summary-generate-hook} is called as the last thing before
+doing the threading and the generation of the summary buffer. It's
+quite convenient for customizing the threading variables based on what
+data the newsgroup has. This hook is called from the summary buffer
+after most summary buffer variables has been set.
+
@vindex gnus-summary-prepare-hook
@code{gnus-summary-prepare-hook} is called after the summary buffer has
been generated. You might use it to, for instance, highlight lines or
@kindex A D (Summary)
@findex gnus-summary-enter-digest-group
If the current article is a digest, you might use this command to enter
-you into a group based on the current digest to ease reading
-(@code{gnus-summary-enter-digest-group}).
+a group based on the current digest
+(@code{gnus-summary-enter-digest-group}). Gnus will try to guess what
+article type is currently displayed unless you give a prefix to this
+command, which forces a "digest" interpretation.
+
@item C-t
@kindex C-t (Summary)
@findex gnus-summary-toggle-truncation
Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
+
@item =
@kindex = (Summary)
@findex gnus-summary-expand-window
If given a prefix, force an @code{article} window configuration.
@end table
+
@node The Article Buffer
@chapter The Article Buffer
@cindex article buffer
There is a lot of useful information in the head: the name of the person
who wrote the article, the date it was written and the subject of the
article. That's well and nice, but there's also lots of information
-most people do not want to see - what systems the article has passed
-through before reaching you, the @code{Message-Id}, the
-@code{References}, etc. ad nauseum - and you'll probably want to get rid
+most people do not want to see---what systems the article has passed
+through before reaching you, the @code{Message-ID}, the
+@code{References}, etc. ad nauseum---and you'll probably want to get rid
of some of those lines. If you want to keep all those lines in the
article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
You can, of course, write your own functions. The functions are called
from the article buffer, and you can do anything you like, pretty much.
-There is no information that you have to keep in the buffer - you can
+There is no information that you have to keep in the buffer---you can
change everything. However, you shouldn't delete any headers. Instead
make them invisible if you want to make them go away.
@item C-c ^
@kindex C-c ^ (Article)
@findex gnus-article-refer-article
-If point is in the neighborhood of a @code{Message-Id} and you press
+If point is in the neighborhood of a @code{Message-ID} and you press
@kbd{r}, Gnus will try to get that article from the server
(@code{gnus-article-refer-article}).
@item C-c C-m
backend represents a virtual server.
For instance, the @code{nntp} backend may be used to connect to several
-different actual nntp servers, or, perhaps, to many different ports on
-the same actual nntp server. You tell Gnus which backend to use, and
-what parameters to set by specifying a @dfn{select method}.
+different actual @sc{nntp} servers, or, perhaps, to many different ports
+on the same actual @sc{nntp} server. You tell Gnus which backend to
+use, and what parameters to set by specifying a @dfn{select method}.
These select methods specifications can sometimes become quite
-complicated - say, for instance, that you want to read from the nntp
-server @samp{news.funet.fi} on port number @samp{13}, which hangs if
-queried for @sc{nov} headers and has a buggy select. Ahem. Anyways, if
-you had to specify that for each group that used this server, that would
-be too much work, so Gnus offers a way of putting names to methods,
-which is what you do in the server buffer.
+complicated---say, for instance, that you want to read from the
+@sc{nntp} server @samp{news.funet.fi} on port number @samp{13}, which
+hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
+Anyways, if you had to specify that for each group that used this
+server, that would be too much work, so Gnus offers a way of putting
+names to methods, which is what you do in the server buffer.
To enter the server buffer, user the @kbd{^}
(@code{gnus-group-enter-server-mode}) command in the group buffer.
* Server Commands:: Commands to manipulate servers.
* Example Methods:: Examples server specifications.
* Servers & Methods:: You can use server names as select methods.
+* Unavailable Servers:: Some servers you try to contact may be down.
@end menu
@node Server Buffer Format
@table @samp
@item h
-How the news is fetched - the backend name.
+How the news is fetched---the backend name.
@item n
The name of this server.
@item w
-Where the news is to be fetched from - the address.
+Where the news is to be fetched from---the address.
@end table
@node Server Commands
After these two elements, there may be a random number of @var{(variable
form)} pairs.
-To go back to the first example - imagine that you want to read from
+To go back to the first example---imagine that you want to read from
port @code{15} from that machine. This is what the select method should
look like then:
over.
+@node Unavailable Servers
+@section Unavailable Servers
+
+If a server seems to be unreachable, Gnus will mark that server as
+@code{denied}. That means that any subsequent attempt to make contact
+with that server will just be ignored. "It can't be opened," Gnus will
+tell you, without making the least effort to see whether that is
+actually the case or not.
+
+That might seem quite naughty, but it does make sense most of the time.
+Let's say you have 10 groups subscribed to the server
+@samp{nepholococcygia.com}. This server is located somewhere quite far
+away from you, the machine is quite, so it takes 1 minute just to find
+out that it refuses connection from you today. If Gnus were to attempt
+to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
+that. Once it has gotten a single "connection refused", it will regard
+that server as "down".
+
+So, what happens if the machine was only feeling unwell temporarily?
+How do you test to see whether the machine has come up again?
+
+You jump to the server buffer (@pxref{The Server Buffer}) and poke ut
+with the following commands:
+
+@table @kbd
+
+@item O
+@kindex O (Server)
+@findex gnus-server-open-server
+Try to establish connection to the server on the current line
+(@code{gnus-server-open-server}).
+
+@item C
+@kindex C (Server)
+@findex gnus-server-close-server
+Close the connection (if any) to the server
+(@code{gnus-server-close-server}).
+
+@item D
+@kindex D (Server)
+@findex gnus-server-deny-server
+Mark the current server as unreachable
+(@code{gnus-server-deny-server}).
+
+@item R
+@kindex R (Server)
+@findex gnus-server-remove-denials
+Remove all marks to whether Gnus was denied connection from all servers
+(@code{gnus-server-remove-denials}).
+
+@end table
+
+
@node Scoring
@chapter Scoring
@cindex scoring
attention!
@vindex gnus-summary-mark-below
-All articles have a default score (@code{gnus-summary-default-score}).
-This score may be raised or lowered either interactively or by score
-files. Articles that have a score lower than
+All articles have a default score (@code{gnus-summary-default-score}),
+which is 0 by default. This score may be raised or lowered either
+interactively or by score files. Articles that have a score lower than
@code{gnus-summary-mark-below} are marked as read.
Gnus will read any @dfn{score files} that apply to the current group
before generating the summary buffer.
There are several commands in the summary buffer that insert score
-entries based on the current article. You can, for instance, ask Gnus to
+entries based on the current article. You can, for instance, ask Gnus to
lower or increase the score of all articles with a certain subject.
There are two sorts of scoring entries: Permanent and temporary.
@item s
Score on the subject line.
@item x
-Score on the Xref line - i.e., the cross-posting line.
+Score on the Xref line---i.e., the cross-posting line.
@item t
-Score on thread - the References line.
+Score on thread---the References line.
@item d
Score on the date.
@item l
@item gnus-use-scoring
@vindex gnus-use-scoring
If @code{nil}, Gnus will not check for score files, and will not, in
-general, do any score-related work.
+general, do any score-related work. This is @code{t} by default.
@item gnus-kill-killed
@vindex gnus-kill-killed
may save you lots of time, it also means that if you apply a kill file
to a group, and then change the kill file and want to run it over you
group again to kill more articles, it won't work. You have to set this
-variable to @code{t} to do that.
+variable to @code{t} to do that. (It is @code{t} by default.)
@item gnus-kill-files-directory
@vindex gnus-kill-files-directory
All kill and score files will be stored in this directory, which is
initialized from the @samp{SAVEDIR} environment variable by default.
+This is @file{~/News/} by default.
@item gnus-score-file-suffix
@vindex gnus-score-file-suffix
variable is @samp{"ADAPT$"} by default, so no adaptive score files will
be cached.
+@item gnus-save-score
+@vindex gnus-save-score
+If you have really complicated score files, and do lots of batch
+scoring, then you might set this variable to @code{t}. This will make
+Gnus save the scores into the @file{.newsrc.eld} file.
+
+@item gnus-save-score
+@vindex gnus-save-score
+If you have really complicated score files, and do lots of batch
+scoring, then you might set this variable to @code{t}. This will make
+Gnus save the scores into the @file{.newsrc.eld} file.
+
@item gnus-score-interactive-default-score
@vindex gnus-score-interactive-default-score
Score used by all the interactive raise/lower commands to raise/lower
@item gnus-score-find-bnews
@findex gnus-score-find-bnews
-Apply all score files that match, using bnews syntax. For instance, if
-the current group is @samp{gnu.emacs.gnus}, @samp{all.emacs.all.SCORE},
-@samp{not.alt.all.SCORE} and @samp{gnu.all.SCORE} would all apply. In
-short, the instances of @samp{all} in the score file names are
-translated into @samp{.*}, and then a regexp match is done.
+Apply all score files that match, using bnews syntax. This is the
+default. For instance, if the current group is @samp{gnu.emacs.gnus},
+@samp{all.emacs.all.SCORE}, @samp{not.alt.all.SCORE} and
+@samp{gnu.all.SCORE} would all apply. In short, the instances of
+@samp{all} in the score file names are translated into @samp{.*}, and
+then a regexp match is done.
+
+This means that if you have some score entries that you want to apply to
+all groups, then you put those entries in the @file{all.SCORE} file.
If @code{gnus-use-long-file-name} is non-@code{nil}, this won't work
-very will. It will find stuff like @file{gnu/all/SCORE}, but will not
+very will. It will find stuff like @file{gnu/all/SCORE}, but will not
find files like @file{not/gnu/all/SCORE}.
@item gnus-score-find-hierarchical
@findex gnus-score-find-hierarchical
-Apply all score files from all the parent groups.
+Apply all score files from all the parent groups. This means that you
+can't have score files like @file{all.SCORE} or @file{all.emacs.SCORE},
+but you can have @file{SCORE}, @file{comp.SCORE} and
+@file{comp.emacs.SCORE}.
+
@end table
This variable can also be a list of functions. In that case, all these
functions will be called, and all the returned lists of score files will
(orphan -10)
(adapt t)
(files "/hom/larsi/News/gnu.SCORE")
+ (exclude-files "all.SCORE")
(local (gnus-newsgroup-auto-expire t)
(gnus-summary-make-false-root 'empty))
(eval (ding)))
be a string, but on the Lines and Chars headers, this must be an
integer.
@item
-If the second element is present, it should be a number - the @dfn{score
+If the second element is present, it should be a number---the @dfn{score
element}. This number should be an integer in the neginf to posinf
interval. This number is added to the score of the article if the match
is successful. If this element is not present, the
-@code{gnus-score-interactive-default-score} number will be used instead.
+@code{gnus-score-interactive-default-score} number will be used
+instead. This is 1000 by default.
@item
-If the third element is present, it should be a number - the @dfn{date
+If the third element is present, it should be a number---the @dfn{date
element}. This date says when the last time this score entry matched,
which provides a mechanism for expiring the score entries. It this
element is not present, the score entry is permanent. The date is
represented by the number of days since December 31, 1 ce.
@item
-If the fourth element is present, it should be a symbol - the @dfn{type
+If the fourth element is present, it should be a symbol---the @dfn{type
element}. This element specifies what function should be used to see
whether this score entry matches the article. What match types that can
be used depends on what header you wish to perform the match on.
@cindex local variables
The value of this entry should be a list of @code{(VAR VALUE)} pairs.
Each @var{var} will be made buffer-local to the current summary buffer,
-and set to the value specified. This is a convenient, if somewhat
+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.
@end table
@cindex adaptive scoring
If all this scoring is getting you down, Gnus has a way of making it all
-happen automatically - as if by magic. Or rather, as if by artificial
+happen automatically---as if by magic. Or rather, as if by artificial
stupidity, to be precise.
@vindex gnus-use-adaptive-scoring
@end lisp
As you see, each element in this alist has a mark as a key (either a
-variable name or a "real" mark - a character). Following this key is a
+variable name or a "real" mark---a character). Following this key is a
random number of header/score pairs.
-To take @code{gnus-del-mark} as an example - this alist says that all
+To take @code{gnus-del-mark} as an example---this alist says that all
articles that have that mark (i.e., are marked with @samp{D}) will have a
score entry added to lower based on the @code{From} header by -4, and
lowered by @code{Subject} by -1. Change this to fit your prejudices.
+The headers you can score on are @code{from}, @code{subject},
+@code{message-id}, @code{references}, @code{xref}, @code{lines},
+@code{chars} and @code{date}. In addition, you can score on
+@code{followup}, which will create an adaptive score entry that matches
+on the @code{References} header using the @code{Message-ID} of the
+current article, thereby matching the following thread.
+
If you use this scheme, you should set @code{mark-below} to something
-small - like -300, perhaps, to avoid having small random changes result
+small---like -300, perhaps, to avoid having small random changes result
in articles getting marked as read.
After using adaptive scoring for a week or so, Gnus should start to
@vindex gnus-adaptive-file-suffix
The adaptive score entries will be put into a file where the name is the
-group name with @code{gnus-adaptive-file-suffix} appended.
+group name with @code{gnus-adaptive-file-suffix} appended. The default
+is @samp{ADAPT}.
@vindex gnus-score-exact-adapt-limit
When doing adaptive scoring, substring or fuzzy matching would probably
-give you the best results in most cases. However, if the header one
+give you the best results in most cases. However, if the header one
matches is short, the possibility for false positives is great, so if
the length of the match is less than
-@code{gnus-score-exact-adapt-limit}, exact matching will be used. If
+@code{gnus-score-exact-adapt-limit}, exact matching will be used. If
this variable is @code{nil}, exact matching will always be used to avoid
this problem.
If you want to lower the score of articles that have been crossposted to
more than, say, 3 groups:
@lisp
-("xref" (" +[^ ]+:[0-9]+ +[^ ]+:[0-9]+ +[^ ]+:[0-9]+" -1000 nil r))
+("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
@end lisp
@item Matching on the body
-This is generally not a very good idea - it takes a very long time.
+This is generally not a very good idea---it takes a very long time.
Gnus actually has to fetch each individual article from the server. But
you might want to anyway, I guess. Even though there are three match
keys (@code{Head}, @code{Body} and @code{All}), you should choose one
use the @code{gnus-score-search-global-directories} command.
Note that, at present, using this option will slow down group entry
-somewhat. (That is - a lot.)
+somewhat. (That is---a lot.)
If you want to start maintaining score files for other people to use,
just put your score file up for anonymous ftp and announce it to the
@item
Articles that are heavily crossposted are probably junk.
@item
-To lower a single inappropriate article, lower by @code{Message-Id}.
+To lower a single inappropriate article, lower by @code{Message-ID}.
@item
Particularly brilliant authors can be raised on a permanent basis.
@item
@menu
* Interactive:: Making Gnus ask you many questions.
+* Formatting Variables:: How to control the look of the buffers.
* Windows Configuration:: Configuring the Gnus buffer windows.
* Buttons:: Get tendonitis in ten easy steps!
+* Compilation & Init File:: How to speed Gnus up.
+* Daemons:: Gnus can do things behind your back.
+* NoCeM:: How to avoid spam and other fatty foods.
* Various Various:: Things that are really various.
@end menu
If this variable is non-@code{nil}, you are either a newcomer to the
World of Usenet, or you are very cautious, which is a nice thing to be,
really. You will be given questions of the type "Are you sure you want
-to do this?" before doing anything dangerous.
+to do this?" before doing anything dangerous. This is @code{t} by
+default.
+
@item gnus-expert-user
@vindex gnus-expert-user
If this variable is non-@code{nil}, you will never ever be asked any
questions by Gnus. It will simply assume you know what your are doing,
no matter how strange.
+
@item gnus-interactive-catchup
@vindex gnus-interactive-catchup
-Require confirmation before catching up a group if non-@code{nil}.
+Require confirmation before catching up a group if non-@code{nil}. It
+is @code{t} by default.
+
@item gnus-interactive-post
@vindex gnus-interactive-post
If non-@code{nil}, the user will be prompted for a group name when
-posting an article.
+posting an article. It is @code{t} by default.
+
@item gnus-interactive-exit
@vindex gnus-interactive-exit
-Require confirmation before exiting Gnus.
+Require confirmation before exiting Gnus. This variable is @code{t} by
+default.
@end table
+
+@node Formatting Variables
+@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
+@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 annoyed by.
+
+Here's an example format spec (from the group buffer): @samp{"%M%S%5y:
+%(%g%)\n"}. We see that it is indeed extremely ugly, and that there are
+lots of percentages everywhere.
+
+Each @samp{%} element will be replaced by some string or other when the
+buffer in question is generated. @samp{%5y} means "insert the @samp{y}
+spec, and pad with spaces to get a 5-character field". Just like a
+normal format spec, almost.
+
+You can also say @samp{%6,4y}, which means that the field will never be
+more than 6 characters wide and never less than 4 characters wide.
+
+There are also specs for highlighting, and these are shared by all the
+format variables. Text inside the @samp{%(} and @samp{%)} specifiers
+will get the special @code{mouse-face} property set, which means that it
+will be highlighted (with @code{gnus-mouse-face}) when you put the mouse
+pointer over it.
+
+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
+@samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
+
+Here's an alternative recipe for the group buffer:
+
+@lisp
+;; Create three face types.
+(setq gnus-face-1 'bold)
+(setq gnus-face-3 'italic)
+
+;; We want the article count to be in
+;; a bold and green face. So we create
+;; a new face called `my-green-bold'.
+(copy-face 'bold 'my-green-bold)
+;; Set the color.
+(set-face-foreground 'my-green-bold "ForestGreen")
+(setq gnus-face-2 'my-green-bold)
+
+;; Set the new & fancy format.
+(setq gnus-group-line-format
+ "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
+@end lisp
+
+I'm sure you'll be able to use this scheme to create totally unreadable
+and extremely vulgar displays. Have fun!
+
+Currently Gnus uses the following formatting variables:
+@code{gnus-group-line-format}, @code{gnus-summary-line-format},
+@code{gnus-server-line-format}, @code{gnus-topic-line-format},
+@code{gnus-group-mode-line-format},
+@code{gnus-summary-mode-line-format},
+@code{gnus-article-mode-line-format},
+@code{gnus-server-mode-line-format}.
+
+Note that the @samp{%(} specs (and friends) do not make any sense on the
+mode-line variables.
+
+All these format variables can also be random elisp forms. In that
+case, they will be @code{eval}ed to insert the required lines.
+
+@kindex M-x gnus-update-format
+@findex gnus-update-format
+Gnus includes a command to help you while creating your own format
+specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
+update the spec in question and pop you to a buffer where you can
+examine the resulting lisp code to be run to generate the line.
+
+
@node Windows Configuration
@section Windows Configuration
@cindex windows configuration
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.
+
+@node Compilation & Init File
+@section Compilation & Init File
+@cindex compilation
+@cindex init file
+@cindex byte-compilation
+
+@vindex gnus-init-file
+@findex gnus-compile
+When Gnus starts up, it will read the Gnus init file
+@code{gnus-init-file}, which is @file{.gnus} by default. It is
+recommended that you keep any Gnus-related functions that you have
+written in that file. If you want to byte-compile the file, Gnus offers
+the handy @kbd{M-x gnus-compile} function that will do that for you.
+
+That's not really why that function was written, though.
+
+Remember all those line format specification variables?
+@code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
+on. Now, Gnus will of course heed whatever these variables are, but,
+unfortunately, changing them will mean a quite significant slow-down.
+(The default values of these variables have byte-compiled functions
+associated with them, while the user-generated versions do not, of
+course.)
+
+To help with this, you can run @code{gnus-compile} after you've fiddled
+around with the variables and feel that you're (kind of) satisfied.
+This will result in the new specs being byte-compiled, and you'll get
+top speed again.
+
+The result of these byte-compilations will be written to
+@file{.gnus.elc} by default.
+
+Note that Gnus will read @file{.gnus.elc} instead of @file{.gnus} if
+@file{.gnus.elc} exists, so if you change @file{.gnus}, you should
+remove @file{.gnus.elc}.
+
+
+@node Daemons
+@section Daemons
+@cindex demons
+@cindex daemons
+
+Gnus, being larger than any program ever written (allegedly), does lots
+of strange stuff that you may wish to have done while you're not
+present. For instance, you may want it to check for new mail once in a
+while. Or you may want it to close down all connections to all servers
+when you leave Emacs idle. And stuff like that.
+
+Gnus will let you do stuff like that by defining various
+@dfn{handlers}. Each handler consists of three elements: A
+@var{function}, a @var{time}, and an @var{idle} parameter.
+
+Here's an example of a handler that closes connections when Emacs has
+been idle for thirty minutes:
+
+@lisp
+(gnus-demon-close-connections nil 30)
+@end lisp
+
+Here's a handler that scans for PGP headers every hour when Emacs is
+idle:
+
+@lisp
+(gnus-demon-scan-pgp 60 t)
+@end lisp
+
+This @var{time} parameter and than @var{idle} parameter works together
+in a strange, but wonderful fashion. Basically, if @var{idle} is
+@code{nil}, then the function will be called every @var{time} minutes.
+
+If @var{idle} is @code{t}, then the function will be called after
+@var{time} minutes only if Emacs is idle. So if Emacs is never idle,
+the function will never be called. But once Emacs goes idle, the
+function will be called every @var{time} minutes.
+
+If @var{idle} is a number and @var{time} is a number, the function will
+be called every @var{time} minutes only when Emacs has been idle for
+@var{idle} minutes.
+
+If @var{idle} is a number and @var{time} is @code{nil}, the function
+will be called once every time Emacs has been idle for @var{idle}
+minutes.
+
+And if @var{time} is a string, it should look like @samp{"07:31"}, and
+the function will then be called once every day somewhere near that
+time. Modified by the @var{idle} parameter, of course.
+
+@vindex gnus-demon-timestep
+(When I say "minute" here, I really mean @code{gnus-demon-timestep}
+seconds. This is @samp{60} by default. If you change that variable,
+all the timings in the handlers will be affected.)
+
+@vindex gnus-use-demon
+To set the whole thing in motion, though, you have to set
+@code{gnus-use-demon} to @code{t}.
+
+@vindex gnus-use-demon
+To set the whole thing in motion, though, you have to set
+@code{gnus-use-demon} to @code{t}.
+
+So, if you want to add a handler, you could put something like this in
+your @file{.gnus} file:
+
+@findex gnus-demon-add-handler
+@lisp
+(gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
+@end lisp
+
+@findex gnus-demon-add-nocem
+@findex gnus-demon-add-scanmail
+@findex gnus-demon-add-disconnection
+Some ready-made functions to do this has been created:
+@code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, and
+@code{gnus-demon-add-scanmail}. Just put those functions in your
+@file{.gnus} if you want those abilities.
+
+@findex gnus-demon-init
+@findex gnus-demon-cancel
+@vindex gnus-demon-handlers
+If you add handlers to @code{gnus-demon-handlers} directly, you should
+run @code{gnus-demon-init} to make the changes take hold. To cancel all
+daemons, you can use the @code{gnus-demon-cancel} function.
+
+Note that adding daemons can be pretty naughty if you overdo it. Adding
+functions that scan all news and mail from all servers every two seconds
+is a sure-fire way of getting booted off any respectable system. So
+behave.
+
+
+@node NoCeM
+@section NoCeM
+@cindex nocem
+@cindex spam
+
+
+
@node Various Various
@section Various Various
@cindex mode lines
@vindex gnus-verbose
This variable is an integer between zero and ten. The higher the value,
the more messages will be displayed. If this variable is zero, Gnus
-will never flash any messages, if it is seven, most important messages
-will be shown, and if it is ten, Gnus won't ever shut up, but will flash
-so many messages it will make your head swim.
+will never flash any messages, if it is seven (which is the default),
+most important messages will be shown, and if it is ten, Gnus won't ever
+shut up, but will flash so many messages it will make your head swim.
+
@item gnus-updated-mode-lines
@vindex gnus-updated-mode-lines
This is a list of buffers that should keep their mode lines updated.
@vindex gnus-display-type
This variable is symbol indicating the display Emacs is running under.
The symbol should be one of @code{color}, @code{grayscale} or
-@code{mono}. If Gnus guesses this display attribute wrongly, either set
+@code{mono}. If Gnus guesses this display attribute wrongly, either set
this variable in your @file{~/.emacs} or set the resource
@code{Emacs.displayType} in your @file{~/.Xdefaults}.
@item gnus-background-mode
@vindex gnus-background-mode
-This is a symbol indicating the Emacs background brightness. The symbol
-should be one of @code{light} or @code{dark}. If Gnus guesses this
+This is a symbol indicating the Emacs background brightness. The symbol
+should be one of @code{light} or @code{dark}. If Gnus guesses this
frame attribute wrongly, either set this variable in your @file{~/.emacs} or
set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
`gnus-display-type'.
buffer all the time.
@item gnus-visible-headers
Cut down on the headers that are included in the articles to the
-minimum. You can, in fact, make do without them altogether - most of 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.
@item gnus-article-display-hook
@table @code
@item gnus-save-newsrc-file
-If this is @code{nil}, Gnus will never save @file{.newsrc} - it will
+If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
only save @file{.newsrc.eld}. This means that you will not be able to
-use any other newsreaders than Gnus.
+use any other newsreaders than Gnus. This variable is @code{t} by
+default.
+
@item gnus-save-killed-list
If this is @code{nil}, Gnus will not save the list of dead groups. You
should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
-variable to @code{nil}.
+variable to @code{nil}. This variable is @code{t} by default.
+
@end table
+
@node Slow Machine
@section Slow Machine
Set @code{gnus-article-display-hook} to @code{nil} to make article
processing a bit faster.
+
@node Troubleshooting
@chapter Troubleshooting
@cindex troubleshooting
-Gnus works @emph{so} well straight out of the box - I can't imagine any
+Gnus works @emph{so} well straight out of the box---I can't imagine any
problems, really.
Ahem.
@enumerate
+
@item
Make sure your computer is switched on.
+
@item
Make sure that you really load the current Gnus version. If you have
been running @sc{gnus}, you need to exit Emacs and start it up again before
Gnus will work.
+
@item
Try doing an @kbd{M-x gnus-version}. If you get something that looks
like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
flee}, you have some old @file{.el} files lying around. Delete these.
+
@item
Read the help group (@kbd{M h} in the group buffer) for a FAQ and a
how-to.
@end enumerate
-If all else fails, report the problem as a bug,
+If all else fails, report the problem as a bug.
@cindex bugs
@cindex reporting bugs
@findex gnus-bug
If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
-me the backtrace. I will fix bugs, but I can only fix them if you send
+me the backtrace. I will fix bugs, but I can only fix them if you send
me a precise description as to how to reproduce the bug.
-@c If you just need help, you are better off asking on
-@c @samp{gnu.emacs.gnus}.
+You really can never be too detailed in a bug report. Always use the
+@kbd{M-x gnus-bug} command when you make bug reports, even if it creates
+a 10Kb mail each time you use it, and even if you have sent me your
+environment 500 times before. I don't care. I want the full info each
+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 insulting
+me about. Always overexplain 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.
+
+If you just need help, you are better off asking on
+@samp{gnu.emacs.gnus}. I'm not very helpful.
+
+@cindex gnu.emacs.gnus
+@cindex ding mailing list
+You can also ask on the ding mailing list---@samp{ding@@ifi.uio.no}.
+Write to @samp{ding-request@@ifi.uio.no} to subscribe.
+
@node The End
@chapter The End
-Well, that's the manual - you can get on with your life now. Keep in
+Well, that's the manual---you can get on with your life now. Keep in
touch. Say hello to your cats from me.
-My @strong{ghod} - I just can't stand goodbyes. Sniffle.
+My @strong{ghod}---I just can't stand goodbyes. Sniffle.
Ol' Chuck Reznikoff said it pretty well, so I leave the floor to him:
but at the common table.@*
@end quotation
-@node Appendix
-@chapter A Programmer's Guide to Gnus
+@node Appendices
+@chapter Appendices
+
+@menu
+* A Programmer@'s Guide to Gnus:: Rilly, rilly technical stuff.
+* Emacs for Heathens:: A short intruduction to Emacsian terms.
+* Frequently Asked Questions:: A question-and-answer session.
+@end menu
+
+
+@node A Programmer@'s Guide to Gnus
+@section A Programmer@'s Guide to Gnus
It is my hope that other people will figure out smart stuff that Gnus
can do, and that other people will write those smart things as well. To
facilitate that I thought it would be a good idea to describe the inner
-workings of Gnus. And some of the not-so-inner workings, while I'm at
+workings of Gnus. And some of the not-so-inner workings, while I'm at
it.
You can never expect the internals of a program not to change, but I
* Headers:: How Gnus stores headers internally.
* Ranges:: A handy format for storing mucho numbers.
* Group Info:: The group info format.
+* Various File Formats:: Formats of files that Gnus use.
@end menu
@node Backend Interface
-@section Backend Interface
+@subsection Backend Interface
-Gnus doesn't know anything about nntp, spools, mail or virtual groups.
-It only knows how to talk to @dfn{virtual servers}. A virtual server is
-a @dfn{backend} and some @dfn{backend variables}. As examples of the
-first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
+Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
+groups. It only knows how to talk to @dfn{virtual servers}. A virtual
+server is a @dfn{backend} and some @dfn{backend variables}. As examples
+of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
examples of the latter we have @code{nntp-port-number} and
-@code{nnmbox-directory}.
+@code{nnmbox-directory}.
-When Gnus asks for information from a backend -- say @code{nntp} -- on
+When Gnus asks for information from a backend---say @code{nntp}---on
something, it will normally include a virtual server name in the
function parameters. (If not, the backend should use the "current"
virtual server.) For instance, @code{nntp-request-list} takes a virtual
In the examples and definitions I will refer to the imaginary backend
@code{nnchoke}.
-@cindex nnchoke
+@cindex @code{nnchoke}
@menu
* Required Backend Functions:: Functions that must be implemented.
@node Required Backend Functions
-@subsection Required Backend Functions
+@subsubsection Required Backend Functions
@table @code
@item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
@var{articles} is either a range of article numbers or a list of
-@code{Message-ID}s. Current backends do not fully support either - only
+@code{Message-ID}s. Current backends do not fully support either---only
sequences (lists) of article numbers, and most backends do not support
retrieval of @code{Message-ID}s. But they should try for both.
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"
+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
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
@end table
@node Optional Backend Functions
-@subsection Optional Backend Functions
+@subsubsection Optional Backend Functions
@table @code
request that the backend check for incoming articles, in one way or
another. A mail backend will typically read the spool file or query the
POP server when this function is invoked. The @var{group} doesn't have
-to be heeded -- if the backend decides that it is too much work just
+to be heeded---if the backend decides that it is too much work just
scanning for a single group, it may do a total scan of all groups. It
would be nice, however, to keep things local if that's practical.
@node Score File Syntax
-@section Score File Syntax
+@subsection Score File Syntax
Score files are meant to be easily parsable, but yet extremely
mallable. It was decided that something that had the same read syntax
As you can see, white space is needed, but the type and amount of white
space is irrelevant. This means that formatting of the score file is
-left up to the programmer -- if it's simpler to just spew it all out on
+left up to the programmer---if it's simpler to just spew it all out on
one looong line, then that's ok.
The meaning of the various atoms are explained elsewhere in this
manual.
@node Headers
-@section Headers
+@subsection Headers
Gnus uses internally a format for storing article headers that
corresponds to the @sc{nov} format in a mysterious fashion. One could
@dfn{Header} is a severly overloaded term. "Header" is used in RFC1036
to talk about lines in the head of an article (eg., @code{From}). It is
-used by many people as a synonym for "head" -- "the header and the
+used by many people as a synonym for "head"---"the header and the
body". (That should be avoided, in my opinion.) And Gnus uses a format
interanally that it calls "header", which is what I'm talking about
here. This is a 9-element vector, basically, with each header (ouch)
be put in there.
@node Ranges
-@section Ranges
+@subsection Ranges
@sc{gnus} introduced a concept that I found so useful that I've started
using it a lot and have elaborated on it greatly.
@node Group Info
-@section Group Info
+@subsection Group Info
Gnus stores all permanent info on groups in a @dfn{group info} list.
This list is from three to six elements (or more) long and exhaustively
("no.group" 5 (1 . 54324))
("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
- ((tick (15 . 19)) (replied 3 6 (19 . 23)))
+ ((tick (15 . 19)) (replied 3 6 (19 . 3)))
(nnml "")
(auto-expire (to-address "ding@@ifi.uio.no")))
@end example
in pseudo-BNF.
+@node Various File Formats
+@subsection Various File Formats
+
+@menu
+* Active File Format:: Information on articles and groups available.
+* Newsgroups File Format:: Group descriptions.
+@end menu
+
+
+@node Active File Format
+@subsubsection Active File Format
+
+The active file lists all groups that are available on the server in
+question. It also lists the highest and lowest current article numbers
+in each group.
+
+Here's an exceprt from a typical active file:
+
+@example
+soc.motss 296030 293865 y
+alt.binaries.pictures.fractals 3922 3913 n
+comp.sources.unix 1605 1593 m
+comp.binaries.ibm.pc 5097 5089 y
+no.general 1000 900 y
+@end example
+
+Here's a pseudo-BNF definition of this file:
+
+@example
+active = *group-line
+group-line = group space high-number space low-number space flag <NEWLINE>
+group = <non-white-space string>
+space = " "
+high-number = <non-negative integer>
+low-number = <positive integer>
+flag = "y" / "n" / "m" / "j" / "x" / "=" group
+@end example
+
+
+@node Newsgroups File Format
+@subsubsection Newsgroups File Format
+
+The newsgroups file lists groups along with their descriptions. Not all
+groups on the server have to be listed, and not all groups in the file
+have to exist on the server. The file is meant purely as information to
+the user.
+
+The format is quite simple; a group name, a tab, and the description.
+Here's the definition:
+
+@example
+newsgroups = *line
+line = group tab description <NEWLINE>
+group = <non-white-space string>
+tab = <TAB>
+description = <string>
+@end example
+
+
+@node Emacs for Heathens
+@section Emacs for Heathens
+
+Believe it or not, but some people who use Gnus haven't really used
+Emacs much before they embarked on their journey on the Gnus Love Boat.
+If you are one of those unfortunates whom "@kbd{M-C-a}", "kill the
+region", and "set @code{gnus-flargblossen} to an alist where the key is
+a regexp that is used for matching on the group name" are magical
+phrases with little or no meaning, then this appendix is for you. If
+you are already familiar with Emacs, just ignore this and go fondle your
+cat instead.
+
+@menu
+* Keystrokes:: Entering text and executing commands.
+* Emacs Lisp:: The built-in Emacs programming language.
+@end menu
+
+
+@node Keystrokes
+@subsection Keystrokes
+
+@itemize @bullet
+@item
+Q: What is an experienced Emacs user?
+@item
+A: A person who wishes that the terminal had pedals.
+@end itemize
+
+Yes, when you use Emacs, you are apt to use the control key, the shift
+key and the meta key a lot. This is very annoying to some people
+(notably @code{vi}le users), and the rest of us just love the hell out
+of it. Just give up and submit. Emacs really does stand for
+"Escape-Meta-Alt-Control-Shift", and not "Editin 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
+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 curretly 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", 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 down the control
+key, and hold it down while you press @kbd{k}". "Press @kbd{M-C-k}"
+means "press down and hold down the meta key and the control key and
+then press @kbd{k}". Simple, ay?
+
+This is somewhat complicated by the fact that not all keyboards have a
+meta key. In that case you can use the "escape" key. Then @kbd{M-k}
+means "press escape, release escape, press @kbd{k}". That's much more
+work than if you have a meta key, so if that's the case, I respectfully
+suggest you get a real keyboard with a meta key. You can't live without
+it.
+
+
+
+@node Emacs Lisp
+@subsection Emacs Lisp
+
+Emacs is the King of Editors because it's really a Lisp interpreter.
+Each and every key you tap runs some Emacs Lisp code snippet, and since
+Emacs Lisp is an interpreted language, that means that you can configure
+any key to run any random code. You just, like, do it.
+
+Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
+functions. (These are byte-compiled for speed, but it's still
+interpreted.) If you decide that you don't like the way Gnus does
+certain things, it's trivial to have it do something a different way.
+(Well, at least if you know how to write Lisp code.) However, that's
+beyond the scope of this manual, so we are simply going to talk about
+some common constructs that you normally use in your @file{.emacs} file
+to customize Gnus.
+
+If you want to set the variable @code{gnus-florgbnize} to four (4), you
+write the following:
+
+@lisp
+(setq gnus-florgbnize 4)
+@end lisp
+
+This function (really "special form") @code{setq} is the one that can
+set a variable to some value. This is really all you need to know. Now
+you can go and fill your @code{.emacs} file with lots of these to change
+how Gnus works.
+
+If you have put that thing in your @code{.emacs} file, it will be read
+and @code{eval}ed (which is lispese 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.
+
+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
+is the return value of the form you @code{eval}ed.
+
+Some pitfalls:
+
+If the manual says "set @code{gnus-read-active-file} to @code{some}",
+that means:
+
+@lisp
+(setq gnus-read-active-file 'some)
+@end lisp
+
+On the other hand, if the manual says "set @code{gnus-nntp-server} to
+@samp{"nntp.ifi.uio.no"}", that means:
+
+@lisp
+(setq gnus-nntp-server "nntp.ifi.uio.no")
+@end lisp
+
+So be careful not to mix up strings (the latter) with symbols (the
+former). The manual is unambiguous, but it can be confusing.
+
+
+@include gnus-faq.texi
+
@node Index
@chapter Index
@printindex cp
projects / gnus / blobdiff