1 \input texinfo @c -*-texinfo-*-
4 @settitle September Gnus Manual
11 @setchapternewpage odd
15 \documentclass[twoside,a4paper,openright]{book}
16 \usepackage[latin1]{inputenc}
17 % \usepackage{fontenc}
19 \usepackage{pagestyle}
21 % \usepackage{ifitricks}
22 \fontfamily{bembo}\selectfont
27 \newcommand{\gnuschaptername}{}
28 \newcommand{\gnussectionname}{}
30 \newcommand{\gnusbackslash}{/}
32 \newcommand{\gnusxref}[1]{See ``#1'' on page \pageref{#1}}
33 \newcommand{\gnuspxref}[1]{see ``#1'' on page \pageref{#1}}
35 \newcommand{\gnuskindex}[1]{\index{#1}}
36 \newcommand{\gnusindex}[1]{\index{#1}}
38 \newcommand{\gnustt}[1]{{\textbf{\textsf{#1}}}}
39 \newcommand{\gnuscode}[1]{\gnustt{#1}}
40 \newcommand{\gnussamp}[1]{``\gnustt{#1}''}
41 \newcommand{\gnuslisp}[1]{\gnustt{#1}}
42 \newcommand{\gnuskbd}[1]{`\gnustt{#1}'}
43 \newcommand{\gnusfile}[1]{`\gnustt{#1}'}
44 \newcommand{\gnusdfn}[1]{\textit{#1}}
45 \newcommand{\gnusi}[1]{\textit{#1}}
46 \newcommand{\gnusstrong}[1]{\textbf{#1}}
47 \newcommand{\gnusemph}[1]{\textit{#1}}
48 \newcommand{\gnusvar}[1]{\textsl{\textsf{#1}}}
49 \newcommand{\gnussc}[1]{\textsc{#1}}
50 \newcommand{\gnustitle}[1]{{\huge\textbf{#1}}}
51 \newcommand{\gnusauthor}[1]{{\large\textbf{#1}}}
53 \newcommand{\gnusbullet}{{${\bullet}$}}
54 \newcommand{\gnusdollar}{\$}
55 \newcommand{\gnusampersand}{\&}
56 \newcommand{\gnuspercent}{\%}
57 \newcommand{\gnushash}{\#}
58 \newcommand{\gnushat}{\symbol{"5E}}
59 \newcommand{\gnusunderline}{\symbol{"5F}}
60 \newcommand{\gnustilde}{\symbol{"7E}}
61 \newcommand{\gnusless}{{$<$}}
62 \newcommand{\gnusgreater}{{$>$}}
64 \newcommand{\gnushead}{\raisebox{-1cm}{\epsfig{figure=gnus-head.eps,height=1cm}}}
65 \newcommand{\gnusinteresting}{
66 \marginpar[\hspace{2.5cm}\gnushead]{\gnushead}
69 \newcommand{\gnuschapter}[1]{
70 \renewcommand{\gnussectionname}{}
72 \renewcommand{\gnuschaptername}{#1}
74 % \epsfig{figure=gnus-herd-\arabic{chapter}.eps,height=15cm}
78 \newcommand{\gnusitemx}[1]{\vspace{-\itemsep}\item#1}
80 \newcommand{\gnussection}[1]{
81 \renewcommand{\gnussectionname}{#1}
85 \newenvironment{codelist}%
90 \newenvironment{kbdlist}%
96 \newenvironment{dfnlist}%
101 \newenvironment{stronglist}%
106 \newenvironment{samplist}%
111 \newenvironment{varlist}%
116 \newenvironment{emphlist}%
128 \makebox[\headtextwidth]{
130 \textbf{\arabic{chapter}.\arabic{section}}
131 \textbf{\gnussectionname\hfill\arabic{page}}
139 \makebox[\headtextwidth]{
140 \textbf{\arabic{page}\hfill\gnuschaptername}
149 \raisebox{-0.5cm}{\epsfig{figure=gnus-big-logo.eps,height=1cm}}
151 \raisebox{-0.5cm}{\epsfig{figure=gnus-big-logo.eps,height=1cm}}
165 %\addtolength{\oddsidemargin}{-5cm}
166 %\addtolength{\evensidemargin}{-5cm}
168 \addtolength{\textheight}{2cm}
170 \gnustitle{\gnustitlename}\\
173 \hspace*{-1cm}\epsfig{figure=gnus-big-logo.eps,height=15cm}
176 \gnusauthor{by Lars Magne Ingebrigtsen}
183 \thispagestyle{empty}
185 Copyright \copyright{} 1995,96 Free Software Foundation, Inc.
187 Permission is granted to make and distribute verbatim copies of
188 this manual provided the copyright notice and this permission notice
189 are preserved on all copies.
191 Permission is granted to copy and distribute modified versions of this
192 manual under the conditions for verbatim copying, provided that the
193 entire resulting derived work is distributed under the terms of a
194 permission notice identical to this one.
196 Permission is granted to copy and distribute translations of this manual
197 into another language, under the above conditions for modified versions.
206 This file documents Gnus, the GNU Emacs newsreader.
208 Copyright (C) 1995,96 Free Software Foundation, Inc.
210 Permission is granted to make and distribute verbatim copies of
211 this manual provided the copyright notice and this permission notice
212 are preserved on all copies.
215 Permission is granted to process this file through Tex and print the
216 results, provided the printed document carries copying permission
217 notice identical to this one except for the removal of this paragraph
218 (this paragraph not being relevant to the printed manual).
221 Permission is granted to copy and distribute modified versions of this
222 manual under the conditions for verbatim copying, provided also that the
223 entire resulting derived work is distributed under the terms of a
224 permission notice identical to this one.
226 Permission is granted to copy and distribute translations of this manual
227 into another language, under the above conditions for modified versions.
233 @title September Gnus Manual
235 @author by Lars Magne Ingebrigtsen
238 @vskip 0pt plus 1filll
239 Copyright @copyright{} 1995,96 Free Software Foundation, Inc.
241 Permission is granted to make and distribute verbatim copies of
242 this manual provided the copyright notice and this permission notice
243 are preserved on all copies.
245 Permission is granted to copy and distribute modified versions of this
246 manual under the conditions for verbatim copying, provided that the
247 entire resulting derived work is distributed under the terms of a
248 permission notice identical to this one.
250 Permission is granted to copy and distribute translations of this manual
251 into another language, under the above conditions for modified versions.
260 @top The Gnus Newsreader
264 You can read news (and mail) from within Emacs by using Gnus. The news
265 can be gotten by any nefarious means you can think of---@sc{nntp}, local
266 spool or your mbox file. All at the same time, if you want to push your
274 \thispagestyle{empty}
277 Gnus is the advanced, self-documenting, customizable, extensible
278 unreal-time newsreader for GNU Emacs.
280 Oops. That sounds oddly familiar, so let's start over again to avoid
281 being accused of plagiarism:
283 Gnus is a message-reading laboratory. It will let you look at just
284 about anything as if it were a newsgroup. You can read mail with it,
285 you can browse directories with it, you can @code{ftp} with it---you can
286 even read news with it!
288 Gnus tries to empower people who read news the same way Emacs empowers
289 people who edit text. Gnus sets no limits to what the user should be
290 allowed to do. Users are encouraged to extend Gnus to make it behave
291 like they want it to behave. A program should not control people;
292 people should be empowered to do what they want by using (or abusing)
299 * Starting Up:: Finding news can be a pain.
300 * The Group Buffer:: Selecting, subscribing and killing groups.
301 * The Summary Buffer:: Reading, saving and posting articles.
302 * The Article Buffer:: Displaying and handling articles.
303 * Composing Messages:: Information on sending mail and news.
304 * Select Methods:: Gnus reads all messages from various select methods.
305 * Scoring:: Assigning values to articles.
306 * Various:: General purpose settings.
307 * The End:: Farewell and goodbye.
308 * Appendices:: Terminology, Emacs intro, FAQ, History, Internals.
309 * Index:: Variable, function and concept index.
310 * Key Index:: Key Index.
315 @chapter Starting Gnus
320 If your system administrator has set things up properly, starting Gnus
321 and reading news is extremely easy---you just type @kbd{M-x gnus} in
324 @findex gnus-other-frame
325 @kindex M-x gnus-other-frame
326 If you want to start Gnus in a different frame, you can use the command
327 @kbd{M-x gnus-other-frame} instead.
329 If things do not go smoothly at startup, you have to twiddle some
333 * Finding the News:: Choosing a method for getting news.
334 * The First Time:: What does Gnus do the first time you start it?
335 * The Server is Down:: How can I read my mail then?
336 * Slave Gnusii:: You can have more than one Gnus active at a time.
337 * Fetching a Group:: Starting Gnus just to read a group.
338 * New Groups:: What is Gnus supposed to do with new groups?
339 * Startup Files:: Those pesky startup files---@file{.newsrc}.
340 * Auto Save:: Recovering from a crash.
341 * The Active File:: Reading the active file over a slow line Takes Time.
342 * Startup Variables:: Other variables you might change.
346 @node Finding the News
347 @section Finding the News
349 @vindex gnus-select-method
351 The @code{gnus-select-method} variable says where Gnus should look for
352 news. This variable should be a list where the first element says
353 @dfn{how} and the second element says @dfn{where}. This method is your
354 native method. All groups that are not fetched with this method are
357 For instance, if the @samp{news.somewhere.edu} @sc{nntp} server is where
358 you want to get your daily dosage of news from, you'd say:
361 (setq gnus-select-method '(nntp "news.somewhere.edu"))
364 If you want to read directly from the local spool, say:
367 (setq gnus-select-method '(nnspool ""))
370 If you can use a local spool, you probably should, as it will almost
371 certainly be much faster.
373 @vindex gnus-nntpserver-file
375 @cindex @sc{nntp} server
376 If this variable is not set, Gnus will take a look at the
377 @code{NNTPSERVER} environment variable. If that variable isn't set,
378 Gnus will see whether @code{gnus-nntpserver-file}
379 (@file{/etc/nntpserver} by default) has any opinions on the matter. If
380 that fails as well, Gnus will will try to use the machine that is
381 running Emacs as an @sc{nntp} server. That's a long-shot, though.
383 @vindex gnus-nntp-server
384 If @code{gnus-nntp-server} is set, this variable will override
385 @code{gnus-select-method}. You should therefore set
386 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
388 @vindex gnus-secondary-servers
389 You can also make Gnus prompt you interactively for the name of an
390 @sc{nntp} server. If you give a non-numerical prefix to @code{gnus}
391 (i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
392 in the @code{gnus-secondary-servers} list (if any). You can also just
393 type in the name of any server you feel like visiting.
395 @findex gnus-group-browse-foreign-server
397 However, if you use one @sc{nntp} server regularly and are just
398 interested in a couple of groups from a different server, you would be
399 better served by using the @kbd{B} command in the group buffer. It will
400 let you have a look at what groups are available, and you can subscribe
401 to any of the groups you want to. This also makes @file{.newsrc}
402 maintenance much tidier. @xref{Foreign Groups}.
404 @vindex gnus-secondary-select-methods
406 A slightly different approach to foreign groups is to set the
407 @code{gnus-secondary-select-methods} variable. The select methods
408 listed in this variable are in many ways just as native as the
409 @code{gnus-select-method} server. They will also be queried for active
410 files during startup (if that's required), and new newsgroups that
411 appear on these servers will be subscribed (or not) just as native
414 For instance, if you use the @code{nnmbox} backend to read your mail, you
415 would typically set this variable to
418 (setq gnus-secondary-select-methods '((nnmbox "")))
423 @section The First Time
424 @cindex first time usage
426 If no startup files exist, Gnus will try to determine what groups should
427 be subscribed by default.
429 @vindex gnus-default-subscribed-newsgroups
430 If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
431 will subscribe you to just those groups in that list, leaving the rest
432 killed. Your system administrator should have set this variable to
435 Since she hasn't, Gnus will just subscribe you to a few arbitrarily
436 picked groups (i.e., @samp{*.newusers}). (@dfn{Arbitrary} is here
437 defined as @dfn{whatever Lars thinks you should read}.)
439 You'll also be subscribed to the Gnus documentation group, which should
440 help you with most common problems.
442 If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
443 use the normal functions for handling new groups, and not do anything
447 @node The Server is Down
448 @section The Server is Down
449 @cindex server errors
451 If the default server is down, Gnus will understandably have some
452 problems starting. However, if you have some mail groups in addition to
453 the news groups, you may want to start Gnus anyway.
455 Gnus, being the trusting sort of program, will ask whether to proceed
456 without a native select method if that server can't be contacted. This
457 will happen whether the server doesn't actually exist (i.e., you have
458 given the wrong address) or the server has just momentarily taken ill
459 for some reason or other. If you decide to continue and have no foreign
460 groups, you'll find it difficult to actually do anything in the group
461 buffer. But, hey, that's your problem. Blllrph!
463 @findex gnus-no-server
465 If you know that the server is definitely down, or you just want to read
466 your mail without bothering with the server at all, you can use the
467 @code{gnus-no-server} command to start Gnus. That might come in handy
468 if you're in a hurry as well.
472 @section Slave Gnusiï
475 You might want to run more than one Emacs with more than one Gnus at the
476 same time. If you are using different @file{.newsrc} files (eg., if you
477 are using the two different Gnusiï to read from two different servers),
478 that is no problem whatsoever. You just do it.
480 The problem appears when you want to run two Gnusiï that use the same
483 To work around that problem some, we here at the Think-Tank at the Gnus
484 Towers have come up with a new concept: @dfn{Masters} and
485 @dfn{servants}. (We have applied for a patent on this concept, and have
486 taken out a copyright on those words. If you wish to use those words in
487 conjunction with each other, you have to send $1 per usage instance to
488 me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
489 Applications}) will be much more expensive, of course.)
491 Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
492 however you do it). Each subsequent slave Gnusiï should be started with
493 @kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
494 files, but instead save @dfn{slave files} that contains information only
495 on what groups have been read in the slave session. When a master Gnus
496 starts, it will read (and delete) these slave files, incorporating all
497 information from them. (The slave files will be read in the sequence
498 they were created, so the latest changes will have precedence.)
500 Information from the slave files has, of course, precedence over the
501 information in the normal (i. e., master) @code{.newsrc} file.
504 @node Fetching a Group
505 @section Fetching a Group
507 @findex gnus-fetch-group
508 It it sometime convenient to be able to just say ``I want to read this
509 group and I don't care whether Gnus has been started or not''. This is
510 perhaps more useful for people who write code than for users, but the
511 command @code{gnus-fetch-group} provides this functionality in any case.
512 It takes the group name as a parameter.
519 @vindex gnus-subscribe-newsgroup-method
520 What Gnus does when it encounters a new group is determined by the
521 @code{gnus-subscribe-newsgroup-method} variable.
523 This variable should contain a function. Some handy pre-fab values
528 @item gnus-subscribe-zombies
529 @vindex gnus-subscribe-zombies
530 Make all new groups zombies. You can browse the zombies later (with
531 @kbd{A z}) and either kill them all off properly, or subscribe to them.
534 @item gnus-subscribe-randomly
535 @vindex gnus-subscribe-randomly
536 Subscribe all new groups randomly.
538 @item gnus-subscribe-alphabetically
539 @vindex gnus-subscribe-alphabetically
540 Subscribe all new groups alphabetically.
542 @item gnus-subscribe-hierarchically
543 @vindex gnus-subscribe-hierarchically
544 Subscribe all new groups hierarchically.
546 @item gnus-subscribe-interactively
547 @vindex gnus-subscribe-interactively
548 Subscribe new groups interactively. This means that Gnus will ask
549 you about @strong{all} new groups.
551 @item gnus-subscribe-killed
552 @vindex gnus-subscribe-killed
557 @vindex gnus-subscribe-hierarchical-interactive
558 A closely related variable is
559 @code{gnus-subscribe-hierarchical-interactive}. (That's quite a
560 mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a
561 hierarchical fashion whether to subscribe to new groups or not. Gnus
562 will ask you for each sub-hierarchy whether you want to descend the
565 One common mistake is to set the variable a few paragraphs above to
566 @code{gnus-subscribe-hierarchical-interactive}. This is an error. This
567 will not work. This is ga-ga. So don't do it.
569 A nice and portable way to control which new newsgroups should be
570 subscribed (or ignored) is to put an @dfn{options} line at the start of
571 the @file{.newsrc} file. Here's an example:
574 options -n !alt.all !rec.all sci.all
577 @vindex gnus-subscribe-options-newsgroup-method
578 This line obviously belongs to a serious-minded intellectual scientific
579 person (or she may just be plain old boring), because it says that all
580 groups that have names beginning with @samp{alt} and @samp{rec} should
581 be ignored, and all groups with names beginning with @samp{sci} should
582 be subscribed. Gnus will not use the normal subscription method for
583 subscribing these groups.
584 @code{gnus-subscribe-options-newsgroup-method} is used instead. This
585 variable defaults to @code{gnus-subscribe-alphabetically}.
587 @vindex gnus-options-not-subscribe
588 @vindex gnus-options-subscribe
589 If you don't want to mess with your @file{.newsrc} file, you can just
590 set the two variables @code{gnus-options-subscribe} and
591 @code{gnus-options-not-subscribe}. These two variables do exactly the
592 same as the @file{.newsrc} @samp{options -n} trick. Both are regexps,
593 and if the the new group matches the former, it will be unconditionally
594 subscribed, and if it matches the latter, it will be ignored.
596 @vindex gnus-auto-subscribed-groups
597 Yet another variable that meddles here is
598 @code{gnus-auto-subscribed-groups}. It works exactly like
599 @code{gnus-options-subscribe}, and is therefore really superfluous, but I
600 thought it would be nice to have two of these. This variable is more
601 meant for setting some ground rules, while the other variable is used
602 more for user fiddling. By default this variable makes all new groups
603 that come from mail backends (@code{nnml}, @code{nnbabyl},
604 @code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you
605 don't like that, just set this variable to @code{nil}.
607 @vindex gnus-check-new-newsgroups
608 If you are satisfied that you really never want to see any new groups,
609 you could set @code{gnus-check-new-newsgroups} to @code{nil}. This will
610 also save you some time at startup. Even if this variable is
611 @code{nil}, you can always subscribe to the new groups just by pressing
612 @kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
613 is @code{t} by default.
615 Gnus normally determines whether a group is new or not by comparing the
616 list of groups from the active file(s) with the lists of subscribed and
617 dead groups. This isn't a particularly fast method. If
618 @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
619 server for new groups since the last time. This is both faster &
620 cheaper. This also means that you can get rid of the list of killed
621 groups altogether, so you may set @code{gnus-save-killed-list} to
622 @code{nil}, which will save time both at startup, at exit, and all over.
623 Saves disk space, too. Why isn't this the default, then?
624 Unfortunately, not all servers support this command.
626 I bet I know what you're thinking now: How do I find out whether my
627 server supports @code{ask-server}? No? Good, because I don't have a
628 fail-safe answer. I would suggest just setting this variable to
629 @code{ask-server} and see whether any new groups appear within the next
630 few days. If any do, then it works. If any don't, then it doesn't
631 work. I could write a function to make Gnus guess whether the server
632 supports @code{ask-server}, but it would just be a guess. So I won't.
633 You could @code{telnet} to the server and say @code{HELP} and see
634 whether it lists @samp{NEWGROUPS} among the commands it understands. If
635 it does, then it might work. (But there are servers that lists
636 @samp{NEWGROUPS} without supporting the function properly.)
638 This variable can also be a list of select methods. If so, Gnus will
639 issue an @code{ask-server} command to each of the select methods, and
640 subscribe them (or not) using the normal methods. This might be handy
641 if you are monitoring a few servers for new groups. A side effect is
642 that startup will take much longer, so you can meditate while waiting.
643 Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss.
647 @section Startup Files
648 @cindex startup files
651 Now, you all know about the @file{.newsrc} file. All subscription
652 information is traditionally stored in this file.
654 Things got a bit more complicated with @sc{gnus}. In addition to
655 keeping the @file{.newsrc} file updated, it also used a file called
656 @file{.newsrc.el} for storing all the information that didn't fit into
657 the @file{.newsrc} file. (Actually, it also duplicated everything in
658 the @file{.newsrc} file.) @sc{gnus} would read whichever one of these
659 files was the most recently saved, which enabled people to swap between
660 @sc{gnus} and other newsreaders.
662 That was kinda silly, so Gnus went one better: In addition to the
663 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
664 @file{.newsrc.eld}. It will read whichever of these files that are most
665 recent, but it will never write a @file{.newsrc.el} file.
667 @vindex gnus-save-newsrc-file
668 You can turn off writing the @file{.newsrc} file by setting
669 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
670 the file and save some space, as well as making exit from Gnus faster.
671 However, this will make it impossible to use other newsreaders than
672 Gnus. But hey, who would want to, right?
674 @vindex gnus-save-killed-list
675 If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus
676 will not save the list of killed groups to the startup file. This will
677 save both time (when starting and quitting) and space (on disk). It
678 will also means that Gnus has no record of what groups are new or old,
679 so the automatic new groups subscription methods become meaningless.
680 You should always set @code{gnus-check-new-newsgroups} to @code{nil} or
681 @code{ask-server} if you set this variable to @code{nil} (@pxref{New
684 @vindex gnus-startup-file
685 The @code{gnus-startup-file} variable says where the startup files are.
686 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
687 file being whatever that one is with a @samp{.eld} appended.
689 @vindex gnus-save-newsrc-hook
690 @vindex gnus-save-quick-newsrc-hook
691 @vindex gnus-save-standard-newsrc-hook
692 @code{gnus-save-newsrc-hook} is called before saving any of the newsrc
693 files, while @code{gnus-save-quick-newsrc-hook} is called just before
694 saving the @file{.newsrc.eld} file, and
695 @code{gnus-save-standard-newsrc-hook} is called just before saving the
696 @file{.newsrc} file. The latter two are commonly used to turn version
697 control on or off. Version control is off by default when saving the
706 Whenever you do something that changes the Gnus data (reading articles,
707 catching up, killing/subscribing groups), the change is added to a
708 special @dfn{dribble buffer}. This buffer is auto-saved the normal
709 Emacs way. If your Emacs should crash before you have saved the
710 @file{.newsrc} files, all changes you have made can be recovered from
713 If Gnus detects this file at startup, it will ask the user whether to
714 read it. The auto save file is deleted whenever the real startup file is
717 @vindex gnus-use-dribble-file
718 If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
719 maintain a dribble buffer. The default is @code{t}.
721 @vindex gnus-dribble-directory
722 Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
723 this variable is @code{nil}, which it is by default, Gnus will dribble
724 into the directory where the @file{.newsrc} file is located. (This is
725 normally the user's home directory.) The dribble file will get the same
726 file permissions as the @code{.newsrc} file.
729 @node The Active File
730 @section The Active File
732 @cindex ignored groups
734 When Gnus starts, or indeed whenever it tries to determine whether new
735 articles have arrived, it reads the active file. This is a very large
736 file that lists all the active groups and articles on the server.
738 @vindex gnus-ignored-newsgroups
739 Before examining the active file, Gnus deletes all lines that match the
740 regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject
741 any groups with bogus names, but you can use this variable to make Gnus
742 ignore hierarchies you aren't ever interested in. However, this is not
743 recommended. In fact, it's highly discouraged. Instead, @pxref{New
744 Groups} for an overview of other variables that can be used instead.
747 @c @code{nil} by default, and will slow down active file handling somewhat
748 @c if you set it to anything else.
750 @vindex gnus-read-active-file
752 The active file can be rather Huge, so if you have a slow network, you
753 can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
754 reading the active file. This variable is @code{t} by default.
756 Gnus will try to make do by getting information just on the groups that
757 you actually subscribe to.
759 Note that if you subscribe to lots and lots of groups, setting this
760 variable to @code{nil} will probably make Gnus slower, not faster. At
761 present, having this variable @code{nil} will slow Gnus down
762 considerably, unless you read news over a 2400 baud modem.
764 This variable can also have the value @code{some}. Gnus will then
765 attempt to read active info only on the subscribed groups. On some
766 servers this is quite fast (on sparkling, brand new INN servers that
767 support the @code{LIST ACTIVE group} command), on others this isn't fast
768 at all. In any case, @code{some} should be faster than @code{nil}, and
769 is certainly faster than @code{t} over slow lines.
771 If this variable is @code{nil}, Gnus will ask for group info in total
772 lock-step, which isn't very fast. If it is @code{some} and you use an
773 @sc{nntp} server, Gnus will pump out commands as fast as it can, and
774 read all the replies in one swoop. This will normally result in better
775 performance, but if the server does not support the aforementioned
776 @code{LIST ACTIVE group} command, this isn't very nice to the server.
778 In any case, if you use @code{some} or @code{nil}, you should definitely
779 kill all groups that you aren't interested in to speed things up.
782 @node Startup Variables
783 @section Startup Variables
788 @vindex gnus-load-hook
789 A hook that is run while Gnus is being loaded. Note that this hook will
790 normally be run just once in each Emacs session, no matter how many
791 times you start Gnus.
793 @item gnus-startup-hook
794 @vindex gnus-startup-hook
795 A hook that is run after starting up Gnus successfully.
797 @item gnus-check-bogus-newsgroups
798 @vindex gnus-check-bogus-newsgroups
799 If non-@code{nil}, Gnus will check for and delete all bogus groups at
800 startup. A @dfn{bogus group} is a group that you have in your
801 @file{.newsrc} file, but doesn't exist on the news server. Checking for
802 bogus groups can take quite a while, so to save time and resources it's
803 best to leave this option off, and do the checking for bogus groups once
804 in a while from the group buffer instead (@pxref{Group Maintenance}).
806 @item gnus-inhibit-startup-message
807 @vindex gnus-inhibit-startup-message
808 If non-@code{nil}, the startup message won't be displayed. That way,
809 your boss might not notice that you are reading news instead of doing
812 @item gnus-no-groups-message
813 @vindex gnus-no-groups-message
814 Message displayed by Gnus when no groups are available.
818 @node The Group Buffer
819 @chapter The Group Buffer
822 The @dfn{group buffer} lists all (or parts) of the available groups. It
823 is the first buffer shown when Gnus starts, and will never be killed as
824 long as Gnus is active.
827 * Group Buffer Format:: Information listed and how you can change it.
828 * Group Maneuvering:: Commands for moving in the group buffer.
829 * Selecting a Group:: Actually reading news.
830 * Subscription Commands:: Unsubscribing, killing, subscribing.
831 * Group Levels:: Levels? What are those, then?
832 * Group Score:: A mechanism for finding out what groups you like.
833 * Marking Groups:: You can mark groups for later processing.
834 * Foreign Groups:: Creating and editing groups.
835 * Group Parameters:: Each group may have different parameters set.
836 * Listing Groups:: Gnus can list various subsets of the groups.
837 * Sorting Groups:: Re-arrange the group order.
838 * Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
839 * Browse Foreign Server:: You can browse a server. See what it has to offer.
840 * Exiting Gnus:: Stop reading news and get some work done.
841 * Group Topics:: A folding group mode divided into topics.
842 * Misc Group Stuff:: Other stuff that you can to do.
846 @node Group Buffer Format
847 @section Group Buffer Format
848 @cindex group buffer format
851 * Group Line Specification:: Deciding how the group buffer is to look.
852 * Group Modeline Specification:: The group buffer modeline.
853 * Group Highlighting:: Having nice colors in the group buffer.
857 @node Group Line Specification
858 @subsection Group Line Specification
860 The default format of the group buffer is nice and dull, but you can
861 make it as exciting and ugly as you feel like.
863 Here's a couple of example group lines:
866 25: news.announce.newusers
867 * 0: alt.fan.andrea-dworkin
872 You can see that there are 25 unread articles in
873 @samp{news.announce.newusers}. There are no unread articles, but some
874 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
875 asterisk at the beginning of the line?)
877 @vindex gnus-group-line-format
878 You can change that format to whatever you want by fiddling with the
879 @code{gnus-group-line-format} variable. This variable works along the
880 lines of a @code{format} specification, which is pretty much the same as
881 a @code{printf} specifications, for those of you who use (feh!) C.
882 @xref{Formatting Variables}.
884 The default value that produced those lines above is
885 @samp{%M%S%5y: %(%g%)\n}.
887 There should always be a colon on the line; the cursor always moves to
888 the colon after performing an operation. Nothing else is required---not
889 even the group name. All displayed text is just window dressing, and is
890 never examined by Gnus. Gnus stores all real information it needs using
893 (Note that if you make a really strange, wonderful, spreadsheet-like
894 layout, everybody will believe you are hard at work with the accounting
895 instead of wasting time reading news.)
897 Here's a list of all available format characters:
902 Only marked articles.
905 Whether the group is subscribed.
908 Level of subscribedness.
911 Number of unread articles.
914 Number of dormant articles.
917 Number of ticked articles.
920 Number of read articles.
923 Total number of articles.
926 Number of unread, unticked, non-dormant articles.
929 Number of ticked and dormant articles.
938 Newsgroup description.
941 @samp{m} if moderated.
944 @samp{(m)} if moderated.
953 A string that looks like @samp{<%s:%n>} if a foreign select method is
957 Indentation based on the level of the topic (@pxref{Group Topics}).
960 @vindex gnus-group-uncollapsed-levels
961 Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels}
962 variable says how many levels to leave at the end of the group name.
963 The default is @code{1}.
966 User defined specifier. The next character in the format string should
967 be a letter. @sc{gnus} will call the function
968 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
969 following @samp{%u}. The function will be passed the current headers as
970 argument. The function should return a string, which will be inserted
971 into the buffer just like information from any other specifier.
975 All the ``number-of'' specs will be filled with an asterisk (@samp{*})
976 if no info is available---for instance, if it is a non-activated foreign
977 group, or a bogus (or semi-bogus) native group.
980 @node Group Modeline Specification
981 @subsection Group Modeline Specification
983 @vindex gnus-group-mode-line-format
984 The mode line can be changed by setting
985 (@code{gnus-group-mode-line-format}). It doesn't understand that many
990 The native news server.
992 The native select method.
996 @node Group Highlighting
997 @subsection Group Highlighting
999 @vindex gnus-group-highlight
1000 Highlighting in the group buffer is controlled by the
1001 @code{gnus-group-highlight} variable. This is an alist with elements
1002 that look like @var{(form . face)}. If @var{form} evaluates to
1003 something non-@code{nil}, the @var{face} will be used on the line.
1005 Here's an example value for this variable that might look nice if the
1009 (setq gnus-group-highlight
1011 ,(custom-face-lookup "Red" nil nil t nil nil))
1012 ((and (< level 3) (zerop unread)) .
1013 ,(custom-face-lookup "SeaGreen" nil nil t nil nil))
1015 ,(custom-face-lookup "SpringGreen" nil nil t nil nil))
1017 ,(custom-face-lookup "SteelBlue" nil nil t nil nil))
1019 ,(custom-face-lookup "SkyBlue" nil nil t nil nil))
1023 Variables that are dynamically bound when the forms are evaluated
1030 The number of unread articles in the group.
1034 Whether the group is a mail group.
1036 The level of the group.
1038 The score of the group.
1040 The number of ticked articles in the group.
1042 When using the topic minor mode, this variable is bound to the current
1043 topic being inserted.
1046 When the forms are @code{eval}ed, point is at the beginning of the line
1047 of the group in question, so you can use many of the normal Gnus
1048 functions for snarfing info on the group.
1050 @vindex gnus-group-update-hook
1051 @findex gnus-group-highlight-line
1052 @code{gnus-group-update-hook} is called when a group line is changed.
1053 It will not be called when @code{gnus-visual} is @code{nil}. This hook
1054 calls @code{gnus-group-highlight-line} by default.
1057 @node Group Maneuvering
1058 @section Group Maneuvering
1059 @cindex group movement
1061 All movement commands understand the numeric prefix and will behave as
1062 expected, hopefully.
1068 @findex gnus-group-next-unread-group
1069 Go to the next group that has unread articles
1070 (@code{gnus-group-next-unread-group}).
1077 @findex gnus-group-prev-unread-group
1078 Go to the previous group group that has unread articles
1079 (@code{gnus-group-prev-unread-group}).
1083 @findex gnus-group-next-group
1084 Go to the next group (@code{gnus-group-next-group}).
1088 @findex gnus-group-prev-group
1089 Go to the previous group (@code{gnus-group-prev-group}).
1093 @findex gnus-group-next-unread-group-same-level
1094 Go to the next unread group on the same level (or lower)
1095 (@code{gnus-group-next-unread-group-same-level}).
1099 @findex gnus-group-prev-unread-group-same-level
1100 Go to the previous unread group on the same level (or lower)
1101 (@code{gnus-group-prev-unread-group-same-level}).
1104 Three commands for jumping to groups:
1110 @findex gnus-group-jump-to-group
1111 Jump to a group (and make it visible if it isn't already)
1112 (@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
1117 @findex gnus-group-best-unread-group
1118 Jump to the unread group with the lowest level
1119 (@code{gnus-group-best-unread-group}).
1123 @findex gnus-group-first-unread-group
1124 Jump to the first group with unread articles
1125 (@code{gnus-group-first-unread-group}).
1128 @vindex gnus-group-goto-unread
1129 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
1130 commands will move to the next group, not the next unread group. Even
1131 the commands that say they move to the next unread group. The default
1135 @node Selecting a Group
1136 @section Selecting a Group
1137 @cindex group selection
1142 @kindex SPACE (Group)
1143 @findex gnus-group-read-group
1144 Select the current group, switch to the summary buffer and display the
1145 first unread article (@code{gnus-group-read-group}). If there are no
1146 unread articles in the group, or if you give a non-numerical prefix to
1147 this command, Gnus will offer to fetch all the old articles in this
1148 group from the server. If you give a numerical prefix @var{N}, Gnus
1149 will fetch @var{N} number of articles. If @var{N} is positive, fetch
1150 the @var{N} newest articles, if @var{N} is negative, fetch the
1151 @var{abs(N)} oldest articles.
1155 @findex gnus-group-select-group
1156 Select the current group and switch to the summary buffer
1157 (@code{gnus-group-select-group}). Takes the same arguments as
1158 @code{gnus-group-read-group}---the only difference is that this command
1159 does not display the first unread article automatically upon group
1163 @kindex M-RET (Group)
1164 @findex gnus-group-quick-select-group
1165 This does the same as the command above, but tries to do it with the
1166 minimum amount off fuzz (@code{gnus-group-quick-select-group}). No
1167 scoring/killing will be performed, there will be no highlights and no
1168 expunging. This might be useful if you're in a real hurry and have to
1169 enter some humongous group.
1172 @kindex M-RET (Group)
1173 @findex gnus-group-visible-select-group
1174 This is yet one more command that does the same as the one above, but
1175 this one does it without expunging and hiding dormants
1176 (@code{gnus-group-visible-select-group}).
1180 @findex gnus-group-catchup-current
1181 @vindex gnus-group-catchup-group-hook
1182 Mark all unticked articles in this group as read
1183 (@code{gnus-group-catchup-current}).
1184 @code{gnus-group-catchup-group-hook} is when catching up a group from
1189 @findex gnus-group-catchup-current-all
1190 Mark all articles in this group, even the ticked ones, as read
1191 (@code{gnus-group-catchup-current-all}).
1194 @vindex gnus-large-newsgroup
1195 The @code{gnus-large-newsgroup} variable says what Gnus should consider
1196 to be a big group. This is 200 by default. If the group has more
1197 unread articles than this, Gnus will query the user before entering the
1198 group. The user can then specify how many articles should be fetched
1199 from the server. If the user specifies a negative number (@code{-n}),
1200 the @code{n} oldest articles will be fetched. If it is positive, the
1201 @code{n} articles that have arrived most recently will be fetched.
1203 @vindex gnus-select-group-hook
1204 @vindex gnus-auto-select-first
1205 @code{gnus-auto-select-first} control whether any articles are selected
1206 automatically when entering a group.
1211 Don't select any articles when entering the group. Just display the
1212 full summary buffer.
1215 Select the first unread article when entering the group.
1218 Select the most high-scored article in the group when entering the
1222 If you want to prevent automatic selection in some group (say, in a
1223 binary group with Huge articles) you can set this variable to @code{nil}
1224 in @code{gnus-select-group-hook}, which is called when a group is
1228 @node Subscription Commands
1229 @section Subscription Commands
1238 @findex gnus-group-unsubscribe-current-group
1239 Toggle subscription to the current group
1240 (@code{gnus-group-unsubscribe-current-group}).
1246 @findex gnus-group-unsubscribe-group
1247 Prompt for a group to subscribe, and then subscribe it. If it was
1248 subscribed already, unsubscribe it instead
1249 (@code{gnus-group-unsubscribe-group}).
1255 @findex gnus-group-kill-group
1256 Kill the current group (@code{gnus-group-kill-group}).
1262 @findex gnus-group-yank-group
1263 Yank the last killed group (@code{gnus-group-yank-group}).
1266 @kindex C-x C-t (Group)
1267 @findex gnus-group-transpose-groups
1268 Transpose two groups (@code{gnus-group-transpose-groups}). This isn't
1269 really a subscription command, but you can use it instead of a
1270 kill-and-yank sequence sometimes.
1276 @findex gnus-group-kill-region
1277 Kill all groups in the region (@code{gnus-group-kill-region}).
1281 @findex gnus-group-kill-all-zombies
1282 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
1285 @kindex S C-k (Group)
1286 @findex gnus-group-kill-level
1287 Kill all groups on a certain level (@code{gnus-group-kill-level}).
1288 These groups can't be yanked back after killing, so this command should
1289 be used with some caution. The only thing where this command comes in
1290 really handy is when you have a @file{.newsrc} with lots of unsubscribed
1291 groups that you want to get rid off. @kbd{S C-k} on level @code{7} will
1292 kill off all unsubscribed groups that do not have message numbers in the
1293 @file{.newsrc} file.
1297 Also @pxref{Group Levels}.
1301 @section Group Levels
1304 All groups have a level of @dfn{subscribedness}. For instance, if a
1305 group is on level 2, it is more subscribed than a group on level 5. You
1306 can ask Gnus to just list groups on a given level or lower
1307 (@pxref{Listing Groups}), or to just check for new articles in groups on
1308 a given level or lower (@pxref{Scanning New Messages}).
1314 @findex gnus-group-set-current-level
1315 Set the level of the current group. If a numeric prefix is given, the
1316 next @var{n} groups will have their levels set. The user will be
1317 prompted for a level.
1320 @vindex gnus-level-killed
1321 @vindex gnus-level-zombie
1322 @vindex gnus-level-unsubscribed
1323 @vindex gnus-level-subscribed
1324 Gnus considers groups on between levels 1 and
1325 @code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed,
1326 @code{gnus-level-subscribed} (exclusive) and
1327 @code{gnus-level-unsubscribed} (inclusive) (default 7) to be
1328 unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
1329 (default 8) and @code{gnus-level-killed} to be killed (default 9),
1330 completely dead. Gnus treats subscribed and unsubscribed groups exactly
1331 the same, but zombie and killed groups have no information on what
1332 articles you have read, etc, stored. This distinction between dead and
1333 living groups isn't done because it is nice or clever, it is done purely
1334 for reasons of efficiency.
1336 It is recommended that you keep all your mail groups (if any) on quite
1337 low levels (eg. 1 or 2).
1339 If you want to play with the level variables, you should show some care.
1340 Set them once, and don't touch them ever again. Better yet, don't touch
1341 them at all unless you know exactly what you're doing.
1343 @vindex gnus-level-default-unsubscribed
1344 @vindex gnus-level-default-subscribed
1345 Two closely related variables are @code{gnus-level-default-subscribed}
1346 (default 3) and @code{gnus-level-default-unsubscribed} (default 6),
1347 which are the levels that new groups will be put on if they are
1348 (un)subscribed. These two variables should, of course, be inside the
1349 relevant legal ranges.
1351 @vindex gnus-keep-same-level
1352 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
1353 will only move to groups that are of the same level (or lower). In
1354 particular, going from the last article in one group to the next group
1355 will go to the next group of the same level (or lower). This might be
1356 handy if you want to read the most important groups before you read the
1359 @vindex gnus-group-default-list-level
1360 All groups with a level less than or equal to
1361 @code{gnus-group-default-list-level} will be listed in the group buffer
1364 @vindex gnus-group-list-inactive-groups
1365 If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active
1366 groups will be listed along with the unread groups. This variable is
1367 @code{t} by default. If it is @code{nil}, inactive groups won't be
1370 @vindex gnus-group-use-permanent-levels
1371 If @code{gnus-group-use-permanent-levels} is non-@code{nil}, once you
1372 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
1373 use this level as the ``work'' level.
1375 @vindex gnus-activate-level
1376 Gnus will normally just activate groups that are on level
1377 @code{gnus-activate-level} or less. If you don't want to activate
1378 unsubscribed groups, for instance, you might set this variable to
1383 @section Group Score
1386 You would normally keep important groups on high levels, but that scheme
1387 is somewhat restrictive. Don't you wish you could have Gnus sort the
1388 group buffer according to how often you read groups, perhaps? Within
1391 This is what @dfn{group score} is for. You can assign a score to each
1392 group. You can then sort the group buffer based on this score.
1393 Alternatively, you can sort on score and then level. (Taken together,
1394 the level and the score is called the @dfn{rank} of the group. A group
1395 that is on level 4 and has a score of 1 has a higher rank than a group
1396 on level 5 that has a score of 300. (The level is the most significant
1397 part and the score is the least significant part.)
1399 @findex gnus-summary-bubble-group
1400 If you want groups you read often to get higher scores than groups you
1401 read seldom you can add the @code{gnus-summary-bubble-group} function to
1402 the @code{gnus-summary-exit-hook} hook. This will result (after
1403 sorting) in a bubbling sort of action. If you want to see that in
1404 action after each summary exit, you can add
1405 @code{gnus-group-sort-groups-by-rank} or
1406 @code{gnus-group-sort-groups-by-score} to the same hook, but that will
1407 slow things down somewhat.
1410 @node Marking Groups
1411 @section Marking Groups
1412 @cindex marking groups
1414 If you want to perform some command on several groups, and they appear
1415 subsequently in the group buffer, you would normally just give a
1416 numerical prefix to the command. Most group commands will then do your
1417 bidding on those groups.
1419 However, if the groups are not in sequential order, you can still
1420 perform a command on several groups. You simply mark the groups first
1421 with the process mark and then execute the command.
1429 @findex gnus-group-mark-group
1430 Set the mark on the current group (@code{gnus-group-mark-group}).
1436 @findex gnus-group-unmark-group
1437 Remove the mark from the current group
1438 (@code{gnus-group-unmark-group}).
1442 @findex gnus-group-unmark-all-groups
1443 Remove the mark from all groups (@code{gnus-group-unmark-all-groups}).
1447 @findex gnus-group-mark-region
1448 Mark all groups between point and mark (@code{gnus-group-mark-region}).
1452 @findex gnus-group-mark-buffer
1453 Mark all groups in the buffer (@code{gnus-group-mark-buffer}).
1457 @findex gnus-group-mark-regexp
1458 Mark all groups that match some regular expression
1459 (@code{gnus-group-mark-regexp}).
1462 Also @pxref{Process/Prefix}.
1464 @findex gnus-group-universal-argument
1465 If you want to execute some command on all groups that have been marked
1466 with the process mark, you can use the @kbd{M-&}
1467 (@code{gnus-group-universal-argument}) command. It will prompt you for
1468 the command to be executed.
1471 @node Foreign Groups
1472 @section Foreign Groups
1474 Here are some group mode commands for making and editing general foreign
1475 groups, as well as commands to ease the creation of a few
1476 special-purpose groups:
1482 @findex gnus-group-make-group
1483 Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
1484 for a name, a method and possibly an @dfn{address}. For an easier way
1485 to subscribe to @sc{nntp} groups, @pxref{Browse Foreign Server}.
1489 @findex gnus-group-rename-group
1490 Rename the current group to something else
1491 (@code{gnus-group-rename-group}). This is legal only on some groups --
1492 mail groups mostly. This command might very well be quite slow on some
1497 @findex gnus-group-edit-group-method
1498 Enter a buffer where you can edit the select method of the current
1499 group (@code{gnus-group-edit-group-method}).
1503 @findex gnus-group-edit-group-parameters
1504 Enter a buffer where you can edit the group parameters
1505 (@code{gnus-group-edit-group-parameters}).
1509 @findex gnus-group-edit-group
1510 Enter a buffer where you can edit the group info
1511 (@code{gnus-group-edit-group}).
1515 @findex gnus-group-make-directory-group
1516 Make a directory group. You will be prompted for a directory name
1517 (@code{gnus-group-make-directory-group}).
1521 @findex gnus-group-make-help-group
1522 Make the Gnus help group (@code{gnus-group-make-help-group}).
1526 @findex gnus-group-make-archive-group
1527 @vindex gnus-group-archive-directory
1528 @vindex gnus-group-recent-archive-directory
1529 Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
1530 default a group pointing to the most recent articles will be created
1531 (@code{gnus-group-recent-archive-directory}), but given a prefix, a full
1532 group will be created from from @code{gnus-group-archive-directory}.
1536 @findex gnus-group-make-kiboze-group
1537 Make a kiboze group. You will be prompted for a name, for a regexp to
1538 match groups to be ``included'' in the kiboze group, and a series of
1539 strings to match on headers (@code{gnus-group-make-kiboze-group}).
1543 @findex gnus-group-enter-directory
1544 Read an arbitrary directory as if with were a newsgroup with the
1545 @code{nneething} backend (@code{gnus-group-enter-directory}).
1549 @findex gnus-group-make-doc-group
1550 @cindex ClariNet Briefs
1551 Make a group based on some file or other
1552 (@code{gnus-group-make-doc-group}). If you give a prefix to this
1553 command, you will be prompted for a file name and a file type.
1554 Currently supported types are @code{babyl}, @code{mbox}, @code{digest},
1555 @code{mmdf}, @code{news}, @code{rnews}, @code{clari-briefs}, and
1556 @code{forward}. If you run this command without a prefix, Gnus will
1557 guess at the file type.
1560 @kindex G DEL (Group)
1561 @findex gnus-group-delete-group
1562 This function will delete the current group
1563 (@code{gnus-group-delete-group}). If given a prefix, this function will
1564 actually delete all the articles in the group, and forcibly remove the
1565 group itself from the face of the Earth. Use a prefix only if you are
1566 absolutely sure of what you are doing.
1570 @findex gnus-group-make-empty-virtual
1571 Make a new, fresh, empty @code{nnvirtual} group
1572 (@code{gnus-group-make-empty-virtual}).
1576 @findex gnus-group-add-to-virtual
1577 Add the current group to an @code{nnvirtual} group
1578 (@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
1581 @xref{Select Methods} for more information on the various select
1584 @vindex gnus-activate-foreign-newsgroups
1585 If the @code{gnus-activate-foreign-newsgroups} is a positive number,
1586 Gnus will check all foreign groups with this level or lower at startup.
1587 This might take quite a while, especially if you subscribe to lots of
1588 groups from different @sc{nntp} servers.
1591 @node Group Parameters
1592 @section Group Parameters
1593 @cindex group parameters
1595 Gnus stores all information on a group in a list that is usually known
1596 as the @dfn{group info}. This list has from three to six elements.
1597 Here's an example info.
1600 ("nnml:mail.ding" 3 ((1 . 232) 244 (256 . 270)) ((tick 246 249))
1601 (nnml "private") ((to-address . "ding@@ifi.uio.no")))
1604 The first element is the @dfn{group name}, as Gnus knows the group,
1605 anyway. The second element is the @dfn{subscription level}, which
1606 normally is a small integer. The third element is a list of ranges of
1607 read articles. The fourth element is a list of lists of article marks
1608 of various kinds. The fifth element is the select method (or virtual
1609 server, if you like). The sixth element is a list of @dfn{group
1610 parameters}, which is what this section is about.
1612 Any of the last three elements may be missing if they are not required.
1613 In fact, the vast majority of groups will normally only have the first
1614 three elements, which saves quite a lot of cons cells.
1616 The group parameters store information local to a particular group:
1621 If the group parameter list contains an element that looks like
1622 @code{(to-address . "some@@where.com")}, that address will be used by
1623 the backend when doing followups and posts. This is primarily useful in
1624 mail groups that represent closed mailing lists---mailing lists where
1625 it's expected that everybody that writes to the mailing list is
1626 subscribed to it. Since using this parameter ensures that the mail only
1627 goes to the mailing list itself, it means that members won't receive two
1628 copies of your followups.
1630 Using @code{to-address} will actually work whether the group is foreign
1631 or not. Let's say there's a group on the server that is called
1632 @samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten
1633 the articles from a mail-to-news gateway. Posting directly to this
1634 group is therefore impossible---you have to send mail to the mailing
1635 list address instead.
1639 If the group parameter list has an element that looks like
1640 @code{(to-list . "some@@where.com")}, that address will be used when
1641 doing a @kbd{a} in any group. It is totally ignored when doing a
1642 followup---except that if it is present in a news group, you'll get mail
1643 group semantics when doing @kbd{f}.
1645 @item broken-reply-to
1646 @cindex broken-reply-to
1647 Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To}
1648 headers in this group are to be ignored. This can be useful if you're
1649 reading a mailing list group where the listserv has inserted
1650 @code{Reply-To} headers that point back to the listserv itself. This is
1651 broken behavior. So there!
1655 If the group parameter list contains an element like @code{(to-group
1656 . "some.group.name")}, all posts will be sent to that group.
1660 If this symbol is present in the group parameter list, all articles that
1661 are read will be marked as expirable. For an alternative approach,
1662 @pxref{Expiring Mail}.
1665 @cindex total-expire
1666 If this symbol is present, all read articles will be put through the
1667 expiry process, even if they are not marked as expirable. Use with
1672 @vindex nnmail-expiry-wait-function
1673 If the group parameter has an element that looks like @code{(expiry-wait
1674 . 10)}, this value will override any @code{nnmail-expiry-wait} and
1675 @code{nnmail-expiry-wait-function} when expiring expirable messages.
1676 The value can either be a number of days (not necessarily an integer) or
1677 the symbols @code{never} or @code{immediate}.
1680 Elements that look like @code{(score-file . "file")} will make
1681 @samp{file} into the current score file for the group in question. This
1682 means that all score commands you issue will end up in that file.
1685 When unsubscribing to a mailing list you should never send the
1686 unsubscription notice to the mailing list itself. Instead, you'd send
1687 messages to the administrative address. This parameter allows you to
1688 put the admin address somewhere convenient.
1691 This parameter allows you to enter a arbitrary comment on the group.
1693 @item @var{(variable form)}
1694 You can use the group parameters to set variables local to the group you
1695 are entering. Say you want to turn threading off in
1696 @samp{news.answers}. You'd then put @code{(gnus-show-threads nil)} in
1697 the group parameters of that group. @code{gnus-show-threads} will be
1698 made into a local variable in the summary buffer you enter, and the form
1699 @code{nil} will be @code{eval}ed there.
1701 This can also be used as a group-specific hook function, if you'd like.
1702 If you want to hear a beep when you enter the group
1703 @samp{alt.binaries.pictures.furniture}, you could put something like
1704 @code{(dummy-variable (ding))} in the parameters of that group.
1705 @code{dummy-variable} will be set to the result of the @code{(ding)}
1706 form, but who cares?
1710 If you want to change the group info you can use the @kbd{G E} command
1711 to enter a buffer where you can edit it.
1713 You usually don't want to edit the entire group info, so you'd be better
1714 off using the @kbd{G p} command to just edit the group parameters.
1717 @node Listing Groups
1718 @section Listing Groups
1719 @cindex group listing
1721 These commands all list various slices of the groups that are available.
1729 @findex gnus-group-list-groups
1730 List all groups that have unread articles
1731 (@code{gnus-group-list-groups}). If the numeric prefix is used, this
1732 command will list only groups of level ARG and lower. By default, it
1733 only lists groups of level five or lower (i.e., just subscribed groups).
1739 @findex gnus-group-list-all-groups
1740 List all groups, whether they have unread articles or not
1741 (@code{gnus-group-list-all-groups}). If the numeric prefix is used,
1742 this command will list only groups of level ARG and lower. By default,
1743 it lists groups of level seven or lower (i.e., just subscribed and
1744 unsubscribed groups).
1748 @findex gnus-group-list-level
1749 List all unread groups on a specific level
1750 (@code{gnus-group-list-level}). If given a prefix, also list the groups
1751 with no unread articles.
1755 @findex gnus-group-list-killed
1756 List all killed groups (@code{gnus-group-list-killed}). If given a
1757 prefix argument, really list all groups that are available, but aren't
1758 currently (un)subscribed. This could entail reading the active file
1763 @findex gnus-group-list-zombies
1764 List all zombie groups (@code{gnus-group-list-zombies}).
1768 @findex gnus-group-list-matching
1769 List all subscribed groups with unread articles that match a regexp
1770 (@code{gnus-group-list-matching}).
1774 @findex gnus-group-list-all-matching
1775 List groups that match a regexp (@code{gnus-group-list-all-matching}).
1779 @findex gnus-group-list-active
1780 List absolutely all groups that are in the active file(s) of the
1781 server(s) you are connected to (@code{gnus-group-list-active}). This
1782 might very well take quite a while. It might actually be a better idea
1783 to do a @kbd{A m} to list all matching, and just give @samp{.} as the
1788 @findex gnus-group-apropos
1789 List all groups that have names that match a regexp
1790 (@code{gnus-group-apropos}).
1794 @findex gnus-group-description-apropos
1795 List all groups that have names or descriptions that match a regexp
1796 (@code{gnus-group-description-apropos}).
1800 @vindex gnus-permanently-visible-groups
1801 @cindex visible group parameter
1802 Groups that match the @code{gnus-permanently-visible-groups} regexp will
1803 always be shown, whether they have unread articles or not. You can also
1804 add the @code{visible} element to the group parameters in question to
1805 get the same effect.
1807 @vindex gnus-list-groups-with-ticked-articles
1808 Groups that have just ticked articles in it are normally listed in the
1809 group buffer. If @code{gnus-list-groups-with-ticked-articles} is
1810 @code{nil}, these groups will be treated just like totally empty
1811 groups. It is @code{t} by default.
1814 @node Sorting Groups
1815 @section Sorting Groups
1816 @cindex sorting groups
1818 @kindex C-c C-s (Group)
1819 @findex gnus-group-sort-groups
1820 @vindex gnus-group-sort-function
1821 The @kbd{C-c C-s} (@code{gnus-group-sort-groups}) command sorts the
1822 group buffer according to the function(s) given by the
1823 @code{gnus-group-sort-function} variable. Available sorting functions
1828 @item gnus-group-sort-by-alphabet
1829 @findex gnus-group-sort-by-alphabet
1830 Sort the group names alphabetically. This is the default.
1832 @item gnus-group-sort-by-level
1833 @findex gnus-group-sort-by-level
1834 Sort by group level.
1836 @item gnus-group-sort-by-score
1837 @findex gnus-group-sort-by-score
1838 Sort by group score.
1840 @item gnus-group-sort-by-rank
1841 @findex gnus-group-sort-by-rank
1842 Sort by group score and then the group level. The level and the score
1843 are, when taken together, the group's @dfn{rank}.
1845 @item gnus-group-sort-by-unread
1846 @findex gnus-group-sort-by-unread
1847 Sort by number of unread articles.
1849 @item gnus-group-sort-by-method
1850 @findex gnus-group-sort-by-method
1851 Sort by alphabetically on the select method.
1856 @code{gnus-group-sort-function} can also be a list of sorting
1857 functions. In that case, the most significant sort key function must be
1861 There are also a number of commands for sorting directly according to
1862 some sorting criteria:
1866 @kindex G S a (Group)
1867 @findex gnus-group-sort-groups-by-alphabet
1868 Sort the group buffer alphabetically by group name
1869 (@code{gnus-group-sort-groups-by-alphabet}).
1872 @kindex G S u (Group)
1873 @findex gnus-group-sort-groups-by-unread
1874 Sort the group buffer by the number of unread articles
1875 (@code{gnus-group-sort-groups-by-unread}).
1878 @kindex G S l (Group)
1879 @findex gnus-group-sort-groups-by-level
1880 Sort the group buffer by group level
1881 (@code{gnus-group-sort-groups-by-level}).
1884 @kindex G S v (Group)
1885 @findex gnus-group-sort-groups-by-score
1886 Sort the group buffer by group score
1887 (@code{gnus-group-sort-groups-by-score}).
1890 @kindex G S r (Group)
1891 @findex gnus-group-sort-groups-by-rank
1892 Sort the group buffer by group level
1893 (@code{gnus-group-sort-groups-by-rank}).
1896 @kindex G S m (Group)
1897 @findex gnus-group-sort-groups-by-method
1898 Sort the group buffer alphabetically by backend name
1899 (@code{gnus-group-sort-groups-by-method}).
1903 When given a prefix, all these commands will sort in reverse order.
1906 @node Group Maintenance
1907 @section Group Maintenance
1908 @cindex bogus groups
1913 @findex gnus-group-check-bogus-groups
1914 Find bogus groups and delete them
1915 (@code{gnus-group-check-bogus-groups}).
1919 @findex gnus-find-new-newsgroups
1920 Find new groups and process them (@code{gnus-find-new-newsgroups}). If
1921 given a prefix, use the @code{ask-server} method to query the server for
1925 @kindex C-c C-x (Group)
1926 @findex gnus-group-expire-articles
1927 Run all expirable articles in the current group through the expiry
1928 process (if any) (@code{gnus-group-expire-articles}).
1931 @kindex C-c M-C-x (Group)
1932 @findex gnus-group-expire-all-groups
1933 Run all articles in all groups through the expiry process
1934 (@code{gnus-group-expire-all-groups}).
1939 @node Browse Foreign Server
1940 @section Browse Foreign Server
1941 @cindex foreign servers
1942 @cindex browsing servers
1947 @findex gnus-group-browse-foreign-server
1948 You will be queried for a select method and a server name. Gnus will
1949 then attempt to contact this server and let you browse the groups there
1950 (@code{gnus-group-browse-foreign-server}).
1953 @findex gnus-browse-server-mode
1954 A new buffer with a list of available groups will appear. This buffer
1955 will be use the @code{gnus-browse-server-mode}. This buffer looks a bit
1956 (well, a lot) like a normal group buffer, but with one major difference
1957 - you can't enter any of the groups. If you want to read any of the
1958 news available on that server, you have to subscribe to the groups you
1959 think may be interesting, and then you have to exit this buffer. The
1960 new groups will be added to the group buffer, and then you can read them
1961 as you would any other group.
1963 Future versions of Gnus may possibly permit reading groups straight from
1966 Here's a list of keystrokes available in the browse mode:
1971 @findex gnus-group-next-group
1972 Go to the next group (@code{gnus-group-next-group}).
1976 @findex gnus-group-prev-group
1977 Go to the previous group (@code{gnus-group-prev-group}).
1980 @kindex SPACE (Browse)
1981 @findex gnus-browse-read-group
1982 Enter the current group and display the first article
1983 (@code{gnus-browse-read-group}).
1986 @kindex RET (Browse)
1987 @findex gnus-browse-select-group
1988 Enter the current group (@code{gnus-browse-select-group}).
1992 @findex gnus-browse-unsubscribe-current-group
1993 Unsubscribe to the current group, or, as will be the case here,
1994 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
2000 @findex gnus-browse-exit
2001 Exit browse mode (@code{gnus-browse-exit}).
2005 @findex gnus-browse-describe-briefly
2006 Describe browse mode briefly (well, there's not much to describe, is
2007 there) (@code{gnus-browse-describe-briefly}).
2012 @section Exiting Gnus
2013 @cindex exiting Gnus
2015 Yes, Gnus is ex(c)iting.
2020 @findex gnus-group-suspend
2021 Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
2022 but it kills all buffers except the Group buffer. I'm not sure why this
2023 is a gain, but then who am I to judge?
2027 @findex gnus-group-exit
2028 Quit Gnus (@code{gnus-group-exit}).
2032 @findex gnus-group-quit
2033 Quit Gnus without saving any startup files (@code{gnus-group-quit}).
2036 @vindex gnus-exit-gnus-hook
2037 @vindex gnus-suspend-gnus-hook
2038 @code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
2039 @code{gnus-exit-gnus-hook} is called when you quit Gnus, while
2040 @code{gnus-after-exiting-gnus-hook} is called as the final item when
2045 If you wish to completely unload Gnus and all its adherents, you can use
2046 the @code{gnus-unload} command. This command is also very handy when
2047 trying to customize meta-variables.
2052 Miss Lisa Cannifax, while sitting in English class, feels her feet go
2053 numbly heavy and herself fall into a hazy trance as the boy sitting
2054 behind her drew repeated lines with his pencil across the back of her
2060 @section Group Topics
2063 If you read lots and lots of groups, it might be convenient to group
2064 them hierarchically according to topics. You put your Emacs groups over
2065 here, your sex groups over there, and the rest (what, two groups or so?)
2066 you put in some misc section that you never bother with anyway. You can
2067 even group the Emacs sex groups as a sub-topic to either the Emacs
2068 groups or the sex groups---or both! Go wild!
2070 @findex gnus-topic-mode
2072 To get this @emph{fab} functionality you simply turn on (ooh!) the
2073 @code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This
2074 is a toggling command.)
2076 Go ahead, just try it. I'll still be here when you get back. La de
2077 dum... Nice tune, that... la la la... What, you're back? Yes, and now
2078 press @kbd{l}. There. All your groups are now listed under
2079 @samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
2082 If you want this permanently enabled, you should add that minor mode to
2083 the hook for the group mode:
2086 (add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
2090 * Topic Variables:: How to customize the topics the Lisp Way.
2091 * Topic Commands:: Interactive E-Z commands.
2092 * Topic Topology:: A map of the world.
2096 @node Topic Variables
2097 @subsection Topic Variables
2098 @cindex topic variables
2100 Now, if you select a topic, if will fold/unfold that topic, which is
2101 really neat, I think.
2103 @vindex gnus-topic-line-format
2104 The topic lines themselves are created according to the
2105 @code{gnus-topic-line-format} variable. @xref{Formatting Variables}.
2106 Elements allowed are:
2118 Number of groups in the topic.
2120 Number of unread articles in the topic.
2122 Number of unread articles in the topic and all its subtopics.
2125 @vindex gnus-topic-indent-level
2126 Each sub-topic (and the groups in the sub-topics) will be indented with
2127 @code{gnus-topic-indent-level} times the topic level number of spaces.
2128 The default is @code{2}.
2130 @vindex gnus-topic-mode-hook
2131 @code{gnus-topic-mode-hook} is called in topic minor mode buffers.
2134 @node Topic Commands
2135 @subsection Topic Commands
2136 @cindex topic commands
2138 When the topic minor mode is turned on, a new @kbd{T} submap will be
2139 available. In addition, a few of the standard keys change their
2140 definitions slightly.
2146 @findex gnus-topic-create-topic
2147 Prompt for a new topic name and create it
2148 (@code{gnus-topic-create-topic}).
2152 @findex gnus-topic-move-group
2153 Move the current group to some other topic
2154 (@code{gnus-topic-move-group}). This command understands the
2155 process/prefix convention (@pxref{Process/Prefix}).
2159 @findex gnus-topic-copy-group
2160 Copy the current group to some other topic
2161 (@code{gnus-topic-copy-group}). This command understands the
2162 process/prefix convention (@pxref{Process/Prefix}).
2166 @findex gnus-topic-remove-group
2167 Remove a group from the current topic (@code{gnus-topic-remove-group}).
2168 This command understands the process/prefix convention
2169 (@pxref{Process/Prefix}).
2173 @findex gnus-topic-move-matching
2174 Move all groups that match some regular expression to a topic
2175 (@code{gnus-topic-move-matching}).
2179 @findex gnus-topic-copy-matching
2180 Copy all groups that match some regular expression to a topic
2181 (@code{gnus-topic-copy-matching}).
2185 @findex gnus-topic-mark-topic
2186 Mark all groups in the current topic with the process mark
2187 (@code{gnus-topic-mark-topic}).
2190 @kindex T M-# (Group)
2191 @findex gnus-topic-unmark-topic
2192 Remove the process mark from all groups in the current topic
2193 (@code{gnus-topic-unmark-topic}).
2197 @findex gnus-topic-select-group
2199 Either select a group or fold a topic (@code{gnus-topic-select-group}).
2200 When you perform this command on a group, you'll enter the group, as
2201 usual. When done on a topic line, the topic will be folded (if it was
2202 visible) or unfolded (if it was folded already). So it's basically a
2203 toggling command on topics. In addition, if you give a numerical
2204 prefix, group on that level (and lower) will be displayed.
2207 @kindex T TAB (Group)
2208 @findex gnus-topic-indent
2209 ``Indent'' the current topic so that it becomes a sub-topic of the
2210 previous topic (@code{gnus-topic-indent}). If given a prefix,
2211 ``un-indent'' the topic instead.
2215 @findex gnus-topic-kill-group
2216 Kill a group or topic (@code{gnus-topic-kill-group}).
2220 @findex gnus-topic-yank-group
2221 Yank the previously killed group or topic (@code{gnus-topic-yank-group}).
2222 Note that all topics will be yanked before all groups.
2226 @findex gnus-topic-rename
2227 Rename a topic (@code{gnus-topic-rename}).
2230 @kindex T DEL (Group)
2231 @findex gnus-topic-delete
2232 Delete an empty topic (@code{gnus-topic-delete}).
2236 @findex gnus-topic-list-active
2237 List all groups that Gnus knows about in a topics-ified way
2238 (@code{gnus-topic-list-active}).
2243 @node Topic Topology
2244 @subsection Topic Topology
2245 @cindex topic topology
2248 So, let's have a look at an example group buffer:
2254 2: alt.religion.emacs
2257 0: comp.talk.emacs.recovery
2259 8: comp.binaries.fractals
2260 13: comp.sources.unix
2263 So, here we have one top-level topic, two topics under that, and one
2264 sub-topic under one of the sub-topics. (There is always just one (1)
2265 top-level topic). This topology can be expressed as follows:
2269 (("Emacs -- I wuw it!" visible)
2270 (("Naughty Emacs" visible)))
2274 @vindex gnus-topic-topology
2275 This is in fact how the variable @code{gnus-topic-topology} would look
2276 for the display above. That variable is saved in the @file{.newsrc.eld}
2277 file, and shouldn't be messed with manually---unless you really want
2278 to. Since this variable is read from the @file{.newsrc.eld} file,
2279 setting it in any other startup files will have no effect.
2281 This topology shows what topics are sub-topics of what topics (right),
2282 and which topics are visible. Two settings are currently
2283 allowed---@code{visible} and @code{invisible}.
2286 @node Misc Group Stuff
2287 @section Misc Group Stuff
2290 * Scanning New Messages:: Asking Gnus to see whether new messages have arrived.
2291 * Group Information:: Information and help on groups and Gnus.
2292 * File Commands:: Reading and writing the Gnus files.
2299 @findex gnus-group-enter-server-mode
2300 Enter the server buffer (@code{gnus-group-enter-server-mode}). @xref{The
2305 @findex gnus-group-post-news
2306 Post an article to a group (@code{gnus-group-post-news}). The current
2307 group name will be used as the default.
2311 @findex gnus-group-mail
2312 Mail a message somewhere (@code{gnus-group-mail}).
2316 Variables for the group buffer:
2320 @item gnus-group-mode-hook
2321 @vindex gnus-group-mode-hook
2322 @code{gnus-group-mode-hook} is called after the group buffer has been
2325 @item gnus-group-prepare-hook
2326 @vindex gnus-group-prepare-hook
2327 @code{gnus-group-prepare-hook} is called after the group buffer is
2328 generated. It may be used to modify the buffer in some strange,
2331 @item gnus-permanently-visible-groups
2332 @vindex gnus-permanently-visible-groups
2333 Groups matching this regexp will always be listed in the group buffer,
2334 whether they are empty or not.
2339 @node Scanning New Messages
2340 @subsection Scanning New Messages
2341 @cindex new messages
2342 @cindex scanning new news
2348 @findex gnus-group-get-new-news
2349 Check the server(s) for new articles. If the numerical prefix is used,
2350 this command will check only groups of level @var{arg} and lower
2351 (@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
2352 command will force a total rereading of the active file(s) from the
2357 @findex gnus-group-get-new-news-this-group
2358 @vindex gnus-goto-next-group-when-activating
2359 Check whether new articles have arrived in the current group
2360 (@code{gnus-group-get-new-news-this-group}). The
2361 @code{gnus-goto-next-group-when-activating} variable controls whether
2362 this command is to move point to the next group or not. It is @code{t}
2365 @findex gnus-activate-all-groups
2366 @cindex activating groups
2368 @kindex C-c M-g (Group)
2369 Activate absolutely all groups (@code{gnus-activate-all-groups}).
2374 @findex gnus-group-restart
2375 Restart Gnus (@code{gnus-group-restart}).
2379 @vindex gnus-get-new-news-hook
2380 @code{gnus-get-new-news-hook} is run just before checking for new news.
2382 @vindex gnus-after-getting-new-news-hook
2383 @code{gnus-after-getting-new-news-hook} is run after checking for new
2387 @node Group Information
2388 @subsection Group Information
2389 @cindex group information
2390 @cindex information on groups
2396 @findex gnus-group-fetch-faq
2399 Try to fetch the FAQ for the current group
2400 (@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
2401 @code{gnus-group-faq-directory}, which is usually a directory on a
2402 remote machine. @code{ange-ftp} will be used for fetching the file.
2406 @cindex describing groups
2407 @cindex group description
2408 @findex gnus-group-describe-group
2409 Describe the current group (@code{gnus-group-describe-group}). If given
2410 a prefix, force Gnus to re-read the description from the server.
2414 @findex gnus-group-describe-all-groups
2415 Describe all groups (@code{gnus-group-describe-all-groups}). If given a
2416 prefix, force Gnus to re-read the description file from the server.
2421 @findex gnus-version
2422 Display current Gnus version numbers (@code{gnus-version}).
2426 @findex gnus-group-describe-briefly
2427 Give a very short help message (@code{gnus-group-describe-briefly}).
2430 @kindex C-c C-i (Group)
2433 @findex gnus-info-find-node
2434 Go to the Gnus info node (@code{gnus-info-find-node}).
2439 @subsection File Commands
2440 @cindex file commands
2446 @findex gnus-group-read-init-file
2447 @vindex gnus-init-file
2448 @cindex reading init file
2449 Read the init file (@code{gnus-init-file}, which defaults to
2450 @file{~/.gnus}) (@code{gnus-group-read-init-file}).
2454 @findex gnus-group-save-newsrc
2455 @cindex saving .newsrc
2456 Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
2457 (@code{gnus-group-save-newsrc}). If given a prefix, force saving the
2458 file(s) whether Gnus thinks it is necessary or not.
2462 @findex gnus-group-clear-dribble
2463 Clear the dribble buffer (@code{gnus-group-clear-dribble}).
2468 @node The Summary Buffer
2469 @chapter The Summary Buffer
2470 @cindex summary buffer
2472 A line for each article is displayed in the summary buffer. You can
2473 move around, read articles, post articles and reply to articles.
2476 * Summary Buffer Format:: Deciding how the summary buffer is to look.
2477 * Summary Maneuvering:: Moving around the summary buffer.
2478 * Choosing Articles:: Reading articles.
2479 * Paging the Article:: Scrolling the current article.
2480 * Reply Followup and Post:: Posting articles.
2481 * Canceling and Superseding:: ``Whoops, I shouldn't have called him that.''
2482 * Marking Articles:: Marking articles as read, expirable, etc.
2483 * Limiting:: You can limit the summary buffer.
2484 * Threading:: How threads are made.
2485 * Sorting:: How articles and threads are sorted.
2486 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
2487 * Article Caching:: You may store articles in a cache.
2488 * Persistent Articles:: Making articles expiry-resistant.
2489 * Article Backlog:: Having already read articles hang around.
2490 * Saving Articles:: Ways of customizing article saving.
2491 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
2492 * Article Treatment:: The article buffer can be mangled at will.
2493 * Summary Sorting:: Sorting the summary buffer in various ways.
2494 * Finding the Parent:: No child support? Get the parent.
2495 * Alternative Approaches:: Reading using non-default summaries.
2496 * Tree Display:: A more visual display of threads.
2497 * Mail Group Commands:: Some commands can only be used in mail groups.
2498 * Various Summary Stuff:: What didn't fit anywhere else.
2499 * Exiting the Summary Buffer:: Returning to the Group buffer.
2503 @node Summary Buffer Format
2504 @section Summary Buffer Format
2505 @cindex summary buffer format
2508 * Summary Buffer Lines:: You can specify how summary lines should look.
2509 * Summary Buffer Mode Line:: You can say how the mode line should look.
2510 * Summary Highlighting:: Making the summary buffer all pretty and nice.
2513 @findex mail-extract-address-components
2514 @findex gnus-extract-address-components
2515 @vindex gnus-extract-address-components
2516 Gnus will use the value of the @code{gnus-extract-address-components}
2517 variable as a function for getting the name and address parts of a
2518 @code{From} header. Two pre-defined function exist:
2519 @code{gnus-extract-address-components}, which is the default, quite
2520 fast, and too simplistic solution; and
2521 @code{mail-extract-address-components}, which works very nicely, but is
2522 slower. The default function will return the wrong answer in 5% of the
2523 cases. If this is unacceptable to you, use the other function instead.
2525 @vindex gnus-summary-same-subject
2526 @code{gnus-summary-same-subject} is a string indicating that the current
2527 article has the same subject as the previous. This string will be used
2528 with those specs that require it. The default is @samp{}.
2531 @node Summary Buffer Lines
2532 @subsection Summary Buffer Lines
2534 @vindex gnus-summary-line-format
2535 You can change the format of the lines in the summary buffer by changing
2536 the @code{gnus-summary-line-format} variable. It works along the same
2537 lines a a normal @code{format} string, with some extensions.
2539 The default string is @samp{%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n}.
2541 The following format specification characters are understood:
2549 Subject if the article is the root, @code{gnus-summary-same-subject}
2552 Full @code{From} line.
2554 The name (from the @code{From} header).
2556 The name (from the @code{From} header). This differs from the @code{n}
2557 spec in that it uses @code{gnus-extract-address-components}, which is
2558 slower, but may be more thorough.
2560 The address (from the @code{From} header). This works the same way as
2563 Number of lines in the article.
2565 Number of characters in the article.
2567 Indentation based on thread level (@pxref{Customizing Threading}).
2569 Nothing if the article is a root and lots of spaces if it isn't (it
2570 pushes everything after it off the screen).
2572 Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
2573 for adopted articles.
2575 Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
2576 for adopted articles.
2578 One space for each thread level.
2580 Twenty minus thread level spaces.
2588 @vindex gnus-summary-zcore-fuzz
2589 Zcore, @samp{+} if above the default level and @samp{-} if below the
2590 default level. If the difference between
2591 @code{gnus-summary-default-level} and the score is less than
2592 @code{gnus-summary-zcore-fuzz}, this spec will not be used.
2604 Number of articles in the current sub-thread. Using this spec will slow
2605 down summary buffer generation somewhat.
2607 A single character will be displayed if the article has any children.
2609 User defined specifier. The next character in the format string should
2610 be a letter. @sc{gnus} will call the function
2611 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
2612 following @samp{%u}. The function will be passed the current header as
2613 argument. The function should return a string, which will be inserted
2614 into the summary just like information from any other summary specifier.
2617 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
2618 have to be handled with care. For reasons of efficiency, Gnus will
2619 compute what column these characters will end up in, and ``hard-code''
2620 that. This means that it is illegal to have these specs after a
2621 variable-length spec. Well, you might not be arrested, but your summary
2622 buffer will look strange, which is bad enough.
2624 The smart choice is to have these specs as far to the left as possible.
2625 (Isn't that the case with everything, though? But I digress.)
2627 This restriction may disappear in later versions of Gnus.
2630 @node Summary Buffer Mode Line
2631 @subsection Summary Buffer Mode Line
2633 @vindex gnus-summary-mode-line-format
2634 You can also change the format of the summary mode bar. Set
2635 @code{gnus-summary-mode-line-format} to whatever you like. Here are the
2636 elements you can play with:
2642 Unprefixed group name.
2644 Current article number.
2648 Number of unread articles in this group.
2650 Number of unselected articles in this group.
2652 A string with the number of unread and unselected articles represented
2653 either as @samp{<%U(+%u) more>} if there are both unread and unselected
2654 articles, and just as @samp{<%U more>} if there are just unread articles
2655 and no unselected ones.
2657 Shortish group name. For instance, @samp{rec.arts.anime} will be
2658 shortened to @samp{r.a.anime}.
2660 Subject of the current article.
2664 Name of the current score file.
2666 Number of dormant articles.
2668 Number of ticked articles.
2670 Number of articles that have been marked as read in this session.
2672 Number of articles expunged by the score files.
2676 @node Summary Highlighting
2677 @subsection Summary Highlighting
2681 @item gnus-visual-mark-article-hook
2682 @vindex gnus-visual-mark-article-hook
2683 This hook is run after selecting an article. It is meant to be used for
2684 highlighting the article in some way. It is not run if
2685 @code{gnus-visual} is @code{nil}.
2687 @item gnus-summary-update-hook
2688 @vindex gnus-summary-update-hook
2689 This hook is called when a summary line is changed. It is not run if
2690 @code{gnus-visual} is @code{nil}.
2692 @item gnus-summary-selected-face
2693 @vindex gnus-summary-selected-face
2694 This is the face (or @dfn{font} as some people call it) that is used to
2695 highlight the current article in the summary buffer.
2697 @item gnus-summary-highlight
2698 @vindex gnus-summary-highlight
2699 Summary lines are highlighted according to this variable, which is a
2700 list where the elements are on the format @code{(FORM . FACE)}. If you
2701 would, for instance, like ticked articles to be italic and high-scored
2702 articles to be bold, you could set this variable to something like
2704 (((eq mark gnus-ticked-mark) . italic)
2705 ((> score default) . bold))
2707 As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
2708 @var{FACE} will be applied to the line.
2712 @node Summary Maneuvering
2713 @section Summary Maneuvering
2714 @cindex summary movement
2716 All the straight movement commands understand the numeric prefix and
2717 behave pretty much as you'd expect.
2719 None of these commands select articles.
2724 @kindex M-n (Summary)
2725 @kindex G M-n (Summary)
2726 @findex gnus-summary-next-unread-subject
2727 Go to the next summary line of an unread article
2728 (@code{gnus-summary-next-unread-subject}).
2732 @kindex M-p (Summary)
2733 @kindex G M-p (Summary)
2734 @findex gnus-summary-prev-unread-subject
2735 Go to the previous summary line of an unread article
2736 (@code{gnus-summary-prev-unread-subject}).
2741 @kindex G j (Summary)
2742 @findex gnus-summary-goto-article
2743 Ask for an article number and then go that article
2744 (@code{gnus-summary-goto-article}).
2747 @kindex G g (Summary)
2748 @findex gnus-summary-goto-subject
2749 Ask for an article number and then go the summary line of that article
2750 (@code{gnus-summary-goto-subject}).
2753 If Gnus asks you to press a key to confirm going to the next group, you
2754 can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
2755 buffer, searching for the next group to read without actually returning
2756 to the group buffer.
2758 Variables related to summary movement:
2762 @vindex gnus-auto-select-next
2763 @item gnus-auto-select-next
2764 If you are at the end of the group and issue one of the movement
2765 commands, Gnus will offer to go to the next group. If this variable is
2766 @code{t} and the next group is empty, Gnus will exit summary mode and
2767 return to the group buffer. If this variable is neither @code{t} nor
2768 @code{nil}, Gnus will select the next group, no matter whether it has
2769 any unread articles or not. As a special case, if this variable is
2770 @code{quietly}, Gnus will select the next group without asking for
2771 confirmation. If this variable is @code{almost-quietly}, the same will
2772 happen only if you are located on the last article in the group.
2773 Finally, if this variable is @code{slightly-quietly}, the @kbd{Z n}
2774 command will go to the next group without confirmation. Also
2775 @pxref{Group Levels}.
2777 @item gnus-auto-select-same
2778 @vindex gnus-auto-select-same
2779 If non-@code{nil}, all the movement commands will try to go to the next
2780 article with the same subject as the current. This variable is not
2781 particularly useful if you use a threaded display.
2783 @item gnus-summary-check-current
2784 @vindex gnus-summary-check-current
2785 If non-@code{nil}, all the ``unread'' movement commands will not proceed
2786 to the next (or previous) article if the current article is unread.
2787 Instead, they will choose the current article.
2789 @item gnus-auto-center-summary
2790 @vindex gnus-auto-center-summary
2791 If non-@code{nil}, Gnus will keep the point in the summary buffer
2792 centered at all times. This makes things quite tidy, but if you have a
2793 slow network connection, or simply do not like this un-Emacsism, you can
2794 set this variable to @code{nil} to get the normal Emacs scrolling
2795 action. This will also inhibit horizontal re-centering of the summary
2796 buffer, which might make it more inconvenient to read extremely long
2802 @node Choosing Articles
2803 @section Choosing Articles
2804 @cindex selecting articles
2806 None of the following movement commands understand the numeric prefix,
2807 and they all select and display an article.
2811 @kindex SPACE (Summary)
2812 @findex gnus-summary-next-page
2813 Select the current article, or, if that one's read already, the next
2814 unread article (@code{gnus-summary-next-page}).
2819 @kindex G n (Summary)
2820 @findex gnus-summary-next-unread-article
2821 Go to next unread article (@code{gnus-summary-next-unread-article}).
2826 @findex gnus-summary-prev-unread-article
2827 Go to previous unread article (@code{gnus-summary-prev-unread-article}).
2832 @kindex G N (Summary)
2833 @findex gnus-summary-next-article
2834 Go to the next article (@code{gnus-summary-next-article}).
2839 @kindex G P (Summary)
2840 @findex gnus-summary-prev-article
2841 Go to the previous article (@code{gnus-summary-prev-article}).
2844 @kindex G C-n (Summary)
2845 @findex gnus-summary-next-same-subject
2846 Go to the next article with the same subject
2847 (@code{gnus-summary-next-same-subject}).
2850 @kindex G C-p (Summary)
2851 @findex gnus-summary-prev-same-subject
2852 Go to the previous article with the same subject
2853 (@code{gnus-summary-prev-same-subject}).
2857 @kindex G f (Summary)
2859 @findex gnus-summary-first-unread-article
2860 Go to the first unread article
2861 (@code{gnus-summary-first-unread-article}).
2865 @kindex G b (Summary)
2867 @findex gnus-summary-best-unread-article
2868 Go to the article with the highest score
2869 (@code{gnus-summary-best-unread-article}).
2874 @kindex G l (Summary)
2875 @findex gnus-summary-goto-last-article
2876 Go to the previous article read (@code{gnus-summary-goto-last-article}).
2879 @kindex G p (Summary)
2880 @findex gnus-summary-pop-article
2881 Pop an article off the summary history and go to this article
2882 (@code{gnus-summary-pop-article}). This command differs from the
2883 command above in that you can pop as many previous articles off the
2884 history as you like.
2887 Some variables that are relevant for moving and selecting articles:
2890 @item gnus-auto-extend-newsgroup
2891 @vindex gnus-auto-extend-newsgroup
2892 All the movement commands will try to go to the previous (or next)
2893 article, even if that article isn't displayed in the Summary buffer if
2894 this variable is non-@code{nil}. Gnus will then fetch the article from
2895 the server and display it in the article buffer.
2897 @item gnus-select-article-hook
2898 @vindex gnus-select-article-hook
2899 This hook is called whenever an article is selected. By default it
2900 exposes any threads hidden under the selected article.
2902 @item gnus-mark-article-hook
2903 @vindex gnus-mark-article-hook
2904 @findex gnus-summary-mark-unread-as-read
2905 @findex gnus-summary-mark-read-and-unread-as-read
2906 @findex gnus-unread-mark
2907 This hook is called whenever an article is selected. It is intended to
2908 be used for marking articles as read. The default value is
2909 @code{gnus-summary-mark-read-and-unread-as-read}, and will change the
2910 mark of almost any article you read to @code{gnus-unread-mark}. The
2911 only articles not affected by this function are ticked, dormant, and
2912 expirable articles. If you'd instead like to just have unread articles
2913 marked as read, you can use @code{gnus-summary-mark-unread-as-read}
2914 instead. It will leave marks like @code{gnus-low-score-mark},
2915 @code{gnus-del-mark} (and so on) alone.
2920 @node Paging the Article
2921 @section Scrolling the Article
2922 @cindex article scrolling
2927 @kindex SPACE (Summary)
2928 @findex gnus-summary-next-page
2929 Pressing @kbd{SPACE} will scroll the current article forward one page,
2930 or, if you have come to the end of the current article, will choose the
2931 next article (@code{gnus-summary-next-page}).
2934 @kindex DEL (Summary)
2935 @findex gnus-summary-prev-page
2936 Scroll the current article back one page (@code{gnus-summary-prev-page}).
2939 @kindex RET (Summary)
2940 @findex gnus-summary-scroll-up
2941 Scroll the current article one line forward
2942 (@code{gnus-summary-scroll-up}).
2946 @kindex A g (Summary)
2948 @findex gnus-summary-show-article
2949 (Re)fetch the current article (@code{gnus-summary-show-article}). If
2950 given a prefix, fetch the current article, but don't run any of the
2951 article treatment functions. This will give you a ``raw'' article, just
2952 the way it came from the server.
2957 @kindex A < (Summary)
2958 @findex gnus-summary-beginning-of-article
2959 Scroll to the beginning of the article
2960 (@code{gnus-summary-beginning-of-article}).
2965 @kindex A > (Summary)
2966 @findex gnus-summary-end-of-article
2967 Scroll to the end of the article (@code{gnus-summary-end-of-article}).
2970 @kindex A s (Summary)
2971 @findex gnus-summary-isearch-article
2972 Perform an isearch in the article buffer
2973 (@code{gnus-summary-isearch-article}).
2978 @node Reply Followup and Post
2979 @section Reply, Followup and Post
2982 * Summary Mail Commands:: Sending mail.
2983 * Summary Post Commands:: Sending news.
2984 * Summary Mail and Post Commands:: Sending both news and mail.
2988 @node Summary Mail Commands
2989 @subsection Summary Mail Commands
2991 @cindex composing mail
2993 Commands for composing a mail message:
2999 @kindex S r (Summary)
3001 @findex gnus-summary-reply
3002 Mail a reply to the author of the current article
3003 (@code{gnus-summary-reply}).
3008 @kindex S R (Summary)
3009 @findex gnus-summary-reply-with-original
3010 Mail a reply to the author of the current article and include the
3011 original message (@code{gnus-summary-reply-with-original}). This
3012 command uses the process/prefix convention.
3015 @kindex S o m (Summary)
3016 @findex gnus-summary-mail-forward
3017 Forward the current article to some other person
3018 (@code{gnus-summary-mail-forward}).
3021 @kindex S o p (Summary)
3022 @findex gnus-summary-post-forward
3023 Forward the current article to a newsgroup
3024 (@code{gnus-summary-post-forward}).
3029 @kindex S m (Summary)
3030 @findex gnus-summary-mail-other-window
3031 Send a mail to some other person
3032 (@code{gnus-summary-mail-other-window}).
3035 @kindex S D b (Summary)
3036 @findex gnus-summary-resend-bounced-mail
3037 @vindex gnus-bounced-headers-junk
3038 @cindex bouncing mail
3039 If you have sent a mail, but the mail was bounced back to you for some
3040 reason (wrong address, transient failure), you can use this command to
3041 resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
3042 will be popped into a mail buffer where you can edit the headers before
3043 sending the mail off again. The headers that match the regexp
3044 @code{gnus-bounced-headers-junk} (default @samp{^Received:}) are
3045 automatically deleted first. If you give a prefix to this command, and
3046 the bounced mail is a reply to some other mail, Gnus will try to fetch
3047 that mail and display it for easy perusal of its headers. This might
3048 very well fail, though.
3051 @kindex S D r (Summary)
3052 @findex gnus-summary-resend-message
3053 @vindex gnus-ignored-resent-headers
3054 Not to be confused with the previous command,
3055 @code{gnus-summary-resend-message} will prompt you for an address to
3056 send the current message off to, and then send it to that place. The
3057 headers of the message won't be altered---but lots of headers that say
3058 @code{Resent-To}, @code{Resent-From} and so on will be added. This
3059 means that you actually send a mail to someone that has a @code{To}
3060 header that (probably) points to yourself. This will confuse people.
3061 So, natcherly you'll only do that if you're really eVIl. All old
3062 headers that match the regular expression
3063 @code{gnus-ignored-resent-headers} will be deleted before resending the
3064 message. The default is @samp{"^Return-receipt"}.
3066 This command is mainly used if you have several accounts and want to
3067 ship a mail to a different account of yours. (If you're both
3068 @code{root} and @code{postmaster} and get a mail for @code{postmaster}
3069 to the @code{root} account, you may want to resend it to
3070 @code{postmaster}. Ordnung muss sein!
3073 @kindex S O m (Summary)
3074 @findex gnus-uu-digest-mail-forward
3075 Digest the current series and forward the result using mail
3076 (@code{gnus-uu-digest-mail-forward}). This command uses the
3077 process/prefix convention (@pxref{Process/Prefix}).
3080 @kindex S O p (Summary)
3081 @findex gnus-uu-digest-post-forward
3082 Digest the current series and forward the result to a newsgroup
3083 (@code{gnus-uu-digest-mail-forward}).
3087 @node Summary Post Commands
3088 @subsection Summary Post Commands
3090 @cindex composing news
3092 Commands for posting an article:
3098 @kindex S p (Summary)
3099 @findex gnus-summary-post-news
3100 Post an article to the current group
3101 (@code{gnus-summary-post-news}).
3106 @kindex S f (Summary)
3107 @findex gnus-summary-followup
3108 Post a followup to the current article (@code{gnus-summary-followup}).
3112 @kindex S F (Summary)
3114 @findex gnus-summary-followup-with-original
3115 Post a followup to the current article and include the original message
3116 (@code{gnus-summary-followup-with-original}). This command uses the
3117 process/prefix convention.
3120 @kindex S u (Summary)
3121 @findex gnus-uu-post-news
3122 Uuencode a file, split it into parts, and post it as a series
3123 (@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}).
3127 @node Summary Mail and Post Commands
3128 @subsection Summary Mail and Post Commands
3129 @cindex mail and post
3130 @cindex post and mail
3132 Commands for sending mail and post at the same time:
3136 @kindex S b (Summary)
3137 @findex gnus-summary-followup-and-reply
3138 Post a followup and send a reply to the current article
3139 (@code{gnus-summary-followup-and-reply}).
3142 @kindex S B (Summary)
3143 @findex gnus-summary-followup-and-reply-with-original
3144 Post a followup and send a reply to the current article and include the
3145 original message (@code{gnus-summary-followup-and-reply-with-original}).
3146 This command uses the process/prefix convention.
3150 @node Canceling and Superseding
3151 @section Canceling Articles
3152 @cindex canceling articles
3153 @cindex superseding articles
3155 Have you ever written something, and then decided that you really,
3156 really, really wish you hadn't posted that?
3158 Well, you can't cancel mail, but you can cancel posts.
3160 @findex gnus-summary-cancel-article
3162 Find the article you wish to cancel (you can only cancel your own
3163 articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
3164 c} (@code{gnus-summary-cancel-article}). Your article will be
3165 canceled---machines all over the world will be deleting your article.
3167 Be aware, however, that not all sites honor cancels, so your article may
3168 live on here and there, while most sites will delete the article in
3171 If you discover that you have made some mistakes and want to do some
3172 corrections, you can post a @dfn{superseding} article that will replace
3173 your original article.
3175 @findex gnus-summary-supersede-article
3177 Go to the original article and press @kbd{S s}
3178 (@code{gnus-summary-supersede-article}). You will be put in a buffer
3179 where you can edit the article all you want before sending it off the
3182 @vindex gnus-delete-supersedes-headers
3183 You probably want to delete some of the old headers before sending the
3184 superseding article---@code{Path} and @code{Date} are probably
3185 incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
3186 match the lines you want removed. The default is
3187 @samp{^Path:\\|^Date}.
3189 The same goes for superseding as for canceling, only more so: Some
3190 sites do not honor superseding. On those sites, it will appear that you
3191 have posted almost the same article twice.
3193 If you have just posted the article, and change your mind right away,
3194 there is a trick you can use to cancel/supersede the article without
3195 waiting for the article to appear on your site first. You simply return
3196 to the post buffer (which is called @code{*post-buf*}). There you will
3197 find the article you just posted, with all the headers intact. Change
3198 the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes}
3199 header by substituting one of those words for @code{Message-ID}. Then
3200 just press @kbd{C-c C-c} to send the article as you would do normally.
3201 The previous article will be canceled/superseded.
3203 Just remember, kids: There is no 'c' in 'supersede'.
3206 @node Marking Articles
3207 @section Marking Articles
3208 @cindex article marking
3209 @cindex article ticking
3212 There are several marks you can set on an article.
3214 You have marks that decide the @dfn{readedness} (whoo, neato-keano
3215 neologism ohoy!) of the article. Alphabetic marks generally mean
3216 @dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
3218 In addition, you also have marks that do not affect readedness.
3221 * Unread Articles:: Marks for unread articles.
3222 * Read Articles:: Marks for read articles.
3223 * Other Marks:: Marks that do not affect readedness.
3227 There's a plethora of commands for manipulating these marks:
3231 * Setting Marks:: How to set and remove marks.
3232 * Setting Process Marks:: How to mark articles for later processing.
3236 @node Unread Articles
3237 @subsection Unread Articles
3239 The following marks mark articles as unread, in one form or other.
3241 @vindex gnus-dormant-mark
3242 @vindex gnus-ticked-mark
3245 @dfn{Ticked articles} are articles that will remain visible always. If
3246 you see an article that you find interesting, or you want to put off
3247 reading it, or replying to it, until sometime later, you'd typically
3248 tick it. However, articles can be expired, so if you want to keep an
3249 article forever, you'll have to save it. Ticked articles have a
3250 @samp{!} (@code{gnus-ticked-mark}) in the first column.
3253 @vindex gnus-dormant-mark
3254 A @dfn{dormant} article is marked with a @samp{?}
3255 (@code{gnus-dormant-mark}), and will only appear in the summary buffer
3256 if there are followups to it.
3259 @vindex gnus-unread-mark
3260 An @dfn{unread} article is marked with a @samp{SPACE}
3261 (@code{gnus-unread-mark}). These are articles that haven't been read at
3267 @subsection Read Articles
3268 @cindex expirable mark
3270 All the following marks mark articles as read.
3275 @vindex gnus-del-mark
3276 Articles that are marked as read. They have a @samp{r}
3277 (@code{gnus-del-mark}) in the first column. These are articles that the
3278 user has marked as read more or less manually.
3281 @vindex gnus-read-mark
3282 Articles that are actually read are marked with @samp{R}
3283 (@code{gnus-read-mark}).
3286 @vindex gnus-ancient-mark
3287 Articles that were marked as read in previous sessions are now
3288 @dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
3291 @vindex gnus-killed-mark
3292 Marked as killed (@code{gnus-killed-mark}).
3295 @vindex gnus-kill-file-mark
3296 Marked as killed by kill files (@code{gnus-kill-file-mark}).
3299 @vindex gnus-low-score-mark
3300 Marked as read by having a too low score (@code{gnus-low-score-mark}).
3303 @vindex gnus-catchup-mark
3304 Marked as read by a catchup (@code{gnus-catchup-mark}).
3307 @vindex gnus-canceled-mark
3308 Canceled article (@code{gnus-canceled-mark})
3311 @vindex gnus-souped-mark
3312 @sc{SOUP}ed article (@code{gnus-souped-mark}).
3315 @vindex gnus-sparse-mark
3316 Sparsely reffed article (@code{gnus-sparse-mark}).
3319 All these marks just mean that the article is marked as read, really.
3320 They are interpreted differently by the adaptive scoring scheme,
3323 One more special mark, though:
3327 @vindex gnus-expirable-mark
3328 You can also mark articles as @dfn{expirable} (or have them marked as
3329 such automatically). That doesn't make much sense in normal groups,
3330 because a user does not control the expiring of news articles, but in
3331 mail groups, for instance, articles that are marked as @dfn{expirable}
3332 can be deleted by Gnus at any time. Expirable articles are marked with
3333 @samp{E} (@code{gnus-expirable-mark}).
3338 @subsection Other Marks
3339 @cindex process mark
3342 There are some marks that have nothing to do with whether the article is
3348 You can set a bookmark in the current article. Say you are reading a
3349 long thesis on cats' urinary tracts, and have to go home for dinner
3350 before you've finished reading the thesis. You can then set a bookmark
3351 in the article, and Gnus will jump to this bookmark the next time it
3352 encounters the article.
3355 @vindex gnus-replied-mark
3356 All articles that you have replied to or made a followup to (i.e., have
3357 answered) will be marked with an @samp{A} in the second column
3358 (@code{gnus-replied-mark}).
3361 @vindex gnus-cached-mark
3362 Articles that are stored in the article cache will be marked with an
3363 @samp{*} in the second column (@code{gnus-cached-mark}).
3366 @vindex gnus-saved-mark
3367 Articles that are ``saved'' (in some manner or other; not necessarily
3368 religiously) are marked with an @samp{S} in the second column
3369 (@code{gnus-saved-mark}.
3372 @vindex gnus-not-empty-thread-mark
3373 @vindex gnus-empty-thread-mark
3374 It the @samp{%e} spec is used, the presence of threads or not will be
3375 marked with @code{gnus-not-empty-thread-mark} and
3376 @code{gnus-empty-thread-mark} in the third column, respectively.
3379 @vindex gnus-process-mark
3380 Finally we have the @dfn{process mark} (@code{gnus-process-mark}. A
3381 variety of commands react to the presence of the process mark. For
3382 instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
3383 all articles that have been marked with the process mark. Articles
3384 marked with the process mark have a @samp{#} in the second column.
3388 You might have noticed that most of these ``non-readedness'' marks
3389 appear in the second column by default. So if you have a cached, saved,
3390 replied article that you have process-marked, what will that look like?
3392 Nothing much. The precedence rules go as follows: process -> cache ->
3393 replied -> saved. So if the article is in the cache and is replied,
3394 you'll only see the cache mark and not the replied mark.
3398 @subsection Setting Marks
3399 @cindex setting marks
3401 All the marking commands understand the numeric prefix.
3407 @kindex M t (Summary)
3408 @findex gnus-summary-tick-article-forward
3409 Tick the current article (@code{gnus-summary-tick-article-forward}).
3414 @kindex M ? (Summary)
3415 @findex gnus-summary-mark-as-dormant
3416 Mark the current article as dormant
3417 (@code{gnus-summary-mark-as-dormant}).
3421 @kindex M d (Summary)
3423 @findex gnus-summary-mark-as-read-forward
3424 Mark the current article as read
3425 (@code{gnus-summary-mark-as-read-forward}).
3430 @kindex M k (Summary)
3431 @findex gnus-summary-kill-same-subject-and-select
3432 Mark all articles that have the same subject as the current one as read,
3433 and then select the next unread article
3434 (@code{gnus-summary-kill-same-subject-and-select}).
3438 @kindex M K (Summary)
3439 @kindex C-k (Summary)
3440 @findex gnus-summary-kill-same-subject
3441 Mark all articles that have the same subject as the current one as read
3442 (@code{gnus-summary-kill-same-subject}).
3445 @kindex M C (Summary)
3446 @findex gnus-summary-catchup
3447 Mark all unread articles in the group as read
3448 (@code{gnus-summary-catchup}).
3451 @kindex M C-c (Summary)
3452 @findex gnus-summary-catchup-all
3453 Mark all articles in the group as read---even the ticked and dormant
3454 articles (@code{gnus-summary-catchup-all}).
3457 @kindex M H (Summary)
3458 @findex gnus-summary-catchup-to-here
3459 Catchup the current group to point
3460 (@code{gnus-summary-catchup-to-here}).
3463 @kindex C-w (Summary)
3464 @findex gnus-summary-mark-region-as-read
3465 Mark all articles between point and mark as read
3466 (@code{gnus-summary-mark-region-as-read}).
3469 @kindex M V k (Summary)
3470 @findex gnus-summary-kill-below
3471 Kill all articles with scores below the default score (or below the
3472 numeric prefix) (@code{gnus-summary-kill-below}).
3476 @kindex M c (Summary)
3477 @kindex M-u (Summary)
3478 @findex gnus-summary-clear-mark-forward
3479 Clear all readedness-marks from the current article
3480 (@code{gnus-summary-clear-mark-forward}).
3484 @kindex M e (Summary)
3486 @findex gnus-summary-mark-as-expirable
3487 Mark the current article as expirable
3488 (@code{gnus-summary-mark-as-expirable}).
3491 @kindex M b (Summary)
3492 @findex gnus-summary-set-bookmark
3493 Set a bookmark in the current article
3494 (@code{gnus-summary-set-bookmark}).
3497 @kindex M B (Summary)
3498 @findex gnus-summary-remove-bookmark
3499 Remove the bookmark from the current article
3500 (@code{gnus-summary-remove-bookmark}).
3503 @kindex M V c (Summary)
3504 @findex gnus-summary-clear-above
3505 Clear all marks from articles with scores over the default score (or
3506 over the numeric prefix) (@code{gnus-summary-clear-above}).
3509 @kindex M V u (Summary)
3510 @findex gnus-summary-tick-above
3511 Tick all articles with scores over the default score (or over the
3512 numeric prefix) (@code{gnus-summary-tick-above}).
3515 @kindex M V m (Summary)
3516 @findex gnus-summary-mark-above
3517 Prompt for a mark, and mark all articles with scores over the default
3518 score (or over the numeric prefix) with this mark
3519 (@code{gnus-summary-clear-above}).
3522 @vindex gnus-summary-goto-unread
3523 The @code{gnus-summary-goto-unread} variable controls what action should
3524 be taken after setting a mark. If non-@code{nil}, point will move to
3525 the next/previous unread article. If @code{nil}, point will just move
3526 one line up or down. As a special case, if this variable is
3527 @code{never}, all the marking commands as well as other commands (like
3528 @kbd{SPACE}) will move to the next article, whether it is unread or not.
3529 The default is @code{t}.
3532 @node Setting Process Marks
3533 @subsection Setting Process Marks
3534 @cindex setting process marks
3541 @kindex M P p (Summary)
3542 @findex gnus-summary-mark-as-processable
3543 Mark the current article with the process mark
3544 (@code{gnus-summary-mark-as-processable}).
3545 @findex gnus-summary-unmark-as-processable
3549 @kindex M P u (Summary)
3550 @kindex M-# (Summary)
3551 Remove the process mark, if any, from the current article
3552 (@code{gnus-summary-unmark-as-processable}).
3555 @kindex M P U (Summary)
3556 @findex gnus-summary-unmark-all-processable
3557 Remove the process mark from all articles
3558 (@code{gnus-summary-unmark-all-processable}).
3561 @kindex M P R (Summary)
3562 @findex gnus-uu-mark-by-regexp
3563 Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
3566 @kindex M P r (Summary)
3567 @findex gnus-uu-mark-region
3568 Mark articles in region (@code{gnus-uu-mark-region}).
3571 @kindex M P t (Summary)
3572 @findex gnus-uu-mark-thread
3573 Mark all articles in the current (sub)thread
3574 (@code{gnus-uu-mark-thread}).
3577 @kindex M P T (Summary)
3578 @findex gnus-uu-unmark-thread
3579 Unmark all articles in the current (sub)thread
3580 (@code{gnus-uu-unmark-thread}).
3583 @kindex M P v (Summary)
3584 @findex gnus-uu-mark-over
3585 Mark all articles that have a score above the prefix argument
3586 (@code{gnus-uu-mark-over}).
3589 @kindex M P s (Summary)
3590 @findex gnus-uu-mark-series
3591 Mark all articles in the current series (@code{gnus-uu-mark-series}).
3594 @kindex M P S (Summary)
3595 @findex gnus-uu-mark-sparse
3596 Mark all series that have already had some articles marked
3597 (@code{gnus-uu-mark-sparse}).
3600 @kindex M P a (Summary)
3601 @findex gnus-uu-mark-all
3602 Mark all articles in series order (@code{gnus-uu-mark-series}).
3605 @kindex M P b (Summary)
3606 @findex gnus-uu-mark-buffer
3607 Mark all articles in the buffer in the order they appear
3608 (@code{gnus-uu-mark-buffer}).
3616 It can be convenient to limit the summary buffer to just show some
3617 subset of the articles currently in the group. The effect most limit
3618 commands have is to remove a few (or many) articles from the summary
3625 @kindex / / (Summary)
3626 @findex gnus-summary-limit-to-subject
3627 Limit the summary buffer to articles that match some subject
3628 (@code{gnus-summary-limit-to-subject}).
3631 @kindex / a (Summary)
3632 @findex gnus-summary-limit-to-author
3633 Limit the summary buffer to articles that match some author
3634 (@code{gnus-summary-limit-to-author}).
3638 @kindex / u (Summary)
3640 @findex gnus-summary-limit-to-unread
3641 Limit the summary buffer to articles that are not marked as read
3642 (@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
3643 buffer to articles that are strictly unread. This means that ticked and
3644 dormant articles will also be excluded.
3647 @kindex / m (Summary)
3648 @findex gnus-summary-limit-to-marks
3649 Ask for a mark and then limit to all articles that have not been marked
3650 with that mark (@code{gnus-summary-limit-to-marks}).
3653 @kindex / n (Summary)
3654 @findex gnus-summary-limit-to-articles
3655 Limit the summary buffer to the current article
3656 (@code{gnus-summary-limit-to-articles}). Uses the process/prefix
3657 convention (@pxref{Process/Prefix}).
3660 @kindex / w (Summary)
3661 @findex gnus-summary-pop-limit
3662 Pop the previous limit off the stack and restore it
3663 (@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
3667 @kindex / v (Summary)
3668 @findex gnus-summary-limit-to-score
3669 Limit the summary buffer to articles that have a score at or above some
3670 score (@code{gnus-summary-limit-to-score}).
3674 @kindex M S (Summary)
3675 @kindex / E (Summary)
3676 @findex gnus-summary-limit-include-expunged
3677 Display all expunged articles
3678 (@code{gnus-summary-limit-include-expunged}).
3681 @kindex / D (Summary)
3682 @findex gnus-summary-limit-include-dormant
3683 Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
3686 @kindex / d (Summary)
3687 @findex gnus-summary-limit-exclude-dormant
3688 Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
3691 @kindex / c (Summary)
3692 @findex gnus-summary-limit-exclude-childless-dormant
3693 Hide all dormant articles that have no children
3694 (@code{gnus-summary-limit-exclude-childless-dormant}).
3697 @kindex / C (Summary)
3698 @findex gnus-summary-limit-mark-excluded-as-read
3699 Mark all excluded unread articles as read
3700 (@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix,
3701 also mark excluded ticked and dormant articles as read.
3709 @cindex article threading
3711 Gnus threads articles by default. @dfn{To thread} is to put replies to
3712 articles directly after the articles they reply to---in a hierarchical
3716 * Customizing Threading:: Variables you can change to affect the threading.
3717 * Thread Commands:: Thread based commands in the summary buffer.
3721 @node Customizing Threading
3722 @subsection Customizing Threading
3723 @cindex customizing threading
3729 @item gnus-show-threads
3730 @vindex gnus-show-threads
3731 If this variable is @code{nil}, no threading will be done, and all of
3732 the rest of the variables here will have no effect. Turning threading
3733 off will speed group selection up a bit, but it is sure to make reading
3734 slower and more awkward.
3736 @item gnus-fetch-old-headers
3737 @vindex gnus-fetch-old-headers
3738 If non-@code{nil}, Gnus will attempt to build old threads by fetching
3739 more old headers---headers to articles that are marked as read. If you
3740 would like to display as few summary lines as possible, but still
3741 connect as many loose threads as possible, you should set this variable
3742 to @code{some} or a number. If you set it to a number, no more than
3743 that number of extra old headers will be fetched. In either case,
3744 fetching old headers only works if the backend you are using carries
3745 overview files---this would normally be @code{nntp}, @code{nnspool} and
3746 @code{nnml}. Also remember that if the root of the thread has been
3747 expired by the server, there's not much Gnus can do about that.
3749 @item gnus-build-sparse-threads
3750 @vindex gnus-build-sparse-threads
3751 Fetching old headers can be slow. A low-rent similar effect can be
3752 gotten by setting this variable to @code{some}. Gnus will then look at
3753 the complete @code{References} headers of all articles and try to string
3754 articles that belong in the same thread together. This will leave
3755 @dfn{gaps} in the threading display where Gnus guesses that an article
3756 is missing from the thread. (These gaps appear like normal summary
3757 lines. If you select a gap, Gnus will try to fetch the article in
3758 question.) If this variable is @code{t}, Gnus will display all these
3759 ``gaps'' without regard for whether they are useful for completing the
3760 thread or not. Finally, if this variable is @code{more}, Gnus won't cut
3761 off sparse leaf nodes that don't lead anywhere. This variable is
3762 @code{nil} by default.
3764 @item gnus-summary-gather-subject-limit
3765 @vindex gnus-summary-gather-subject-limit
3766 Loose threads are gathered by comparing subjects of articles. If this
3767 variable is @code{nil}, Gnus requires an exact match between the
3768 subjects of the loose threads before gathering them into one big
3769 super-thread. This might be too strict a requirement, what with the
3770 presence of stupid newsreaders that chop off long subjects lines. If
3771 you think so, set this variable to, say, 20 to require that only the
3772 first 20 characters of the subjects have to match. If you set this
3773 variable to a really low number, you'll find that Gnus will gather
3774 everything in sight into one thread, which isn't very helpful.
3776 @cindex fuzzy article gathering
3777 If you set this variable to the special value @code{fuzzy}, Gnus will
3778 use a fuzzy string comparison algorithm on the subjects.
3780 @item gnus-simplify-subject-fuzzy-regexp
3781 @vindex gnus-simplify-subject-fuzzy-regexp
3782 This can either be a regular expression or list of regular expressions
3783 that match strings that will be removed from subjects if fuzzy subject
3784 simplification is used.
3786 @item gnus-simplify-ignored-prefixes
3787 @vindex gnus-simplify-ignored-prefixes
3788 If you set @code{gnus-summary-gather-subject-limit} to something as low
3789 as 10, you might consider setting this variable to something sensible:
3791 @c Written by Michael Ernst <mernst@cs.rice.edu>
3793 (setq gnus-simplify-ignored-prefixes
3796 (mapconcat 'identity
3798 "wanted" "followup" "summary\\( of\\)?"
3799 "help" "query" "problem" "question"
3800 "answer" "reference" "announce"
3801 "How can I" "How to" "Comparison of"
3806 (mapconcat 'identity
3807 '("for" "for reference" "with" "about")
3809 "\\)?\\]?:?[ \t]*"))
3812 All words that match this regexp will be removed before comparing two
3815 @item gnus-summary-gather-exclude-subject
3816 @vindex gnus-summary-gather-exclude-subject
3817 Since loose thread gathering is done on subjects only, that might lead
3818 to many false hits, especially with certain common subjects like
3819 @samp{} and @samp{(none)}. To make the situation slightly better,
3820 you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
3821 what subjects should be excluded from the gathering process. The
3822 default is @samp{^ *$\\|^(none)$}.
3824 @item gnus-summary-thread-gathering-function
3825 @vindex gnus-summary-thread-gathering-function
3826 Gnus gathers threads by looking at @code{Subject} headers. This means
3827 that totally unrelated articles may end up in the same ``thread'', which
3828 is confusing. An alternate approach is to look at all the
3829 @code{Message-ID}s in all the @code{References} headers to find matches.
3830 This will ensure that no gathered threads ever includes unrelated
3831 articles, but it's also means that people who have posted with broken
3832 newsreaders won't be gathered properly. The choice is yours---plague or
3836 @item gnus-gather-threads-by-subject
3837 @findex gnus-gather-threads-by-subject
3838 This function is the default gathering function and looks at
3839 @code{Subject}s exclusively.
3841 @item gnus-gather-threads-by-references
3842 @findex gnus-gather-threads-by-references
3843 This function looks at @code{References} headers exclusively.
3846 If you want to test gathering by @code{References}, you could say
3850 (setq gnus-summary-thread-gathering-function
3851 'gnus-gather-threads-by-references)
3854 @item gnus-summary-make-false-root
3855 @vindex gnus-summary-make-false-root
3856 If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
3857 and create a dummy root at the top. (Wait a minute. Root at the top?
3858 Yup.) Loose subtrees occur when the real root has expired, or you've
3859 read or killed the root in a previous session.
3861 When there is no real root of a thread, Gnus will have to fudge
3862 something. This variable says what fudging method Gnus should use.
3863 There are four possible values:
3865 @cindex adopting articles
3870 Gnus will make the first of the orphaned articles the parent. This
3871 parent will adopt all the other articles. The adopted articles will be
3872 marked as such by pointy brackets (@samp{<>}) instead of the standard
3873 square brackets (@samp{[]}). This is the default method.
3876 @vindex gnus-summary-dummy-line-format
3877 Gnus will create a dummy summary line that will pretend to be the
3878 parent. This dummy line does not correspond to any real article, so
3879 selecting it will just select the first real article after the dummy
3880 article. @code{gnus-summary-dummy-line-format} is used to specify the
3881 format of the dummy roots. It accepts only one format spec: @samp{S},
3882 which is the subject of the article. @xref{Formatting Variables}.
3885 Gnus won't actually make any article the parent, but simply leave the
3886 subject field of all orphans except the first empty. (Actually, it will
3887 use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
3891 Don't make any article parent at all. Just gather the threads and
3892 display them after one another.
3895 Don't gather loose threads.
3898 @item gnus-thread-hide-subtree
3899 @vindex gnus-thread-hide-subtree
3900 If non-@code{nil}, all threads will be hidden when the summary buffer is
3903 @item gnus-thread-hide-killed
3904 @vindex gnus-thread-hide-killed
3905 if you kill a thread and this variable is non-@code{nil}, the subtree
3908 @item gnus-thread-ignore-subject
3909 @vindex gnus-thread-ignore-subject
3910 Sometimes somebody changes the subject in the middle of a thread. If
3911 this variable is non-@code{nil}, the subject change is ignored. If it
3912 is @code{nil}, which is the default, a change in the subject will result
3915 @item gnus-thread-indent-level
3916 @vindex gnus-thread-indent-level
3917 This is a number that says how much each sub-thread should be indented.
3918 The default is @code{4}.
3922 @node Thread Commands
3923 @subsection Thread Commands
3924 @cindex thread commands
3930 @kindex T k (Summary)
3931 @kindex M-C-k (Summary)
3932 @findex gnus-summary-kill-thread
3933 Mark all articles in the current sub-thread as read
3934 (@code{gnus-summary-kill-thread}). If the prefix argument is positive,
3935 remove all marks instead. If the prefix argument is negative, tick
3940 @kindex T l (Summary)
3941 @kindex M-C-l (Summary)
3942 @findex gnus-summary-lower-thread
3943 Lower the score of the current thread
3944 (@code{gnus-summary-lower-thread}).
3947 @kindex T i (Summary)
3948 @findex gnus-summary-raise-thread
3949 Increase the score of the current thread
3950 (@code{gnus-summary-raise-thread}).
3953 @kindex T # (Summary)
3954 @findex gnus-uu-mark-thread
3955 Set the process mark on the current thread
3956 (@code{gnus-uu-mark-thread}).
3959 @kindex T M-# (Summary)
3960 @findex gnus-uu-unmark-thread
3961 Remove the process mark from the current thread
3962 (@code{gnus-uu-unmark-thread}).
3965 @kindex T T (Summary)
3966 @findex gnus-summary-toggle-threads
3967 Toggle threading (@code{gnus-summary-toggle-threads}).
3970 @kindex T s (Summary)
3971 @findex gnus-summary-show-thread
3972 Expose the thread hidden under the current article, if any
3973 (@code{gnus-summary-show-thread}).
3976 @kindex T h (Summary)
3977 @findex gnus-summary-hide-thread
3978 Hide the current (sub)thread (@code{gnus-summary-hide-thread}).
3981 @kindex T S (Summary)
3982 @findex gnus-summary-show-all-threads
3983 Expose all hidden threads (@code{gnus-summary-show-all-threads}).
3986 @kindex T H (Summary)
3987 @findex gnus-summary-hide-all-threads
3988 Hide all threads (@code{gnus-summary-hide-all-threads}).
3991 @kindex T t (Summary)
3992 @findex gnus-summary-rethread-current
3993 Re-thread the thread the current article is part of
3994 (@code{gnus-summary-rethread-current}). This works even when the
3995 summary buffer is otherwise unthreaded.
3998 @kindex T ^ (Summary)
3999 @findex gnus-summary-reparent-thread
4000 Make the current article the child of the marked (or previous) article
4001 (@code{gnus-summary-reparent-thread}.
4005 The following commands are thread movement commands. They all
4006 understand the numeric prefix.
4011 @kindex T n (Summary)
4012 @findex gnus-summary-next-thread
4013 Go to the next thread (@code{gnus-summary-next-thread}).
4016 @kindex T p (Summary)
4017 @findex gnus-summary-prev-thread
4018 Go to the previous thread (@code{gnus-summary-prev-thread}).
4021 @kindex T d (Summary)
4022 @findex gnus-summary-down-thread
4023 Descend the thread (@code{gnus-summary-down-thread}).
4026 @kindex T u (Summary)
4027 @findex gnus-summary-up-thread
4028 Ascend the thread (@code{gnus-summary-up-thread}).
4031 @kindex T o (Summary)
4032 @findex gnus-summary-top-thread
4033 Go to the top of the thread (@code{gnus-summary-top-thread}).
4036 @vindex gnus-thread-operation-ignore-subject
4037 If you ignore subject while threading, you'll naturally end up with
4038 threads that have several different subjects in them. If you then issue
4039 a command like `T k' (@code{gnus-summary-kill-thread}) you might not
4040 wish to kill the entire thread, but just those parts of the thread that
4041 have the same subject as the current article. If you like this idea,
4042 you can fiddle with @code{gnus-thread-operation-ignore-subject}. If is
4043 is non-@code{nil} (which it is by default), subjects will be ignored
4044 when doing thread commands. If this variable is @code{nil}, articles in
4045 the same thread with different subjects will not be included in the
4046 operation in question. If this variable is @code{fuzzy}, only articles
4047 that have subjects that are fuzzily equal will be included.
4053 @findex gnus-thread-sort-by-total-score
4054 @findex gnus-thread-sort-by-date
4055 @findex gnus-thread-sort-by-score
4056 @findex gnus-thread-sort-by-subject
4057 @findex gnus-thread-sort-by-author
4058 @findex gnus-thread-sort-by-number
4059 @vindex gnus-thread-sort-functions
4060 If you are using a threaded summary display, you can sort the threads by
4061 setting @code{gnus-thread-sort-functions}, which is a list of functions.
4062 By default, sorting is done on article numbers. Ready-made sorting
4063 predicate functions include @code{gnus-thread-sort-by-number},
4064 @code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
4065 @code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and
4066 @code{gnus-thread-sort-by-total-score}.
4068 Each function takes two threads and return non-@code{nil} if the first
4069 thread should be sorted before the other. Note that sorting really is
4070 normally done by looking only at the roots of each thread. If you use
4071 more than one function, the primary sort key should be the last function
4072 in the list. You should probably always include
4073 @code{gnus-thread-sort-by-number} in the list of sorting
4074 functions---preferably first. This will ensure that threads that are
4075 equal with respect to the other sort criteria will be displayed in
4076 ascending article order.
4078 If you would like to sort by score, then by subject, and finally by
4079 number, you could do something like:
4082 (setq gnus-thread-sort-functions
4083 '(gnus-thread-sort-by-number
4084 gnus-thread-sort-by-subject
4085 gnus-thread-sort-by-score))
4088 The threads that have highest score will be displayed first in the
4089 summary buffer. When threads have the same score, they will be sorted
4090 alphabetically. The threads that have the same score and the same
4091 subject will be sorted by number, which is (normally) the sequence in
4092 which the articles arrived.
4094 If you want to sort by score and then reverse arrival order, you could
4098 (setq gnus-thread-sort-functions
4100 (not (gnus-thread-sort-by-number t1 t2)))
4101 gnus-thread-sort-by-score))
4104 @vindex gnus-thread-score-function
4105 The function in the @code{gnus-thread-score-function} variable (default
4106 @code{+}) is used for calculating the total score of a thread. Useful
4107 functions might be @code{max}, @code{min}, or squared means, or whatever
4110 @findex gnus-article-sort-functions
4111 @findex gnus-article-sort-by-date
4112 @findex gnus-article-sort-by-score
4113 @findex gnus-article-sort-by-subject
4114 @findex gnus-article-sort-by-author
4115 @findex gnus-article-sort-by-number
4116 If you are using an unthreaded display for some strange reason or other,
4117 you have to fiddle with the @code{gnus-article-sort-functions} variable.
4118 It is very similar to the @code{gnus-thread-sort-functions}, except that
4119 is uses slightly different functions for article comparison. Available
4120 sorting predicate functions are @code{gnus-article-sort-by-number},
4121 @code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject},
4122 @code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}.
4124 If you want to sort an unthreaded summary display by subject, you could
4128 (setq gnus-article-sort-functions
4129 '(gnus-article-sort-by-number
4130 gnus-article-sort-by-subject))
4135 @node Asynchronous Fetching
4136 @section Asynchronous Article Fetching
4137 @cindex asynchronous article fetching
4139 If you read your news from an @sc{nntp} server that's far away, the
4140 network latencies may make reading articles a chore. You have to wait
4141 for a while after pressing @kbd{n} to go to the next article before the
4142 article appears. Why can't Gnus just go ahead and fetch the article
4143 while you are reading the previous one? Why not, indeed.
4145 First, some caveats. There are some pitfalls to using asynchronous
4146 article fetching, especially the way Gnus does it.
4148 Let's say you are reading article 1, which is short, and article 2 is
4149 quite long, and you are not interested in reading that. Gnus does not
4150 know this, so it goes ahead and fetches article 2. You decide to read
4151 article 3, but since Gnus is in the process of fetching article 2, the
4152 connection is blocked.
4154 To avoid these situations, Gnus will open two (count 'em two)
4155 connections to the server. Some people may think this isn't a very nice
4156 thing to do, but I don't see any real alternatives. Setting up that
4157 extra connection takes some time, so Gnus startup will be slower.
4159 Gnus will fetch more articles than you will read. This will mean that
4160 the link between your machine and the @sc{nntp} server will become more
4161 loaded than if you didn't use article pre-fetch. The server itself will
4162 also become more loaded---both with the extra article requests, and the
4165 Ok, so now you know that you shouldn't really use this thing... unless
4168 @vindex gnus-asynchronous
4169 Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
4170 happen automatically.
4172 @vindex nntp-async-number
4173 You can control how many articles that are to be pre-fetched by setting
4174 @code{nntp-async-number}. This is five by default, which means that when
4175 you read an article in the group, @code{nntp} will pre-fetch the next
4176 five articles. If this variable is @code{t}, @code{nntp} will pre-fetch
4177 all the articles that it can without bound. If it is @code{nil}, no
4178 pre-fetching will be made.
4180 @vindex gnus-asynchronous-article-function
4181 You may wish to create some sort of scheme for choosing which articles
4182 that @code{nntp} should consider as candidates for pre-fetching. For
4183 instance, you may wish to pre-fetch all articles with high scores, and
4184 not pre-fetch low-scored articles. You can do that by setting the
4185 @code{gnus-asynchronous-article-function}, which will be called with an
4186 alist where the keys are the article numbers. Your function should
4187 return an alist where the articles you are not interested in have been
4188 removed. You could also do sorting on article score and the like.
4191 @node Article Caching
4192 @section Article Caching
4193 @cindex article caching
4196 If you have an @emph{extremely} slow @sc{nntp} connection, you may
4197 consider turning article caching on. Each article will then be stored
4198 locally under your home directory. As you may surmise, this could
4199 potentially use @emph{huge} amounts of disk space, as well as eat up all
4200 your inodes so fast it will make your head swim. In vodka.
4202 Used carefully, though, it could be just an easier way to save articles.
4204 @vindex gnus-use-long-file-name
4205 @vindex gnus-cache-directory
4206 @vindex gnus-use-cache
4207 To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
4208 all articles that are ticked or marked as dormant will then be copied
4209 over to your local cache (@code{gnus-cache-directory}). Whether this
4210 cache is flat or hierarchal is controlled by the
4211 @code{gnus-use-long-file-name} variable, as usual.
4213 When re-select a ticked or dormant article, it will be fetched from the
4214 cache instead of from the server. As articles in your cache will never
4215 expire, this might serve as a method of saving articles while still
4216 keeping them where they belong. Just mark all articles you want to save
4217 as dormant, and don't worry.
4219 When an article is marked as read, is it removed from the cache.
4221 @vindex gnus-cache-remove-articles
4222 @vindex gnus-cache-enter-articles
4223 The entering/removal of articles from the cache is controlled by the
4224 @code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
4225 variables. Both are lists of symbols. The first is @code{(ticked
4226 dormant)} by default, meaning that ticked and dormant articles will be
4227 put in the cache. The latter is @code{(read)} by default, meaning that
4228 articles that are marked as read are removed from the cache. Possibly
4229 symbols in these two lists are @code{ticked}, @code{dormant},
4230 @code{unread} and @code{read}.
4232 @findex gnus-jog-cache
4233 So where does the massive article-fetching and storing come into the
4234 picture? The @code{gnus-jog-cache} command will go through all
4235 subscribed newsgroups, request all unread articles, and store them in
4236 the cache. You should only ever, ever ever ever, use this command if 1)
4237 your connection to the @sc{nntp} server is really, really, really slow
4238 and 2) you have a really, really, really huge disk. Seriously.
4240 @vindex gnus-uncacheable-groups
4241 It is likely that you do not want caching on some groups. For instance,
4242 if your @code{nnml} mail is located under your home directory, it makes no
4243 sense to cache it somewhere else under your home directory. Unless you
4244 feel that it's neat to use twice as much space. To limit the caching,
4245 you could set the @code{gnus-uncacheable-groups} regexp to
4246 @samp{^nnml}, for instance. This variable is @code{nil} by
4249 @findex gnus-cache-generate-nov-databases
4250 @findex gnus-cache-generate-active
4251 @vindex gnus-cache-active-file
4252 The cache stores information on what articles it contains in its active
4253 file (@code{gnus-cache-active-file}). If this file (or any other parts
4254 of the cache) becomes all messed up for some reason or other, Gnus
4255 offers two functions that will try to set things right. @kbd{M-x
4256 gnus-cache-generate-nov-databases} will (re)build all the @sc{nov}
4257 files, and @kbd{gnus-cache-generate-active} will (re)generate the active
4261 @node Persistent Articles
4262 @section Persistent Articles
4263 @cindex persistent articles
4265 Closely related to article caching, we have @dfn{persistent articles}.
4266 In fact, it's just a different way of looking at caching, and much more
4267 useful in my opinion.
4269 Say you're reading a newsgroup, and you happen on to some valuable gem
4270 that you want to keep and treasure forever. You'd normally just save it
4271 (using one of the many saving commands) in some file. The problem with
4272 that is that it's just, well, yucky. Ideally you'd prefer just having
4273 the article remain in the group where you found it forever; untouched by
4274 the expiry going on at the news server.
4276 This is what a @dfn{persistent article} is---an article that just won't
4277 be deleted. It's implemented using the normal cache functions, but
4278 you use two explicit commands for managing persistent articles:
4284 @findex gnus-cache-enter-article
4285 Make the current article persistent (@code{gnus-cache-enter-article}).
4288 @kindex M-* (Summary)
4289 @findex gnus-cache-remove-article
4290 Remove the current article from the persistent articles
4291 (@code{gnus-cache-remove-article}). This will normally delete the
4295 Both these commands understand the process/prefix convention.
4297 To avoid having all ticked articles (and stuff) entered into the cache,
4298 you should set @code{gnus-use-cache} to @code{passive} if you're just
4299 interested in persistent articles:
4302 (setq gnus-use-cache 'passive)
4306 @node Article Backlog
4307 @section Article Backlog
4309 @cindex article backlog
4311 If you have a slow connection, but the idea of using caching seems
4312 unappealing to you (and it is, really), you can help the situation some
4313 by switching on the @dfn{backlog}. This is where Gnus will buffer
4314 already read articles so that it doesn't have to re-fetch articles
4315 you've already read. This only helps if you are in the habit of
4316 re-selecting articles you've recently read, of course. If you never do
4317 that, turning the backlog on will slow Gnus down a little bit, and
4318 increase memory usage some.
4320 @vindex gnus-keep-backlog
4321 If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store
4322 at most @var{n} old articles in a buffer for later re-fetching. If this
4323 variable is non-@code{nil} and is not a number, Gnus will store
4324 @emph{all} read articles, which means that your Emacs will grow without
4325 bound before exploding and taking your machine down with you. I put
4326 that in there just to keep y'all on your toes.
4328 This variable is @code{nil} by default.
4331 @node Saving Articles
4332 @section Saving Articles
4333 @cindex saving articles
4335 Gnus can save articles in a number of ways. Below is the documentation
4336 for saving articles in a fairly straight-forward fashion (i.e., little
4337 processing of the article is done before it is saved). For a different
4338 approach (uudecoding, unsharing) you should use @code{gnus-uu}
4339 (@pxref{Decoding Articles}).
4341 @vindex gnus-save-all-headers
4342 If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
4343 unwanted headers before saving the article.
4345 @vindex gnus-saved-headers
4346 If the preceding variable is @code{nil}, all headers that match the
4347 @code{gnus-saved-headers} regexp will be kept, while the rest will be
4348 deleted before saving.
4354 @kindex O o (Summary)
4356 @findex gnus-summary-save-article
4357 Save the current article using the default article saver
4358 (@code{gnus-summary-save-article}).
4361 @kindex O m (Summary)
4362 @findex gnus-summary-save-article-mail
4363 Save the current article in mail format
4364 (@code{gnus-summary-save-article-mail}).
4367 @kindex O r (Summary)
4368 @findex gnus-summary-save-article-rmail
4369 Save the current article in rmail format
4370 (@code{gnus-summary-save-article-rmail}).
4373 @kindex O f (Summary)
4374 @findex gnus-summary-save-article-file
4375 Save the current article in plain file format
4376 (@code{gnus-summary-save-article-file}).
4379 @kindex O b (Summary)
4380 @findex gnus-summary-save-article-body-file
4381 Save the current article body in plain file format
4382 (@code{gnus-summary-save-article-body-file}).
4385 @kindex O h (Summary)
4386 @findex gnus-summary-save-article-folder
4387 Save the current article in mh folder format
4388 (@code{gnus-summary-save-article-folder}).
4391 @kindex O v (Summary)
4392 @findex gnus-summary-save-article-vm
4393 Save the current article in a VM folder
4394 (@code{gnus-summary-save-article-vm}).
4397 @kindex O p (Summary)
4398 @findex gnus-summary-pipe-output
4399 Save the current article in a pipe. Uhm, like, what I mean is---Pipe
4400 the current article to a process (@code{gnus-summary-pipe-output}).
4403 @vindex gnus-prompt-before-saving
4404 All these commands use the process/prefix convention
4405 (@pxref{Process/Prefix}). If you save bunches of articles using these
4406 functions, you might get tired of being prompted for files to save each
4407 and every article in. The prompting action is controlled by
4408 the @code{gnus-prompt-before-saving} variable, which is @code{always} by
4409 default, giving you that excessive prompting action you know and
4410 loathe. If you set this variable to @code{t} instead, you'll be prompted
4411 just once for each series of articles you save. If you like to really
4412 have Gnus do all your thinking for you, you can even set this variable
4413 to @code{nil}, which means that you will never be prompted for files to
4414 save articles in. Gnus will simply save all the articles in the default
4418 @vindex gnus-default-article-saver
4419 You can customize the @code{gnus-default-article-saver} variable to make
4420 Gnus do what you want it to. You can use any of the four ready-made
4421 functions below, or you can create your own.
4425 @item gnus-summary-save-in-rmail
4426 @findex gnus-summary-save-in-rmail
4427 @vindex gnus-rmail-save-name
4428 @findex gnus-plain-save-name
4429 This is the default format, @dfn{babyl}. Uses the function in the
4430 @code{gnus-rmail-save-name} variable to get a file name to save the
4431 article in. The default is @code{gnus-plain-save-name}.
4433 @item gnus-summary-save-in-mail
4434 @findex gnus-summary-save-in-mail
4435 @vindex gnus-mail-save-name
4436 Save in a Unix mail (mbox) file. Uses the function in the
4437 @code{gnus-mail-save-name} variable to get a file name to save the
4438 article in. The default is @code{gnus-plain-save-name}.
4440 @item gnus-summary-save-in-file
4441 @findex gnus-summary-save-in-file
4442 @vindex gnus-file-save-name
4443 @findex gnus-numeric-save-name
4444 Append the article straight to an ordinary file. Uses the function in
4445 the @code{gnus-file-save-name} variable to get a file name to save the
4446 article in. The default is @code{gnus-numeric-save-name}.
4448 @item gnus-summary-save-body-in-file
4449 @findex gnus-summary-save-body-in-file
4450 Append the article body to an ordinary file. Uses the function in the
4451 @code{gnus-file-save-name} variable to get a file name to save the
4452 article in. The default is @code{gnus-numeric-save-name}.
4454 @item gnus-summary-save-in-folder
4455 @findex gnus-summary-save-in-folder
4456 @findex gnus-folder-save-name
4457 @findex gnus-Folder-save-name
4458 @vindex gnus-folder-save-name
4461 Save the article to an MH folder using @code{rcvstore} from the MH
4462 library. Uses the function in the @code{gnus-folder-save-name} variable
4463 to get a file name to save the article in. The default is
4464 @code{gnus-folder-save-name}, but you can also use
4465 @code{gnus-Folder-save-name}. The former creates capitalized names, and
4466 the latter does not.
4468 @item gnus-summary-save-in-vm
4469 @findex gnus-summary-save-in-vm
4470 Save the article in a VM folder. You have to have the VM mail
4471 reader to use this setting.
4474 @vindex gnus-article-save-directory
4475 All of these functions, except for the last one, will save the article
4476 in the @code{gnus-article-save-directory}, which is initialized from the
4477 @code{SAVEDIR} environment variable. This is @file{~/News/} by
4480 As you can see above, the functions use different functions to find a
4481 suitable name of a file to save the article in. Below is a list of
4482 available functions that generate names:
4486 @item gnus-Numeric-save-name
4487 @findex gnus-Numeric-save-name
4488 Generates file names that look like @file{~/News/Alt.andrea-dworkin/45}.
4490 @item gnus-numeric-save-name
4491 @findex gnus-numeric-save-name
4492 Generates file names that look like @file{~/News/alt.andrea-dworkin/45}.
4494 @item gnus-Plain-save-name
4495 @findex gnus-Plain-save-name
4496 Generates file names that look like @file{~/News/Alt.andrea-dworkin}.
4498 @item gnus-plain-save-name
4499 @findex gnus-plain-save-name
4500 Generates file names that look like @file{~/News/alt.andrea-dworkin}.
4503 @vindex gnus-split-methods
4504 You can have Gnus suggest where to save articles by plonking a regexp into
4505 the @code{gnus-split-methods} alist. For instance, if you would like to
4506 save articles related to Gnus in the file @file{gnus-stuff}, and articles
4507 related to VM in @code{vm-stuff}, you could set this variable to something
4511 (("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
4512 ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff")
4513 (my-choosing-function "../other-dir/my-stuff")
4514 ((equal gnus-newsgroup-name "mail.misc") "mail-stuff"))
4517 We see that this is a list where each element is a list that has two
4518 elements---the @dfn{match} and the @dfn{file}. The match can either be
4519 a string (in which case it is used as a regexp to match on the article
4520 head); it can be a symbol (which will be called as a function); or it
4521 can be a list (which will be @code{eval}ed). If any of these actions
4522 have a non-@code{nil} result, the @dfn{file} will be used as a default
4523 prompt. In addition, the result of the operation itself will be used if
4524 the function or form called returns a string or a list of strings.
4526 You basically end up with a list of file names that might be used when
4527 saving the current article. (All ``matches'' will be used.) You will
4528 then be prompted for what you really want to use as a name, with file
4529 name completion over the results from applying this variable.
4531 This variable is @code{((gnus-article-archive-name))} by default, which
4532 means that Gnus will look at the articles it saves for an
4533 @code{Archive-name} line and use that as a suggestion for the file
4536 @vindex gnus-use-long-file-name
4537 Finally, you have the @code{gnus-use-long-file-name} variable. If it is
4538 @code{nil}, all the preceding functions will replace all periods
4539 (@samp{.}) in the group names with slashes (@samp{/})---which means that
4540 the functions will generate hierarchies of directories instead of having
4541 all the files in the toplevel directory
4542 (@file{~/News/alt/andrea-dworkin} instead of
4543 @file{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default
4544 on most systems. However, for historical reasons, this is @code{nil} on
4545 Xenix and usg-unix-v machines by default.
4547 This function also affects kill and score file names. If this variable
4548 is a list, and the list contains the element @code{not-score}, long file
4549 names will not be used for score files, if it contains the element
4550 @code{not-save}, long file names will not be used for saving, and if it
4551 contains the element @code{not-kill}, long file names will not be used
4554 If you'd like to save articles in a hierarchy that looks something like
4558 (setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
4559 (setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
4562 Then just save with @kbd{o}. You'd then read this hierarchy with
4563 ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
4564 the toplevel directory as the argument (@file{~/News/}). Then just walk
4565 around to the groups/directories with @code{nneething}.
4568 @node Decoding Articles
4569 @section Decoding Articles
4570 @cindex decoding articles
4572 Sometime users post articles (or series of articles) that have been
4573 encoded in some way or other. Gnus can decode them for you.
4576 * Uuencoded Articles:: Uudecode articles.
4577 * Shared Articles:: Unshar articles.
4578 * PostScript Files:: Split PostScript.
4579 * Decoding Variables:: Variables for a happy decoding.
4580 * Viewing Files:: You want to look at the result of the decoding?
4583 All these functions use the process/prefix convention
4584 (@pxref{Process/Prefix}) for finding out what articles to work on, with
4585 the extension that a ``single article'' means ``a single series''. Gnus
4586 can find out by itself what articles belong to a series, decode all the
4587 articles and unpack/view/save the resulting file(s).
4589 Gnus guesses what articles are in the series according to the following
4590 simplish rule: The subjects must be (nearly) identical, except for the
4591 last two numbers of the line. (Spaces are largely ignored, however.)
4593 For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus
4594 will find all the articles that match the regexp @samp{^cat.gif
4595 ([0-9]+/[0-9]+).*$}.
4597 Subjects that are nonstandard, like @samp{cat.gif (2/3) Part 6 of a
4598 series}, will not be properly recognized by any of the automatic viewing
4599 commands, and you have to mark the articles manually with @kbd{#}.
4602 @node Uuencoded Articles
4603 @subsection Uuencoded Articles
4605 @cindex uuencoded articles
4610 @kindex X u (Summary)
4611 @findex gnus-uu-decode-uu
4612 Uudecodes the current series (@code{gnus-uu-decode-uu}).
4615 @kindex X U (Summary)
4616 @findex gnus-uu-decode-uu-and-save
4617 Uudecodes and saves the current series
4618 (@code{gnus-uu-decode-uu-and-save}).
4621 @kindex X v u (Summary)
4622 @findex gnus-uu-decode-uu-view
4623 Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
4626 @kindex X v U (Summary)
4627 @findex gnus-uu-decode-uu-and-save-view
4628 Uudecodes, views and saves the current series
4629 (@code{gnus-uu-decode-uu-and-save-view}).
4632 Remember that these all react to the presence of articles marked with
4633 the process mark. If, for instance, you'd like to decode and save an
4634 entire newsgroup, you'd typically do @kbd{M P a}
4635 (@code{gnus-uu-mark-all}) and then @kbd{X U}
4636 (@code{gnus-uu-decode-uu-and-save}).
4638 All this is very much different from how @code{gnus-uu} worked with
4639 @sc{gnus 4.1}, where you had explicit keystrokes for everything under
4640 the sun. This version of @code{gnus-uu} generally assumes that you mark
4641 articles in some way (@pxref{Setting Process Marks}) and then press
4644 @vindex gnus-uu-notify-files
4645 Note: When trying to decode articles that have names matching
4646 @code{gnus-uu-notify-files}, which is hard-coded to
4647 @samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
4648 automatically post an article on @samp{comp.unix.wizards} saying that
4649 you have just viewed the file in question. This feature can't be turned
4653 @node Shared Articles
4654 @subsection Shared Articles
4656 @cindex shared articles
4661 @kindex X s (Summary)
4662 @findex gnus-uu-decode-unshar
4663 Unshars the current series (@code{gnus-uu-decode-unshar}).
4666 @kindex X S (Summary)
4667 @findex gnus-uu-decode-unshar-and-save
4668 Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
4671 @kindex X v s (Summary)
4672 @findex gnus-uu-decode-unshar-view
4673 Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
4676 @kindex X v S (Summary)
4677 @findex gnus-uu-decode-unshar-and-save-view
4678 Unshars, views and saves the current series
4679 (@code{gnus-uu-decode-unshar-and-save-view}).
4683 @node PostScript Files
4684 @subsection PostScript Files
4690 @kindex X p (Summary)
4691 @findex gnus-uu-decode-postscript
4692 Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
4695 @kindex X P (Summary)
4696 @findex gnus-uu-decode-postscript-and-save
4697 Unpack and save the current PostScript series
4698 (@code{gnus-uu-decode-postscript-and-save}).
4701 @kindex X v p (Summary)
4702 @findex gnus-uu-decode-postscript-view
4703 View the current PostScript series
4704 (@code{gnus-uu-decode-postscript-view}).
4707 @kindex X v P (Summary)
4708 @findex gnus-uu-decode-postscript-and-save-view
4709 View and save the current PostScript series
4710 (@code{gnus-uu-decode-postscript-and-save-view}).
4714 @node Decoding Variables
4715 @subsection Decoding Variables
4717 Adjective, not verb.
4720 * Rule Variables:: Variables that say how a file is to be viewed.
4721 * Other Decode Variables:: Other decode variables.
4722 * Uuencoding and Posting:: Variables for customizing uuencoding.
4726 @node Rule Variables
4727 @subsubsection Rule Variables
4728 @cindex rule variables
4730 Gnus uses @dfn{rule variables} to decide how to view a file. All these
4731 variables are on the form
4734 (list '(regexp1 command2)
4741 @item gnus-uu-user-view-rules
4742 @vindex gnus-uu-user-view-rules
4744 This variable is consulted first when viewing files. If you wish to use,
4745 for instance, @code{sox} to convert an @samp{.au} sound file, you could
4748 (setq gnus-uu-user-view-rules
4749 (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
4752 @item gnus-uu-user-view-rules-end
4753 @vindex gnus-uu-user-view-rules-end
4754 This variable is consulted if Gnus couldn't make any matches from the
4755 user and default view rules.
4757 @item gnus-uu-user-archive-rules
4758 @vindex gnus-uu-user-archive-rules
4759 This variable can be used to say what commands should be used to unpack
4764 @node Other Decode Variables
4765 @subsubsection Other Decode Variables
4768 @vindex gnus-uu-grabbed-file-functions
4770 @item gnus-uu-grabbed-file-functions
4771 All functions in this list will be called right each file has been
4772 successfully decoded---so that you can move or view files right away,
4773 and don't have to wait for all files to be decoded before you can do
4774 anything. Ready-made functions you can put in this list are:
4778 @item gnus-uu-grab-view
4779 @findex gnus-uu-grab-view
4782 @item gnus-uu-grab-move
4783 @findex gnus-uu-grab-move
4784 Move the file (if you're using a saving function.)
4787 @item gnus-uu-ignore-files-by-name
4788 @vindex gnus-uu-ignore-files-by-name
4789 Files with name matching this regular expression won't be viewed.
4791 @item gnus-uu-ignore-files-by-type
4792 @vindex gnus-uu-ignore-files-by-type
4793 Files with a @sc{mime} type matching this variable won't be viewed.
4794 Note that Gnus tries to guess what type the file is based on the name.
4795 @code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
4798 @item gnus-uu-tmp-dir
4799 @vindex gnus-uu-tmp-dir
4800 Where @code{gnus-uu} does its work.
4802 @item gnus-uu-do-not-unpack-archives
4803 @vindex gnus-uu-do-not-unpack-archives
4804 Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
4805 looking for files to display.
4807 @item gnus-uu-view-and-save
4808 @vindex gnus-uu-view-and-save
4809 Non-@code{nil} means that the user will always be asked to save a file
4812 @item gnus-uu-ignore-default-view-rules
4813 @vindex gnus-uu-ignore-default-view-rules
4814 Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
4817 @item gnus-uu-ignore-default-archive-rules
4818 @vindex gnus-uu-ignore-default-archive-rules
4819 Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
4822 @item gnus-uu-kill-carriage-return
4823 @vindex gnus-uu-kill-carriage-return
4824 Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
4827 @item gnus-uu-unmark-articles-not-decoded
4828 @vindex gnus-uu-unmark-articles-not-decoded
4829 Non-@code{nil} means that @code{gnus-uu} will mark articles that were
4830 unsuccessfully decoded as unread.
4832 @item gnus-uu-correct-stripped-uucode
4833 @vindex gnus-uu-correct-stripped-uucode
4834 Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
4835 uuencoded files that have had trailing spaces deleted.
4837 @item gnus-uu-view-with-metamail
4838 @vindex gnus-uu-view-with-metamail
4840 Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
4841 commands defined by the rule variables and just fudge a @sc{mime}
4842 content type based on the file name. The result will be fed to
4843 @code{metamail} for viewing.
4845 @item gnus-uu-save-in-digest
4846 @vindex gnus-uu-save-in-digest
4847 Non-@code{nil} means that @code{gnus-uu}, when asked to save without
4848 decoding, will save in digests. If this variable is @code{nil},
4849 @code{gnus-uu} will just save everything in a file without any
4850 embellishments. The digesting almost conforms to RFC1153---no easy way
4851 to specify any meaningful volume and issue numbers were found, so I
4852 simply dropped them.
4857 @node Uuencoding and Posting
4858 @subsubsection Uuencoding and Posting
4862 @item gnus-uu-post-include-before-composing
4863 @vindex gnus-uu-post-include-before-composing
4864 Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
4865 before you compose the article. If this variable is @code{t}, you can
4866 either include an encoded file with @kbd{C-c C-i} or have one included
4867 for you when you post the article.
4869 @item gnus-uu-post-length
4870 @vindex gnus-uu-post-length
4871 Maximum length of an article. The encoded file will be split into how
4872 many articles it takes to post the entire file.
4874 @item gnus-uu-post-threaded
4875 @vindex gnus-uu-post-threaded
4876 Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
4877 thread. This may not be smart, as no other decoder I have seen are able
4878 to follow threads when collecting uuencoded articles. (Well, I have
4879 seen one package that does that---@code{gnus-uu}, but somehow, I don't
4880 think that counts...) Default is @code{nil}.
4882 @item gnus-uu-post-separate-description
4883 @vindex gnus-uu-post-separate-description
4884 Non-@code{nil} means that the description will be posted in a separate
4885 article. The first article will typically be numbered (0/x). If this
4886 variable is @code{nil}, the description the user enters will be included
4887 at the beginning of the first article, which will be numbered (1/x).
4888 Default is @code{t}.
4894 @subsection Viewing Files
4895 @cindex viewing files
4896 @cindex pseudo-articles
4898 After decoding, if the file is some sort of archive, Gnus will attempt
4899 to unpack the archive and see if any of the files in the archive can be
4900 viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
4901 containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
4902 uncompress and de-tar the main file, and then view the two pictures.
4903 This unpacking process is recursive, so if the archive contains archives
4904 of archives, it'll all be unpacked.
4906 Finally, Gnus will normally insert a @dfn{pseudo-article} for each
4907 extracted file into the summary buffer. If you go to these
4908 ``articles'', you will be prompted for a command to run (usually Gnus
4909 will make a suggestion), and then the command will be run.
4911 @vindex gnus-view-pseudo-asynchronously
4912 If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
4913 until the viewing is done before proceeding.
4915 @vindex gnus-view-pseudos
4916 If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
4917 the pseudo-articles into the summary buffer, but view them
4918 immediately. If this variable is @code{not-confirm}, the user won't even
4919 be asked for a confirmation before viewing is done.
4921 @vindex gnus-view-pseudos-separately
4922 If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
4923 pseudo-article will be created for each file to be viewed. If
4924 @code{nil}, all files that use the same viewing command will be given as
4925 a list of parameters to that command.
4927 @vindex gnus-insert-pseudo-articles
4928 If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert
4929 pseudo-articles when decoding. It is @code{t} by default.
4931 So; there you are, reading your @emph{pseudo-articles} in your
4932 @emph{virtual newsgroup} from the @emph{virtual server}; and you think:
4933 Why isn't anything real anymore? How did we get here?
4936 @node Article Treatment
4937 @section Article Treatment
4939 Reading through this huge manual, you may have quite forgotten that the
4940 object of newsreaders are to actually, like, read what people have
4941 written. Reading articles. Unfortunately, people are quite bad at
4942 writing, so there are tons of functions and variables to make reading
4943 these articles easier.
4946 * Article Highlighting:: You want to make the article look like fruit salad.
4947 * Article Hiding:: You also want to make certain info go away.
4948 * Article Washing:: Lots of way-neat functions to make life better.
4949 * Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
4950 * Article Date:: Grumble, UT!
4954 @node Article Highlighting
4955 @subsection Article Highlighting
4958 Not only do you want your article buffer to look like fruit salad, but
4959 you want it to look like technicolor fruit salad.
4964 @kindex W H a (Summary)
4965 @findex gnus-article-highlight
4966 Highlight the current article (@code{gnus-article-highlight}).
4969 @kindex W H h (Summary)
4970 @findex gnus-article-highlight-headers
4971 @vindex gnus-header-face-alist
4972 Highlight the headers (@code{gnus-article-highlight-headers}). The
4973 highlighting will be done according to the @code{gnus-header-face-alist}
4974 variable, which is a list where each element has the form @var{(regexp
4975 name content)}. @var{regexp} is a regular expression for matching the
4976 header, @var{name} is the face used for highlighting the header name and
4977 @var{content} is the face for highlighting the header value. The first
4978 match made will be used. Note that @var{regexp} shouldn't have @samp{^}
4979 prepended---Gnus will add one.
4982 @kindex W H c (Summary)
4983 @findex gnus-article-highlight-citation
4984 Highlight cited text (@code{gnus-article-highlight-citation}).
4986 Some variables to customize the citation highlights:
4989 @vindex gnus-cite-parse-max-size
4991 @item gnus-cite-parse-max-size
4992 If the article size if bigger than this variable (which is 25000 by
4993 default), no citation highlighting will be performed.
4995 @item gnus-cite-prefix-regexp
4996 @vindex gnus-cite-prefix-regexp
4997 Regexp matching the longest possible citation prefix on a line.
4999 @item gnus-cite-max-prefix
5000 @vindex gnus-cite-max-prefix
5001 Maximum possible length for a citation prefix (default 20).
5003 @item gnus-cite-face-list
5004 @vindex gnus-cite-face-list
5005 List of faces used for highlighting citations. When there are citations
5006 from multiple articles in the same message, Gnus will try to give each
5007 citation from each article its own face. This should make it easier to
5010 @item gnus-supercite-regexp
5011 @vindex gnus-supercite-regexp
5012 Regexp matching normal SuperCite attribution lines.
5014 @item gnus-supercite-secondary-regexp
5015 @vindex gnus-supercite-secondary-regexp
5016 Regexp matching mangled SuperCite attribution lines.
5018 @item gnus-cite-minimum-match-count
5019 @vindex gnus-cite-minimum-match-count
5020 Minimum number of identical prefixes we have to see before we believe
5021 that it's a citation.
5023 @item gnus-cite-attribution-prefix
5024 @vindex gnus-cite-attribution-prefix
5025 Regexp matching the beginning of an attribution line.
5027 @item gnus-cite-attribution-suffix
5028 @vindex gnus-cite-attribution-suffix
5029 Regexp matching the end of an attribution line.
5031 @item gnus-cite-attribution-face
5032 @vindex gnus-cite-attribution-face
5033 Face used for attribution lines. It is merged with the face for the
5034 cited text belonging to the attribution.
5040 @kindex W H s (Summary)
5041 @vindex gnus-signature-separator
5042 @vindex gnus-signature-face
5043 @findex gnus-article-highlight-signature
5044 Highlight the signature (@code{gnus-article-highlight-signature}).
5045 Everything after @code{gnus-signature-separator} in an article will be
5046 considered a signature and will be highlighted with
5047 @code{gnus-signature-face}, which is @code{italic} by default.
5052 @node Article Hiding
5053 @subsection Article Hiding
5054 @cindex article hiding
5056 Or rather, hiding certain things in each article. There usually is much
5057 too much cruft in most articles.
5062 @kindex W W a (Summary)
5063 @findex gnus-article-hide
5064 Do maximum hiding on the summary buffer (@kbd{gnus-article-hide}).
5067 @kindex W W h (Summary)
5068 @findex gnus-article-hide-headers
5069 Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
5073 @kindex W W b (Summary)
5074 @findex gnus-article-hide-boring-headers
5075 Hide headers that aren't particularly interesting
5076 (@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}.
5079 @kindex W W s (Summary)
5080 @findex gnus-article-hide-signature
5081 Hide signature (@code{gnus-article-hide-signature}).
5084 @kindex W W p (Summary)
5085 @findex gnus-article-hide-pgp
5086 Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}).
5089 @kindex W W c (Summary)
5090 @findex gnus-article-hide-citation
5091 Hide citation (@code{gnus-article-hide-citation}). Some variables for
5092 customizing the hiding:
5096 @item gnus-cite-hide-percentage
5097 @vindex gnus-cite-hide-percentage
5098 If the cited text is of a bigger percentage than this variable (default
5099 50), hide the cited text.
5101 @item gnus-cite-hide-absolute
5102 @vindex gnus-cite-hide-absolute
5103 The cited text must be have at least this length (default 10) before it
5106 @item gnus-cited-text-button-line-format
5107 @vindex gnus-cited-text-button-line-format
5108 Gnus adds buttons show where the cited text has been hidden, and to
5109 allow toggle hiding the text. The format of the variable is specified
5110 by this format-like variable. These specs are legal:
5114 Start point of the hidden text.
5116 End point of the hidden text.
5118 Length of the hidden text.
5121 @item gnus-cited-lines-visible
5122 @vindex gnus-cited-lines-visible
5123 The number of lines at the beginning of the cited text to leave shown.
5128 @kindex W W C (Summary)
5129 @findex gnus-article-hide-citation-in-followups
5130 Hide cited text in articles that aren't roots
5131 (@code{gnus-article-hide-citation-in-followups}). This isn't very
5132 useful as an interactive command, but might be a handy function to stick
5133 in @code{gnus-article-display-hook} (@pxref{Customizing Articles}).
5137 All these ``hiding'' commands are toggles, but if you give a negative
5138 prefix to these commands, they will show what they have previously
5139 hidden. If you give a positive prefix, they will always hide.
5141 Also @pxref{Article Highlighting} for further variables for
5142 citation customization.
5144 @vindex gnus-signature-limit
5145 @code{gnus-signature-limit} provides a limit to what is considered a
5146 signature. If it is a number, no signature may not be longer (in
5147 characters) than that number. If it is a function, the function will be
5148 called without any parameters, and if it returns @code{nil}, there is no
5149 signature in the buffer. If it is a string, it will be used as a
5150 regexp. If it matches, the text in question is not a signature.
5153 @node Article Washing
5154 @subsection Article Washing
5156 @cindex article washing
5158 We call this ``article washing'' for a really good reason. Namely, the
5159 @kbd{A} key was taken, so we had to use the @kbd{W} key instead.
5161 @dfn{Washing} is defined by us as ``changing something from something to
5162 something else'', but normally results in something looking better.
5168 @kindex W l (Summary)
5169 @findex gnus-summary-stop-page-breaking
5170 Remove page breaks from the current article
5171 (@code{gnus-summary-stop-page-breaking}).
5174 @kindex W r (Summary)
5175 @findex gnus-summary-caesar-message
5176 Do a Caesar rotate (rot13) on the article buffer
5177 (@code{gnus-summary-caesar-message}).
5180 @kindex W t (Summary)
5181 @findex gnus-summary-toggle-header
5182 Toggle whether to display all headers in the article buffer
5183 (@code{gnus-summary-toggle-header}).
5186 @kindex W v (Summary)
5187 @findex gnus-summary-verbose-header
5188 Toggle whether to display all headers in the article buffer permanently
5189 (@code{gnus-summary-verbose-header}).
5192 @kindex W m (Summary)
5193 @findex gnus-summary-toggle-mime
5194 Toggle whether to run the article through @sc{mime} before displaying
5195 (@code{gnus-summary-toggle-mime}).
5198 @kindex W o (Summary)
5199 @findex gnus-article-treat-overstrike
5200 Treat overstrike (@code{gnus-article-treat-overstrike}).
5203 @kindex W w (Summary)
5204 @findex gnus-article-fill-cited-article
5205 Do word wrap (@code{gnus-article-fill-cited-article}).
5208 @kindex W c (Summary)
5209 @findex gnus-article-remove-cr
5210 Remove CR (@code{gnus-article-remove-cr}).
5213 @kindex W L (Summary)
5214 @findex gnus-article-remove-trailing-blank-lines
5215 Remove all blank lines at the end of the article
5216 (@code{gnus-article-remove-trailing-blank-lines}).
5219 @kindex W q (Summary)
5220 @findex gnus-article-de-quoted-unreadable
5221 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
5224 @kindex W f (Summary)
5226 @findex gnus-article-display-x-face
5227 @findex gnus-article-x-face-command
5228 @vindex gnus-article-x-face-command
5229 @vindex gnus-article-x-face-too-ugly
5230 Look for and display any X-Face headers
5231 (@code{gnus-article-display-x-face}). The command executed by this
5232 function is given by the @code{gnus-article-x-face-command} variable. If
5233 this variable is a string, this string will be executed in a sub-shell.
5234 If it is a function, this function will be called with the face as the
5235 argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
5236 matches the @code{From} header, the face will not be shown.
5239 @kindex W b (Summary)
5240 @findex gnus-article-add-buttons
5241 Add clickable buttons to the article (@code{gnus-article-add-buttons}).
5244 @kindex W B (Summary)
5245 @findex gnus-article-add-buttons-to-head
5246 Add clickable buttons to the article headers
5247 (@code{gnus-article-add-buttons-to-head}).
5252 @node Article Buttons
5253 @subsection Article Buttons
5256 People often include references to other stuff in articles, and it would
5257 be nice if Gnus could just fetch whatever it is that people talk about
5258 with the minimum of fuzz.
5260 Gnus adds @dfn{buttons} to certain standard references by default:
5261 Well-formed URLs, mail addresses and Message-IDs. This is controlled by
5262 two variables, one that handles article bodies and one that handles
5267 @item gnus-button-alist
5268 @vindex gnus-button-alist
5269 This is an alist where each entry has this form:
5272 (REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
5278 All text that match this regular expression will be considered an
5279 external reference. Here's a typical regexp that match embedded URLs:
5280 @samp{<URL:\\([^\n\r>]*\\)>}.
5283 Gnus has to know which parts of the match is to be highlighted. This is
5284 a number that says what sub-expression of the regexp that is to be
5285 highlighted. If you want it all highlighted, you use @code{0} here.
5288 This form will be @code{eval}ed, and if the result is non-@code{nil},
5289 this is considered a match. This is useful if you want extra sifting to
5290 avoid false matches.
5293 This function will be called when you click on this button.
5296 As with @var{button-par}, this is a sub-expression number, but this one
5297 says which part of the match is to be sent as data to @var{function}.
5301 So the full entry for buttonizing URLs is then
5304 ("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
5307 @item gnus-header-button-alist
5308 @vindex gnus-header-button-alist
5309 This is just like the other alist, except that it is applied to the
5310 article head only, and that each entry has an additional element that is
5311 used to say what headers to apply the buttonize coding to:
5314 (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
5317 @var{header} is a regular expression.
5319 @item gnus-button-url-regexp
5320 @vindex gnus-button-url-regexp
5321 A regular expression that matches embedded URLs. It is used in the
5322 default values of the variables above.
5324 @item gnus-article-button-face
5325 @vindex gnus-article-button-face
5326 Face used on bottons.
5328 @item gnus-article-mouse-face
5329 @vindex gnus-article-mouse-face
5330 Face is used when the mouse cursor is over a button.
5336 @subsection Article Date
5338 The date is most likely generated in some obscure timezone you've never
5339 heard of, so it's quite nice to be able to find out what the time was
5340 when the article was sent.
5345 @kindex W T u (Summary)
5346 @findex gnus-article-date-ut
5347 Display the date in UT (aka. GMT, aka ZULU)
5348 (@code{gnus-article-date-ut}).
5351 @kindex W T l (Summary)
5352 @findex gnus-article-date-local
5353 Display the date in the local timezone (@code{gnus-article-date-local}).
5356 @kindex W T e (Summary)
5357 @findex gnus-article-date-lapsed
5358 Say how much time has (e)lapsed between the article was posted and now
5359 (@code{gnus-article-date-lapsed}).
5362 @kindex W T o (Summary)
5363 @findex gnus-article-date-original
5364 Display the original date (@code{gnus-article-date-original}). This can
5365 be useful if you normally use some other conversion function and is
5366 worried that it might be doing something totally wrong. Say, claiming
5367 that the article was posted in 1854. Although something like that is
5368 @emph{totally} impossible. Don't you trust me? *titter*
5373 @node Summary Sorting
5374 @section Summary Sorting
5375 @cindex summary sorting
5377 You can have the summary buffer sorted in various ways, even though I
5378 can't really see why you'd want that.
5383 @kindex C-c C-s C-n (Summary)
5384 @findex gnus-summary-sort-by-number
5385 Sort by article number (@code{gnus-summary-sort-by-number}).
5388 @kindex C-c C-s C-a (Summary)
5389 @findex gnus-summary-sort-by-author
5390 Sort by author (@code{gnus-summary-sort-by-author}).
5393 @kindex C-c C-s C-s (Summary)
5394 @findex gnus-summary-sort-by-subject
5395 Sort by subject (@code{gnus-summary-sort-by-subject}).
5398 @kindex C-c C-s C-d (Summary)
5399 @findex gnus-summary-sort-by-date
5400 Sort by date (@code{gnus-summary-sort-by-date}).
5403 @kindex C-c C-s C-i (Summary)
5404 @findex gnus-summary-sort-by-score
5405 Sort by score (@code{gnus-summary-sort-by-score}).
5408 These functions will work both when you use threading and when you don't
5409 use threading. In the latter case, all summary lines will be sorted,
5410 line by line. In the former case, sorting will be done on a
5411 root-by-root basis, which might not be what you were looking for. To
5412 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
5416 @node Finding the Parent
5417 @section Finding the Parent
5418 @cindex parent articles
5419 @cindex referring articles
5421 @findex gnus-summary-refer-parent-article
5423 If you'd like to read the parent of the current article, and it is not
5424 displayed in the summary buffer, you might still be able to. That is,
5425 if the current group is fetched by @sc{nntp}, the parent hasn't expired
5426 and the @code{References} in the current article are not mangled, you
5427 can just press @kbd{^} or @kbd{A r}
5428 (@code{gnus-summary-refer-parent-article}). If everything goes well,
5429 you'll get the parent. If the parent is already displayed in the
5430 summary buffer, point will just move to this article.
5432 @findex gnus-summary-refer-references
5433 @kindex A R (Summary)
5434 You can have Gnus fetch all articles mentioned in the @code{References}
5435 header of the article by pushing @kbd{A R}
5436 (@code{gnus-summary-refer-references}).
5438 @findex gnus-summary-refer-article
5439 @kindex M-^ (Summary)
5440 You can also ask the @sc{nntp} server for an arbitrary article, no
5441 matter what group it belongs to. @kbd{M-^}
5442 (@code{gnus-summary-refer-article}) will ask you for a
5443 @code{Message-ID}, which is one of those long thingies that look
5444 something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
5445 it all exactly right. No fuzzy searches, I'm afraid.
5447 @vindex gnus-refer-article-method
5448 If the group you are reading is located on a backend that does not
5449 support fetching by @code{Message-ID} very well (like @code{nnspool}),
5450 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
5451 would, perhaps, be best if the @sc{nntp} server you consult is the same
5452 as the one that keeps the spool you are reading from updated, but that's
5453 not really necessary.
5455 Most of the mail backends support fetching by @code{Message-ID}, but do
5456 not do a particularly excellent job of it. That is, @code{nnmbox} and
5457 @code{nnbabyl} are able to locate articles from any groups, while
5458 @code{nnml} and @code{nnfolder} are only able to locate articles that
5459 have been posted to the current group. (Anything else would be too time
5460 consuming.) @code{nnmh} does not support this at all.
5463 @node Alternative Approaches
5464 @section Alternative Approaches
5466 Different people like to read news using different methods. This being
5467 Gnus, we offer a small selection of minor modes for the summary buffers.
5470 * Pick and Read:: First mark articles and then read them.
5471 * Binary Groups:: Auto-decode all articles.
5476 @subsection Pick and Read
5477 @cindex pick and read
5479 Some newsreaders (like @code{nn} and, uhm, @code{nn}) use a two-phased
5480 reading interface. The user first marks the articles she wants to read
5481 from a summary buffer. Then she starts reading the articles with just
5482 an article buffer displayed.
5484 @findex gnus-pick-mode
5485 @kindex M-x gnus-pick-mode
5486 Gnus provides a summary buffer minor mode that allows
5487 this---@code{gnus-pick-mode}. This basically means that a few process
5488 mark commands become one-keystroke commands to allow easy marking, and
5489 it makes one additional command for switching to the summary buffer
5492 Here are the available keystrokes when using pick mode:
5496 @kindex SPACE (Pick)
5497 @findex gnus-summary-mark-as-processable
5498 Pick the article (@code{gnus-summary-mark-as-processable}).
5502 @findex gnus-summary-unmark-as-processable
5503 Unpick the article (@code{gnus-summary-unmark-as-processable}).
5507 @findex gnus-summary-unmark-all-processable
5508 Unpick all articles (@code{gnus-summary-unmark-all-processable}).
5512 @findex gnus-uu-mark-thread
5513 Pick the thread (@code{gnus-uu-mark-thread}).
5517 @findex gnus-uu-unmark-thread
5518 Unpick the thread (@code{gnus-uu-unmark-thread}).
5522 @findex gnus-uu-mark-region
5523 Pick the region (@code{gnus-uu-mark-region}).
5527 @findex gnus-uu-unmark-region
5528 Unpick the region (@code{gnus-uu-unmark-region}).
5532 @findex gnus-uu-unmark-regexp
5533 Pick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
5537 @findex gnus-uu-unmark-regexp
5538 Unpick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
5542 @findex gnus-uu-mark-buffer
5543 Pick the buffer (@code{gnus-uu-mark-buffer}).
5547 @findex gnus-uu-unmark-buffer
5548 Unpick the buffer (@code{gnus-uu-unmark-buffer}).
5552 @findex gnus-pick-start-reading
5553 @vindex gnus-pick-display-summary
5554 Start reading the picked articles (@code{gnus-pick-start-reading}). If
5555 given a prefix, mark all unpicked articles as read first. If
5556 @code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer
5557 will still be visible when you are reading.
5561 If this sounds like a good idea to you, you could say:
5564 (add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)
5567 @vindex gnus-pick-mode-hook
5568 @code{gnus-pick-mode-hook} is run in pick minor mode buffers.
5572 @subsection Binary Groups
5573 @cindex binary groups
5575 @findex gnus-binary-mode
5576 @kindex M-x gnus-binary-mode
5577 If you spend much time in binary groups, you may grow tired of hitting
5578 @kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode}
5579 is a minor mode for summary buffers that makes all ordinary Gnus article
5580 selection functions uudecode series of articles and display the result
5581 instead of just displaying the articles the normal way.
5584 @findex gnus-binary-show-article
5585 In fact, the only way to see the actual articles if you have turned this
5586 mode on is the @kbd{g} command (@code{gnus-binary-show-article}).
5588 @vindex gnus-binary-mode-hook
5589 @code{gnus-binary-mode-hook} is called in binary minor mode buffers.
5593 @section Tree Display
5596 @vindex gnus-use-trees
5597 If you don't like the normal Gnus summary display, you might try setting
5598 @code{gnus-use-trees} to @code{t}. This will create (by default) an
5599 additional @dfn{tree buffer}. You can execute all summary mode commands
5602 There are a few variables to customize the tree display, of course:
5605 @item gnus-tree-mode-hook
5606 @vindex gnus-tree-mode-hook
5607 A hook called in all tree mode buffers.
5609 @item gnus-tree-mode-line-format
5610 @vindex gnus-tree-mode-line-format
5611 A format string for the mode bar in the tree mode buffers. The default
5612 is @samp{Gnus: %%b [%A] %Z}. For a list of legal specs, @pxref{Summary
5615 @item gnus-selected-tree-face
5616 @vindex gnus-selected-tree-face
5617 Face used for highlighting the selected article in the tree buffer. The
5618 default is @code{modeline}.
5620 @item gnus-tree-line-format
5621 @vindex gnus-tree-line-format
5622 A format string for the tree nodes. The name is a bit of a misnomer,
5623 though---it doesn't define a line, but just the node. The default value
5624 is @samp{%(%[%3,3n%]%)}, which displays the first three characters of
5625 the name of the poster. It is vital that all nodes are of the same
5626 length, so you @emph{must} use @samp{%4,4n}-like specifiers.
5632 The name of the poster.
5634 The @code{From} header.
5636 The number of the article.
5638 The opening bracket.
5640 The closing bracket.
5645 @xref{Formatting Variables}.
5647 Variables related to the display are:
5650 @item gnus-tree-brackets
5651 @vindex gnus-tree-brackets
5652 This is used for differentiating between ``real'' articles and
5653 ``sparse'' articles. The format is @var{((real-open . real-close)
5654 (sparse-open . sparse-close) (dummy-open . dummy-close))}, and the
5655 default is @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}))}.
5657 @item gnus-tree-parent-child-edges
5658 @vindex gnus-tree-parent-child-edges
5659 This is a list that contains the characters used for connecting parent
5660 nodes to their children. The default is @code{(?- ?\\ ?|)}.
5664 @item gnus-tree-minimize-window
5665 @vindex gnus-tree-minimize-window
5666 If this variable is non-@code{nil}, Gnus will try to keep the tree
5667 buffer as small as possible to allow more room for the other Gnus
5668 windows. If this variable is a number, the tree buffer will never be
5669 higher than that number. The default is @code{t}.
5671 @item gnus-generate-tree-function
5672 @vindex gnus-generate-tree-function
5673 @findex gnus-generate-horizontal-tree
5674 @findex gnus-generate-vertical-tree
5675 The function that actually generates the thread tree. Two predefined
5676 functions are available: @code{gnus-generate-horizontal-tree} and
5677 @code{gnus-generate-vertical-tree} (which is the default).
5681 Here's and example from a horizontal tree buffer:
5684 @{***@}-(***)-[odd]-[Gun]
5694 Here's the same thread displayed in a vertical tree buffer:
5698 |--------------------------\-----\-----\
5699 (***) [Bjo] [Gun] [Gun]
5701 [odd] [Jan] [odd] (***) [Jor]
5703 [Gun] [Eri] [Eri] [odd]
5709 @node Mail Group Commands
5710 @section Mail Group Commands
5711 @cindex mail group commands
5713 Some commands only make sense in mail groups. If these commands are
5714 illegal in the current group, they will raise a hell and let you know.
5716 All these commands (except the expiry and edit commands) use the
5717 process/prefix convention (@pxref{Process/Prefix}).
5722 @kindex B e (Summary)
5723 @findex gnus-summary-expire-articles
5724 Expire all expirable articles in the group
5725 (@code{gnus-summary-expire-articles}).
5728 @kindex B M-C-e (Summary)
5729 @findex gnus-summary-expire-articles-now
5730 Expunge all the expirable articles in the group
5731 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
5732 articles that are eligible for expiry in the current group will
5733 disappear forever into that big @file{/dev/null} in the sky.
5736 @kindex B DEL (Summary)
5737 @findex gnus-summary-delete-articles
5738 Delete the mail article. This is ``delete'' as in ``delete it from your
5739 disk forever and ever, never to return again.'' Use with caution.
5740 (@code{gnus-summary-delete-article}).
5743 @kindex B m (Summary)
5745 @findex gnus-summary-move-article
5746 Move the article from one mail group to another
5747 (@code{gnus-summary-move-article}).
5750 @kindex B c (Summary)
5752 @findex gnus-summary-copy-article
5753 Copy the article from one group (mail group or not) to a mail group
5754 (@code{gnus-summary-copy-article}).
5757 @kindex B C (Summary)
5758 @cindex crosspost mail
5759 @findex gnus-summary-crosspost-article
5760 Crosspost the current article to some other group
5761 (@code{gnus-summary-crosspost-article}). This will create a new copy of
5762 the article in the other group, and the Xref headers of the article will
5763 be properly updated.
5766 @kindex B i (Summary)
5767 @findex gnus-summary-import-article
5768 Import an arbitrary file into the current mail newsgroup
5769 (@code{gnus-summary-import-article}). You will be prompted for a file
5770 name, a @code{From} header and a @code{Subject} header.
5772 Something similar can be done by just starting to compose a mail
5773 message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
5774 @kbd{C-c M-C-p} instead. This will put the message you have just created
5775 into the current mail group.
5778 @kindex B r (Summary)
5779 @findex gnus-summary-respool-article
5780 Respool the mail article (@code{gnus-summary-move-article}).
5784 @kindex B w (Summary)
5786 @findex gnus-summary-edit-article
5787 @kindex C-c C-c (Article)
5788 Edit the current article (@code{gnus-summary-edit-article}). To finish
5789 editing and make the changes permanent, type @kbd{C-c C-c}
5790 (@kbd{gnus-summary-edit-article-done}).
5793 @kindex B q (Summary)
5794 @findex gnus-summary-respool-query
5795 If you want to re-spool an article, you might be curious as to what group
5796 the article will end up in before you do the re-spooling. This command
5797 will tell you (@code{gnus-summary-respool-query}).
5800 @vindex gnus-move-split-methods
5801 @cindex moving articles
5802 If you move (or copy) articles regularly, you might wish to have Gnus
5803 suggest where to put the articles. @code{gnus-move-split-methods} is a
5804 variable that uses the same syntax as @code{gnus-split-methods}
5805 (@pxref{Saving Articles}). You may customize that variable to create
5806 suggestions you find reasonable.
5809 @node Various Summary Stuff
5810 @section Various Summary Stuff
5813 * Summary Group Information:: Information oriented commands.
5814 * Searching for Articles:: Multiple article commands.
5815 * Really Various Summary Commands:: Those pesky non-conformant commands.
5819 @vindex gnus-summary-mode-hook
5820 @item gnus-summary-mode-hook
5821 This hook is called when creating a summary mode buffer.
5823 @vindex gnus-summary-generate-hook
5824 @item gnus-summary-generate-hook
5825 This is called as the last thing before doing the threading and the
5826 generation of the summary buffer. It's quite convenient for customizing
5827 the threading variables based on what data the newsgroup has. This hook
5828 is called from the summary buffer after most summary buffer variables
5831 @vindex gnus-summary-prepare-hook
5832 @item gnus-summary-prepare-hook
5833 Is is called after the summary buffer has been generated. You might use
5834 it to, for instance, highlight lines or modify the look of the buffer in
5835 some other ungodly manner. I don't care.
5840 @node Summary Group Information
5841 @subsection Summary Group Information
5846 @kindex H f (Summary)
5847 @findex gnus-summary-fetch-faq
5848 @vindex gnus-group-faq-directory
5849 Try to fetch the FAQ (list of frequently asked questions) for the
5850 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
5851 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
5852 on a remote machine. This variable can also be a list of directories.
5853 In that case, giving a prefix to this command will allow you to choose
5854 between the various sites. @code{ange-ftp} probably will be used for
5858 @kindex H d (Summary)
5859 @findex gnus-summary-describe-group
5860 Give a brief description of the current group
5861 (@code{gnus-summary-describe-group}). If given a prefix, force
5862 rereading the description from the server.
5865 @kindex H h (Summary)
5866 @findex gnus-summary-describe-briefly
5867 Give a very brief description of the most important summary keystrokes
5868 (@code{gnus-summary-describe-briefly}).
5871 @kindex H i (Summary)
5872 @findex gnus-info-find-node
5873 Go to the Gnus info node (@code{gnus-info-find-node}).
5877 @node Searching for Articles
5878 @subsection Searching for Articles
5883 @kindex M-s (Summary)
5884 @findex gnus-summary-search-article-forward
5885 Search through all subsequent articles for a regexp
5886 (@code{gnus-summary-search-article-forward}).
5889 @kindex M-r (Summary)
5890 @findex gnus-summary-search-article-backward
5891 Search through all previous articles for a regexp
5892 (@code{gnus-summary-search-article-backward}).
5896 @findex gnus-summary-execute-command
5897 This command will prompt you for a header field, a regular expression to
5898 match on this field, and a command to be executed if the match is made
5899 (@code{gnus-summary-execute-command}).
5902 @kindex M-& (Summary)
5903 @findex gnus-summary-universal-argument
5904 Perform any operation on all articles that have been marked with
5905 the process mark (@code{gnus-summary-universal-argument}).
5909 @node Really Various Summary Commands
5910 @subsection Really Various Summary Commands
5915 @kindex A D (Summary)
5916 @findex gnus-summary-enter-digest-group
5917 If the current article is a collection of other articles (for instance,
5918 a digest), you might use this command to enter a group based on the that
5919 article (@code{gnus-summary-enter-digest-group}). Gnus will try to
5920 guess what article type is currently displayed unless you give a prefix
5921 to this command, which forces a ``digest'' interpretation. Basically,
5922 whenever you see a message that is a collection of other messages on
5923 some format, you @kbd{A D} and read these messages in a more convenient
5927 @kindex C-t (Summary)
5928 @findex gnus-summary-toggle-truncation
5929 Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
5933 @findex gnus-summary-expand-window
5934 Expand the summary buffer window (@code{gnus-summary-expand-window}).
5935 If given a prefix, force an @code{article} window configuration.
5939 @node Exiting the Summary Buffer
5940 @section Exiting the Summary Buffer
5941 @cindex summary exit
5942 @cindex exiting groups
5944 Exiting from the summary buffer will normally update all info on the
5945 group and return you to the group buffer.
5951 @kindex Z Z (Summary)
5953 @findex gnus-summary-exit
5954 @vindex gnus-summary-exit-hook
5955 @vindex gnus-summary-prepare-exit-hook
5956 Exit the current group and update all information on the group
5957 (@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
5958 called before doing much of the exiting, and calls
5959 @code{gnus-summary-expire-articles} by default.
5960 @code{gnus-summary-exit-hook} is called after finishing the exiting
5965 @kindex Z E (Summary)
5967 @findex gnus-summary-exit-no-update
5968 Exit the current group without updating any information on the group
5969 (@code{gnus-summary-exit-no-update}).
5973 @kindex Z c (Summary)
5975 @findex gnus-summary-catchup-and-exit
5976 Mark all unticked articles in the group as read and then exit
5977 (@code{gnus-summary-catchup-and-exit}).
5980 @kindex Z C (Summary)
5981 @findex gnus-summary-catchup-all-and-exit
5982 Mark all articles, even the ticked ones, as read and then exit
5983 (@code{gnus-summary-catchup-all-and-exit}).
5986 @kindex Z n (Summary)
5987 @findex gnus-summary-catchup-and-goto-next-group
5988 Mark all articles as read and go to the next group
5989 (@code{gnus-summary-catchup-and-goto-next-group}).
5992 @kindex Z R (Summary)
5993 @findex gnus-summary-reselect-current-group
5994 Exit this group, and then enter it again
5995 (@code{gnus-summary-reselect-current-group}). If given a prefix, select
5996 all articles, both read and unread.
6000 @kindex Z G (Summary)
6001 @kindex M-g (Summary)
6002 @findex gnus-summary-rescan-group
6003 Exit the group, check for new articles in the group, and select the
6004 group (@code{gnus-summary-rescan-group}). If given a prefix, select all
6005 articles, both read and unread.
6008 @kindex Z N (Summary)
6009 @findex gnus-summary-next-group
6010 Exit the group and go to the next group
6011 (@code{gnus-summary-next-group}).
6014 @kindex Z P (Summary)
6015 @findex gnus-summary-prev-group
6016 Exit the group and go to the previous group
6017 (@code{gnus-summary-prev-group}).
6020 @vindex gnus-exit-group-hook
6021 @code{gnus-exit-group-hook} is called when you exit the current
6024 @findex gnus-summary-wake-up-the-dead
6025 @findex gnus-dead-summary-mode
6026 @vindex gnus-kill-summary-on-exit
6027 If you're in the habit of exiting groups, and then changing your mind
6028 about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}.
6029 If you do that, Gnus won't kill the summary buffer when you exit it.
6030 (Quelle surprise!) Instead it will change the name of the buffer to
6031 something like @samp{*Dead Summary ... *} and install a minor mode
6032 called @code{gnus-dead-summary-mode}. Now, if you switch back to this
6033 buffer, you'll find that all keys are mapped to a function called
6034 @code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead
6035 summary buffer will result in a live, normal summary buffer.
6037 There will never be more than one dead summary buffer at any one time.
6039 @vindex gnus-use-cross-reference
6040 The data on the current group will be updated (which articles you have
6041 read, which articles you have replied to, etc.) when you exit the
6042 summary buffer. If the @code{gnus-use-cross-reference} variable is
6043 @code{t} (which is the default), articles that are cross-referenced to
6044 this group and are marked as read, will also be marked as read in the
6045 other subscribed groups they were cross-posted to. If this variable is
6046 neither @code{nil} nor @code{t}, the article will be marked as read in
6047 both subscribed and unsubscribed groups.
6051 Marking cross-posted articles as read ensures that you'll never have to
6052 read the same article more than once. Unless, of course, somebody has
6053 posted it to several groups separately. Posting the same article to
6054 several groups (not cross-posting) is called @dfn{spamming}, and you are
6055 by law required to send nasty-grams to anyone who perpetrates such a
6058 Remember: Cross-posting is kinda ok, but posting the same article
6059 separately to several groups is not.
6061 @cindex cross-posting
6064 One thing that may cause Gnus to not do the cross-posting thing
6065 correctly is if you use an @sc{nntp} server that supports @sc{xover}
6066 (which is very nice, because it speeds things up considerably) which
6067 does not include the @code{Xref} header in its @sc{nov} lines. This is
6068 Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
6069 even with @sc{xover} by registering the @code{Xref} lines of all
6070 articles you actually read, but if you kill the articles, or just mark
6071 them as read without reading them, Gnus will not get a chance to snoop
6072 the @code{Xref} lines out of these articles, and will be unable to use
6073 the cross reference mechanism.
6075 @cindex LIST overview.fmt
6076 @cindex overview.fmt
6077 To check whether your @sc{nntp} server includes the @code{Xref} header
6078 in its overview files, try @samp{telnet your.nntp.server nntp},
6079 @samp{MODE READER} on @code{inn} servers, and then say @samp{LIST
6080 overview.fmt}. This may not work, but if it does, and the last line you
6081 get does not read @samp{Xref:full}, then you should shout and whine at
6082 your news admin until she includes the @code{Xref} header in the
6085 @vindex gnus-nov-is-evil
6086 If you want Gnus to get the @code{Xref}s right all the time, you have to
6087 set @code{gnus-nov-is-evil} to @code{t}, which slows things down
6093 @node The Article Buffer
6094 @chapter The Article Buffer
6095 @cindex article buffer
6097 The articles are displayed in the article buffer, of which there is only
6098 one. All the summary buffers share the same article buffer unless you
6099 tell Gnus otherwise.
6102 * Hiding Headers:: Deciding what headers should be displayed.
6103 * Using MIME:: Pushing articles through @sc{mime} before reading them.
6104 * Customizing Articles:: Tailoring the look of the articles.
6105 * Article Keymap:: Keystrokes available in the article buffer
6106 * Misc Article:: Other stuff.
6110 @node Hiding Headers
6111 @section Hiding Headers
6112 @cindex hiding headers
6113 @cindex deleting headers
6115 The top section of each article is the @dfn{head}. (The rest is the
6116 @dfn{body}, but you may have guessed that already.)
6118 @vindex gnus-show-all-headers
6119 There is a lot of useful information in the head: the name of the person
6120 who wrote the article, the date it was written and the subject of the
6121 article. That's well and nice, but there's also lots of information
6122 most people do not want to see---what systems the article has passed
6123 through before reaching you, the @code{Message-ID}, the
6124 @code{References}, etc. ad nauseum---and you'll probably want to get rid
6125 of some of those lines. If you want to keep all those lines in the
6126 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
6128 Gnus provides you with two variables for sifting headers:
6132 @item gnus-visible-headers
6133 @vindex gnus-visible-headers
6134 If this variable is non-@code{nil}, it should be a regular expression
6135 that says what headers you wish to keep in the article buffer. All
6136 headers that do not match this variable will be hidden.
6138 For instance, if you only want to see the name of the person who wrote
6139 the article and the subject, you'd say:
6142 (setq gnus-visible-headers "^From:\\|^Subject:")
6145 This variable can also be a list of regexps to match headers that are to
6148 @item gnus-ignored-headers
6149 @vindex gnus-ignored-headers
6150 This variable is the reverse of @code{gnus-visible-headers}. If this
6151 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
6152 should be a regular expression that matches all lines that you want to
6153 hide. All lines that do not match this variable will remain visible.
6155 For instance, if you just want to get rid of the @code{References} line
6156 and the @code{Xref} line, you might say:
6159 (setq gnus-ignored-headers "^References:\\|^Xref:")
6162 This variable can also be a list of regexps to match headers that are to
6165 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
6166 variable will have no effect.
6170 @vindex gnus-sorted-header-list
6171 Gnus can also sort the headers for you. (It does this by default.) You
6172 can control the sorting by setting the @code{gnus-sorted-header-list}
6173 variable. It is a list of regular expressions that says in what order
6174 the headers are to be displayed.
6176 For instance, if you want the name of the author of the article first,
6177 and then the subject, you might say something like:
6180 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
6183 Any headers that are to remain visible, but are not listed in this
6184 variable, will be displayed in random order after all the headers that
6185 are listed in this variable.
6187 @findex gnus-article-hide-boring-headers
6188 @vindex gnus-article-display-hook
6189 @vindex gnus-boring-article-headers
6190 You can hide further boring headers by entering
6191 @code{gnus-article-hide-boring-headers} into
6192 @code{gnus-article-display-hook}. What this function does depends on
6193 the @code{gnus-boring-article-headers} variable. It's a list, but this
6194 list doesn't actually contain header names. Instead is lists various
6195 @dfn{boring conditions} that Gnus can check and remove from sight.
6197 These conditions are:
6200 Remove all empty headers.
6202 Remove the @code{Newsgroups} header if it only contains the current group
6205 Remove the @code{Followup-To} header if it is identical to the
6206 @code{Newsgroups} header.
6208 Remove the @code{Reply-To} header if it lists the same address as the
6211 Remove the @code{Date} header if the article is less than three days
6215 To include the four first elements, you could say something like;
6218 (setq gnus-boring-article-headers
6219 '(empty newsgroups followup-to reply-to))
6222 This is also the default value for this variable.
6226 @section Using @sc{mime}
6229 Mime is a standard for waving your hands through the air, aimlessly,
6230 while people stand around yawning.
6232 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
6233 while all newsreaders die of fear.
6235 @sc{mime} may specify what character set the article uses, the encoding
6236 of the characters, and it also makes it possible to embed pictures and
6237 other naughty stuff in innocent-looking articles.
6239 @vindex gnus-show-mime
6240 @vindex gnus-show-mime-method
6241 @vindex gnus-strict-mime
6242 @findex metamail-buffer
6243 Gnus handles @sc{mime} by shoving the articles through
6244 @code{gnus-show-mime-method}, which is @code{metamail-buffer} by
6245 default. Set @code{gnus-show-mime} to @code{t} if you want to use
6246 @sc{mime} all the time. However, if @code{gnus-strict-mime} is
6247 non-@code{nil}, the @sc{mime} method will only be used if there are
6248 @sc{mime} headers in the article.
6250 It might be best to just use the toggling functions from the summary
6251 buffer to avoid getting nasty surprises. (For instance, you enter the
6252 group @samp{alt.sing-a-long} and, before you know it, @sc{mime} has
6253 decoded the sound file in the article and some horrible sing-a-long song
6254 comes streaming out out your speakers, and you can't find the volume
6255 button, because there isn't one, and people are starting to look at you,
6256 and you try to stop the program, but you can't, and you can't find the
6257 program to control the volume, and everybody else in the room suddenly
6258 decides to look at you disdainfully, and you'll feel rather stupid.)
6260 Any similarity to real events and people is purely coincidental. Ahem.
6263 @node Customizing Articles
6264 @section Customizing Articles
6265 @cindex article customization
6267 @vindex gnus-article-display-hook
6268 The @code{gnus-article-display-hook} is called after the article has
6269 been inserted into the article buffer. It is meant to handle all
6270 treatment of the article before it is displayed.
6272 @findex gnus-article-maybe-highlight
6273 By default it contains @code{gnus-article-hide-headers},
6274 @code{gnus-article-treat-overstrike}, and
6275 @code{gnus-article-maybe-highlight}, but there are thousands, nay
6276 millions, of functions you can put in this hook. For an overview of
6277 functions @pxref{Article Highlighting}, @pxref{Article Hiding},
6278 @pxref{Article Washing}, @pxref{Article Buttons} and @pxref{Article
6281 You can, of course, write your own functions. The functions are called
6282 from the article buffer, and you can do anything you like, pretty much.
6283 There is no information that you have to keep in the buffer---you can
6284 change everything. However, you shouldn't delete any headers. Instead
6285 make them invisible if you want to make them go away.
6288 @node Article Keymap
6289 @section Article Keymap
6291 Most of the keystrokes in the summary buffer can also be used in the
6292 article buffer. They should behave as if you typed them in the summary
6293 buffer, which means that you don't actually have to have a summary
6294 buffer displayed while reading. You can do it all from the article
6297 A few additional keystrokes are available:
6302 @kindex SPACE (Article)
6303 @findex gnus-article-next-page
6304 Scroll forwards one page (@code{gnus-article-next-page}).
6307 @kindex DEL (Article)
6308 @findex gnus-article-prev-page
6309 Scroll backwards one page (@code{gnus-article-prev-page}).
6312 @kindex C-c ^ (Article)
6313 @findex gnus-article-refer-article
6314 If point is in the neighborhood of a @code{Message-ID} and you press
6315 @kbd{r}, Gnus will try to get that article from the server
6316 (@code{gnus-article-refer-article}).
6319 @kindex C-c C-m (Article)
6320 @findex gnus-article-mail
6321 Send a reply to the address near point (@code{gnus-article-mail}). If
6322 given a prefix, include the mail.
6326 @findex gnus-article-show-summary
6327 Reconfigure the buffers so that the summary buffer becomes visible
6328 (@code{gnus-article-show-summary}).
6332 @findex gnus-article-describe-briefly
6333 Give a very brief description of the available keystrokes
6334 (@code{gnus-article-describe-briefly}).
6337 @kindex TAB (Article)
6338 @findex gnus-article-next-button
6339 Go to the next button, if any (@code{gnus-article-next-button}. This
6340 only makes sense if you have buttonizing turned on.
6343 @kindex M-TAB (Article)
6344 @findex gnus-article-prev-button
6345 Go to the previous button, if any (@code{gnus-article-prev-button}.
6351 @section Misc Article
6355 @item gnus-single-article-buffer
6356 @vindex gnus-single-article-buffer
6357 If non-@code{nil}, use the same article buffer for all the groups.
6358 (This is the default.) If @code{nil}, each group will have its own
6361 @vindex gnus-article-prepare-hook
6362 @item gnus-article-prepare-hook
6363 This hook is called right after the article has been inserted into the
6364 article buffer. It is mainly intended for functions that do something
6365 depending on the contents; it should probably not be used for changing
6366 the contents of the article buffer.
6368 @vindex gnus-article-display-hook
6369 @item gnus-article-display-hook
6370 This hook is called as the last thing when displaying an article, and is
6371 intended for modifying the contents of the buffer, doing highlights,
6372 hiding headers, and the like.
6374 @item gnus-article-mode-hook
6375 @vindex gnus-article-mode-hook
6376 Hook called in article mode buffers.
6378 @vindex gnus-article-mode-line-format
6379 @item gnus-article-mode-line-format
6380 This variable is a format string along the same lines as
6381 @code{gnus-summary-mode-line-format}. It accepts exactly the same
6382 format specifications as that variable.
6383 @vindex gnus-break-pages
6385 @item gnus-break-pages
6386 Controls whether @dfn{page breaking} is to take place. If this variable
6387 is non-@code{nil}, the articles will be divided into pages whenever a
6388 page delimiter appears in the article. If this variable is @code{nil},
6389 paging will not be done.
6391 @item gnus-page-delimiter
6392 @vindex gnus-page-delimiter
6393 This is the delimiter mentioned above. By default, it is @samp{^L}
6398 @node Composing Messages
6399 @chapter Composing Messages
6404 @kindex C-c C-c (Post)
6405 All commands for posting and mailing will put you in a message buffer
6406 where you can edit the article all you like, before you send the article
6407 by pressing @kbd{C-c C-c}. If you are in a foreign news group, and you
6408 wish to post the article using the foreign server, you can give a prefix
6409 to @kbd{C-c C-c} to make Gnus try to post using the foreign server.
6412 * Mail:: Mailing and replying.
6413 * Post:: Posting and following up.
6414 * Posting Server:: What server should you post via?
6415 * Mail and Post:: Mailing and posting at the same time.
6416 * Archived Messages:: Where Gnus stores the messages you've sent.
6417 @c * Posting Styles:: An easier way to configure some key elements.
6418 @c * Drafts:: Postponing messages and rejected messages.
6419 @c * Rejected Articles:: What happens if the server doesn't like your article?
6422 Also see @pxref{Canceling and Superseding} for information on how to
6423 remove articles you shouldn't have posted.
6429 Variables for customizing outgoing mail:
6432 @item gnus-uu-digest-headers
6433 @vindex gnus-uu-digest-headers
6434 List of regexps to match headers included in digested messages. The
6435 headers will be included in the sequence they are matched.
6443 Variables for composing news articles:
6446 @item gnus-sent-message-ids-file
6447 @vindex gnus-sent-message-ids-file
6448 Gnus will keep a @code{Message-ID} history file of all the mails it has
6449 sent. If it discovers that it has already sent a mail, it will ask the
6450 user whether to re-send the mail. (This is primarily useful when
6451 dealing with @sc{soup} packets and the like where one is apt to sent the
6452 same packet multiple times.) This variable says what the name of this
6453 history file is. It is @file{~/News/Sent-Message-IDs} by default. Set
6454 this variable to @code{nil} if you don't want Gnus to keep a history
6457 @item gnus-sent-message-ids-length
6458 @vindex gnus-sent-message-ids-length
6459 This variable says how many @code{Message-ID}s to keep in the history
6460 file. It is 1000 by default.
6465 @node Posting Server
6466 @section Posting Server
6468 When you press those magical @kbd{C-c C-c} keys to ship off your latest
6469 (extremely intelligent, of course) article, where does it go?
6471 Thank you for asking. I hate you.
6473 @vindex gnus-post-method
6475 It can be quite complicated. Normally, Gnus will use the same native
6476 server. However. If your native server doesn't allow posting, just
6477 reading, you probably want to use some other server to post your
6478 (extremely intelligent and fabulously interesting) articles. You can
6479 then set the @code{gnus-post-method} to some other method:
6482 (setq gnus-post-method '(nnspool ""))
6485 Now, if you've done this, and then this server rejects your article, or
6486 this server is down, what do you do then? To override this variable you
6487 can use a non-zero prefix to the @kbd{C-c C-c} command to force using
6488 the ``current'' server for posting.
6490 If you give a zero prefix (i. e., @kbd{C-u 0 C-c C-c}) to that command,
6491 Gnus will prompt you for what method to use for posting.
6493 You can also set @code{gnus-post-method} to a list of select methods.
6494 If that's the case, Gnus will always prompt you for what method to use
6499 @section Mail and Post
6501 Here's a list of variables that are relevant to both mailing and
6505 @item gnus-mailing-list-groups
6506 @findex gnus-mailing-list-groups
6507 @cindex mailing lists
6509 If your news server offers groups that are really mailing lists that are
6510 gatewayed to the @sc{nntp} server, you can read those groups without
6511 problems, but you can't post/followup to them without some difficulty.
6512 One solution is to add a @code{to-address} to the group parameters
6513 (@pxref{Group Parameters}). An easier thing to do is set the
6514 @code{gnus-mailing-list-groups} to a regexp that match the groups that
6515 really are mailing lists. Then, at least, followups to the mailing
6516 lists will work most of the time. Posting to these groups (@kbd{a}) is
6517 still a pain, though.
6521 You may want to do spell-checking on messages that you send out. Or, if
6522 you don't want to spell-check by hand, you could add automatic
6523 spell-checking via the @code{ispell} package:
6525 @vindex news-inews-hook
6527 @findex ispell-message
6529 (add-hook 'message-send-hook 'ispell-message)
6533 @node Archived Messages
6534 @section Archived Messages
6535 @cindex archived messages
6536 @cindex sent messages
6538 Gnus provides a few different methods for storing the mail you send.
6539 The default method is to use the @dfn{archive virtual server} to store
6540 the mail. If you want to disable this completely, you should set
6541 @code{gnus-message-archive-group} to @code{nil}.
6543 @vindex gnus-message-archive-method
6544 @code{gnus-message-archive-method} says what virtual server Gnus is to
6545 use to store sent messages. It is @code{(nnfolder "archive"
6546 (nnfolder-directory "~/Mail/archive/"))} by default, but you can use any
6547 mail select method (@code{nnml}, @code{nnmbox}, etc.). However,
6548 @code{nnfolder} is a quite likeable select method for doing this sort of
6549 thing. If you don't like the default directory chosen, you could say
6553 (setq gnus-message-archive-method
6554 '(nnfolder "archive"
6555 (nnfolder-inhibit-expiry t)
6556 (nnfolder-active-file "~/News/sent-mail/active")
6557 (nnfolder-directory "~/News/sent-mail/")))
6560 @vindex gnus-message-archive-group
6562 Gnus will insert @code{Gcc} headers in all outgoing messages that point
6563 to one or more group(s) on that server. Which group to use is
6564 determined by the @code{gnus-message-archive-group} variable.
6566 This variable can be:
6570 Messages will be saved in that group.
6571 @item a list of strings
6572 Messages will be saved in all those groups.
6573 @item an alist of regexps, functions and forms
6574 When a key ``matches'', the result is used.
6579 Just saving to a single group called @samp{MisK}:
6581 (setq gnus-message-archive-group "MisK")
6584 Saving to two groups, @samp{MisK} and @samp{safe}:
6586 (setq gnus-message-archive-group '("MisK" "safe"))
6589 Save to different groups based on what group you are in:
6591 (setq gnus-message-archive-group
6592 '(("^alt" "sent-to-alt")
6593 ("mail" "sent-to-mail")
6594 (".*" "sent-to-misc")))
6599 (setq gnus-message-archive-group
6600 '((if (message-news-p)
6605 This is the default.
6607 How about storing all news messages in one file, but storing all mail
6608 messages in one file per month:
6611 (setq gnus-message-archive-group
6612 '((if (message-news-p)
6614 (concat "mail." (format-time-string
6615 "%Y-%m" (current-time))))))
6618 Now, when you send a message off, it will be stored in the appropriate
6619 group. (If you want to disable storing for just one particular message,
6620 you can just remove the @code{Gcc} header that has been inserted.) The
6621 archive group will appear in the group buffer the next time you start
6622 Gnus, or the next time you press @kbd{F} in the group buffer. You can
6623 enter it and read the articles in it just like you'd read any other
6624 group. If the group gets really big and annoying, you can simply rename
6625 if (using @kbd{G r} in the group buffer) to something nice --
6626 @samp{misc-mail-september-1995}, or whatever. New messages will
6627 continue to be stored in the old (now empty) group.
6629 That's the default method of archiving sent mail. Gnus also offers two
6630 other variables for the people who don't like the default method. In
6631 that case you should set @code{gnus-message-archive-group} to
6632 @code{nil}; this will disable archiving.
6635 @item gnus-author-copy
6636 @vindex gnus-author-copy
6638 This is a file name, and all outgoing articles will be saved in that
6639 file. Initialized from the @code{AUTHORCOPY} environment variable.
6641 If this variable begins with the character @samp{|}, outgoing articles
6642 will be piped to the named program. It is possible to save an article in
6643 an MH folder as follows:
6646 (setq gnus-author-copy
6647 "|/usr/local/lib/mh/rcvstore +Article")
6650 If the first character is not a pipe, articles are saved using the
6651 function specified by the @code{gnus-author-copy-saver} variable.
6653 @item gnus-author-copy-saver
6654 @vindex gnus-author-copy-saver
6655 @findex rmail-output
6656 A function called to save outgoing articles. This function will be
6657 called with the same of the file to store the article in. The default
6658 function is @code{rmail-output} which saves in the Unix mailbox format.
6660 @item gnus-outgoing-message-group
6661 @vindex gnus-outgoing-message-group
6662 All outgoing messages will be put in this group. If you want to store
6663 all your outgoing mail and articles in the group @samp{nnml:archive},
6664 you set this variable to that value. This variable can also be a list of
6667 If you want to have greater control over what group to put each
6668 message in, you can set this variable to a function that checks the
6669 current newsgroup name and then returns a suitable group name (or list
6674 @c @node Posting Styles
6675 @c @section Posting Styles
6676 @c @cindex posting styles
6679 @c All them variables, they make my head swim.
6681 @c So what if you want a different @code{Organization} and signature based
6682 @c on what groups you post to? And you post both from your home machine
6683 @c and your work machine, and you want different @code{From} lines, and so
6686 @c @vindex gnus-posting-styles
6687 @c One way to do stuff like that is to write clever hooks that change the
6688 @c variables you need to have changed. That's a bit boring, so somebody
6689 @c came up with the bright idea of letting the user specify these things in
6690 @c a handy alist. Here's an example of a @code{gnus-posting-styles}
6695 @c (signature . "Peace and happiness")
6696 @c (organization . "What me?"))
6698 @c (signature . "Death to everybody"))
6699 @c ("comp.emacs.i-love-it"
6700 @c (organization . "Emacs is it")))
6703 @c As you might surmise from this example, this alist consists of several
6704 @c @dfn{styles}. Each style will be applicable if the first element
6705 @c ``matches'', in some form or other. The entire alist will be iterated
6706 @c over, from the beginning towards the end, and each match will be
6707 @c applied, which means that attributes in later styles that match override
6708 @c the same attributes in earlier matching styles. So
6709 @c @samp{comp.programming.literate} will have the @samp{Death to everybody}
6710 @c signature and the @samp{What me?} @code{Organization} header.
6712 @c The first element in each style is called the @code{match}. If it's a
6713 @c string, then Gnus will try to regexp match it against the group name.
6714 @c If it's a function symbol, that function will be called with no
6715 @c arguments. If it's a variable symbol, then the variable will be
6716 @c referenced. If it's a list, then that list will be @code{eval}ed. In
6717 @c any case, if this returns a non-@code{nil} value, then the style is said
6720 @c Each style may contain a arbitrary amount of @dfn{attributes}. Each
6721 @c attribute consists of a @var{(name . value)} pair. The attribute name
6722 @c can be one of @code{signature}, @code{organization} or @code{from}. The
6723 @c attribute name can also be a string. In that case, this will be used as
6724 @c a header name, and the value will be inserted in the headers of the
6727 @c The attribute value can be a string (used verbatim), a function (the
6728 @c return value will be used), a variable (its value will be used) or a
6729 @c list (it will be @code{eval}ed and the return value will be used).
6731 @c So here's a new example:
6734 @c (setq gnus-posting-styles
6736 @c (signature . "~/.signature")
6737 @c (from . "user@@foo (user)")
6738 @c ("X-Home-Page" . (getenv "WWW_HOME"))
6739 @c (organization . "People's Front Against MWM"))
6741 @c (signature . my-funny-signature-randomizer))
6742 @c ((equal (system-name) "gnarly")
6743 @c (signature . my-quote-randomizer))
6744 @c (posting-from-work-p
6745 @c (signature . "~/.work-signature")
6746 @c (from . "user@@bar.foo (user)")
6747 @c (organization . "Important Work, Inc"))
6749 @c (signature . "~/.mail-signature"))))
6756 @c If you are writing a message (mail or news) and suddenly remember that
6757 @c you have a steak in the oven (or some pesto in the food processor, you
6758 @c craazy vegetarians), you'll probably wish there was a method to save the
6759 @c message you are writing so that you can continue editing it some other
6760 @c day, and send it when you feel its finished.
6762 @c Well, don't worry about it. Whenever you start composing a message of
6763 @c some sort using the Gnus mail and post commands, the buffer you get will
6764 @c automatically associate to an article in a special @dfn{draft} group.
6765 @c If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the
6766 @c article will be saved there. (Auto-save files also go to the draft
6770 @c @vindex gnus-draft-group-directory
6771 @c The draft group is a special group (which is implemented as an
6772 @c @code{nndraft} group, if you absolutely have to know) called
6773 @c @samp{nndraft:drafts}. The variable @code{gnus-draft-group-directory}
6774 @c controls both the name of the group and the location---the leaf element
6775 @c in the path will be used as the name of the group. What makes this
6776 @c group special is that you can't tick any articles in it or mark any
6777 @c articles as read---all articles in the group are permanently unread.
6779 @c If the group doesn't exist, it will be created and you'll be subscribed
6782 @c @findex gnus-dissociate-buffer-from-draft
6783 @c @kindex C-c M-d (Mail)
6784 @c @kindex C-c M-d (Post)
6785 @c @findex gnus-associate-buffer-with-draft
6786 @c @kindex C-c C-d (Mail)
6787 @c @kindex C-c C-d (Post)
6788 @c If you're writing some super-secret message that you later want to
6789 @c encode with PGP before sending, you may wish to turn the auto-saving
6790 @c (and association with the draft group) off. You never know who might be
6791 @c interested in reading all your extremely valuable and terribly horrible
6792 @c and interesting secrets. The @kbd{C-c M-d}
6793 @c (@code{gnus-dissociate-buffer-from-draft}) command does that for you.
6794 @c If you change your mind and want to turn the auto-saving back on again,
6795 @c @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that.
6797 @c @vindex gnus-use-draft
6798 @c To leave association with the draft group off by default, set
6799 @c @code{gnus-use-draft} to @code{nil}. It is @code{t} by default.
6801 @c @findex gnus-summary-send-draft
6802 @c @kindex S D c (Summary)
6803 @c When you want to continue editing the article, you simply enter the
6804 @c draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
6805 @c that. You will be placed in a buffer where you left off.
6807 @c Rejected articles will also be put in this draft group (@pxref{Rejected
6810 @c @findex gnus-summary-send-all-drafts
6811 @c If you have lots of rejected messages you want to post (or mail) without
6812 @c doing further editing, you can use the @kbd{S D a} command
6813 @c (@code{gnus-summary-send-all-drafts}). This command understands the
6814 @c process/prefix convention (@pxref{Process/Prefix}).
6817 @c @node Rejected Articles
6818 @c @section Rejected Articles
6819 @c @cindex rejected articles
6821 @c Sometimes a news server will reject an article. Perhaps the server
6822 @c doesn't like your face. Perhaps it just feels miserable. Perhaps
6823 @c @emph{there be demons}. Perhaps you have included too much cited text.
6824 @c Perhaps the disk is full. Perhaps the server is down.
6826 @c These situations are, of course, totally beyond the control of Gnus.
6827 @c (Gnus, of course, loves the way you look, always feels great, has angels
6828 @c fluttering around inside of it, doesn't care about how much cited text
6829 @c you include, never runs full and never goes down.) So Gnus saves these
6830 @c articles until some later time when the server feels better.
6832 @c The rejected articles will automatically be put in a special draft group
6833 @c (@pxref{Drafts}). When the server comes back up again, you'd then
6834 @c typically enter that group and send all the articles off.
6837 @node Select Methods
6838 @chapter Select Methods
6839 @cindex foreign groups
6840 @cindex select methods
6842 A @dfn{foreign group} is a group that is not read by the usual (or
6843 default) means. It could be, for instance, a group from a different
6844 @sc{nntp} server, it could be a virtual group, or it could be your own
6845 personal mail group.
6847 A foreign group (or any group, really) is specified by a @dfn{name} and
6848 a @dfn{select method}. To take the latter first, a select method is a
6849 list where the first element says what backend to use (eg. @code{nntp},
6850 @code{nnspool}, @code{nnml}) and the second element is the @dfn{server
6851 name}. There may be additional elements in the select method, where the
6852 value may have special meaning for the backend in question.
6854 One could say that a select method defines a @dfn{virtual server}---so
6855 we do just that (@pxref{The Server Buffer}).
6857 The @dfn{name} of the group is the name the backend will recognize the
6860 For instance, the group @samp{soc.motss} on the @sc{nntp} server
6861 @samp{some.where.edu} will have the name @samp{soc.motss} and select
6862 method @code{(nntp "some.where.edu")}. Gnus will call this group, in
6863 all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
6864 @code{nntp} backend just knows this group as @samp{soc.motss}.
6866 The different methods all have their peculiarities, of course.
6869 * The Server Buffer:: Making and editing virtual servers.
6870 * Getting News:: Reading USENET news with Gnus.
6871 * Getting Mail:: Reading your personal mail with Gnus.
6872 * Other Sources:: Reading directories, files, SOUP packets.
6873 * Combined Groups:: Combining groups into one group.
6877 @node The Server Buffer
6878 @section The Server Buffer
6880 Traditionally, a @dfn{server} is a machine or a piece of software that
6881 one connects to, and then requests information from. Gnus does not
6882 connect directly to any real servers, but does all transactions through
6883 one backend or other. But that's just putting one layer more between
6884 the actual media and Gnus, so we might just as well say that each
6885 backend represents a virtual server.
6887 For instance, the @code{nntp} backend may be used to connect to several
6888 different actual @sc{nntp} servers, or, perhaps, to many different ports
6889 on the same actual @sc{nntp} server. You tell Gnus which backend to
6890 use, and what parameters to set by specifying a @dfn{select method}.
6892 These select methods specifications can sometimes become quite
6893 complicated---say, for instance, that you want to read from the
6894 @sc{nntp} server @samp{news.funet.fi} on port number @code{13}, which
6895 hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
6896 Anyways, if you had to specify that for each group that used this
6897 server, that would be too much work, so Gnus offers a way of naming
6898 select methods, which is what you do in the server buffer.
6900 To enter the server buffer, user the @kbd{^}
6901 (@code{gnus-group-enter-server-mode}) command in the group buffer.
6904 * Server Buffer Format:: You can customize the look of this buffer.
6905 * Server Commands:: Commands to manipulate servers.
6906 * Example Methods:: Examples server specifications.
6907 * Creating a Virtual Server:: An example session.
6908 * Servers and Methods:: You can use server names as select methods.
6909 * Unavailable Servers:: Some servers you try to contact may be down.
6912 @vindex gnus-server-mode-hook
6913 @code{gnus-server-mode-hook} is run when creating the server buffer.
6916 @node Server Buffer Format
6917 @subsection Server Buffer Format
6918 @cindex server buffer format
6920 @vindex gnus-server-line-format
6921 You can change the look of the server buffer lines by changing the
6922 @code{gnus-server-line-format} variable. This is a @code{format}-like
6923 variable, with some simple extensions:
6928 How the news is fetched---the backend name.
6931 The name of this server.
6934 Where the news is to be fetched from---the address.
6937 The opened/closed/denied status of the server.
6940 @vindex gnus-server-mode-line-format
6941 The mode line can also be customized by using the
6942 @code{gnus-server-mode-line-format} variable. The following specs are
6953 Also @pxref{Formatting Variables}.
6956 @node Server Commands
6957 @subsection Server Commands
6958 @cindex server commands
6964 @findex gnus-server-add-server
6965 Add a new server (@code{gnus-server-add-server}).
6969 @findex gnus-server-edit-server
6970 Edit a server (@code{gnus-server-edit-server}).
6973 @kindex SPACE (Server)
6974 @findex gnus-server-read-server
6975 Browse the current server (@code{gnus-server-read-server}).
6979 @findex gnus-server-exit
6980 Return to the group buffer (@code{gnus-server-exit}).
6984 @findex gnus-server-kill-server
6985 Kill the current server (@code{gnus-server-kill-server}).
6989 @findex gnus-server-yank-server
6990 Yank the previously killed server (@code{gnus-server-yank-server}).
6994 @findex gnus-server-copy-server
6995 Copy the current server (@code{gnus-server-copy-server}).
6999 @findex gnus-server-list-servers
7000 List all servers (@code{gnus-server-list-servers}).
7005 @node Example Methods
7006 @subsection Example Methods
7008 Most select methods are pretty simple and self-explanatory:
7011 (nntp "news.funet.fi")
7014 Reading directly from the spool is even simpler:
7020 As you can see, the first element in a select method is the name of the
7021 backend, and the second is the @dfn{address}, or @dfn{name}, if you
7024 After these two elements, there may be a arbitrary number of
7025 @var{(variable form)} pairs.
7027 To go back to the first example---imagine that you want to read from
7028 port @code{15} from that machine. This is what the select method should
7032 (nntp "news.funet.fi" (nntp-port-number 15))
7035 You should read the documentation to each backend to find out what
7036 variables are relevant, but here's an @code{nnmh} example.
7038 @code{nnmh} is a mail backend that reads a spool-like structure. Say
7039 you have two structures that you wish to access: One is your private
7040 mail spool, and the other is a public one. Here's the possible spec for
7044 (nnmh "private" (nnmh-directory "~/private/mail/"))
7047 (This server is then called @samp{private}, but you may have guessed
7050 Here's the method for a public spool:
7054 (nnmh-directory "/usr/information/spool/")
7055 (nnmh-get-new-mail nil))
7059 @node Creating a Virtual Server
7060 @subsection Creating a Virtual Server
7062 If you're saving lots of articles in the cache by using persistent
7063 articles, you may want to create a virtual server to read the cache.
7065 First you need to add a new server. The @kbd{a} command does that. It
7066 would probably be best to use @code{nnspool} to read the cache. You
7067 could also use @code{nnml} or @code{nnmh}, though.
7069 Type @kbd{a nnspool RET cache RET}.
7071 You should now have a brand new @code{nnspool} virtual server called
7072 @samp{cache}. You now need to edit it to have the right definitions.
7073 Type @kbd{e} to edit the server. You'll be entered into a buffer that
7074 will contain the following:
7084 (nnspool-spool-directory "~/News/cache/")
7085 (nnspool-nov-directory "~/News/cache/")
7086 (nnspool-active-file "~/News/cache/active"))
7089 Type @kbd{C-c C-c} to return to the server buffer. If you now press
7090 @kbd{RET} over this virtual server, you should be entered into a browse
7091 buffer, and you should be able to enter any of the groups displayed.
7094 @node Servers and Methods
7095 @subsection Servers and Methods
7097 Wherever you would normally use a select method
7098 (eg. @code{gnus-secondary-select-method}, in the group select method,
7099 when browsing a foreign server) you can use a virtual server name
7100 instead. This could potentially save lots of typing. And it's nice all
7104 @node Unavailable Servers
7105 @subsection Unavailable Servers
7107 If a server seems to be unreachable, Gnus will mark that server as
7108 @code{denied}. That means that any subsequent attempt to make contact
7109 with that server will just be ignored. ``It can't be opened,'' Gnus
7110 will tell you, without making the least effort to see whether that is
7111 actually the case or not.
7113 That might seem quite naughty, but it does make sense most of the time.
7114 Let's say you have 10 groups subscribed to the server
7115 @samp{nepholococcygia.com}. This server is located somewhere quite far
7116 away from you, the machine is quite, so it takes 1 minute just to find
7117 out that it refuses connection from you today. If Gnus were to attempt
7118 to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
7119 that. Once it has gotten a single ``connection refused'', it will
7120 regard that server as ``down''.
7122 So, what happens if the machine was only feeling unwell temporarily?
7123 How do you test to see whether the machine has come up again?
7125 You jump to the server buffer (@pxref{The Server Buffer}) and poke it
7126 with the following commands:
7132 @findex gnus-server-open-server
7133 Try to establish connection to the server on the current line
7134 (@code{gnus-server-open-server}).
7138 @findex gnus-server-close-server
7139 Close the connection (if any) to the server
7140 (@code{gnus-server-close-server}).
7144 @findex gnus-server-deny-server
7145 Mark the current server as unreachable
7146 (@code{gnus-server-deny-server}).
7150 @findex gnus-server-remove-denials
7151 Remove all marks to whether Gnus was denied connection from all servers
7152 (@code{gnus-server-remove-denials}).
7158 @section Getting News
7159 @cindex reading news
7160 @cindex news backends
7162 A newsreader is normally used for reading news. Gnus currently provides
7163 only two methods of getting news -- it can read from an @sc{nntp}
7164 server, or it can read from a local spool.
7167 * NNTP:: Reading news from an @sc{nntp} server.
7168 * News Spool:: Reading news from the local spool.
7173 @subsection @sc{nntp}
7176 Subscribing to a foreign group from an @sc{nntp} server is rather easy.
7177 You just specify @code{nntp} as method and the address of the @sc{nntp}
7178 server as the, uhm, address.
7180 If the @sc{nntp} server is located at a non-standard port, setting the
7181 third element of the select method to this port number should allow you
7182 to connect to the right port. You'll have to edit the group info for
7183 that (@pxref{Foreign Groups}).
7185 The name of the foreign group can be the same as a native group. In
7186 fact, you can subscribe to the same group from as many different servers
7187 you feel like. There will be no name collisions.
7189 The following variables can be used to create a virtual @code{nntp}
7194 @item nntp-server-opened-hook
7195 @vindex nntp-server-opened-hook
7196 @cindex @sc{mode reader}
7198 @cindex authentification
7199 @cindex nntp authentification
7200 @findex nntp-send-authinfo
7201 @findex nntp-send-mode-reader
7202 @code{nntp-server-opened-hook} is run after a connection has been made.
7203 It can be used to send commands to the @sc{nntp} server after it has
7204 been contacted. By default is sends the command @code{MODE READER} to
7205 the server with the @code{nntp-send-mode-reader} function. Another
7206 popular function is @code{nntp-send-authinfo}, which will prompt you for
7207 an @sc{nntp} password and stuff.
7209 @item nntp-server-action-alist
7210 @vindex nntp-server-action-alist
7211 This is an list of regexps to match on server types and actions to be
7212 taken when matches are made. For instance, if you want Gnus to beep
7213 every time you connect to innd, you could say something like:
7216 (setq nntp-server-action-alist
7220 You probably don't want to do that, though.
7222 The default value is
7225 '(("nntpd 1\\.5\\.11t"
7226 (remove-hook 'nntp-server-opened-hook nntp-send-mode-reader)))
7229 This ensures that Gnus doesn't send the @code{MODE READER} command to
7230 nntpd 1.5.11t, since that command chokes that server, I've been told.
7232 @item nntp-maximum-request
7233 @vindex nntp-maximum-request
7234 If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
7235 will collect headers by sending a series of @code{head} commands. To
7236 speed things up, the backend sends lots of these commands without
7237 waiting for reply, and then reads all the replies. This is controlled
7238 by the @code{nntp-maximum-request} variable, and is 400 by default. If
7239 your network is buggy, you should set this to 1.
7241 @item nntp-connection-timeout
7242 @vindex nntp-connection-timeout
7243 If you have lots of foreign @code{nntp} groups that you connect to
7244 regularly, you're sure to have problems with @sc{nntp} servers not
7245 responding properly, or being too loaded to reply within reasonable
7246 time. This is can lead to awkward problems, which can be helped
7247 somewhat by setting @code{nntp-connection-timeout}. This is an integer
7248 that says how many seconds the @code{nntp} backend should wait for a
7249 connection before giving up. If it is @code{nil}, which is the default,
7250 no timeouts are done.
7252 @item nntp-command-timeout
7253 @vindex nntp-command-timeout
7254 @cindex PPP connections
7255 @cindex dynamic IP addresses
7256 If you're running Gnus on a machine that has a dynamically assigned
7257 address, Gnus may become confused. If the address of your machine
7258 changes after connecting to the @sc{nntp} server, Gnus will simply sit
7259 waiting forever for replies from the server. To help with this
7260 unfortunate problem, you can set this command to a number. Gnus will
7261 then, if it sits waiting longer than that number of seconds for a reply
7262 from the server, shut down the connection, start a new one, and resend
7263 the command. This should hopefully be transparent to the user. A
7264 likely number is 30 seconds.
7266 @item nntp-retry-on-break
7267 @vindex nntp-retry-on-break
7268 If this variable is non-@code{nil}, you can also @kbd{C-g} if Gnus
7269 hangs. This will have much the same effect as the command timeout
7272 @item nntp-server-hook
7273 @vindex nntp-server-hook
7274 This hook is run as the last step when connecting to an @sc{nntp}
7277 @findex nntp-open-rlogin
7278 @findex nntp-open-network-stream
7279 @item nntp-open-server-function
7280 @vindex nntp-open-server-function
7281 This function is used to connect to the remote system. Two pre-made
7282 functions are @code{nntp-open-network-stream}, which is the default, and
7283 simply connects to some port or other on the remote system. The other
7284 is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
7285 and then does a telnet to the @sc{nntp} server available there.
7287 @item nntp-rlogin-parameters
7288 @vindex nntp-rlogin-parameters
7289 If you use @code{nntp-open-rlogin} as the
7290 @code{nntp-open-server-function}, this list will be used as the
7291 parameter list given to @code{rsh}.
7293 @item nntp-end-of-line
7294 @vindex nntp-end-of-line
7295 String to use as end-of-line markers when talking to the @sc{nntp}
7296 server. This is @samp{\r\n} by default, but should be @samp{\n} when
7297 using @code{rlogin} to talk to the server.
7299 @item nntp-rlogin-user-name
7300 @vindex nntp-rlogin-user-name
7301 User name on the remote system when using the @code{rlogin} connect
7305 @vindex nntp-address
7306 The address of the remote system running the @sc{nntp} server.
7308 @item nntp-port-number
7309 @vindex nntp-port-number
7310 Port number to connect to when using the @code{nntp-open-network-stream}
7313 @item nntp-buggy-select
7314 @vindex nntp-buggy-select
7315 Set this to non-@code{nil} if your select routine is buggy.
7317 @item nntp-nov-is-evil
7318 @vindex nntp-nov-is-evil
7319 If the @sc{nntp} server does not support @sc{nov}, you could set this
7320 variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
7321 can be used automatically.
7323 @item nntp-xover-commands
7324 @vindex nntp-xover-commands
7327 List of strings that are used as commands to fetch @sc{nov} lines from a
7328 server. The default value of this variable is @code{("XOVER"
7332 @vindex nntp-nov-gap
7333 @code{nntp} normally sends just one big request for @sc{nov} lines to
7334 the server. The server responds with one huge list of lines. However,
7335 if you have read articles 2-5000 in the group, and only want to read
7336 article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
7337 lines that you do not want, and will not use. This variable says how
7338 big a gap between two consecutive articles is allowed to be before the
7339 @code{XOVER} request is split into several request. Note that if your
7340 network is fast, setting this variable to a really small number means
7341 that fetching will probably be slower. If this variable is @code{nil},
7342 @code{nntp} will never split requests.
7344 @item nntp-prepare-server-hook
7345 @vindex nntp-prepare-server-hook
7346 A hook run before attempting to connect to an @sc{nntp} server.
7348 @item nntp-async-number
7349 @vindex nntp-async-number
7350 How many articles should be pre-fetched when in asynchronous mode. If
7351 this variable is @code{t}, @code{nntp} will pre-fetch all the articles
7352 that it can without bound. If it is @code{nil}, no pre-fetching will be
7355 @item nntp-warn-about-losing-connection
7356 @vindex nntp-warn-about-losing-connection
7357 If this variable is non-@code{nil}, some noise will be made when a
7358 server closes connection.
7364 @subsection News Spool
7368 Subscribing to a foreign group from the local spool is extremely easy,
7369 and might be useful, for instance, to speed up reading groups like
7370 @samp{alt.binaries.pictures.furniture}.
7372 Anyways, you just specify @code{nnspool} as the method and @samp{} (or
7373 anything else) as the address.
7375 If you have access to a local spool, you should probably use that as the
7376 native select method (@pxref{Finding the News}). It is normally faster
7377 than using an @code{nntp} select method, but might not be. It depends.
7378 You just have to try to find out what's best at your site.
7382 @item nnspool-inews-program
7383 @vindex nnspool-inews-program
7384 Program used to post an article.
7386 @item nnspool-inews-switches
7387 @vindex nnspool-inews-switches
7388 Parameters given to the inews program when posting an article.
7390 @item nnspool-spool-directory
7391 @vindex nnspool-spool-directory
7392 Where @code{nnspool} looks for the articles. This is normally
7393 @file{/usr/spool/news/}.
7395 @item nnspool-nov-directory
7396 @vindex nnspool-nov-directory
7397 Where @code{nnspool} will look for @sc{nov} files. This is normally
7398 @file{/usr/spool/news/over.view/}.
7400 @item nnspool-lib-dir
7401 @vindex nnspool-lib-dir
7402 Where the news lib dir is (@file{/usr/lib/news/} by default).
7404 @item nnspool-active-file
7405 @vindex nnspool-active-file
7406 The path of the active file.
7408 @item nnspool-newsgroups-file
7409 @vindex nnspool-newsgroups-file
7410 The path of the group descriptions file.
7412 @item nnspool-history-file
7413 @vindex nnspool-history-file
7414 The path of the news history file.
7416 @item nnspool-active-times-file
7417 @vindex nnspool-active-times-file
7418 The path of the active date file.
7420 @item nnspool-nov-is-evil
7421 @vindex nnspool-nov-is-evil
7422 If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
7425 @item nnspool-sift-nov-with-sed
7426 @vindex nnspool-sift-nov-with-sed
7428 If non-@code{nil}, which is the default, use @code{sed} to get the
7429 relevant portion from the overview file. If nil, @code{nnspool} will
7430 load the entire file into a buffer and process it there.
7436 @section Getting Mail
7437 @cindex reading mail
7440 Reading mail with a newsreader---isn't that just plain WeIrD? But of
7444 * Getting Started Reading Mail:: A simple cookbook example.
7445 * Splitting Mail:: How to create mail groups.
7446 * Mail Backend Variables:: Variables for customizing mail handling.
7447 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
7448 * Mail and Procmail:: Reading mail groups that procmail create.
7449 * Incorporating Old Mail:: What about the old mail you have?
7450 * Expiring Mail:: Getting rid of unwanted mail.
7451 * Duplicates:: Dealing with duplicated mail.
7452 * Not Reading Mail:: Using mail backends for reading other files.
7453 * Choosing a Mail Backend:: Gnus can read a variety of mail formats.
7457 @node Getting Started Reading Mail
7458 @subsection Getting Started Reading Mail
7460 It's quite easy to use Gnus to read your new mail. You just plonk the
7461 mail backend of your choice into @code{gnus-secondary-select-methods},
7462 and things will happen automatically.
7464 For instance, if you want to use @code{nnml} (which is a one file per
7465 mail backend), you could put the following in your @file{.gnus} file:
7468 (setq gnus-secondary-select-methods
7469 '((nnml "private")))
7472 Now, the next time you start Gnus, this backend will be queried for new
7473 articles, and it will move all the messages in your spool file to its
7474 directory, which is @code{~/Mail/} by default. The new group that will
7475 be created (@samp{mail.misc}) will be subscribed, and you can read it
7476 like any other group.
7478 You will probably want to split the mail into several groups, though:
7481 (setq nnmail-split-methods
7482 '(("junk" "^From:.*Lars Ingebrigtsen")
7483 ("crazy" "^Subject:.*die\\|^Organization:.*flabby")
7487 This will result in three new mail groups being created:
7488 @samp{nnml:junk}, @samp{nnml:crazy}, and @samp{nnml:other}. All the
7489 mail that doesn't fit into the first two groups will be placed in the
7492 This should be sufficient for reading mail with Gnus. You might want to
7493 give the other sections in this part of the manual a perusal, though,
7494 especially @pxref{Choosing a Mail Backend} and @pxref{Expiring Mail}.
7497 @node Splitting Mail
7498 @subsection Splitting Mail
7499 @cindex splitting mail
7500 @cindex mail splitting
7502 @vindex nnmail-split-methods
7503 The @code{nnmail-split-methods} variable says how the incoming mail is
7504 to be split into groups.
7507 (setq nnmail-split-methods
7508 '(("mail.junk" "^From:.*Lars Ingebrigtsen")
7509 ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
7513 This variable is a list of lists, where the first element of each of
7514 these lists is the name of the mail group (they do not have to be called
7515 something beginning with @samp{mail}, by the way), and the second
7516 element is a regular expression used on the header of each mail to
7517 determine if it belongs in this mail group.
7519 The second element can also be a function. In that case, it will be
7520 called narrowed to the headers with the first element of the rule as the
7521 argument. It should return a non-@code{nil} value if it thinks that the
7522 mail belongs in that group.
7524 The last of these groups should always be a general one, and the regular
7525 expression should @emph{always} be @samp{} so that it matches any
7526 mails that haven't been matched by any of the other regexps.
7528 If you like to tinker with this yourself, you can set this variable to a
7529 function of your choice. This function will be called without any
7530 arguments in a buffer narrowed to the headers of an incoming mail
7531 message. The function should return a list of groups names that it
7532 thinks should carry this mail message.
7534 Note that the mail backends are free to maul the poor, innocent
7535 incoming headers all they want to. They all add @code{Lines} headers;
7536 some add @code{X-Gnus-Group} headers; most rename the Unix mbox
7537 @code{From<SPACE>} line to something else.
7539 @vindex nnmail-crosspost
7540 The mail backends all support cross-posting. If several regexps match,
7541 the mail will be ``cross-posted'' to all those groups.
7542 @code{nnmail-crosspost} says whether to use this mechanism or not. Note
7543 that no articles are crossposted to the general (@samp{}) group.
7545 @vindex nnmail-crosspost-link-function
7548 @code{nnmh} and @code{nnml} makes crossposts by creating hard links to
7549 the crossposted articles. However, not all files systems support hard
7550 links. If that's the case for you, set
7551 @code{nnmail-crosspost-link-function} to @code{copy-file}. (This
7552 variable is @code{add-name-to-file} by default.)
7554 Gnus gives you all the opportunity you could possibly want for shooting
7555 yourself in the foot. Let's say you create a group that will contain
7556 all the mail you get from your boss. And then you accidentally
7557 unsubscribe from the group. Gnus will still put all the mail from your
7558 boss in the unsubscribed group, and so, when your boss mails you ``Have
7559 that report ready by Monday or you're fired!'', you'll never see it and,
7560 come Tuesday, you'll still believe that you're gainfully employed while
7561 you really should be out collecting empty bottles to save up for next
7565 @node Mail Backend Variables
7566 @subsection Mail Backend Variables
7568 These variables are (for the most part) pertinent to all the various
7572 @vindex nnmail-read-incoming-hook
7573 @item nnmail-read-incoming-hook
7574 The mail backends all call this hook after reading new mail. You can
7575 use this hook to notify any mail watch programs, if you want to.
7577 @vindex nnmail-spool-file
7578 @item nnmail-spool-file
7582 The backends will look for new mail in this file. If this variable is
7583 @code{nil}, the mail backends will never attempt to fetch mail by
7584 themselves. If you are using a POP mail server and your name is
7585 @samp{larsi}, you should set this variable to @samp{po:larsi}. If
7586 your name is not @samp{larsi}, you should probably modify that
7587 slightly, but you may have guessed that already, you smart & handsome
7588 devil! You can also set this variable to @code{pop}, and Gnus will try
7589 to figure out the POP mail string by itself. In any case, Gnus will
7590 call @code{movemail} which will contact the POP server named in the
7591 @code{MAILHOST} environment variable.
7593 When you use a mail backend, Gnus will slurp all your mail from your
7594 inbox and plonk it down in your home directory. Gnus doesn't move any
7595 mail if you're not using a mail backend---you have to do a lot of magic
7596 invocations first. At the time when you have finished drawing the
7597 pentagram, lightened the candles, and sacrificed the goat, you really
7598 shouldn't be too surprised when Gnus moves your mail.
7600 @vindex nnmail-use-procmail
7601 @vindex nnmail-procmail-suffix
7602 @item nnmail-use-procmail
7603 If non-@code{nil}, the mail backends will look in
7604 @code{nnmail-procmail-directory} for incoming mail. All the files in
7605 that directory that have names ending in @code{nnmail-procmail-suffix}
7606 will be considered incoming mailboxes, and will be searched for new
7609 @vindex nnmail-crash-box
7610 @item nnmail-crash-box
7611 When the mail backends read a spool file, it is first moved to this
7612 file, which is @file{~/.gnus-crash-box} by default. If this file
7613 already exists, it will always be read (and incorporated) before any
7616 @vindex nnmail-prepare-incoming-hook
7617 @item nnmail-prepare-incoming-hook
7618 This is run in a buffer that holds all the new incoming mail, and can be
7619 used for, well, anything, really.
7621 @vindex nnmail-pre-get-new-mail-hook
7622 @vindex nnmail-post-get-new-mail-hook
7623 @item nnmail-pre-get-new-mail-hook
7624 @itemx nnmail-post-get-new-mail-hook
7625 These are two useful hooks executed when treating new incoming
7626 mail---@code{nnmail-pre-get-new-mail-hook} (is called just before
7627 starting to handle the new mail) and
7628 @code{nnmail-post-get-new-mail-hook} (is called when the mail handling
7629 is done). Here's and example of using these two hooks to change the
7630 default file modes the new mail files get:
7633 (add-hook 'gnus-pre-get-new-mail-hook
7634 (lambda () (set-default-file-modes 511)))
7636 (add-hook 'gnus-post-get-new-mail-hook
7637 (lambda () (set-default-file-modes 551)))
7640 @item nnmail-tmp-directory
7641 @vindex nnmail-tmp-directory
7642 This variable says where to move the incoming mail to while processing
7643 it. This is usually done in the same directory that the mail backend
7644 inhabits (i.e., @file{~/Mail/}), but if this variable is non-@code{nil},
7645 it will be used instead.
7647 @item nnmail-movemail-program
7648 @vindex nnmail-movemail-program
7649 This program is executed to move mail from the user's inbox to her home
7650 directory. The default is @samp{movemail}.
7652 @item nnmail-delete-incoming
7653 @vindex nnmail-delete-incoming
7654 @cindex incoming mail files
7655 @cindex deleting incoming files
7656 If non-@code{nil}, the mail backends will delete the temporary incoming
7657 file after splitting mail into the proper groups. This is @code{nil} by
7658 default for reasons of security.
7660 @item nnmail-use-long-file-names
7661 @vindex nnmail-use-long-file-names
7662 If non-@code{nil}, the mail backends will use long file and directory
7663 names. Groups like @samp{mail.misc} will end up in directories like
7664 @file{mail.misc/}. If it is @code{nil}, the same group will end up in
7667 @item nnmail-delete-file-function
7668 @vindex nnmail-delete-file-function
7670 Function called to delete files. It is @code{delete-file} by default.
7675 @node Fancy Mail Splitting
7676 @subsection Fancy Mail Splitting
7677 @cindex mail splitting
7678 @cindex fancy mail splitting
7680 @vindex nnmail-split-fancy
7681 @findex nnmail-split-fancy
7682 If the rather simple, standard method for specifying how to split mail
7683 doesn't allow you to do what you want, you can set
7684 @code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
7685 play with the @code{nnmail-split-fancy} variable.
7687 Let's look at an example value of this variable first:
7690 ;; Messages from the mailer daemon are not crossposted to any of
7691 ;; the ordinary groups. Warnings are put in a separate group
7692 ;; from real errors.
7693 (| ("from" mail (| ("subject" "warn.*" "mail.warning")
7695 ;; Non-error messages are crossposted to all relevant
7696 ;; groups, but we don't crosspost between the group for the
7697 ;; (ding) list and the group for other (ding) related mail.
7698 (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
7699 ("subject" "ding" "ding.misc"))
7700 ;; Other mailing lists...
7701 (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
7702 (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
7704 (any "larsi@@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
7705 ;; Unmatched mail goes to the catch all group.
7709 This variable has the format of a @dfn{split}. A split is a (possibly)
7710 recursive structure where each split may contain other splits. Here are
7711 the four possible split syntaxes:
7716 If the split is a string, that will be taken as a group name.
7718 @item (FIELD VALUE SPLIT)
7719 If the split is a list, and the first element is a string, then that
7720 means that if header FIELD (a regexp) contains VALUE (also a regexp),
7721 then store the message as specified by SPLIT.
7724 If the split is a list, and the first element is @code{|} (vertical
7725 bar), then process each SPLIT until one of them matches. A SPLIT is
7726 said to match if it will cause the mail message to be stored in one or
7730 If the split is a list, and the first element is @code{&}, then process
7731 all SPLITs in the list.
7734 In these splits, FIELD must match a complete field name. VALUE must
7735 match a complete word according to the fundamental mode syntax table.
7736 You can use @code{.*} in the regexps to match partial field names or
7739 @vindex nnmail-split-abbrev-alist
7740 FIELD and VALUE can also be lisp symbols, in that case they are expanded
7741 as specified by the variable @code{nnmail-split-abbrev-alist}. This is
7742 an alist of cons cells, where the car of the cells contains the key, and
7743 the cdr contains a string.
7745 @vindex nnmail-split-fancy-syntax-table
7746 @code{nnmail-split-fancy-syntax-table} is the syntax table in effect
7747 when all this splitting is performed.
7750 @node Mail and Procmail
7751 @subsection Mail and Procmail
7756 Many people use @code{procmail} (or some other mail filter program or
7757 external delivery agent---@code{slocal}, @code{elm}, etc) to split
7758 incoming mail into groups. If you do that, you should set
7759 @code{nnmail-spool-file} to @code{procmail} to ensure that the mail
7760 backends never ever try to fetch mail by themselves.
7762 This also means that you probably don't want to set
7763 @code{nnmail-split-methods} either, which has some, perhaps, unexpected
7766 When a mail backend is queried for what groups it carries, it replies
7767 with the contents of that variable, along with any groups it has figured
7768 out that it carries by other means. None of the backends (except
7769 @code{nnmh}) actually go out to the disk and check what groups actually
7770 exist. (It's not trivial to distinguish between what the user thinks is
7771 a basis for a newsgroup and what is just a plain old file or directory.)
7773 This means that you have to tell Gnus (and the backends) what groups
7776 Let's take the @code{nnmh} backend as an example.
7778 The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
7779 There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
7781 Go to the group buffer and type @kbd{G m}. When prompted, answer
7782 @samp{foo} for the name and @samp{nnmh} for the method. Repeat
7783 twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
7784 to include all your mail groups.
7786 That's it. You are now set to read your mail. An active file for this
7787 method will be created automatically.
7789 @vindex nnmail-procmail-suffix
7790 @vindex nnmail-procmail-directory
7791 If you use @code{nnfolder} or any other backend that store more than a
7792 single article in each file, you should never have procmail add mails to
7793 the file that Gnus sees. Instead, procmail should put all incoming mail
7794 in @code{nnmail-procmail-directory}. To arrive at the file name to put
7795 the incoming mail in, append @code{nnmail-procmail-suffix} to the group
7796 name. The mail backends will read the mail from these files.
7798 @vindex nnmail-resplit-incoming
7799 When Gnus reads a file called @file{mail.misc.spool}, this mail will be
7800 put in the @code{mail.misc}, as one would expect. However, if you want
7801 Gnus to split the mail the normal way, you could set
7802 @code{nnmail-resplit-incoming} to @code{t}.
7804 @vindex nnmail-keep-last-article
7805 If you use @code{procmail} to split things directory into an @code{nnmh}
7806 directory (which you shouldn't do), you should set
7807 @code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
7808 ever expiring the final article in a mail newsgroup. This is quite,
7812 @node Incorporating Old Mail
7813 @subsection Incorporating Old Mail
7815 Most people have lots of old mail stored in various file formats. If
7816 you have set up Gnus to read mail using one of the spiffy Gnus mail
7817 backends, you'll probably wish to have that old mail incorporated into
7820 Doing so can be quite easy.
7822 To take an example: You're reading mail using @code{nnml}
7823 (@pxref{Mail Spool}), and have set @code{nnmail-split-methods} to a
7824 satisfactory value (@pxref{Splitting Mail}). You have an old Unix mbox
7825 file filled with important, but old, mail. You want to move it into
7826 your @code{nnml} groups.
7832 Go to the group buffer.
7835 Type `G f' and give the path of the mbox file when prompted to create an
7836 @code{nndoc} group from the mbox file (@pxref{Foreign Groups}).
7839 Type `SPACE' to enter the newly created group.
7842 Type `M P b' to process-mark all articles in this group (@pxref{Setting
7846 Type `B r' to respool all the process-marked articles, and answer
7847 @samp{nnml} when prompted (@pxref{Mail Group Commands}).
7850 All the mail messages in the mbox file will now also be spread out over
7851 all your @code{nnml} groups. Try entering them and check whether things
7852 have gone without a glitch. If things look ok, you may consider
7853 deleting the mbox file, but I wouldn't do that unless I was absolutely
7854 sure that all the mail has ended up where it should be.
7856 Respooling is also a handy thing to do if you're switching from one mail
7857 backend to another. Just respool all the mail in the old mail groups
7858 using the new mail backend.
7862 @subsection Expiring Mail
7863 @cindex article expiry
7865 Traditional mail readers have a tendency to remove mail articles when
7866 you mark them as read, in some way. Gnus takes a fundamentally
7867 different approach to mail reading.
7869 Gnus basically considers mail just to be news that has been received in
7870 a rather peculiar manner. It does not think that it has the power to
7871 actually change the mail, or delete any mail messages. If you enter a
7872 mail group, and mark articles as ``read'', or kill them in some other
7873 fashion, the mail articles will still exist on the system. I repeat:
7874 Gnus will not delete your old, read mail. Unless you ask it to, of
7877 To make Gnus get rid of your unwanted mail, you have to mark the
7878 articles as @dfn{expirable}. This does not mean that the articles will
7879 disappear right away, however. In general, a mail article will be
7880 deleted from your system if, 1) it is marked as expirable, AND 2) it is
7881 more than one week old. If you do not mark an article as expirable, it
7882 will remain on your system until hell freezes over. This bears
7883 repeating one more time, with some spurious capitalizations: IF you do
7884 NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
7886 @vindex gnus-auto-expirable-newsgroups
7887 You do not have to mark articles as expirable by hand. Groups that
7888 match the regular expression @code{gnus-auto-expirable-newsgroups} will
7889 have all articles that you read marked as expirable automatically. All
7890 articles that are marked as expirable have an @samp{E} in the first
7891 column in the summary buffer.
7893 Let's say you subscribe to a couple of mailing lists, and you want the
7894 articles you have read to disappear after a while:
7897 (setq gnus-auto-expirable-newsgroups
7898 "mail.nonsense-list\\|mail.nice-list")
7901 Another way to have auto-expiry happen is to have the element
7902 @code{auto-expire} in the group parameters of the group.
7904 @vindex nnmail-expiry-wait
7905 The @code{nnmail-expiry-wait} variable supplies the default time an
7906 expirable article has to live. The default is seven days.
7908 Gnus also supplies a function that lets you fine-tune how long articles
7909 are to live, based on what group they are in. Let's say you want to
7910 have one month expiry period in the @samp{mail.private} group, a one day
7911 expiry period in the @samp{mail.junk} group, and a six day expiry period
7914 @vindex nnmail-expiry-wait-function
7916 (setq nnmail-expiry-wait-function
7918 (cond ((string= group "mail.private")
7920 ((string= group "mail.junk")
7922 ((string= group "important")
7928 The group names that this function is fed are ``unadorned'' group
7929 names---no @samp{nnml:} prefixes and the like.
7931 The @code{nnmail-expiry-wait} variable and
7932 @code{nnmail-expiry-wait-function} function can be either a number (not
7933 necessarily an integer) or the symbols @code{immediate} or
7936 You can also use the @code{expiry-wait} group parameter to selectively
7937 change the expiry period (@pxref{Group Parameters}).
7939 @vindex nnmail-keep-last-article
7940 If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
7941 expire the final article in a mail newsgroup. This is to make life
7942 easier for procmail users.
7944 @vindex gnus-total-expirable-newsgroups
7945 By the way, that line up there about Gnus never expiring non-expirable
7946 articles is a lie. If you put @code{total-expire} in the group
7947 parameters, articles will not be marked as expirable, but all read
7948 articles will be put through the expiry process. Use with extreme
7949 caution. Even more dangerous is the
7950 @code{gnus-total-expirable-newsgroups} variable. All groups that match
7951 this regexp will have all read articles put through the expiry process,
7952 which means that @emph{all} old mail articles in the groups in question
7953 will be deleted after a while. Use with extreme caution, and don't come
7954 crying to me when you discover that the regexp you used matched the
7955 wrong group and all your important mail has disappeared. Be a
7956 @emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
7961 @subsection Duplicates
7963 @vindex nnmail-delete-duplicates
7964 @vindex nnmail-message-id-cache-length
7965 @vindex nnmail-message-id-cache-file
7966 @vindex nnmail-treat-duplicates
7967 @cindex duplicate mails
7968 If you are a member of a couple of mailing list, you will sometime
7969 receive two copies of the same mail. This can be quite annoying, so
7970 @code{nnmail} checks for and treats any duplicates it might find. To do
7971 this, it keeps a cache of old @code{Message-ID}s -
7972 @code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
7973 default. The approximate maximum number of @code{Message-ID}s stored
7974 there is controlled by the @code{nnmail-message-id-cache-length}
7975 variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
7976 stored.) If all this sounds scary to you, you can set
7977 @code{nnmail-delete-duplicates} to @code{warn} (which is what it is by
7978 default), and @code{nnmail} won't delete duplicate mails. Instead it
7979 will generate a brand new @code{Message-ID} for the mail and insert a
7980 warning into the head of the mail saying that it thinks that this is a
7981 duplicate of a different message.
7983 This variable can also be a function. If that's the case, the function
7984 will be called from a buffer narrowed to the message in question with
7985 the @code{Message-ID} as a parameter. The function must return either
7986 @code{nil}, @code{warn}, or @code{delete}.
7988 You can turn this feature off completely by setting the variable to
7991 If you want all the duplicate mails to be put into a special
7992 @dfn{duplicates} group, you could do that using the normal mail split
7996 (setq nnmail-split-fancy
7997 '(| ;; Messages duplicates go to a separate group.
7998 ("gnus-warning" "duplication of message" "duplicate")
7999 ;; Message from daemons, postmaster, and the like to another.
8000 (any mail "mail.misc")
8007 (setq nnmail-split-methods
8008 '(("duplicates" "^Gnus-Warning:")
8013 Here's a neat feature: If you know that the recipient reads her mail
8014 with Gnus, and that she has @code{nnmail-treat-duplicates} set to
8015 @code{delete}, you can send her as many insults as you like, just by
8016 using a @code{Message-ID} of a mail that you know that she's already
8017 received. Think of all the fun! She'll never see any of it! Whee!
8020 @node Not Reading Mail
8021 @subsection Not Reading Mail
8023 If you start using any of the mail backends, they have the annoying
8024 habit of assuming that you want to read mail with them. This might not
8025 be unreasonable, but it might not be what you want.
8027 If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
8028 will ever attempt to read incoming mail, which should help.
8030 @vindex nnbabyl-get-new-mail
8031 @vindex nnmbox-get-new-mail
8032 @vindex nnml-get-new-mail
8033 @vindex nnmh-get-new-mail
8034 @vindex nnfolder-get-new-mail
8035 This might be too much, if, for instance, you are reading mail quite
8036 happily with @code{nnml} and just want to peek at some old @sc{rmail}
8037 file you have stashed away with @code{nnbabyl}. All backends have
8038 variables called backend-@code{get-new-mail}. If you want to disable
8039 the @code{nnbabyl} mail reading, you edit the virtual server for the
8040 group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
8042 All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
8043 narrowed to the article to be saved before saving it when reading
8047 @node Choosing a Mail Backend
8048 @subsection Choosing a Mail Backend
8050 Gnus will read the mail spool when you activate a mail group. The mail
8051 file is first copied to your home directory. What happens after that
8052 depends on what format you want to store your mail in.
8055 * Unix Mail Box:: Using the (quite) standard Un*x mbox.
8056 * Rmail Babyl:: Emacs programs use the rmail babyl format.
8057 * Mail Spool:: Store your mail in a private spool?
8058 * MH Spool:: An mhspool-like backend.
8059 * Mail Folders:: Having one file for each group.
8064 @subsubsection Unix Mail Box
8066 @cindex unix mail box
8068 @vindex nnmbox-active-file
8069 @vindex nnmbox-mbox-file
8070 The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
8071 mail. @code{nnmbox} will add extra headers to each mail article to say
8072 which group it belongs in.
8074 Virtual server settings:
8077 @item nnmbox-mbox-file
8078 @vindex nnmbox-mbox-file
8079 The name of the mail box in the user's home directory.
8081 @item nnmbox-active-file
8082 @vindex nnmbox-active-file
8083 The name of the active file for the mail box.
8085 @item nnmbox-get-new-mail
8086 @vindex nnmbox-get-new-mail
8087 If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
8093 @subsubsection Rmail Babyl
8097 @vindex nnbabyl-active-file
8098 @vindex nnbabyl-mbox-file
8099 The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
8100 mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
8101 article to say which group it belongs in.
8103 Virtual server settings:
8106 @item nnbabyl-mbox-file
8107 @vindex nnbabyl-mbox-file
8108 The name of the rmail mbox file.
8110 @item nnbabyl-active-file
8111 @vindex nnbabyl-active-file
8112 The name of the active file for the rmail box.
8114 @item nnbabyl-get-new-mail
8115 @vindex nnbabyl-get-new-mail
8116 If non-@code{nil}, @code{nnbabyl} will read incoming mail.
8121 @subsubsection Mail Spool
8123 @cindex mail @sc{nov} spool
8125 The @dfn{nnml} spool mail format isn't compatible with any other known
8126 format. It should be used with some caution.
8128 @vindex nnml-directory
8129 If you use this backend, Gnus will split all incoming mail into files;
8130 one file for each mail, and put the articles into the correct
8131 directories under the directory specified by the @code{nnml-directory}
8132 variable. The default value is @file{~/Mail/}.
8134 You do not have to create any directories beforehand; Gnus will take
8137 If you have a strict limit as to how many files you are allowed to store
8138 in your account, you should not use this backend. As each mail gets its
8139 own file, you might very well occupy thousands of inodes within a few
8140 weeks. If this is no problem for you, and it isn't a problem for you
8141 having your friendly systems administrator walking around, madly,
8142 shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should
8143 know that this is probably the fastest format to use. You do not have
8144 to trudge through a big mbox file just to read your new mail.
8146 @code{nnml} is probably the slowest backend when it comes to article
8147 splitting. It has to create lots of files, and it also generates
8148 @sc{nov} databases for the incoming mails. This makes is the fastest
8149 backend when it comes to reading mail.
8151 Virtual server settings:
8154 @item nnml-directory
8155 @vindex nnml-directory
8156 All @code{nnml} directories will be placed under this directory.
8158 @item nnml-active-file
8159 @vindex nnml-active-file
8160 The active file for the @code{nnml} server.
8162 @item nnml-newsgroups-file
8163 @vindex nnml-newsgroups-file
8164 The @code{nnml} group descriptions file. @xref{Newsgroups File
8167 @item nnml-get-new-mail
8168 @vindex nnml-get-new-mail
8169 If non-@code{nil}, @code{nnml} will read incoming mail.
8171 @item nnml-nov-is-evil
8172 @vindex nnml-nov-is-evil
8173 If non-@code{nil}, this backend will ignore any @sc{nov} files.
8175 @item nnml-nov-file-name
8176 @vindex nnml-nov-file-name
8177 The name of the @sc{nov} files. The default is @file{.overview}.
8179 @item nnml-prepare-save-mail-hook
8180 @vindex nnml-prepare-save-mail-hook
8181 Hook run narrowed to an article before saving.
8185 @findex nnml-generate-nov-databases
8186 If your @code{nnml} groups and @sc{nov} files get totally out of whack,
8187 you can do a complete update by typing @kbd{M-x
8188 nnml-generate-nov-databases}. This command will trawl through the
8189 entire @code{nnml} hierarchy, looking at each and every article, so it
8190 might take a while to complete.
8194 @subsubsection MH Spool
8196 @cindex mh-e mail spool
8198 @code{nnmh} is just like @code{nnml}, except that is doesn't generate
8199 @sc{nov} databases and it doesn't keep an active file. This makes
8200 @code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
8201 makes it easier to write procmail scripts for.
8203 Virtual server settings:
8206 @item nnmh-directory
8207 @vindex nnmh-directory
8208 All @code{nnmh} directories will be located under this directory.
8210 @item nnmh-get-new-mail
8211 @vindex nnmh-get-new-mail
8212 If non-@code{nil}, @code{nnmh} will read incoming mail.
8215 @vindex nnmh-be-safe
8216 If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
8217 sure that the articles in the folder are actually what Gnus thinks they
8218 are. It will check date stamps and stat everything in sight, so
8219 setting this to @code{t} will mean a serious slow-down. If you never
8220 use anything but Gnus to read the @code{nnmh} articles, you do not have
8221 to set this variable to @code{t}.
8226 @subsubsection Mail Folders
8228 @cindex mbox folders
8229 @cindex mail folders
8231 @code{nnfolder} is a backend for storing each mail group in a separate
8232 file. Each file is in the standard Un*x mbox format. @code{nnfolder}
8233 will add extra headers to keep track of article numbers and arrival
8236 Virtual server settings:
8239 @item nnfolder-directory
8240 @vindex nnfolder-directory
8241 All the @code{nnfolder} mail boxes will be stored under this directory.
8243 @item nnfolder-active-file
8244 @vindex nnfolder-active-file
8245 The name of the active file.
8247 @item nnfolder-newsgroups-file
8248 @vindex nnfolder-newsgroups-file
8249 The name of the group descriptions file. @xref{Newsgroups File Format}.
8251 @item nnfolder-get-new-mail
8252 @vindex nnfolder-get-new-mail
8253 If non-@code{nil}, @code{nnfolder} will read incoming mail.
8256 @findex nnfolder-generate-active-file
8257 @kindex M-x nnfolder-generate-active-file
8258 If you have lots of @code{nnfolder}-like files you'd like to read with
8259 @code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file}
8260 command to make @code{nnfolder} aware of all likely files in
8261 @code{nnfolder-directory}.
8265 @section Other Sources
8267 Gnus can do more than just read news or mail. The methods described
8268 below allow Gnus to view directories and files as if they were
8272 * Directory Groups:: You can read a directory as if it was a newsgroup.
8273 * Anything Groups:: Dired? Who needs dired?
8274 * Document Groups:: Single files can be the basis of a group.
8275 * SOUP:: Reading @sc{SOUP} packets ``offline''.
8279 @node Directory Groups
8280 @subsection Directory Groups
8282 @cindex directory groups
8284 If you have a directory that has lots of articles in separate files in
8285 it, you might treat it as a newsgroup. The files have to have numerical
8288 This might be an opportune moment to mention @code{ange-ftp}, that most
8289 wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
8290 didn't think much about it---a backend to read directories. Big deal.
8292 @code{ange-ftp} changes that picture dramatically. For instance, if you
8293 enter @file{"/ftp.hpc.uh.edu:/pub/emacs/ding-list/"} as the the
8294 directory name, ange-ftp will actually allow you to read this directory
8295 over at @samp{sina} as a newsgroup. Distributed news ahoy!
8297 @code{nndir} will use @sc{nov} files if they are present.
8299 @code{nndir} is a ``read-only'' backend---you can't delete or expire
8300 articles with this method. You can use @code{nnmh} or @code{nnml} for
8301 whatever you use @code{nndir} for, so you could switch to any of those
8302 methods if you feel the need to have a non-read-only @code{nndir}.
8305 @node Anything Groups
8306 @subsection Anything Groups
8309 From the @code{nndir} backend (which reads a single spool-like
8310 directory), it's just a hop and a skip to @code{nneething}, which
8311 pretends that any arbitrary directory is a newsgroup. Strange, but
8314 When @code{nneething} is presented with a directory, it will scan this
8315 directory and assign article numbers to each file. When you enter such
8316 a group, @code{nneething} must create ``headers'' that Gnus can use.
8317 After all, Gnus is a newsreader, in case you're
8318 forgetting. @code{nneething} does this in a two-step process. First, it
8319 snoops each file in question. If the file looks like an article (i.e.,
8320 the first few lines look like headers), it will use this as the head.
8321 If this is just some arbitrary file without a head (eg. a C source
8322 file), @code{nneething} will cobble up a header out of thin air. It
8323 will use file ownership, name and date and do whatever it can with these
8326 All this should happen automatically for you, and you will be presented
8327 with something that looks very much like a newsgroup. Totally like a
8328 newsgroup, to be precise. If you select an article, it will be displayed
8329 in the article buffer, just as usual.
8331 If you select a line that represents a directory, Gnus will pop you into
8332 a new summary buffer for this @code{nneething} group. And so on. You can
8333 traverse the entire disk this way, if you feel like, but remember that
8334 Gnus is not dired, really, and does not intend to be, either.
8336 There are two overall modes to this action---ephemeral or solid. When
8337 doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
8338 will not store information on what files you have read, and what files
8339 are new, and so on. If you create a solid @code{nneething} group the
8340 normal way with @kbd{G m}, Gnus will store a mapping table between
8341 article numbers and file names, and you can treat this group like any
8342 other groups. When you activate a solid @code{nneething} group, you will
8343 be told how many unread articles it contains, etc., etc.
8348 @item nneething-map-file-directory
8349 @vindex nneething-map-file-directory
8350 All the mapping files for solid @code{nneething} groups will be stored
8351 in this directory, which defaults to @file{~/.nneething/}.
8353 @item nneething-exclude-files
8354 @vindex nneething-exclude-files
8355 All files that match this regexp will be ignored. Nice to use to exclude
8356 auto-save files and the like, which is what it does by default.
8358 @item nneething-map-file
8359 @vindex nneething-map-file
8360 Name of the map files.
8364 @node Document Groups
8365 @subsection Document Groups
8367 @cindex documentation group
8370 @code{nndoc} is a cute little thing that will let you read a single file
8371 as a newsgroup. Several files types are supported:
8378 The babyl (rmail) mail box.
8383 The standard Unix mbox file.
8385 @cindex MMDF mail box
8387 The MMDF mail box format.
8390 Several news articles appended into a file.
8393 @cindex rnews batch files
8394 The rnews batch transport format.
8395 @cindex forwarded messages
8404 @cindex RFC 1153 digest
8405 @cindex RFC 341 digest
8406 MIME (RFC 1341) digest format.
8408 @item standard-digest
8409 The standard (RFC 1153) digest format.
8412 Non-standard digest format---matches most things, but does it badly.
8415 You can also use the special ``file type'' @code{guess}, which means
8416 that @code{nndoc} will try to guess what file type it is looking at.
8417 @code{digest} means that @code{nndoc} should guess what digest type the
8420 @code{nndoc} will not try to change the file or insert any extra headers into
8421 it---it will simply, like, let you use the file as the basis for a
8422 group. And that's it.
8424 If you have some old archived articles that you want to insert into your
8425 new & spiffy Gnus mail backend, @code{nndoc} can probably help you with
8426 that. Say you have an old @file{RMAIL} file with mail that you now want
8427 to split into your new @code{nnml} groups. You look at that file using
8428 @code{nndoc}, set the process mark on all the articles in the buffer
8429 (@kbd{M P b}, for instance), and then re-spool (@kbd{B r}) using
8430 @code{nnml}. If all goes well, all the mail in the @file{RMAIL} file is
8431 now also stored in lots of @code{nnml} directories, and you can delete
8432 that pesky @file{RMAIL} file. If you have the guts!
8434 Virtual server variables:
8437 @item nndoc-article-type
8438 @vindex nndoc-article-type
8439 This should be one of @code{mbox}, @code{babyl}, @code{digest},
8440 @code{mmdf}, @code{forward}, @code{news}, @code{rnews},
8441 @code{mime-digest}, @code{clari-briefs}, or @code{guess}.
8443 @item nndoc-post-type
8444 @vindex nndoc-post-type
8445 This variable says whether Gnus is to consider the group a news group or
8446 a mail group. There are two legal values: @code{mail} (the default)
8456 In the PC world people often talk about ``offline'' newsreaders. These
8457 are thingies that are combined reader/news transport monstrosities.
8458 With built-in modem programs. Yecchh!
8460 Of course, us Unix Weenie types of human beans use things like
8461 @code{uucp} and, like, @code{nntpd} and set up proper news and mail
8462 transport things like Ghod intended. And then we just use normal
8465 However, it can sometimes be convenient to do something a that's a bit
8466 easier on the brain if you have a very slow modem, and you're not really
8467 that interested in doing things properly.
8469 A file format called @sc{soup} has been developed for transporting news
8470 and mail from servers to home machines and back again. It can be a bit
8476 You log in on the server and create a @sc{soup} packet. You can either
8477 use a dedicated @sc{soup} thingie, or you can use Gnus to create the
8478 packet with the @kbd{O s} command.
8481 You transfer the packet home. Rail, boat, car or modem will do fine.
8484 You put the packet in your home directory.
8487 You fire up Gnus using the @code{nnsoup} backend as the native server.
8490 You read articles and mail and answer and followup to the things you
8494 You do the @kbd{G s r} command to pack these replies into a @sc{soup}
8498 You transfer this packet to the server.
8501 You use Gnus to mail this packet out with the @kbd{G s s} command.
8504 You then repeat until you die.
8508 So you basically have a bipartite system---you use @code{nnsoup} for
8509 reading and Gnus for packing/sending these @sc{soup} packets.
8512 * SOUP Commands:: Commands for creating and sending @sc{soup} packets
8513 * SOUP Groups:: A backend for reading @sc{soup} packets.
8514 * SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
8519 @subsubsection SOUP Commands
8523 @kindex G s b (Group)
8524 @findex gnus-group-brew-soup
8525 Pack all unread articles in the current group
8526 (@code{gnus-group-brew-soup}). This command understands the
8527 process/prefix convention.
8530 @kindex G s w (Group)
8531 @findex gnus-soup-save-areas
8532 Save all data files (@code{gnus-soup-save-areas}).
8535 @kindex G s s (Group)
8536 @findex gnus-soup-send-replies
8537 Send all replies from the replies packet
8538 (@code{gnus-soup-send-replies}).
8541 @kindex G s p (Group)
8542 @findex gnus-soup-pack-packet
8543 Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
8546 @kindex G s r (Group)
8547 @findex nnsoup-pack-replies
8548 Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
8551 @kindex O s (Summary)
8552 @findex gnus-soup-add-article
8553 This summary-mode command adds the current article to a @sc{soup} packet
8554 (@code{gnus-soup-add-article}). It understands the process/prefix
8560 There are a few variables to customize where Gnus will put all these
8565 @item gnus-soup-directory
8566 @vindex gnus-soup-directory
8567 Directory where Gnus will save intermediate files while composing
8568 @sc{soup} packets. The default is @file{~/SoupBrew/}.
8570 @item gnus-soup-replies-directory
8571 @vindex gnus-soup-replies-directory
8572 This is what Gnus will use as a temporary directory while sending our
8573 reply packets. The default is @file{~/SoupBrew/SoupReplies/}.
8575 @item gnus-soup-prefix-file
8576 @vindex gnus-soup-prefix-file
8577 Name of the file where Gnus stores the last used prefix. The default is
8580 @item gnus-soup-packer
8581 @vindex gnus-soup-packer
8582 A format string command for packing a @sc{soup} packet. The default is
8583 @samp{tar cf - %s | gzip > $HOME/Soupout%d.tgz}.
8585 @item gnus-soup-unpacker
8586 @vindex gnus-soup-unpacker
8587 Format string command for unpacking a @sc{soup} packet. The default is
8588 @samp{gunzip -c %s | tar xvf -}.
8590 @item gnus-soup-packet-directory
8591 @vindex gnus-soup-packet-directory
8592 Where Gnus will look for reply packets. The default is @file{~/}.
8594 @item gnus-soup-packet-regexp
8595 @vindex gnus-soup-packet-regexp
8596 Regular expression matching @sc{soup} reply packets in
8597 @code{gnus-soup-packet-directory}.
8603 @subsubsection @sc{soup} Groups
8606 @code{nnsoup} is the backend for reading @sc{soup} packets. It will
8607 read incoming packets, unpack them, and put them in a directory where
8608 you can read them at leisure.
8610 These are the variables you can use to customize its behavior:
8614 @item nnsoup-tmp-directory
8615 @vindex nnsoup-tmp-directory
8616 When @code{nnsoup} unpacks a @sc{soup} packet, it does it in this
8617 directory. (@file{/tmp/} by default.)
8619 @item nnsoup-directory
8620 @vindex nnsoup-directory
8621 @code{nnsoup} then moves each message and index file to this directory.
8622 The default is @file{~/SOUP/}.
8624 @item nnsoup-replies-directory
8625 @vindex nnsoup-replies-directory
8626 All replies will stored in this directory before being packed into a
8627 reply packet. The default is @file{~/SOUP/replies/"}.
8629 @item nnsoup-replies-format-type
8630 @vindex nnsoup-replies-format-type
8631 The @sc{soup} format of the replies packets. The default is @samp{?n}
8632 (rnews), and I don't think you should touch that variable. I probably
8633 shouldn't even have documented it. Drats! Too late!
8635 @item nnsoup-replies-index-type
8636 @vindex nnsoup-replies-index-type
8637 The index type of the replies packet. The is @samp{?n}, which means
8638 ``none''. Don't fiddle with this one either!
8640 @item nnsoup-active-file
8641 @vindex nnsoup-active-file
8642 Where @code{nnsoup} stores lots of information. This is not an ``active
8643 file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
8644 this file or mess it up in any way, you're dead. The default is
8645 @file{~/SOUP/active}.
8648 @vindex nnsoup-packer
8649 Format string command for packing a reply @sc{soup} packet. The default
8650 is @samp{tar cf - %s | gzip > $HOME/Soupin%d.tgz}.
8652 @item nnsoup-unpacker
8653 @vindex nnsoup-unpacker
8654 Format string command for unpacking incoming @sc{soup} packets. The
8655 default is @samp{gunzip -c %s | tar xvf -}.
8657 @item nnsoup-packet-directory
8658 @vindex nnsoup-packet-directory
8659 Where @code{nnsoup} will look for incoming packets. The default is
8662 @item nnsoup-packet-regexp
8663 @vindex nnsoup-packet-regexp
8664 Regular expression matching incoming @sc{soup} packets. The default is
8671 @subsubsection SOUP Replies
8673 Just using @code{nnsoup} won't mean that your postings and mailings end
8674 up in @sc{soup} reply packets automagically. You have to work a bit
8675 more for that to happen.
8677 @findex nnsoup-set-variables
8678 The @code{nnsoup-set-variables} command will set the appropriate
8679 variables to ensure that all your followups and replies end up in the
8682 In specific, this is what it does:
8685 (setq gnus-inews-article-function 'nnsoup-request-post)
8686 (setq send-mail-function 'nnsoup-request-mail)
8689 And that's it, really. If you only want news to go into the @sc{soup}
8690 system you just use the first line. If you only want mail to be
8691 @sc{soup}ed you use the second.
8694 @node Combined Groups
8695 @section Combined Groups
8697 Gnus allows combining a mixture of all the other group types into bigger
8701 * Virtual Groups:: Combining articles from many groups.
8702 * Kibozed Groups:: Looking through parts of the newsfeed for articles.
8706 @node Virtual Groups
8707 @subsection Virtual Groups
8709 @cindex virtual groups
8711 An @dfn{nnvirtual group} is really nothing more than a collection of
8714 For instance, if you are tired of reading many small group, you can
8715 put them all in one big group, and then grow tired of reading one
8716 big, unwieldy group. The joys of computing!
8718 You specify @code{nnvirtual} as the method. The address should be a
8719 regexp to match component groups.
8721 All marks in the virtual group will stick to the articles in the
8722 component groups. So if you tick an article in a virtual group, the
8723 article will also be ticked in the component group from whence it came.
8724 (And vice versa---marks from the component groups will also be shown in
8727 Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
8728 newsgroups into one, big, happy newsgroup:
8731 (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
8734 The component groups can be native or foreign; everything should work
8735 smoothly, but if your computer explodes, it was probably my fault.
8737 Collecting the same group from several servers might actually be a good
8738 idea if users have set the Distribution header to limit distribution.
8739 If you would like to read @samp{soc.motss} both from a server in Japan
8740 and a server in Norway, you could use the following as the group regexp:
8743 "^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
8746 This should work kinda smoothly---all articles from both groups should
8747 end up in this one, and there should be no duplicates. Threading (and
8748 the rest) will still work as usual, but there might be problems with the
8749 sequence of articles. Sorting on date might be an option here
8750 (@pxref{Selecting a Group}.
8752 One limitation, however---all groups that are included in a virtual
8753 group has to be alive (i.e., subscribed or unsubscribed). Killed or
8754 zombie groups can't be component groups for @code{nnvirtual} groups.
8756 @vindex nnvirtual-always-rescan
8757 If the @code{nnvirtual-always-rescan} is non-@code{nil},
8758 @code{nnvirtual} will always scan groups for unread articles when
8759 entering a virtual group. If this variable is @code{nil} (which is the
8760 default) and you read articles in a component group after the virtual
8761 group has been activated, the read articles from the component group
8762 will show up when you enter the virtual group. You'll also see this
8763 effect if you have two virtual groups that contain the same component
8764 group. If that's the case, you should set this variable to @code{t}.
8765 Or you can just tap @code{M-g} on the virtual group every time before
8766 you enter it---it'll have much the same effect.
8769 @node Kibozed Groups
8770 @subsection Kibozed Groups
8774 @dfn{Kibozing} is defined by @sc{oed} as ``grepping through (parts of)
8775 the news feed''. @code{nnkiboze} is a backend that will do this for
8776 you. Oh joy! Now you can grind any @sc{nntp} server down to a halt
8777 with useless requests! Oh happiness!
8779 The address field of the @code{nnkiboze} method is, as with
8780 @code{nnvirtual}, a regexp to match groups to be ``included'' in the
8781 @code{nnkiboze} group. There most similarities between @code{nnkiboze}
8782 and @code{nnvirtual} ends.
8784 In addition to this regexp detailing component groups, an @code{nnkiboze} group
8785 must have a score file to say what articles that are to be included in
8786 the group (@pxref{Scoring}).
8788 @kindex M-x nnkiboze-generate-groups
8789 @findex nnkiboze-generate-groups
8790 You must run @kbd{M-x nnkiboze-generate-groups} after creating the
8791 @code{nnkiboze} groups you want to have. This command will take time. Lots of
8792 time. Oodles and oodles of time. Gnus has to fetch the headers from
8793 all the articles in all the components groups and run them through the
8794 scoring process to determine if there are any articles in the groups
8795 that are to be part of the @code{nnkiboze} groups.
8797 Please limit the number of component groups by using restrictive
8798 regexps. Otherwise your sysadmin may become annoyed with you, and the
8799 @sc{nntp} site may throw you off and never let you back in again.
8800 Stranger things have happened.
8802 @code{nnkiboze} component groups do not have to be alive---they can be dead,
8803 and they can be foreign. No restrictions.
8805 @vindex nnkiboze-directory
8806 The generation of an @code{nnkiboze} group means writing two files in
8807 @code{nnkiboze-directory}, which is @file{~/News/} by default. One
8808 contains the @sc{nov} header lines for all the articles in the group,
8809 and the other is an additional @file{.newsrc} file to store information
8810 on what groups that have been searched through to find component
8813 Articles that are marked as read in the @code{nnkiboze} group will have their
8814 @sc{nov} lines removed from the @sc{nov} file.
8821 Other people use @dfn{kill files}, but we here at Gnus Towers like
8822 scoring better than killing, so we'd rather switch than fight. They do
8823 something completely different as well, so sit up straight and pay
8826 @vindex gnus-summary-mark-below
8827 All articles have a default score (@code{gnus-summary-default-score}),
8828 which is 0 by default. This score may be raised or lowered either
8829 interactively or by score files. Articles that have a score lower than
8830 @code{gnus-summary-mark-below} are marked as read.
8832 Gnus will read any @dfn{score files} that apply to the current group
8833 before generating the summary buffer.
8835 There are several commands in the summary buffer that insert score
8836 entries based on the current article. You can, for instance, ask Gnus to
8837 lower or increase the score of all articles with a certain subject.
8839 There are two sorts of scoring entries: Permanent and temporary.
8840 Temporary score entries are self-expiring entries. Any entries that are
8841 temporary and have not been used for, say, a week, will be removed
8842 silently to help keep the sizes of the score files down.
8845 * Summary Score Commands:: Adding score entries for the current group.
8846 * Group Score Commands:: General score commands.
8847 * Score Variables:: Customize your scoring. (My, what terminology).
8848 * Score File Format:: What a score file may contain.
8849 * Score File Editing:: You can edit score files by hand as well.
8850 * Adaptive Scoring:: Big Sister Gnus *knows* what you read.
8851 * Followups To Yourself:: Having Gnus notice when people answer you.
8852 * Scoring Tips:: How to score effectively.
8853 * Reverse Scoring:: That problem child of old is not problem.
8854 * Global Score Files:: Earth-spanning, ear-splitting score files.
8855 * Kill Files:: They are still here, but they can be ignored.
8856 * GroupLens:: Getting predictions on what you like to read.
8860 @node Summary Score Commands
8861 @section Summary Score Commands
8862 @cindex score commands
8864 The score commands that alter score entries do not actually modify real
8865 score files. That would be too inefficient. Gnus maintains a cache of
8866 previously loaded score files, one of which is considered the
8867 @dfn{current score file alist}. The score commands simply insert
8868 entries into this list, and upon group exit, this list is saved.
8870 The current score file is by default the group's local score file, even
8871 if no such score file actually exists. To insert score commands into
8872 some other score file (eg. @file{all.SCORE}), you must first make this
8873 score file the current one.
8875 General score commands that don't actually change the score file:
8880 @kindex V s (Summary)
8881 @findex gnus-summary-set-score
8882 Set the score of the current article (@code{gnus-summary-set-score}).
8885 @kindex V S (Summary)
8886 @findex gnus-summary-current-score
8887 Display the score of the current article
8888 (@code{gnus-summary-current-score}).
8891 @kindex V t (Summary)
8892 @findex gnus-score-find-trace
8893 Display all score rules that have been used on the current article
8894 (@code{gnus-score-find-trace}).
8897 @cindex V R (Summary)
8898 @findex gnus-summary-rescore
8899 Run the current summary through the scoring process
8900 (@code{gnus-summary-rescore}). This might be useful if you're playing
8901 around with your score files behind Gnus' back and want to see the
8902 effect you're having.
8905 @kindex V a (Summary)
8906 @findex gnus-summary-score-entry
8907 Add a new score entry, and allow specifying all elements
8908 (@code{gnus-summary-score-entry}).
8911 @kindex V c (Summary)
8912 @findex gnus-score-change-score-file
8913 Make a different score file the current
8914 (@code{gnus-score-change-score-file}).
8917 @kindex V e (Summary)
8918 @findex gnus-score-edit-current-scores
8919 Edit the current score file (@code{gnus-score-edit-current-scores}).
8920 You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score
8924 @kindex V f (Summary)
8925 @findex gnus-score-edit-file
8926 Edit a score file and make this score file the current one
8927 (@code{gnus-score-edit-file}).
8930 @kindex V C (Summary)
8931 @findex gnus-score-customize
8932 Customize a score file in a visually pleasing manner
8933 (@code{gnus-score-customize}).
8936 @kindex I C-i (Summary)
8937 @findex gnus-summary-raise-score
8938 Increase the score of the current article
8939 (@code{gnus-summary-raise-score}).
8942 @kindex L C-l (Summary)
8943 @findex gnus-summary-lower-score
8944 Lower the score of the current article
8945 (@code{gnus-summary-lower-score}).
8948 The rest of these commands modify the local score file.
8953 @kindex V m (Summary)
8954 @findex gnus-score-set-mark-below
8955 Prompt for a score, and mark all articles with a score below this as
8956 read (@code{gnus-score-set-mark-below}).
8959 @kindex V E (Summary)
8960 @findex gnus-score-set-expunge-below
8961 Expunge all articles with a score below the default score (or the
8962 numeric prefix) (@code{gnus-score-set-expunge-below}).
8965 The keystrokes for actually making score entries follow a very regular
8966 pattern, so there's no need to list all the commands. (Hundreds of
8971 The first key is either @kbd{I} (upper case i) for increasing the score
8972 or @kbd{L} for lowering the score.
8974 The second key says what header you want to score on. The following
8979 Score on the author name.
8982 Score on the subject line.
8985 Score on the Xref line---i.e., the cross-posting line.
8988 Score on thread---the References line.
8994 Score on the number of lines.
8997 Score on the Message-ID.
9010 The third key is the match type. Which match types are legal depends on
9011 what headers you are scoring on.
9055 Greater than number.
9060 The fourth and final key says whether this is a temporary (i.e., expiring)
9061 score entry, or a permanent (i.e., non-expiring) score entry, or whether
9062 it is to be done immediately, without adding to the score file.
9066 Temporary score entry.
9069 Permanent score entry.
9072 Immediately scoring.
9077 So, let's say you want to increase the score on the current author with
9078 exact matching permanently: @kbd{I a e p}. If you want to lower the
9079 score based on the subject line, using substring matching, and make a
9080 temporary score entry: @kbd{L s s t}. Pretty easy.
9082 To make things a bit more complicated, there are shortcuts. If you use
9083 a capital letter on either the second or third keys, Gnus will use
9084 defaults for the remaining one or two keystrokes. The defaults are
9085 ``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s
9086 t}, and @kbd{I a R} is the same as @kbd{I a r t}.
9088 @vindex gnus-score-mimic-keymap
9089 The @code{gnus-score-mimic-keymap} says whether these commands will
9090 pretend they are keymaps or not.
9093 @node Group Score Commands
9094 @section Group Score Commands
9095 @cindex group score commands
9097 There aren't many of these as yet, I'm afraid.
9103 @findex gnus-score-flush-cache
9104 Gnus maintains a cache of score alists to avoid having to reload them
9105 all the time. This command will flush the cache
9106 (@code{gnus-score-flush-cache}).
9111 @node Score Variables
9112 @section Score Variables
9113 @cindex score variables
9117 @item gnus-use-scoring
9118 @vindex gnus-use-scoring
9119 If @code{nil}, Gnus will not check for score files, and will not, in
9120 general, do any score-related work. This is @code{t} by default.
9122 @item gnus-kill-killed
9123 @vindex gnus-kill-killed
9124 If this variable is @code{nil}, Gnus will never apply score files to
9125 articles that have already been through the kill process. While this
9126 may save you lots of time, it also means that if you apply a kill file
9127 to a group, and then change the kill file and want to run it over you
9128 group again to kill more articles, it won't work. You have to set this
9129 variable to @code{t} to do that. (It is @code{t} by default.)
9131 @item gnus-kill-files-directory
9132 @vindex gnus-kill-files-directory
9133 All kill and score files will be stored in this directory, which is
9134 initialized from the @code{SAVEDIR} environment variable by default.
9135 This is @file{~/News/} by default.
9137 @item gnus-score-file-suffix
9138 @vindex gnus-score-file-suffix
9139 Suffix to add to the group name to arrive at the score file name
9140 (@samp{SCORE} by default.)
9142 @item gnus-score-uncacheable-files
9143 @vindex gnus-score-uncacheable-files
9145 All score files are normally cached to avoid excessive re-loading of
9146 score files. However, if this might make you Emacs grow big and
9147 bloated, so this regexp can be used to weed out score files that are
9148 unlikely to be needed again. It would be a bad idea to deny caching of
9149 @file{all.SCORE}, while it might be a good idea to not cache
9150 @file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
9151 variable is @samp{ADAPT$} by default, so no adaptive score files will
9154 @item gnus-save-score
9155 @vindex gnus-save-score
9156 If you have really complicated score files, and do lots of batch
9157 scoring, then you might set this variable to @code{t}. This will make
9158 Gnus save the scores into the @file{.newsrc.eld} file.
9160 @item gnus-score-interactive-default-score
9161 @vindex gnus-score-interactive-default-score
9162 Score used by all the interactive raise/lower commands to raise/lower
9163 score with. Default is 1000, which may seem excessive, but this is to
9164 ensure that the adaptive scoring scheme gets enough room to play with.
9165 We don't want the small changes from the adaptive scoring to overwrite
9166 manually entered data.
9168 @item gnus-summary-default-score
9169 @vindex gnus-summary-default-score
9170 Default score of an article, which is 0 by default.
9172 @item gnus-score-over-mark
9173 @vindex gnus-score-over-mark
9174 Mark (in the third column) used for articles with a score over the
9175 default. Default is @samp{+}.
9177 @item gnus-score-below-mark
9178 @vindex gnus-score-below-mark
9179 Mark (in the third column) used for articles with a score below the
9180 default. Default is @samp{-}.
9182 @item gnus-score-find-score-files-function
9183 @vindex gnus-score-find-score-files-function
9184 Function used to find score files for the current group. This function
9185 is called with the name of the group as the argument.
9187 Predefined functions available are:
9190 @item gnus-score-find-single
9191 @findex gnus-score-find-single
9192 Only apply the group's own score file.
9194 @item gnus-score-find-bnews
9195 @findex gnus-score-find-bnews
9196 Apply all score files that match, using bnews syntax. This is the
9197 default. For instance, if the current group is @samp{gnu.emacs.gnus},
9198 @file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and
9199 @file{gnu.all.SCORE} would all apply. In short, the instances of
9200 @samp{all} in the score file names are translated into @samp{.*}, and
9201 then a regexp match is done.
9203 This means that if you have some score entries that you want to apply to
9204 all groups, then you put those entries in the @file{all.SCORE} file.
9206 @item gnus-score-find-hierarchical
9207 @findex gnus-score-find-hierarchical
9208 Apply all score files from all the parent groups. This means that you
9209 can't have score files like @file{all.SCORE} or @file{all.emacs.SCORE},
9210 but you can have @file{SCORE}, @file{comp.SCORE} and
9211 @file{comp.emacs.SCORE}.
9214 This variable can also be a list of functions. In that case, all these
9215 functions will be called, and all the returned lists of score files will
9216 be applied. These functions can also return lists of score alists
9217 directly. In that case, the functions that return these non-file score
9218 alists should probably be placed before the ``real'' score file
9219 functions, to ensure that the last score file returned is the local
9222 @item gnus-score-expiry-days
9223 @vindex gnus-score-expiry-days
9224 This variable says how many days should pass before an unused score file
9225 entry is expired. If this variable is @code{nil}, no score file entries
9226 are expired. It's 7 by default.
9228 @item gnus-update-score-entry-dates
9229 @vindex gnus-update-score-entry-dates
9230 If this variable is non-@code{nil}, matching score entries will have
9231 their dates updated. (This is how Gnus controls expiry---all
9232 non-matching entries will become too old while matching entries will
9233 stay fresh and young.) However, if you set this variable to @code{nil},
9234 even matching entries will grow old and will have to face that oh-so
9237 @item gnus-score-after-write-file-function
9238 @vindex gnus-score-after-write-file-function
9239 Function called with the name of the score file just written.
9244 @node Score File Format
9245 @section Score File Format
9246 @cindex score file format
9248 A score file is an @code{emacs-lisp} file that normally contains just a
9249 single form. Casual users are not expected to edit these files;
9250 everything can be changed from the summary buffer.
9252 Anyway, if you'd like to dig into it yourself, here's an example:
9256 ("Lars Ingebrigtsen" -10000)
9258 ("larsi\\|lmi" -50000 nil R))
9260 ("Ding is Badd" nil 728373))
9262 ("alt.politics" -1000 728372 s))
9267 (mark-and-expunge -10)
9271 (files "/hom/larsi/News/gnu.SCORE")
9272 (exclude-files "all.SCORE")
9273 (local (gnus-newsgroup-auto-expire t)
9274 (gnus-summary-make-false-root 'empty))
9278 This example demonstrates absolutely everything about a score file.
9280 Even though this looks much like lisp code, nothing here is actually
9281 @code{eval}ed. The lisp reader is used to read this form, though, so it
9282 has to be legal syntactically, if not semantically.
9284 Six keys are supported by this alist:
9289 If the key is a string, it is the name of the header to perform the
9290 match on. Scoring can only be performed on these eight headers:
9291 @code{From}, @code{Subject}, @code{References}, @code{Message-ID},
9292 @code{Xref}, @code{Lines}, @code{Chars} and @code{Date}. In addition to
9293 these headers, there are three strings to tell Gnus to fetch the entire
9294 article and do the match on larger parts of the article: @code{Body}
9295 will perform the match on the body of the article, @code{Head} will
9296 perform the match on the head of the article, and @code{All} will
9297 perform the match on the entire article. Note that using any of these
9298 last three keys will slow down group entry @emph{considerably}. The
9299 final ``header'' you can score on is @code{Followup}. These score
9300 entries will result in new score entries being added for all follow-ups
9301 to articles that matches these score entries.
9303 Following this key is a arbitrary number of score entries, where each
9304 score entry has one to four elements.
9308 The first element is the @dfn{match element}. On most headers this will
9309 be a string, but on the Lines and Chars headers, this must be an
9313 If the second element is present, it should be a number---the @dfn{score
9314 element}. This number should be an integer in the neginf to posinf
9315 interval. This number is added to the score of the article if the match
9316 is successful. If this element is not present, the
9317 @code{gnus-score-interactive-default-score} number will be used
9318 instead. This is 1000 by default.
9321 If the third element is present, it should be a number---the @dfn{date
9322 element}. This date says when the last time this score entry matched,
9323 which provides a mechanism for expiring the score entries. It this
9324 element is not present, the score entry is permanent. The date is
9325 represented by the number of days since December 31, 1 ce.
9328 If the fourth element is present, it should be a symbol---the @dfn{type
9329 element}. This element specifies what function should be used to see
9330 whether this score entry matches the article. What match types that can
9331 be used depends on what header you wish to perform the match on.
9334 @item From, Subject, References, Xref, Message-ID
9335 For most header types, there are the @code{r} and @code{R} (regexp) as
9336 well as @code{s} and @code{S} (substring) types and @code{e} and
9337 @code{E} (exact match) types. If this element is not present, Gnus will
9338 assume that substring matching should be used. @code{R} and @code{S}
9339 differ from the other two in that the matches will be done in a
9340 case-sensitive manner. All these one-letter types are really just
9341 abbreviations for the @code{regexp}, @code{string} and @code{exact}
9342 types, which you can use instead, if you feel like.
9345 These two headers use different match types: @code{<}, @code{>},
9346 @code{=}, @code{>=} and @code{<=}.
9349 For the Date header we have three match types: @code{before}, @code{at}
9350 and @code{after}. I can't really imagine this ever being useful, but,
9351 like, it would feel kinda silly not to provide this function. Just in
9352 case. You never know. Better safe than sorry. Once burnt, twice shy.
9353 Don't judge a book by its cover. Never not have sex on a first date.
9355 @item Head, Body, All
9356 These three match keys use the same match types as the @code{From} (etc)
9360 This match key will add a score entry on all articles that followup to
9361 some author. Uses the same match types as the @code{From} header uses.
9364 This match key will add a score entry on all articles that are part of
9365 a thread. Uses the same match types as the @code{References} header
9371 The value of this entry should be a number. Any articles with a score
9372 lower than this number will be marked as read.
9375 The value of this entry should be a number. Any articles with a score
9376 lower than this number will be removed from the summary buffer.
9378 @item mark-and-expunge
9379 The value of this entry should be a number. Any articles with a score
9380 lower than this number will be marked as read and removed from the
9383 @item thread-mark-and-expunge
9384 The value of this entry should be a number. All articles that belong to
9385 a thread that has a total score below this number will be marked as read
9386 and removed from the summary buffer. @code{gnus-thread-score-function}
9387 says how to compute the total score for a thread.
9390 The value of this entry should be any number of file names. These files
9391 are assumed to be score files as well, and will be loaded the same way
9395 The clue of this entry should be any number of files. This files will
9396 not be loaded, even though they would normally be so, for some reason or
9400 The value of this entry will be @code{eval}el. This element will be
9401 ignored when handling global score files.
9404 Read-only score files will not be updated or saved. Global score files
9405 should feature this atom (@pxref{Global Score Files}).
9408 The value of this entry should be a number. Articles that do not have
9409 parents will get this number added to their scores. Imagine you follow
9410 some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you
9411 will only follow a few of the threads, also want to see any new threads.
9413 You can do this with the following two score file entries:
9417 (mark-and-expunge -100)
9420 When you enter the group the first time, you will only see the new
9421 threads. You then raise the score of the threads that you find
9422 interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{C y}) the
9423 rest. Next time you enter the group, you will see new articles in the
9424 interesting threads, plus any new threads.
9426 I.e. -- the orphan score atom is for high-volume groups where there
9427 exist a few interesting threads which can't be found automatically by
9428 ordinary scoring rules.
9431 This entry controls the adaptive scoring. If it is @code{t}, the
9432 default adaptive scoring rules will be used. If it is @code{ignore}, no
9433 adaptive scoring will be performed on this group. If it is a list, this
9434 list will be used as the adaptive scoring rules. If it isn't present,
9435 or is something other than @code{t} or @code{ignore}, the default
9436 adaptive scoring rules will be used. If you want to use adaptive
9437 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
9438 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
9439 not want adaptive scoring. If you only want adaptive scoring in a few
9440 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
9441 insert @code{(adapt t)} in the score files of the groups where you want
9445 All adaptive score entries will go to the file named by this entry. It
9446 will also be applied when entering the group. This atom might be handy
9447 if you want to adapt on several groups at once, using the same adaptive
9448 file for a number of groups.
9451 @cindex local variables
9452 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
9453 Each @var{var} will be made buffer-local to the current summary buffer,
9454 and set to the value specified. This is a convenient, if somewhat
9455 strange, way of setting variables in some groups if you don't like hooks
9460 @node Score File Editing
9461 @section Score File Editing
9463 You normally enter all scoring commands from the summary buffer, but you
9464 might feel the urge to edit them by hand as well, so we've supplied you
9465 with a mode for that.
9467 It's simply a slightly customized @code{emacs-lisp} mode, with these
9468 additional commands:
9473 @kindex C-c C-c (Score)
9474 @findex gnus-score-edit-done
9475 Save the changes you have made and return to the summary buffer
9476 (@code{gnus-score-edit-done}).
9479 @kindex C-c C-d (Score)
9480 @findex gnus-score-edit-insert-date
9481 Insert the current date in numerical format
9482 (@code{gnus-score-edit-insert-date}). This is really the day number, if
9486 @kindex C-c C-p (Score)
9487 @findex gnus-score-pretty-print
9488 The adaptive score files are saved in an unformatted fashion. If you
9489 intend to read one of these files, you want to @dfn{pretty print} it
9490 first. This command (@code{gnus-score-pretty-print}) does that for
9495 Type @kbd{M-x gnus-score-mode} to use this mode.
9497 @vindex gnus-score-mode-hook
9498 @code{gnus-score-menu-hook} is run in score mode buffers.
9500 In the summary buffer you can use commands like @kbd{V f} and @kbd{V
9501 e} to begin editing score files.
9504 @node Adaptive Scoring
9505 @section Adaptive Scoring
9506 @cindex adaptive scoring
9508 If all this scoring is getting you down, Gnus has a way of making it all
9509 happen automatically---as if by magic. Or rather, as if by artificial
9510 stupidity, to be precise.
9512 @vindex gnus-use-adaptive-scoring
9513 When you read an article, or mark an article as read, or kill an
9514 article, you leave marks behind. On exit from the group, Gnus can sniff
9515 these marks and add score elements depending on what marks it finds.
9516 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
9519 @vindex gnus-default-adaptive-score-alist
9520 To give you complete control over the scoring process, you can customize
9521 the @code{gnus-default-adaptive-score-alist} variable. For instance, it
9522 might look something like this:
9525 (defvar gnus-default-adaptive-score-alist
9526 '((gnus-unread-mark)
9527 (gnus-ticked-mark (from 4))
9528 (gnus-dormant-mark (from 5))
9529 (gnus-del-mark (from -4) (subject -1))
9530 (gnus-read-mark (from 4) (subject 2))
9531 (gnus-expirable-mark (from -1) (subject -1))
9532 (gnus-killed-mark (from -1) (subject -3))
9533 (gnus-kill-file-mark)
9535 (gnus-low-score-mark)
9536 (gnus-catchup-mark (from -1) (subject -1))))
9539 As you see, each element in this alist has a mark as a key (either a
9540 variable name or a ``real'' mark---a character). Following this key is
9541 a arbitrary number of header/score pairs. If there are no header/score
9542 pairs following the key, no adaptive scoring will be done on articles
9543 that have that key as the article mark. For instance, articles with
9544 @code{gnus-unread-mark} in the example above will not get adaptive score
9547 Each article can have only one mark, so just a single of these rules
9548 will be applied to each article.
9550 To take @code{gnus-del-mark} as an example---this alist says that all
9551 articles that have that mark (i.e., are marked with @samp{D}) will have a
9552 score entry added to lower based on the @code{From} header by -4, and
9553 lowered by @code{Subject} by -1. Change this to fit your prejudices.
9555 If you have marked 10 articles with the same subject with
9556 @code{gnus-del-mark}, the rule for that mark will be applied ten times.
9557 That means that that subject will get a score of ten times -1, which
9558 should be, unless I'm much mistaken, -10.
9560 The headers you can score on are @code{from}, @code{subject},
9561 @code{message-id}, @code{references}, @code{xref}, @code{lines},
9562 @code{chars} and @code{date}. In addition, you can score on
9563 @code{followup}, which will create an adaptive score entry that matches
9564 on the @code{References} header using the @code{Message-ID} of the
9565 current article, thereby matching the following thread.
9567 You can also score on @code{thread}, which will try to score all
9568 articles that appear in a thread. @code{thread} matches uses a
9569 @code{Message-ID} to match on the @code{References} header of the
9570 article. If the match is made, the @code{Message-ID} of the article is
9571 added to the @code{thread} rule. (Think about it. I'd recommend two
9572 aspirins afterwards.)
9574 If you use this scheme, you should set the score file atom @code{mark}
9575 to something small---like -300, perhaps, to avoid having small random
9576 changes result in articles getting marked as read.
9578 After using adaptive scoring for a week or so, Gnus should start to
9579 become properly trained and enhance the authors you like best, and kill
9580 the authors you like least, without you having to say so explicitly.
9582 You can control what groups the adaptive scoring is to be performed on
9583 by using the score files (@pxref{Score File Format}). This will also
9584 let you use different rules in different groups.
9586 @vindex gnus-adaptive-file-suffix
9587 The adaptive score entries will be put into a file where the name is the
9588 group name with @code{gnus-adaptive-file-suffix} appended. The default
9591 @vindex gnus-score-exact-adapt-limit
9592 When doing adaptive scoring, substring or fuzzy matching would probably
9593 give you the best results in most cases. However, if the header one
9594 matches is short, the possibility for false positives is great, so if
9595 the length of the match is less than
9596 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
9597 this variable is @code{nil}, exact matching will always be used to avoid
9601 @node Followups To Yourself
9602 @section Followups To Yourself
9604 Gnus offers two commands for picking out the @code{Message-ID} header in
9605 the current buffer. Gnus will then add a score rule that scores using
9606 this @code{Message-ID} on the @code{References} header of other
9607 articles. This will, in effect, increase the score of all articles that
9608 respond to the article in the current buffer. Quite useful if you want
9609 to easily note when people answer what you've said.
9613 @item gnus-score-followup-article
9614 @findex gnus-score-followup-article
9615 This will add a score to articles that directly follow up your own
9618 @item gnus-score-followup-thread
9619 @findex gnus-score-followup-thread
9620 This will add a score to all articles that appear in a thread ``below''
9624 @vindex gnus-inews-article-hook
9625 These two functions are both primarily meant to be used in hooks like
9626 @code{gnus-inews-article-hook}.
9630 @section Scoring Tips
9631 @cindex scoring tips
9637 @cindex scoring crossposts
9638 If you want to lower the score of crossposts, the line to match on is
9639 the @code{Xref} header.
9641 ("xref" (" talk.politics.misc:" -1000))
9644 @item Multiple crossposts
9645 If you want to lower the score of articles that have been crossposted to
9646 more than, say, 3 groups:
9648 ("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
9651 @item Matching on the body
9652 This is generally not a very good idea---it takes a very long time.
9653 Gnus actually has to fetch each individual article from the server. But
9654 you might want to anyway, I guess. Even though there are three match
9655 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
9656 and stick with it in each score file. If you use any two, each article
9657 will be fetched @emph{twice}. If you want to match a bit on the
9658 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
9661 @item Marking as read
9662 You will probably want to mark articles that has a score below a certain
9663 number as read. This is most easily achieved by putting the following
9664 in your @file{all.SCORE} file:
9668 You may also consider doing something similar with @code{expunge}.
9670 @item Negated character classes
9671 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
9672 That will match newlines, which might lead to, well, The Unknown. Say
9673 @code{[^abcd\n]*} instead.
9677 @node Reverse Scoring
9678 @section Reverse Scoring
9679 @cindex reverse scoring
9681 If you want to keep just articles that have @samp{Sex with Emacs} in the
9682 subject header, and expunge all other articles, you could put something
9683 like this in your score file:
9687 ("Sex with Emacs" 2))
9692 So, you raise all articles that match @samp{Sex with Emacs} and mark the
9693 rest as read, and expunge them to boot.
9696 @node Global Score Files
9697 @section Global Score Files
9698 @cindex global score files
9700 Sure, other newsreaders have ``global kill files''. These are usually
9701 nothing more than a single kill file that applies to all groups, stored
9702 in the user's home directory. Bah! Puny, weak newsreaders!
9704 What I'm talking about here are Global Score Files. Score files from
9705 all over the world, from users everywhere, uniting all nations in one
9706 big, happy score file union! Ange-score! New and untested!
9708 @vindex gnus-global-score-files
9709 All you have to do to use other people's score files is to set the
9710 @code{gnus-global-score-files} variable. One entry for each score file,
9711 or each score file directory. Gnus will decide by itself what score
9712 files are applicable to which group.
9714 Say you want to use all score files in the
9715 @file{/ftp@@ftp.some-where:/pub/score} directory and the single score
9716 file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
9719 (setq gnus-global-score-files
9720 '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
9721 "/ftp@@ftp.some-where:/pub/score/"))
9724 @findex gnus-score-search-global-directories
9725 Simple, eh? Directory names must end with a @samp{/}. These
9726 directories are typically scanned only once during each Gnus session.
9727 If you feel the need to manually re-scan the remote directories, you can
9728 use the @code{gnus-score-search-global-directories} command.
9730 Note that, at present, using this option will slow down group entry
9731 somewhat. (That is---a lot.)
9733 If you want to start maintaining score files for other people to use,
9734 just put your score file up for anonymous ftp and announce it to the
9735 world. Become a retro-moderator! Participate in the retro-moderator
9736 wars sure to ensue, where retro-moderators battle it out for the
9737 sympathy of the people, luring them to use their score files on false
9738 premises! Yay! The net is saved!
9740 Here are some tips for the would-be retro-moderator, off the top of my
9746 Articles that are heavily crossposted are probably junk.
9748 To lower a single inappropriate article, lower by @code{Message-ID}.
9750 Particularly brilliant authors can be raised on a permanent basis.
9752 Authors that repeatedly post off-charter for the group can safely be
9753 lowered out of existence.
9755 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
9756 articles completely.
9759 Use expiring score entries to keep the size of the file down. You
9760 should probably have a long expiry period, though, as some sites keep
9761 old articles for a long time.
9764 ... I wonder whether other newsreaders will support global score files
9765 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
9766 Wave, xrn and 1stReader are bound to implement scoring. Should we start
9767 holding our breath yet?
9774 Gnus still supports those pesky old kill files. In fact, the kill file
9775 entries can now be expiring, which is something I wrote before Daniel
9776 Quinlan thought of doing score files, so I've left the code in there.
9778 In short, kill processing is a lot slower (and I do mean @emph{a lot})
9779 than score processing, so it might be a good idea to rewrite your kill
9780 files into score files.
9782 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
9783 forms into this file, which means that you can use kill files as some
9784 sort of primitive hook function to be run on group entry, even though
9785 that isn't a very good idea.
9787 XCNormal kill files look like this:
9790 (gnus-kill "From" "Lars Ingebrigtsen")
9791 (gnus-kill "Subject" "ding")
9795 This will mark every article written by me as read, and remove them from
9796 the summary buffer. Very useful, you'll agree.
9798 Other programs use a totally different kill file syntax. If Gnus
9799 encounters what looks like a @code{rn} kill file, it will take a stab at
9802 Two summary functions for editing a GNUS kill file:
9807 @kindex M-k (Summary)
9808 @findex gnus-summary-edit-local-kill
9809 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
9812 @kindex M-K (Summary)
9813 @findex gnus-summary-edit-global-kill
9814 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
9817 Two group mode functions for editing the kill files:
9823 @findex gnus-group-edit-local-kill
9824 Edit this group's kill file (@code{gnus-group-edit-local-kill}).
9828 @findex gnus-group-edit-global-kill
9829 Edit the general kill file (@code{gnus-group-edit-global-kill}).
9832 Kill file variables:
9835 @item gnus-kill-file-name
9836 @vindex gnus-kill-file-name
9837 A kill file for the group @samp{soc.motss} is normally called
9838 @file{soc.motss.KILL}. The suffix appended to the group name to get
9839 this file name is detailed by the @code{gnus-kill-file-name} variable.
9840 The ``global'' kill file (not in the score file sense of ``global'', of
9841 course) is called just @file{KILL}.
9843 @vindex gnus-kill-save-kill-file
9844 @item gnus-kill-save-kill-file
9845 If this variable is non-@code{nil}, Gnus will save the
9846 kill file after processing, which is necessary if you use expiring
9849 @item gnus-apply-kill-hook
9850 @vindex gnus-apply-kill-hook
9851 @findex gnus-apply-kill-file-unless-scored
9852 @findex gnus-apply-kill-file
9853 A hook called to apply kill files to a group. It is
9854 @code{(gnus-apply-kill-file)} by default. If you want to ignore the
9855 kill file if you have a score file for the same group, you can set this
9856 hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want
9857 kill files to be processed, you should set this variable to @code{nil}.
9859 @item gnus-kill-file-mode-hook
9860 @vindex gnus-kill-file-mode-hook
9861 A hook called in kill-file mode buffers.
9870 GroupLens is a collaborative filtering system that helps you work
9871 together with other people to find the quality news articles out of the
9872 huge volume of news articles generated every day.
9874 To accomplish this the GroupLens system combines your opinions about
9875 articles you have already read with the opinions of others who have done
9876 likewise and gives you a personalized prediction for each unread news
9877 article. Think of GroupLens as a matchmaker. GroupLens watches how you
9878 rate articles, and finds other people that rate articles the same way.
9879 Once it has found for you some people you agree with it tells you, in
9880 the form of a prediction, what they thought of the article. You can use
9881 this prediction to help you decide whether or not you want to read the
9885 * Using GroupLens:: How to make Gnus use GroupLens.
9886 * Rating Articles:: Letting GroupLens know how you rate articles.
9887 * Displaying Predictions:: Displaying predictions given by GroupLens.
9888 * GroupLens Variables:: Customizing GroupLens.
9892 @node Using GroupLens
9893 @subsection Using GroupLens
9895 To use GroupLens you must register a pseudonym with your local Better
9896 Bit Bureau (BBB). At the moment the only better bit in town is at
9897 @samp{http://www.cs.umn.edu/Research/GroupLens/bbb.html}.
9899 Once you have registered you'll need to set a couple of variables.
9903 @item gnus-use-grouplens
9904 @vindex gnus-use-grouplens
9905 Setting this variable to a non-@code{nil} value will make Gnus hook into
9906 all the relevant GroupLens functions.
9908 @item grouplens-pseudonym
9909 @vindex grouplens-pseudonym
9910 This variable should be set to the pseudonum you got when registering
9911 with the Better Bit Bureau.
9913 @item grouplens-newsgroups
9914 @vindex grouplens-newsgroups
9915 A list of groups that you want to get GroupLens predictions for.
9919 Thats the minimum of what you need to get up and running with GroupLens.
9920 Once you've registered, GroupLens will start giving you scores for
9921 articles based on the average of what other people think. But, to get
9922 the real benefit of GroupLens you need to start rating articles
9923 yourself. Then the scores GroupLens gives you will be personalized for
9924 you, based on how the people you usually agree with have already rated.
9927 @node Rating Articles
9928 @subsection Rating Articles
9930 In GroupLens, an article is rated on a scale from 1 to 5, inclusive.
9931 Where 1 means something like this article is a waste of bandwidth and 5
9932 means that the article was really good. The basic question to ask
9933 yourself is, "on a scale from 1 to 5 would I like to see more articles
9936 There are four ways to enter a rating for an article in GroupLens.
9941 @kindex r (GroupLens)
9942 @findex bbb-summary-rate-article
9943 This function will prompt you for a rating on a scale of one to five.
9946 @kindex k (GroupLens)
9947 @findex grouplens-score-thread
9948 This function will prompt you for a rating, and rate all the articles in
9949 the thread. This is really useful for some of those long running giant
9950 threads in rec.humor.
9954 The next two commands, @kbd{n} and @kbd{,} take a numerical prefix to be
9955 the score of the article you're reading.
9960 @kindex n (GroupLens)
9961 @findex grouplens-next-unread-article
9962 Rate the article and go to the next unread article.
9965 @kindex , (GroupLens)
9966 @findex grouplens-best-unread-article
9967 Rate the article and go to the next unread article with the highest score.
9971 If you want to give the current article a score of 4 and then go to the
9972 next article, just type @kbd{4 n}.
9975 @node Displaying Predictions
9976 @subsection Displaying Predictions
9978 GroupLens makes a prediction for you about how much you will like a
9979 news article. The predictions from GroupLens are on a scale from 1 to
9980 5, where 1 is the worst and 5 is the best. You can use the predictions
9981 from GroupLens in one of three ways controlled by the variable
9982 @code{gnus-grouplens-override-scoring}.
9984 @vindex gnus-grouplens-override-scoring
9985 There are three ways to display predictions in grouplens. You may
9986 choose to have the GroupLens scores contribute to, or override the
9987 regular gnus scoring mechanism. override is the default; however, some
9988 people prefer to see the Gnus scores plus the grouplens scores. To get
9989 the separate scoring behavior you need to set
9990 @code{gnus-grouplens-override-scoring} to @code{'separate}. To have the
9991 GroupLens predictions combined with the grouplens scores set it to
9992 @code{'override} and to combine the scores set
9993 @code{gnus-grouplens-override-scoring} to @code{'combine}. When you use
9994 the combine option you will also want to set the values for
9995 @code{grouplens-prediction-offset} and
9996 @code{grouplens-score-scale-factor}.
9998 @vindex grouplens-prediction-display
9999 In either case, GroupLens gives you a few choices for how you would like
10000 to see your predictions displayed. The display of predictions is
10001 controlled by the @code{grouplens-prediction-display} variable.
10003 The following are legal values for that variable.
10006 @item prediction-spot
10007 The higher the prediction, the further to the right an @samp{*} is
10010 @item confidence-interval
10011 A numeric confidence interval.
10013 @item prediction-bar
10014 The higher the prediction, the longer the bar.
10016 @item confidence-bar
10017 Numerical confidence.
10019 @item confidence-spot
10020 The spot gets bigger with more confidence.
10022 @item prediction-num
10023 Plain-old numeric value.
10025 @item confidence-plus-minus
10026 Prediction +/i confidence.
10031 @node GroupLens Variables
10032 @subsection GroupLens Variables
10036 @item gnus-summary-grouplens-line-format
10037 The summary line format used in summary buffers that are GroupLens
10038 enhanced. It accepts the same specs as the normal summary line format
10039 (@pxref{Summary Buffer Lines}). The default is
10040 @samp{%U%R%z%l%I%(%[%4L: %-20,20n%]%) %s\n}.
10042 @item grouplens-bbb-host
10043 Host running the bbbd server. The default is
10044 @samp{grouplens.cs.umn.edu}.
10046 @item grouplens-bbb-port
10047 Port of the host running the bbbd server. The default is 9000.
10049 @item grouplens-score-offset
10050 Offset the prediction by this value. In other words, subtract the
10051 prediction value by this number to arrive at the effective score. The
10054 @item grouplens-score-scale-factor
10055 This variable allows the user to magnify the effect of GroupLens scores.
10056 The scale factor is applied after the offset. The default is 1.
10066 * Process/Prefix:: A convention used by many treatment commands.
10067 * Interactive:: Making Gnus ask you many questions.
10068 * Formatting Variables:: You can specify what buffers should look like.
10069 * Windows Configuration:: Configuring the Gnus buffer windows.
10070 * Compilation:: How to speed Gnus up.
10071 * Mode Lines:: Displaying information in the mode lines.
10072 * Highlighting and Menus:: Making buffers look all nice and cozy.
10073 * Buttons:: Get tendonitis in ten easy steps!
10074 * Daemons:: Gnus can do things behind your back.
10075 * NoCeM:: How to avoid spam and other fatty foods.
10076 * Picons:: How to display pictures of what your reading.
10077 * Various Various:: Things that are really various.
10081 @node Process/Prefix
10082 @section Process/Prefix
10083 @cindex process/prefix convention
10085 Many functions, among them functions for moving, decoding and saving
10086 articles, use what is known as the @dfn{Process/Prefix convention}.
10088 This is a method for figuring out what articles that the user wants the
10089 command to be performed on.
10093 If the numeric prefix is N, perform the operation on the next N
10094 articles, starting with the current one. If the numeric prefix is
10095 negative, perform the operation on the previous N articles, starting
10096 with the current one.
10098 @vindex transient-mark-mode
10099 If @code{transient-mark-mode} in non-@code{nil} and the region is
10100 active, all articles in the region will be worked upon.
10102 If there is no numeric prefix, but some articles are marked with the
10103 process mark, perform the operation on the articles that are marked with
10106 If there is neither a numeric prefix nor any articles marked with the
10107 process mark, just perform the operation on the current article.
10109 Quite simple, really, but it needs to be made clear so that surprises
10112 @vindex gnus-summary-goto-unread
10113 One thing that seems to shock & horrify lots of people is that, for
10114 instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}.
10115 Since each @kbd{d} (which marks the current article as read) by default
10116 goes to the next unread article after marking, this means that @kbd{3 d}
10117 will mark the next three unread articles as read, no matter what the
10118 summary buffer looks like. Set @code{gnus-summary-goto-unread} to
10119 @code{nil} for a more straightforward action.
10123 @section Interactive
10124 @cindex interaction
10128 @item gnus-novice-user
10129 @vindex gnus-novice-user
10130 If this variable is non-@code{nil}, you are either a newcomer to the
10131 World of Usenet, or you are very cautious, which is a nice thing to be,
10132 really. You will be given questions of the type ``Are you sure you want
10133 to do this?'' before doing anything dangerous. This is @code{t} by
10136 @item gnus-expert-user
10137 @vindex gnus-expert-user
10138 If this variable is non-@code{nil}, you will never ever be asked any
10139 questions by Gnus. It will simply assume you know what you're doing, no
10140 matter how strange.
10142 @item gnus-interactive-catchup
10143 @vindex gnus-interactive-catchup
10144 Require confirmation before catching up a group if non-@code{nil}. It
10145 is @code{t} by default.
10147 @item gnus-interactive-post
10148 @vindex gnus-interactive-post
10149 If non-@code{nil}, the user will be prompted for a group name when
10150 posting an article. It is @code{t} by default.
10152 @item gnus-interactive-exit
10153 @vindex gnus-interactive-exit
10154 Require confirmation before exiting Gnus. This variable is @code{t} by
10159 @node Formatting Variables
10160 @section Formatting Variables
10161 @cindex formatting variables
10163 Throughout this manual you've probably noticed lots of variables that
10164 are called things like @code{gnus-group-line-format} and
10165 @code{gnus-summary-mode-line-format}. These control how Gnus is to
10166 output lines in the various buffers. There's quite a lot of them.
10167 Fortunately, they all use the same syntax, so there's not that much to
10170 Here's an example format spec (from the group buffer): @samp{%M%S%5y:
10171 %(%g%)\n}. We see that it is indeed extremely ugly, and that there are
10172 lots of percentages everywhere.
10174 Each @samp{%} element will be replaced by some string or other when the
10175 buffer in question is generated. @samp{%5y} means ``insert the @samp{y}
10176 spec, and pad with spaces to get a 5-character field''. Just like a
10177 normal format spec, almost.
10179 You can also say @samp{%6,4y}, which means that the field will never be
10180 more than 6 characters wide and never less than 4 characters wide.
10182 There are also specs for highlighting, and these are shared by all the
10183 format variables. Text inside the @samp{%(} and @samp{%)} specifiers
10184 will get the special @code{mouse-face} property set, which means that it
10185 will be highlighted (with @code{gnus-mouse-face}) when you put the mouse
10188 Text inside the @samp{%[} and @samp{%]} specifiers will have their
10189 normal faces set using @code{gnus-face-0}, which is @code{bold} by
10190 default. If you say @samp{%1[} instead, you'll get @code{gnus-face-1}
10191 instead, and so on. Create as many faces as you wish. The same goes
10192 for the @code{mouse-face} specs---you can say @samp{%3(hello%)} to have
10193 @samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
10195 Here's an alternative recipe for the group buffer:
10198 ;; Create three face types.
10199 (setq gnus-face-1 'bold)
10200 (setq gnus-face-3 'italic)
10202 ;; We want the article count to be in
10203 ;; a bold and green face. So we create
10204 ;; a new face called `my-green-bold'.
10205 (copy-face 'bold 'my-green-bold)
10207 (set-face-foreground 'my-green-bold "ForestGreen")
10208 (setq gnus-face-2 'my-green-bold)
10210 ;; Set the new & fancy format.
10211 (setq gnus-group-line-format
10212 "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
10215 I'm sure you'll be able to use this scheme to create totally unreadable
10216 and extremely vulgar displays. Have fun!
10218 Currently Gnus uses the following formatting variables:
10219 @code{gnus-group-line-format}, @code{gnus-summary-line-format},
10220 @code{gnus-server-line-format}, @code{gnus-topic-line-format},
10221 @code{gnus-group-mode-line-format},
10222 @code{gnus-summary-mode-line-format},
10223 @code{gnus-article-mode-line-format},
10224 @code{gnus-server-mode-line-format}.
10226 Note that the @samp{%(} specs (and friends) do not make any sense on the
10227 mode-line variables.
10229 All these format variables can also be arbitrary elisp forms. In that
10230 case, they will be @code{eval}ed to insert the required lines.
10232 @kindex M-x gnus-update-format
10233 @findex gnus-update-format
10234 Gnus includes a command to help you while creating your own format
10235 specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
10236 update the spec in question and pop you to a buffer where you can
10237 examine the resulting lisp code to be run to generate the line.
10240 @node Windows Configuration
10241 @section Windows Configuration
10242 @cindex windows configuration
10244 No, there's nothing here about X, so be quiet.
10246 @vindex gnus-use-full-window
10247 If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all
10248 other windows and occupy the entire Emacs screen by itself. It is
10249 @code{t} by default.
10251 @vindex gnus-buffer-configuration
10252 @code{gnus-buffer-configuration} describes how much space each Gnus
10253 buffer should be given. Here's an excerpt of this variable:
10256 ((group (vertical 1.0 (group 1.0 point)
10257 (if gnus-carpal (group-carpal 4))))
10258 (article (vertical 1.0 (summary 0.25 point)
10262 This is an alist. The @dfn{key} is a symbol that names some action or
10263 other. For instance, when displaying the group buffer, the window
10264 configuration function will use @code{group} as the key. A full list of
10265 possible names is listed below.
10267 The @dfn{value} (i. e., the @dfn{split}) says how much space each buffer
10268 should occupy. To take the @code{article} split as an example -
10271 (article (vertical 1.0 (summary 0.25 point)
10275 This @dfn{split} says that the summary buffer should occupy 25% of upper
10276 half of the screen, and that it is placed over the article buffer. As
10277 you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all
10278 reaching for that calculator there). However, the special number
10279 @code{1.0} is used to signal that this buffer should soak up all the
10280 rest of the space available after the rest of the buffers have taken
10281 whatever they need. There should be only one buffer with the @code{1.0}
10282 size spec per split.
10284 Point will be put in the buffer that has the optional third element
10287 Here's a more complicated example:
10290 (article (vertical 1.0 (group 4)
10291 (summary 0.25 point)
10292 (if gnus-carpal (summary-carpal 4))
10296 If the size spec is an integer instead of a floating point number,
10297 then that number will be used to say how many lines a buffer should
10298 occupy, not a percentage.
10300 If the @dfn{split} looks like something that can be @code{eval}ed (to be
10301 precise---if the @code{car} of the split is a function or a subr), this
10302 split will be @code{eval}ed. If the result is non-@code{nil}, it will
10303 be used as a split. This means that there will be three buffers if
10304 @code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal}
10307 Not complicated enough for you? Well, try this on for size:
10310 (article (horizontal 1.0
10315 (summary 0.25 point)
10320 Whoops. Two buffers with the mystery 100% tag. And what's that
10321 @code{horizontal} thingie?
10323 If the first element in one of the split is @code{horizontal}, Gnus will
10324 split the window horizontally, giving you two windows side-by-side.
10325 Inside each of these strips you may carry on all you like in the normal
10326 fashion. The number following @code{horizontal} says what percentage of
10327 the screen is to be given to this strip.
10329 For each split, there @emph{must} be one element that has the 100% tag.
10330 The splitting is never accurate, and this buffer will eat any leftover
10331 lines from the splits.
10333 To be slightly more formal, here's a definition of what a legal split
10337 split = frame | horizontal | vertical | buffer | form
10338 frame = "(frame " size *split ")"
10339 horizontal = "(horizontal " size *split ")"
10340 vertical = "(vertical " size *split ")"
10341 buffer = "(" buffer-name " " size *[ "point" ] ")"
10342 size = number | frame-params
10343 buffer-name = group | article | summary ...
10346 The limitations are that the @code{frame} split can only appear as the
10347 top-level split. @var{form} should be an Emacs Lisp form that should
10348 return a valid split. We see that each split is fully recursive, and
10349 may contain any number of @code{vertical} and @code{horizontal} splits.
10351 @vindex gnus-window-min-width
10352 @vindex gnus-window-min-height
10353 @cindex window height
10354 @cindex window width
10355 Finding the right sizes can be a bit complicated. No window may be less
10356 than @code{gnus-window-min-height} (default 2) characters high, and all
10357 windows must be at least @code{gnus-window-min-width} (default 1)
10358 characters wide. Gnus will try to enforce this before applying the
10359 splits. If you want to use the normal Emacs window width/height limit,
10360 you can just set these two variables to @code{nil}.
10362 If you're not familiar with Emacs terminology, @code{horizontal} and
10363 @code{vertical} splits may work the opposite way of what you'd expect.
10364 Windows inside a @code{horizontal} split are shown side-by-side, and
10365 windows within a @code{vertical} split are shown above each other.
10367 @findex gnus-configure-frame
10368 If you want to experiment with window placement, a good tip is to call
10369 @code{gnus-configure-frame} directly with a split. This is the function
10370 that does all the real work when splitting buffers. Below is a pretty
10371 nonsensical configuration with 5 windows; two for the group buffer and
10372 three for the article buffer. (I said it was nonsensical.) If you
10373 @code{eval} the statement below, you can get an idea of how that would
10374 look straight away, without going through the normal Gnus channels.
10375 Play with it until you're satisfied, and then use
10376 @code{gnus-add-configuration} to add your new creation to the buffer
10377 configuration list.
10380 (gnus-configure-frame
10384 (article 0.3 point))
10392 You might want to have several frames as well. No prob---just use the
10393 @code{frame} split:
10396 (gnus-configure-frame
10399 (summary 0.25 point)
10401 (vertical ((height . 5) (width . 15)
10402 (user-position . t)
10403 (left . -1) (top . 1))
10408 This split will result in the familiar summary/article window
10409 configuration in the first (or ``main'') frame, while a small additional
10410 frame will be created where picons will be shown. As you can see,
10411 instead of the normal @code{1.0} top-level spec, each additional split
10412 should have a frame parameter alist as the size spec.
10413 @xref{(elisp)Frame Parameters}.
10415 Here's a list of all possible keys for
10416 @code{gnus-buffer-configuration}:
10418 @code{group}, @code{summary}, @code{article}, @code{server},
10419 @code{browse}, @code{group-mail}, @code{summary-mail},
10420 @code{summary-reply}, @code{info}, @code{summary-faq},
10421 @code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
10422 @code{followup}, @code{followup-yank}, @code{edit-score}.
10424 @findex gnus-add-configuration
10425 Since the @code{gnus-buffer-configuration} variable is so long and
10426 complicated, there's a function you can use to ease changing the config
10427 of a single setting: @code{gnus-add-configuration}. If, for instance,
10428 you want to change the @code{article} setting, you could say:
10431 (gnus-add-configuration
10432 '(article (vertical 1.0
10434 (summary .25 point)
10438 You'd typically stick these @code{gnus-add-configuration} calls in your
10439 @file{.gnus} file or in some startup hook -- they should be run after
10440 Gnus has been loaded.
10444 @section Compilation
10445 @cindex compilation
10446 @cindex byte-compilation
10448 @findex gnus-compile
10450 Remember all those line format specification variables?
10451 @code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
10452 on. Now, Gnus will of course heed whatever these variables are, but,
10453 unfortunately, changing them will mean a quite significant slow-down.
10454 (The default values of these variables have byte-compiled functions
10455 associated with them, while the user-generated versions do not, of
10458 To help with this, you can run @kbd{M-x gnus-compile} after you've
10459 fiddled around with the variables and feel that you're (kind of)
10460 satisfied. This will result in the new specs being byte-compiled, and
10461 you'll get top speed again.
10465 @section Mode Lines
10468 @vindex gnus-updated-mode-lines
10469 @code{gnus-updated-mode-lines} says what buffers should keep their mode
10470 lines updated. It is a list of symbols. Supported symbols include
10471 @code{group}, @code{article}, @code{summary}, @code{server},
10472 @code{browse}, and @code{tree}. If the corresponding symbol is present,
10473 Gnus will keep that mode line updated with information that may be
10474 pertinent. If this variable is @code{nil}, screen refresh may be
10477 @cindex display-time
10479 @vindex gnus-mode-non-string-length
10480 By default, Gnus displays information on the current article in the mode
10481 lines of the summary and article buffers. The information Gnus wishes
10482 to display (eg. the subject of the article) is often longer than the
10483 mode lines, and therefore have to be cut off at some point. The
10484 @code{gnus-mode-non-string-length} variable says how long the other
10485 elements on the line is (i.e., the non-info part). If you put
10486 additional elements on the mode line (eg. a clock), you should modify
10489 @c Hook written by Francesco Potorti` <pot@cnuce.cnr.it>
10491 (add-hook 'display-time-hook
10492 (lambda () (setq gnus-mode-non-string-length
10494 (if line-number-mode 5 0)
10495 (if column-number-mode 4 0)
10496 (length display-time-string)))))
10499 If this variable is @code{nil} (which is the default), the mode line
10500 strings won't be chopped off, and they won't be padded either.
10503 @node Highlighting and Menus
10504 @section Highlighting and Menus
10506 @cindex highlighting
10509 @vindex gnus-visual
10510 The @code{gnus-visual} variable controls most of the prettifying Gnus
10511 aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy
10512 colors or fonts. This will also inhibit loading the @file{gnus-vis.el}
10515 This variable can be a list of visual properties that are enabled. The
10516 following elements are legal, and are all included by default:
10519 @item group-highlight
10520 Do highlights in the group buffer.
10521 @item summary-highlight
10522 Do highlights in the summary buffer.
10523 @item article-highlight
10524 Do highlights in the article buffer.
10526 Turn on highlighting in all buffers.
10528 Create menus in the group buffer.
10530 Create menus in the summary buffers.
10532 Create menus in the article buffer.
10534 Create menus in the browse buffer.
10536 Create menus in the server buffer.
10538 Create menus in the score buffers.
10540 Create menus in all buffers.
10543 So if you only want highlighting in the article buffer and menus in all
10544 buffers, you could say something like:
10547 (setq gnus-visual '(article-highlight menu))
10550 If you want only highlighting and no menus whatsoever, you'd say:
10553 (setq gnus-visual '(highlight))
10556 If @code{gnus-visual} is @code{t}, highlighting and menus will be used
10557 in all Gnus buffers.
10559 Other general variables that influence the look of all buffers include:
10562 @item gnus-mouse-face
10563 @vindex gnus-mouse-face
10564 This is the face (i.e., font) used for mouse highlighting in Gnus. No
10565 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
10567 @item gnus-display-type
10568 @vindex gnus-display-type
10569 This variable is symbol indicating the display type Emacs is running
10570 under. The symbol should be one of @code{color}, @code{grayscale} or
10571 @code{mono}. If Gnus guesses this display attribute wrongly, either set
10572 this variable in your @file{~/.emacs} or set the resource
10573 @code{Emacs.displayType} in your @file{~/.Xdefaults}.
10575 @item gnus-background-mode
10576 @vindex gnus-background-mode
10577 This is a symbol indicating the Emacs background brightness. The symbol
10578 should be one of @code{light} or @code{dark}. If Gnus guesses this
10579 frame attribute wrongly, either set this variable in your @file{~/.emacs} or
10580 set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
10581 `gnus-display-type'.
10584 There are hooks associated with the creation of all the different menus:
10588 @item gnus-article-menu-hook
10589 @vindex gnus-article-menu-hook
10590 Hook called after creating the article mode menu.
10592 @item gnus-group-menu-hook
10593 @vindex gnus-group-menu-hook
10594 Hook called after creating the group mode menu.
10596 @item gnus-summary-menu-hook
10597 @vindex gnus-summary-menu-hook
10598 Hook called after creating the summary mode menu.
10600 @item gnus-server-menu-hook
10601 @vindex gnus-server-menu-hook
10602 Hook called after creating the server mode menu.
10604 @item gnus-browse-menu-hook
10605 @vindex gnus-browse-menu-hook
10606 Hook called after creating the browse mode menu.
10608 @item gnus-score-menu-hook
10609 @vindex gnus-score-menu-hook
10610 Hook called after creating the score mode menu.
10621 Those new-fangled @dfn{mouse} contraptions is very popular with the
10622 young, hep kids who don't want to learn the proper way to do things
10623 these days. Why, I remember way back in the summer of '89, when I was
10624 using Emacs on a Tops 20 system. Three hundred users on one single
10625 machine, and every user was running Simula compilers. Bah!
10629 @vindex gnus-carpal
10630 Well, you can make Gnus display bufferfuls of buttons you can click to
10631 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
10632 really. Tell the chiropractor I sent you.
10637 @item gnus-carpal-mode-hook
10638 @vindex gnus-carpal-mode-hook
10639 Hook run in all carpal mode buffers.
10641 @item gnus-carpal-button-face
10642 @vindex gnus-carpal-button-face
10643 Face used on buttons.
10645 @item gnus-carpal-header-face
10646 @vindex gnus-carpal-header-face
10647 Face used on carpal buffer headers.
10649 @item gnus-carpal-group-buffer-buttons
10650 @vindex gnus-carpal-group-buffer-buttons
10651 Buttons in the group buffer.
10653 @item gnus-carpal-summary-buffer-buttons
10654 @vindex gnus-carpal-summary-buffer-buttons
10655 Buttons in the summary buffer.
10657 @item gnus-carpal-server-buffer-buttons
10658 @vindex gnus-carpal-server-buffer-buttons
10659 Buttons in the server buffer.
10661 @item gnus-carpal-browse-buffer-buttons
10662 @vindex gnus-carpal-browse-buffer-buttons
10663 Buttons in the browse buffer.
10666 All the @code{buttons} variables are lists. The elements in these list
10667 is either a cons cell where the car contains a text to be displayed and
10668 the cdr contains a function symbol, or a simple string.
10676 Gnus, being larger than any program ever written (allegedly), does lots
10677 of strange stuff that you may wish to have done while you're not
10678 present. For instance, you may want it to check for new mail once in a
10679 while. Or you may want it to close down all connections to all servers
10680 when you leave Emacs idle. And stuff like that.
10682 Gnus will let you do stuff like that by defining various
10683 @dfn{handlers}. Each handler consists of three elements: A
10684 @var{function}, a @var{time}, and an @var{idle} parameter.
10686 Here's an example of a handler that closes connections when Emacs has
10687 been idle for thirty minutes:
10690 (gnus-demon-close-connections nil 30)
10693 Here's a handler that scans for PGP headers every hour when Emacs is
10697 (gnus-demon-scan-pgp 60 t)
10700 This @var{time} parameter and than @var{idle} parameter works together
10701 in a strange, but wonderful fashion. Basically, if @var{idle} is
10702 @code{nil}, then the function will be called every @var{time} minutes.
10704 If @var{idle} is @code{t}, then the function will be called after
10705 @var{time} minutes only if Emacs is idle. So if Emacs is never idle,
10706 the function will never be called. But once Emacs goes idle, the
10707 function will be called every @var{time} minutes.
10709 If @var{idle} is a number and @var{time} is a number, the function will
10710 be called every @var{time} minutes only when Emacs has been idle for
10711 @var{idle} minutes.
10713 If @var{idle} is a number and @var{time} is @code{nil}, the function
10714 will be called once every time Emacs has been idle for @var{idle}
10717 And if @var{time} is a string, it should look like @samp{07:31}, and
10718 the function will then be called once every day somewhere near that
10719 time. Modified by the @var{idle} parameter, of course.
10721 @vindex gnus-demon-timestep
10722 (When I say ``minute'' here, I really mean @code{gnus-demon-timestep}
10723 seconds. This is @code{60} by default. If you change that variable,
10724 all the timings in the handlers will be affected.)
10726 @vindex gnus-use-demon
10727 To set the whole thing in motion, though, you have to set
10728 @code{gnus-use-demon} to @code{t}.
10730 So, if you want to add a handler, you could put something like this in
10731 your @file{.gnus} file:
10733 @findex gnus-demon-add-handler
10735 (gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
10738 @findex gnus-demon-add-nocem
10739 @findex gnus-demon-add-scanmail
10740 @findex gnus-demon-add-disconnection
10741 Some ready-made functions to do this has been created:
10742 @code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, and
10743 @code{gnus-demon-add-scanmail}. Just put those functions in your
10744 @file{.gnus} if you want those abilities.
10746 @findex gnus-demon-init
10747 @findex gnus-demon-cancel
10748 @vindex gnus-demon-handlers
10749 If you add handlers to @code{gnus-demon-handlers} directly, you should
10750 run @code{gnus-demon-init} to make the changes take hold. To cancel all
10751 daemons, you can use the @code{gnus-demon-cancel} function.
10753 Note that adding daemons can be pretty naughty if you overdo it. Adding
10754 functions that scan all news and mail from all servers every two seconds
10755 is a sure-fire way of getting booted off any respectable system. So
10764 @dfn{Spamming} is posting the same article lots and lots of times.
10765 Spamming is bad. Spamming is evil.
10767 Spamming is usually canceled within a day or so by various anti-spamming
10768 agencies. These agencies usually also send out @dfn{NoCeM} messages.
10769 NoCeM is pronounced ``no see-'em'', and means what the name
10770 implies---these are messages that make the offending articles, like, go
10773 What use are these NoCeM messages if the articles are canceled anyway?
10774 Some sites do not honor cancel messages and some sites just honor cancels
10775 from a select few people. Then you may wish to make use of the NoCeM
10776 messages, which are distributed in the @samp{alt.nocem.misc} newsgroup.
10778 Gnus can read and parse the messages in this group automatically, and
10779 this will make spam disappear.
10781 There are some variables to customize, of course:
10784 @item gnus-use-nocem
10785 @vindex gnus-use-nocem
10786 Set this variable to @code{t} to set the ball rolling. It is @code{nil}
10789 @item gnus-nocem-groups
10790 @vindex gnus-nocem-groups
10791 Gnus will look for NoCeM messages in the groups in this list. The
10792 default is @code{("alt.nocem.misc" "news.admin.net-abuse.announce")}.
10794 @item gnus-nocem-issuers
10795 @vindex gnus-nocem-issuers
10796 There are many people issuing NoCeM messages. This list says what
10797 people you want to listen to. The default is @code{("Automoose-1"
10798 "clewis@@ferret.ocunix.on.ca;" "jem@@xpat.com;" "red@@redpoll.mrfs.oh.us
10799 (Richard E. Depew)")}; fine, upstanding citizens all of them.
10801 Known despammers that you can put in this list include:
10804 @item clewis@@ferret.ocunix.on.ca;
10805 @cindex Chris Lewis
10806 Chris Lewis---Major Canadian despammer who has probably canceled more
10807 usenet abuse than anybody else.
10810 @cindex CancelMoose[tm]
10811 The CancelMoose[tm] on autopilot. The CancelMoose[tm] is reputed to be
10812 Norwegian, and was the person(s) who invented NoCeM.
10814 @item jem@@xpat.com;
10816 Jem---Korean despammer who is getting very busy these days.
10818 @item red@@redpoll.mrfs.oh.us (Richard E. Depew)
10819 Richard E. Depew---lone American despammer. He mostly cancels binary
10820 postings to non-binary groups and removes spews (regurgitated articles).
10823 You do not have to heed NoCeM messages from all these people---just the
10824 ones you want to listen to.
10826 @item gnus-nocem-directory
10827 @vindex gnus-nocem-directory
10828 This is where Gnus will store its NoCeM cache files. The default is
10829 @file{~/News/NoCeM/}.
10831 @item gnus-nocem-expiry-wait
10832 @vindex gnus-nocem-expiry-wait
10833 The number of days before removing old NoCeM entries from the cache.
10834 The default is 15. If you make it shorter Gnus will be faster, but you
10835 might then see old spam.
10843 So... You want to slow down your news reader even more! This is a
10844 good way to do so. Its also a great way to impress people staring
10845 over your shoulder as you read news.
10848 * Picon Basics:: What are picons and How do I get them.
10849 * Picon Requirements:: Don't go further if you aren't using XEmacs.
10850 * Easy Picons:: Displaying Picons -- the easy way.
10851 * Hard Picons:: The way you should do it. You'll learn something.
10852 * Picon Configuration:: Other variables you can trash/tweak/munge/play with.
10857 @subsection Picon Basics
10859 What are Picons? To quote directly from the Picons Web site
10860 (@samp{http://www.cs.indiana.edu/picons/ftp/index.html}):
10863 @dfn{Picons} is short for ``personal icons''. They're small,
10864 constrained images used to represent users and domains on the net,
10865 organized into databases so that the appropriate image for a given
10866 e-mail address can be found. Besides users and domains, there are picon
10867 databases for Usenet newsgroups and weather forecasts. The picons are
10868 in either monochrome @code{XBM} format or color @code{XPM} and
10869 @code{GIF} formats.
10872 Please see the above mentioned web site for instructions on obtaining
10873 and installing the picons databases, or the following ftp site:
10874 @samp{http://www.cs.indiana.edu/picons/ftp/index.html}.
10876 @vindex gnus-picons-database
10877 Gnus expects picons to be installed into a location pointed to by
10878 @code{gnus-picons-database}.
10881 @node Picon Requirements
10882 @subsection Picon Requirements
10884 To use have Gnus display Picons for you, you must be running XEmacs
10885 19.13 or greater since all other versions of Emacs aren't yet able to
10888 Additionally, you must have @code{xpm} support compiled into XEmacs.
10890 @vindex gnus-picons-convert-x-face
10891 If you want to display faces from @code{X-Face} headers, you must have
10892 the @code{netpbm} utilities installed, or munge the
10893 @code{gnus-picons-convert-x-face} variable to use something else.
10897 @subsection Easy Picons
10899 To enable displaying picons, simply put the following line in your
10900 @file{~/.gnus} file and start Gnus.
10903 (setq gnus-use-picons t)
10904 (add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
10905 (add-hook 'gnus-summary-prepare-hook 'gnus-group-display-picons t)
10906 (add-hook 'gnus-article-display-hook 'gnus-picons-article-display-x-face)
10911 @subsection Hard Picons
10913 Gnus can display picons for you as you enter and leave groups and
10914 articles. It knows how to interact with three sections of the picons
10915 database. Namely, it can display the picons newsgroup pictures,
10916 author's face picture(s), and the authors domain. To enable this
10917 feature, you need to first decide where to display them.
10921 @item gnus-picons-display-where
10922 @vindex gnus-picons-display-where
10923 Where the picon images should be displayed. It is @code{picons} by
10924 default (which by default maps to the buffer @samp{*Picons*}). Other
10925 valid places could be @code{article}, @code{summary}, or
10926 @samp{"*scratch*"} for all I care. Just make sure that you've made the
10927 buffer visible using the standard Gnus window configuration routines --
10928 @xref{Windows Configuration}.
10932 Note: If you set @code{gnus-use-picons} to @code{t}, it will set up your
10933 window configuration for you to include the @code{picons} buffer.
10935 Now that you've made that decision, you need to add the following
10936 functions to the appropriate hooks so these pictures will get
10937 displayed at the right time.
10939 @vindex gnus-article-display-hook
10940 @vindex gnus-picons-display-where
10942 @item gnus-article-display-picons
10943 @findex gnus-article-display-picons
10944 Looks up and display the picons for the author and the author's domain
10945 in the @code{gnus-picons-display-where} buffer. Should be added to
10946 the @code{gnus-article-display-hook}.
10948 @item gnus-group-display-picons
10949 @findex gnus-article-display-picons
10950 Displays picons representing the current group. This function should
10951 be added to the @code{gnus-summary-prepare-hook} or to the
10952 @code{gnus-article-display-hook} if @code{gnus-picons-display-where}
10953 is set to @code{article}.
10955 @item gnus-picons-article-display-x-face
10956 @findex gnus-article-display-picons
10957 Decodes and displays the X-Face header if present. This function
10958 should be added to @code{gnus-article-display-hook}.
10962 Note: You must append them to the hook, so make sure to specify 't'
10963 to the append flag of @code{add-hook}:
10966 (add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
10970 @node Picon Configuration
10971 @subsection Picon Configuration
10973 The following variables offer further control over how things are
10974 done, where things are located, and other useless stuff you really
10975 don't need to worry about.
10978 @item gnus-picons-database
10979 @vindex gnus-picons-database
10980 The location of the picons database. Should point to a directory
10981 containing the @file{news}, @file{domains}, @file{users} (and so on)
10982 subdirectories. Defaults to @file{/usr/local/faces}.
10984 @item gnus-picons-news-directory
10985 @vindex gnus-picons-news-directory
10986 Sub-directory of the faces database containing the icons for
10989 @item gnus-picons-user-directories
10990 @vindex gnus-picons-user-directories
10991 List of subdirectories to search in @code{gnus-picons-database} for user
10992 faces. Defaults to @code{("local" "users" "usenix" "misc/MISC")}.
10994 @item gnus-picons-domain-directories
10995 @vindex gnus-picons-domain-directories
10996 List of subdirectories to search in @code{gnus-picons-database} for
10997 domain name faces. Defaults to @code{("domains")}. Some people may
10998 want to add @samp{unknown} to this list.
11000 @item gnus-picons-convert-x-face
11001 @vindex gnus-picons-convert-x-face
11002 The command to use to convert the @code{X-Face} header to an X bitmap
11003 (@code{xbm}). Defaults to @code{(format "@{ echo '/* Width=48,
11004 Height=48 */'; uncompface; @} | icontopbm | pbmtoxbm > %s"
11005 gnus-picons-x-face-file-name)}
11007 @item gnus-picons-x-face-file-name
11008 @vindex gnus-picons-x-face-file-name
11009 Names a temporary file to store the @code{X-Face} bitmap in. Defaults
11010 to @code{(format "/tmp/picon-xface.%s.xbm" (user-login-name))}.
11012 @item gnus-picons-buffer
11013 @vindex gnus-picons-buffer
11014 The name of the buffer that @code{picons} points to. Defaults to
11015 @samp{*Icon Buffer*}.
11020 @node Various Various
11021 @section Various Various
11028 @vindex gnus-verbose
11029 This variable is an integer between zero and ten. The higher the value,
11030 the more messages will be displayed. If this variable is zero, Gnus
11031 will never flash any messages, if it is seven (which is the default),
11032 most important messages will be shown, and if it is ten, Gnus won't ever
11033 shut up, but will flash so many messages it will make your head swim.
11035 @item gnus-verbose-backends
11036 @vindex gnus-verbose-backends
11037 This variable works the same way as @code{gnus-verbose}, but it applies
11038 to the Gnus backends instead of Gnus proper.
11040 @item nnheader-max-head-length
11041 @vindex nnheader-max-head-length
11042 When the backends read straight heads of articles, they all try to read
11043 as little as possible. This variable (default @code{4096}) specifies
11044 the absolute max length the backends will try to read before giving up
11045 on finding a separator line between the head and the body. If this
11046 variable is @code{nil}, there is no upper read bound. If it is
11047 @code{t}, the backends won't try to read the articles piece by piece,
11048 but read the entire articles. This makes sense with some versions of
11051 @item nnheader-file-name-translation-alist
11052 @vindex nnheader-file-name-translation-alist
11054 @cindex illegal characters in file names
11055 @cindex characters in file names
11056 This is an alist that says how to translate characters in file names.
11057 For instance, if @samp{:} is illegal as a file character in file names
11058 on your system (you OS/2 user you), you could say something like:
11061 (setq nnheader-file-name-translation-alist
11065 In fact, this is the default value for this variable on OS/2 and MS
11066 Windows (phooey) systems.
11068 @item gnus-hidden-properties
11069 @vindex gnus-hidden-properties
11070 This is a list of properties to use to hide ``invisible'' text. It is
11071 @code{(invisible t intangible t)} by default on most systems, which
11072 makes invisible text invisible and intangible.
11074 @item gnus-parse-header-hook
11075 @vindex gnus-parse-header-hook
11076 A hook called before parsing headers. It can be used, for instance, to
11077 gather statistics on the headers fetched, or perhaps you'd like to prune
11078 some headers. I don't see why you'd want that, though.
11086 Well, that's the manual---you can get on with your life now. Keep in
11087 touch. Say hello to your cats from me.
11089 My @strong{ghod}---I just can't stand goodbyes. Sniffle.
11091 Ol' Charles Reznikoff said it pretty well, so I leave the floor to him:
11096 Not because of victories @*
11099 but for the common sunshine,@*
11101 the largess of the spring.
11104 but for the day's work done@*
11105 as well as I was able;@*
11106 not for a seat upon the dais@*
11107 but at the common table.@*
11112 @chapter Appendices
11115 * History:: How Gnus got where it is today.
11116 * Terminology:: We use really difficult, like, words here.
11117 * Customization:: Tailoring Gnus to your needs.
11118 * Troubleshooting:: What you might try if things do not work.
11119 * A Programmers Guide to Gnus:: Rilly, rilly technical stuff.
11120 * Emacs for Heathens:: A short introduction to Emacsian terms.
11121 * Frequently Asked Questions:: A question-and-answer session.
11129 @sc{gnus} was written by Masanobu @sc{Umeda}. When autumn crept up in
11130 '94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
11132 If you want to investigate the person responsible for this outrage, you
11133 can point your (feh!) web browser to
11134 @file{http://www.ifi.uio.no/~larsi/}. This is also the primary
11135 distribution point for the new and spiffy versions of Gnus, and is known
11136 as The Site That Destroys Newsrcs And Drives People Mad.
11138 During the first extended alpha period of development, the new Gnus was
11139 called ``(ding) Gnus''. @dfn{(ding)}, is, of course, short for
11140 @dfn{ding is not Gnus}, which is a total and utter lie, but who cares?
11141 (Besides, the ``Gnus'' in this abbreviation should probably be
11142 pronounced ``news'' as @sc{Umeda} intended, which makes it a more
11143 appropriate name, don't you think?)
11145 In any case, after spending all that energy on coming up with a new and
11146 spunky name, we decided that the name was @emph{too} spunky, so we
11147 renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs.
11148 ``@sc{gnus}''. New vs. old.
11150 The first ``proper'' release of Gnus 5 was done in November 1995 when it
11151 was included in the Emacs 19.30 distribution.
11153 Incidentally, the next Gnus generation will be called ``September
11154 Gnus'', and won't be released until April 1996. Confused? You will be.
11157 * Why?:: What's the point of Gnus?
11158 * Compatibility:: Just how compatible is Gnus with @sc{gnus}?
11159 * Conformity:: Gnus tries to conform to all standards.
11160 * Emacsen:: Gnus can be run on a few modern Emacsen.
11161 * Contributors:: Oodles of people.
11162 * New Features:: Pointers to some of the new stuff in Gnus.
11163 * Newest Features:: Features so new that they haven't been written yet.
11164 * Censorship:: This manual has been censored.
11171 What's the point of Gnus?
11173 I want to provide a ``rad'', ``happening'', ``way cool'' and ``hep''
11174 newsreader, that lets you do anything you can think of. That was my
11175 original motivation, but while working on Gnus, it has become clear to
11176 me that this generation of newsreaders really belong in the stone age.
11177 Newsreaders haven't developed much since the infancy of the net. If the
11178 volume continues to rise with the current rate of increase, all current
11179 newsreaders will be pretty much useless. How do you deal with
11180 newsgroups that have thousands of new articles each day? How do you
11181 keep track of millions of people who post?
11183 Gnus offers no real solutions to these questions, but I would very much
11184 like to see Gnus being used as a testing ground for new methods of
11185 reading and fetching news. Expanding on @sc{Umeda}-san's wise decision
11186 to separate the newsreader from the backends, Gnus now offers a simple
11187 interface for anybody who wants to write new backends for fetching mail
11188 and news from different sources. I have added hooks for customizations
11189 everywhere I could imagine useful. By doing so, I'm inviting every one
11190 of you to explore and invent.
11192 May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
11195 @node Compatibility
11196 @subsection Compatibility
11198 @cindex compatibility
11199 Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
11200 bindings have been kept. More key bindings have been added, of course,
11201 but only in one or two obscure cases have old bindings been changed.
11206 @center In a cloud bones of steel.
11210 All commands have kept their names. Some internal functions have changed
11213 The @code{gnus-uu} package has changed drastically. @pxref{Decoding
11216 One major compatibility question is the presence of several summary
11217 buffers. All variables that are relevant while reading a group are
11218 buffer-local to the summary buffer they belong in. Although many
11219 important variables have their values copied into their global
11220 counterparts whenever a command is executed in the summary buffer, this
11221 change might lead to incorrect values being used unless you are careful.
11223 All code that relies on knowledge of @sc{gnus} internals will probably
11224 fail. To take two examples: Sorting @code{gnus-newsrc-alist} (or
11225 changing it in any way, as a matter of fact) is strictly verboten. Gnus
11226 maintains a hash table that points to the entries in this alist (which
11227 speeds up many functions), and changing the alist directly will lead to
11231 @cindex highlighting
11232 Old hilit19 code does not work at all. In fact, you should probably
11233 remove all hilit code from all Gnus hooks
11234 (@code{gnus-group-prepare-hook} and @code{gnus-summary-prepare-hook}).
11235 Gnus provides various integrated functions for highlighting. These are
11236 faster and more accurate. To make life easier for everybody, Gnus will
11237 by default remove all hilit calls from all hilit hooks. Uncleanliness!
11240 Packages like @code{expire-kill} will no longer work. As a matter of
11241 fact, you should probably remove all old @sc{gnus} packages (and other
11242 code) when you start using Gnus. More likely than not, Gnus already
11243 does what you have written code to make @sc{gnus} do. (Snicker.)
11245 Even though old methods of doing things are still supported, only the
11246 new methods are documented in this manual. If you detect a new method of
11247 doing something while reading this manual, that does not mean you have
11248 to stop doing it the old way.
11250 Gnus understands all @sc{gnus} startup files.
11252 @kindex M-x gnus-bug
11254 @cindex reporting bugs
11256 Overall, a casual user who hasn't written much code that depends on
11257 @sc{gnus} internals should suffer no problems. If problems occur,
11258 please let me know by issuing that magic command @kbd{M-x gnus-bug}.
11262 @subsection Conformity
11264 No rebels without a clue here, ma'am. We conform to all standards known
11265 to (wo)man. Except for those standards and/or conventions we disagree
11272 There are no known breaches of this standard.
11276 There are no known breaches of this standard, either.
11278 @item Usenet Seal of Approval
11279 @cindex Usenet Seal of Approval
11280 Gnus hasn't been formally through the Seal process, but I have read
11281 through the Seal text and I think Gnus would pass.
11283 @item Son-of-RFC 1036
11284 @cindex Son-of-RFC 1036
11285 We do have some breaches to this one.
11290 Gnus does no MIME handling, and this standard-to-be seems to think that
11291 MIME is the bees' knees, so we have major breakage here.
11294 This is considered to be a ``vanity header'', while I consider it to be
11295 consumer information. After seeing so many badly formatted articles
11296 coming from @code{tin} and @code{Netscape} I know not to use either of
11297 those for posting articles. I would not have known that if it wasn't
11298 for the @code{X-Newsreader} header.
11301 Gnus does line breaking on this header. I infer from RFC1036 that being
11302 conservative in what you output is not creating 5000-character lines, so
11303 it seems like a good idea to me. However, this standard-to-be says that
11304 whitespace in the @code{References} header is to be preserved, so... It
11305 doesn't matter one way or the other to Gnus, so if somebody tells me
11306 what The Way is, I'll change it. Or not.
11311 If you ever notice Gnus acting non-compliantly with regards to the texts
11312 mentioned above, don't hesitate to drop a note to Gnus Towers and let us
11317 @subsection Emacsen
11323 Gnus should work on :
11328 Emacs 19.30 and up.
11331 XEmacs 19.13 and up.
11334 Mule versions based on Emacs 19.30 and up.
11338 Gnus will absolutely not work on any Emacsen older than that. Not
11339 reliably, at least.
11341 There are some vague differences between Gnus on the various platforms:
11346 The mouse-face on Gnus lines under Emacs and Mule is delimited to
11347 certain parts of the lines while they cover the entire line under
11351 The same with current-article marking---XEmacs puts an underline under
11352 the entire summary line while Emacs and Mule are nicer and kinder.
11355 XEmacs features more graphics---a logo and a toolbar.
11358 Citation highlighting us better under Emacs and Mule than under XEmacs.
11361 Emacs 19.26-19.28 have tangible hidden headers, which can be a bit
11368 @subsection Contributors
11369 @cindex contributors
11371 The new Gnus version couldn't have been done without the help of all the
11372 people on the (ding) mailing list. Every day for over a year I have
11373 gotten billions of nice bug reports from them, filling me with joy,
11374 every single one of them. Smooches. The people on the list have been
11375 tried beyond endurance, what with my ``oh, that's a neat idea <type
11376 type>, yup, I'll release it right away <ship off> no wait, that doesn't
11377 work at all <type type>, yup, I'll ship that one off right away <ship
11378 off> no, wait, that absolutely does not work'' policy for releases.
11379 Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that
11380 ``worser''? ``much worser''? ``worsest''?)
11382 I would like to take this opportunity to thank the Academy for... oops,
11387 @item Masanobu @sc{Umeda}
11388 The writer of the original @sc{gnus}.
11390 @item Per Abrahamsen
11391 Custom, scoring, highlighting and @sc{soup} code (as well as numerous
11394 @item Luis Fernandes
11395 Design and graphics.
11398 @file{gnus-picon.el} and the manual section on @dfn{picons}
11402 @file{gnus-gl.el} and the GroupLens manual section (@pxref{GroupLens}).
11404 @item Sudish Joseph
11405 Innumerable bug fixes.
11408 @file{gnus-topic.el}.
11410 @item Steven L. Baur
11411 Lots and lots of bugs detections and fixes.
11413 @item Vladimir Alexiev
11414 The refcard and reference booklets.
11416 @item Felix Lee & JWZ
11417 I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
11420 @file{nnfolder.el} enhancements & rewrite.
11422 @item Peter Mutsaers
11423 Orphan article scoring code.
11428 @item Hallvard B Furuseth
11429 Various bits and pieces, especially dealing with .newsrc files.
11431 @item Brian Edmonds
11432 @file{gnus-bbdb.el}.
11434 @item Ricardo Nassif and Mark Borges
11437 @item Kevin Davidson
11438 Came up with the name @dfn{ding}, so blame him.
11442 Peter Arius, Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel
11443 Quinlan, Frank D. Cringle, Geoffrey T. Dairiki, Fabrice Popineau and
11444 Andrew Eskilsson have all contributed code and suggestions.
11448 @subsection New Features
11449 @cindex new features
11454 The look of all buffers can be changed by setting format-like variables
11455 (@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
11458 Local spool and several @sc{nntp} servers can be used at once
11459 (@pxref{Select Methods}).
11462 You can combine groups into virtual groups (@pxref{Virtual Groups}).
11465 You can read a number of different mail formats (@pxref{Getting Mail}).
11466 All the mail backends implement a convenient mail expiry scheme
11467 (@pxref{Expiring Mail}).
11470 Gnus can use various strategies for gathering threads that have lost
11471 their roots (thereby gathering loose sub-threads into one thread) or it
11472 can go back and retrieve enough headers to build a complete thread
11473 (@pxref{Customizing Threading}).
11476 Killed groups can be displayed in the group buffer, and you can read
11477 them as well (@pxref{Listing Groups}).
11480 Gnus can do partial group updates---you do not have to retrieve the
11481 entire active file just to check for new articles in a few groups
11482 (@pxref{The Active File}).
11485 Gnus implements a sliding scale of subscribedness to groups
11486 (@pxref{Group Levels}).
11489 You can score articles according to any number of criteria
11490 (@pxref{Scoring}). You can even get Gnus to find out how to score
11491 articles for you (@pxref{Adaptive Scoring}).
11494 Gnus maintains a dribble buffer that is auto-saved the normal Emacs
11495 manner, so it should be difficult to lose much data on what you have
11496 read if your machine should go down (@pxref{Auto Save}).
11499 Gnus now has its own startup file (@file{.gnus}) to avoid cluttering up
11500 the @file{.emacs} file.
11503 You can set the process mark on both groups and articles and perform
11504 operations on all the marked items (@pxref{Process/Prefix}).
11507 You can grep through a subset of groups and create a group from the
11508 results (@pxref{Kibozed Groups}).
11511 You can list subsets of groups according to, well, anything
11512 (@pxref{Listing Groups}).
11515 You can browse foreign servers and subscribe to groups from those
11516 servers (@pxref{Browse Foreign Server}).
11519 Gnus can fetch articles asynchronously on a second connection to the
11520 server (@pxref{Asynchronous Fetching}).
11523 You can cache articles locally (@pxref{Article Caching}).
11526 The uudecode functions have been expanded and generalized
11527 (@pxref{Decoding Articles}).
11530 You can still post uuencoded articles, which was a little-known feature
11531 of @sc{gnus}' past (@pxref{Uuencoding and Posting}).
11534 Fetching parents (and other articles) now actually works without
11535 glitches (@pxref{Finding the Parent}).
11538 Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
11541 Digests (and other files) can be used as the basis for groups
11542 (@pxref{Document Groups}).
11545 Articles can be highlighted and customized (@pxref{Customizing
11549 URLs and other external references can be buttonized (@pxref{Article
11553 You can do lots of strange stuff with the Gnus window & frame
11554 configuration (@pxref{Windows Configuration}).
11557 You can click on buttons instead of using the keyboard
11561 Gnus can use NoCeM files to weed out spam (@pxref{NoCeM}).
11565 This is, of course, just a @emph{short} overview of the @emph{most}
11566 important new features. No, really. There are tons more. Yes, we have
11567 feeping creaturism in full effect, but nothing too gratuitous, I would
11571 @node Newest Features
11572 @subsection Newest Features
11575 Also known as the @dfn{todo list}. Sure to be implemented before the
11578 Be afraid. Be very afraid.
11582 Native @sc{mime} support is something that should be done.
11584 A better and simpler method for specifying mail composing methods.
11586 Allow posting through mail-to-news gateways.
11588 Really do unbinhexing.
11591 And much, much, much more. There is more to come than has already been
11592 implemented. (But that's always true, isn't it?)
11594 @code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>} is where the actual
11595 up-to-the-second todo list is located, so if you're really curious, you
11596 could point your Web browser over that-a-way.
11600 @subsection Censorship
11603 This version of the Gnus manual (as well as Gnus itself) has been
11604 censored in accord with the Communications Decency Act. This law was
11605 described by its proponents as a ban on pornography---which was a
11606 deception, since it prohibits far more than that. This manual did not
11607 contain pornography, but part of it was prohibited nonetheless.
11609 For information on US government censorship of the Internet, and
11610 what you can do to bring back freedom of the press, see the web
11611 site @samp{http://www.vtw.org/}.
11615 @section Terminology
11617 @cindex terminology
11622 This is what you are supposed to use this thing for---reading news.
11623 News is generally fetched from a nearby @sc{nntp} server, and is
11624 generally publicly available to everybody. If you post news, the entire
11625 world is likely to read just what you have written, and they'll all
11626 snigger mischievously. Behind your back.
11630 Everything that's delivered to you personally is mail. Some news/mail
11631 readers (like Gnus) blur the distinction between mail and news, but
11632 there is a difference. Mail is private. News is public. Mailing is
11633 not posting, and replying is not following up.
11637 Send a mail to the person who has written what you are reading.
11641 Post an article to the current newsgroup responding to the article you
11646 Gnus gets fed articles from a number of backends, both news and mail
11647 backends. Gnus does not handle the underlying media, so to speak---this
11648 is all done by the backends.
11652 Gnus will always use one method (and backend) as the @dfn{native}, or
11653 default, way of getting news.
11657 You can also have any number of foreign groups active at the same time.
11658 These are groups that use different backends for getting news.
11662 Secondary backends are somewhere half-way between being native and being
11663 foreign, but they mostly act like they are native.
11667 A nessage that has been posted as news.
11670 @cindex mail message
11671 A message that has been mailed.
11675 A mail message or news article
11679 The top part of a message, where administrative information (etc.) is
11684 The rest of an article. Everything that is not in the head is in the
11689 A line from the head of an article.
11693 A collection of such lines, or a collection of heads. Or even a
11694 collection of @sc{nov} lines.
11698 When Gnus enters a group, it asks the backend for the headers of all
11699 unread articles in the group. Most servers support the News OverView
11700 format, which is more compact and much faster to read and parse than the
11701 normal @sc{head} format.
11705 Each group is subscribed at some @dfn{level} or other (1-9). The ones
11706 that have a lower level are ``more'' subscribed than the groups with a
11707 higher level. In fact, groups on levels 1-5 are considered
11708 @dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
11709 are @dfn{killed}. Commands for listing groups and scanning for new
11710 articles will all use the numeric prefix as @dfn{working level}.
11712 @item killed groups
11713 @cindex killed groups
11714 No information on killed groups is stored or updated, which makes killed
11715 groups much easier to handle than subscribed groups.
11717 @item zombie groups
11718 @cindex zombie groups
11719 Just like killed groups, only slightly less dead.
11722 @cindex active file
11723 The news server has to keep track of what articles it carries, and what
11724 groups exist. All this information in stored in the active file, which
11725 is rather large, as you might surmise.
11728 @cindex bogus groups
11729 A group that exists in the @file{.newsrc} file, but isn't known to the
11730 server (i. e., it isn't in the active file), is a @emph{bogus group}.
11731 This means that the group probably doesn't exist (any more).
11735 A machine than one can connect to and get news (or mail) from.
11737 @item select method
11738 @cindex select method
11739 A structure that specifies the backend, the server and the virtual
11742 @item virtual server
11743 @cindex virtual server
11744 A named select method. Since a select methods defines all there is to
11745 know about connecting to a (physical) server, taking the who things as a
11746 whole is a virtual server.
11751 @node Customization
11752 @section Customization
11753 @cindex general customization
11755 All variables are properly documented elsewhere in this manual. This
11756 section is designed to give general pointers on how to customize Gnus
11757 for some quite common situations.
11760 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
11761 * Slow Terminal Connection:: You run a remote Emacs.
11762 * Little Disk Space:: You feel that having large setup files is icky.
11763 * Slow Machine:: You feel like buying a faster machine.
11767 @node Slow/Expensive Connection
11768 @subsection Slow/Expensive @sc{nntp} Connection
11770 If you run Emacs on a machine locally, and get your news from a machine
11771 over some very thin strings, you want to cut down on the amount of data
11772 Gnus has to get from the @sc{nntp} server.
11776 @item gnus-read-active-file
11777 Set this to @code{nil}, which will inhibit Gnus from requesting the
11778 entire active file from the server. This file is often v. large. You
11779 also have to set @code{gnus-check-new-news} and
11780 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
11781 doesn't suddenly decide to fetch the active file anyway.
11783 @item gnus-nov-is-evil
11784 This one has to be @code{nil}. If not, grabbing article headers from
11785 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
11786 support @sc{xover}; Gnus will detect this by itself.
11790 @node Slow Terminal Connection
11791 @subsection Slow Terminal Connection
11793 Let's say you use your home computer for dialing up the system that
11794 runs Emacs and Gnus. If your modem is slow, you want to reduce the
11795 amount of data that is sent over the wires as much as possible.
11799 @item gnus-auto-center-summary
11800 Set this to @code{nil} to inhibit Gnus from re-centering the summary
11801 buffer all the time. If it is @code{vertical}, do only vertical
11802 re-centering. If it is neither @code{nil} nor @code{vertical}, do both
11803 horizontal and vertical recentering.
11805 @item gnus-visible-headers
11806 Cut down on the headers that are included in the articles to the
11807 minimum. You can, in fact, make do without them altogether---most of the
11808 useful data is in the summary buffer, anyway. Set this variable to
11809 @samp{^NEVVVVER} or @samp{From:}, or whatever you feel you need.
11811 @item gnus-article-display-hook
11812 Set this hook to all the available hiding commands:
11814 (setq gnus-article-display-hook
11815 '(gnus-article-hide-headers gnus-article-hide-signature
11816 gnus-article-hide-citation))
11819 @item gnus-use-full-window
11820 By setting this to @code{nil}, you can make all the windows smaller.
11821 While this doesn't really cut down much generally, it means that you
11822 have to see smaller portions of articles before deciding that you didn't
11823 want to read them anyway.
11825 @item gnus-thread-hide-subtree
11826 If this is non-@code{nil}, all threads in the summary buffer will be
11829 @item gnus-updated-mode-lines
11830 If this is @code{nil}, Gnus will not put information in the buffer mode
11831 lines, which might save some time.
11835 @node Little Disk Space
11836 @subsection Little Disk Space
11839 The startup files can get rather large, so you may want to cut their
11840 sizes a bit if you are running out of space.
11844 @item gnus-save-newsrc-file
11845 If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
11846 only save @file{.newsrc.eld}. This means that you will not be able to
11847 use any other newsreaders than Gnus. This variable is @code{t} by
11850 @item gnus-save-killed-list
11851 If this is @code{nil}, Gnus will not save the list of dead groups. You
11852 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
11853 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
11854 variable to @code{nil}. This variable is @code{t} by default.
11860 @subsection Slow Machine
11861 @cindex slow machine
11863 If you have a slow machine, or are just really impatient, there are a
11864 few things you can do to make Gnus run faster.
11866 Set@code{gnus-check-new-newsgroups} and
11867 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
11869 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
11870 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
11871 summary buffer faster.
11873 Set @code{gnus-article-display-hook} to @code{nil} to make article
11874 processing a bit faster.
11877 @node Troubleshooting
11878 @section Troubleshooting
11879 @cindex troubleshooting
11881 Gnus works @emph{so} well straight out of the box---I can't imagine any
11889 Make sure your computer is switched on.
11892 Make sure that you really load the current Gnus version. If you have
11893 been running @sc{gnus}, you need to exit Emacs and start it up again before
11897 Try doing an @kbd{M-x gnus-version}. If you get something that looks
11898 like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
11899 on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
11900 flee}, you have some old @file{.el} files lying around. Delete these.
11903 Read the help group (@kbd{G h} in the group buffer) for a FAQ and a
11907 If all else fails, report the problem as a bug.
11910 @cindex reporting bugs
11912 @kindex M-x gnus-bug
11914 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
11915 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
11916 me the backtrace. I will fix bugs, but I can only fix them if you send
11917 me a precise description as to how to reproduce the bug.
11919 You really can never be too detailed in a bug report. Always use the
11920 @kbd{M-x gnus-bug} command when you make bug reports, even if it creates
11921 a 10Kb mail each time you use it, and even if you have sent me your
11922 environment 500 times before. I don't care. I want the full info each
11925 It is also important to remember that I have no memory whatsoever. If
11926 you send a bug report, and I send you a reply, and then you send back
11927 just ``No, it's not! Moron!'', I will have no idea what you are
11928 insulting me about. Always over-explain everything. It's much easier
11929 for all of us---if I don't have all the information I need, I will just
11930 mail you and ask for more info, and everything takes more time.
11932 If the problem you're seeing is very visual, and you can't quite explain
11933 it, copy the Emacs window to a file (with @code{xwd}, for instance), put
11934 it somewhere it can be reached, and include the URL of the picture in
11937 If you just need help, you are better off asking on
11938 @samp{gnu.emacs.gnus}. I'm not very helpful.
11940 @cindex gnu.emacs.gnus
11941 @cindex ding mailing list
11942 You can also ask on the ding mailing list---@samp{ding@@ifi.uio.no}.
11943 Write to @samp{ding-request@@ifi.uio.no} to subscribe.
11946 @node A Programmers Guide to Gnus
11947 @section A Programmer's Guide to Gnus
11949 It is my hope that other people will figure out smart stuff that Gnus
11950 can do, and that other people will write those smart things as well. To
11951 facilitate that I thought it would be a good idea to describe the inner
11952 workings of Gnus. And some of the not-so-inner workings, while I'm at
11955 You can never expect the internals of a program not to change, but I
11956 will be defining (in some details) the interface between Gnus and its
11957 backends (this is written in stone), the format of the score files
11958 (ditto), data structures (some are less likely to change than others)
11959 and general method of operations.
11962 * Backend Interface:: How Gnus communicates with the servers.
11963 * Score File Syntax:: A BNF definition of the score file standard.
11964 * Headers:: How Gnus stores headers internally.
11965 * Ranges:: A handy format for storing mucho numbers.
11966 * Group Info:: The group info format.
11967 * Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen.
11968 * Various File Formats:: Formats of files that Gnus use.
11972 @node Backend Interface
11973 @subsection Backend Interface
11975 Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
11976 groups. It only knows how to talk to @dfn{virtual servers}. A virtual
11977 server is a @dfn{backend} and some @dfn{backend variables}. As examples
11978 of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
11979 examples of the latter we have @code{nntp-port-number} and
11980 @code{nnmbox-directory}.
11982 When Gnus asks for information from a backend---say @code{nntp}---on
11983 something, it will normally include a virtual server name in the
11984 function parameters. (If not, the backend should use the ``current''
11985 virtual server.) For instance, @code{nntp-request-list} takes a virtual
11986 server as its only (optional) parameter. If this virtual server hasn't
11987 been opened, the function should fail.
11989 Note that a virtual server name has no relation to some physical server
11990 name. Take this example:
11994 (nntp-address "ifi.uio.no")
11995 (nntp-port-number 4324))
11998 Here the virtual server name is @samp{odd-one} while the name of
11999 the physical server is @samp{ifi.uio.no}.
12001 The backends should be able to switch between several virtual servers.
12002 The standard backends implement this by keeping an alist of virtual
12003 server environments that it pulls down/pushes up when needed.
12005 There are two groups of interface functions: @dfn{required functions},
12006 which must be present, and @dfn{optional functions}, which Gnus will
12007 always check whether are present before attempting to call.
12009 All these functions are expected to return data in the buffer
12010 @code{nntp-server-buffer} (@samp{ *nntpd*}), which is somewhat
12011 unfortunately named, but we'll have to live with it. When I talk about
12012 ``resulting data'', I always refer to the data in that buffer. When I
12013 talk about ``return value'', I talk about the function value returned by
12016 Some backends could be said to be @dfn{server-forming} backends, and
12017 some might be said to not be. The latter are backends that generally
12018 only operate on one group at a time, and have no concept of ``server''
12019 -- they have a group, and they deliver info on that group and nothing
12022 In the examples and definitions I will refer to the imaginary backend
12025 @cindex @code{nnchoke}
12028 * Required Backend Functions:: Functions that must be implemented.
12029 * Optional Backend Functions:: Functions that need not be implemented.
12030 * Writing New Backends:: Extending old backends.
12034 @node Required Backend Functions
12035 @subsubsection Required Backend Functions
12039 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
12041 @var{articles} is either a range of article numbers or a list of
12042 @code{Message-ID}s. Current backends do not fully support either---only
12043 sequences (lists) of article numbers, and most backends do not support
12044 retrieval of @code{Message-ID}s. But they should try for both.
12046 The result data should either be HEADs or NOV lines, and the result
12047 value should either be @code{headers} or @code{nov} to reflect this.
12048 This might later be expanded to @code{various}, which will be a mixture
12049 of HEADs and NOV lines, but this is currently not supported by Gnus.
12051 If @var{fetch-old} is non-@code{nil} it says to try to fetch "extra
12052 headers, in some meaning of the word. This is generally done by
12053 fetching (at most) @var{fetch-old} extra headers less than the smallest
12054 article number in @code{articles}, and fill in the gaps as well. The
12055 presence of this parameter can be ignored if the backend finds it
12056 cumbersome to follow the request. If this is non-@code{nil} and not a
12057 number, do maximum fetches.
12059 Here's an example HEAD:
12062 221 1056 Article retrieved.
12063 Path: ifi.uio.no!sturles
12064 From: sturles@@ifi.uio.no (Sturle Sunde)
12065 Newsgroups: ifi.discussion
12066 Subject: Re: Something very droll
12067 Date: 27 Oct 1994 14:02:57 +0100
12068 Organization: Dept. of Informatics, University of Oslo, Norway
12070 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
12071 References: <38jdmq$4qu@@visbur.ifi.uio.no>
12072 NNTP-Posting-Host: holmenkollen.ifi.uio.no
12076 So a @code{headers} return value would imply that there's a number of
12077 these in the data buffer.
12079 Here's a BNF definition of such a buffer:
12083 head = error / valid-head
12084 error-message = [ "4" / "5" ] 2number " " <error message> eol
12085 valid-head = valid-message *header "." eol
12086 valid-message = "221 " <number> " Article retrieved." eol
12087 header = <text> eol
12090 If the return value is @code{nov}, the data buffer should contain
12091 @dfn{network overview database} lines. These are basically fields
12095 nov-buffer = *nov-line
12096 nov-line = 8*9 [ field <TAB> ] eol
12097 field = <text except TAB>
12100 For a closer explanation what should be in those fields,
12104 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
12106 @var{server} is here the virtual server name. @var{definitions} is a
12107 list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
12109 If the server can't be opened, no error should be signaled. The backend
12110 may then choose to refuse further attempts at connecting to this
12111 server. In fact, it should do so.
12113 If the server is opened already, this function should return a
12114 non-@code{nil} value. There should be no data returned.
12117 @item (nnchoke-close-server &optional SERVER)
12119 Close connection to @var{server} and free all resources connected
12120 to it. Return @code{nil} if the server couldn't be closed for some
12123 There should be no data returned.
12126 @item (nnchoke-request-close)
12128 Close connection to all servers and free all resources that the backend
12129 have reserved. All buffers that have been created by that backend
12130 should be killed. (Not the @code{nntp-server-buffer}, though.) This
12131 function is generally only called when Gnus is shutting down.
12133 There should be no data returned.
12136 @item (nnchoke-server-opened &optional SERVER)
12138 If @var{server} is the current virtual server, and the connection to the
12139 physical server is alive, then this function should return a
12140 non-@code{nil} vlue. This function should under no circumstances
12141 attempt to reconnect to a server that is has lost connection to.
12143 There should be no data returned.
12146 @item (nnchoke-status-message &optional SERVER)
12148 This function should return the last error message from @var{server}.
12150 There should be no data returned.
12153 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
12155 The result data from this function should be the article specified by
12156 @var{article}. This might either be a @code{Message-ID} or a number.
12157 It is optional whether to implement retrieval by @code{Message-ID}, but
12158 it would be nice if that were possible.
12160 If @var{to-buffer} is non-@code{nil}, the result data should be returned
12161 in this buffer instead of the normal data buffer. This is to make it
12162 possible to avoid copying large amounts of data from one buffer to
12163 another, and Gnus mainly request articles to be inserted directly into
12164 its article buffer.
12166 If it is at all possible, this function should return a cons cell where
12167 the car is the group name the article was fetched from, and the cdr is
12168 the article number. This will enable Gnus to find out what the real
12169 group and article numbers are when fetching articles by
12170 @code{Message-ID}. If this isn't possible, @code{t} should be returned
12171 on successful article retrievement.
12174 @item (nnchoke-open-group GROUP &optional SERVER)
12176 Make @var{group} the current group.
12178 There should be no data returned by this function.
12181 @item (nnchoke-request-group GROUP &optional SERVER)
12183 Get data on @var{group}. This function also has the side effect of
12184 making @var{group} the current group.
12186 Here's an example of some result data and a definition of the same:
12189 211 56 1000 1059 ifi.discussion
12192 The first number is the status, which should be @code{211}. Next is the
12193 total number of articles in the group, the lowest article number, the
12194 highest article number, and finally the group name. Note that the total
12195 number of articles may be less than one might think while just
12196 considering the highest and lowest article numbers, but some articles
12197 may have been canceled. Gnus just discards the total-number, so
12198 whether one should take the bother to generate it properly (if that is a
12199 problem) is left as an exercise to the reader.
12202 group-status = [ error / info ] eol
12203 error = [ "4" / "5" ] 2<number> " " <Error message>
12204 info = "211 " 3* [ <number> " " ] <string>
12208 @item (nnchoke-close-group GROUP &optional SERVER)
12210 Close @var{group} and free any resources connected to it. This will be
12211 a no-op on most backends.
12213 There should be no data returned.
12216 @item (nnchoke-request-list &optional SERVER)
12218 Return a list of all groups available on @var{server}. And that means
12221 Here's an example from a server that only carries two groups:
12224 ifi.test 0000002200 0000002000 y
12225 ifi.discussion 3324 3300 n
12228 On each line we have a group name, then the highest article number in
12229 that group, the lowest article number, and finally a flag.
12232 active-file = *active-line
12233 active-line = name " " <number> " " <number> " " flags eol
12235 flags = "n" / "y" / "m" / "x" / "j" / "=" name
12238 The flag says whether the group is read-only (@samp{n}), is moderated
12239 (@samp{m}), is dead (@samp{x}), is aliased to some other group
12240 (@samp{=other-group} or none of the above (@samp{y}).
12243 @item (nnchoke-request-post &optional SERVER)
12245 This function should post the current buffer. It might return whether
12246 the posting was successful or not, but that's not required. If, for
12247 instance, the posting is done asynchronously, it has generally not been
12248 completed by the time this function concludes. In that case, this
12249 function should set up some kind of sentinel to beep the user loud and
12250 clear if the posting could not be completed.
12252 There should be no result data from this function.
12257 @node Optional Backend Functions
12258 @subsubsection Optional Backend Functions
12262 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
12264 @var{groups} is a list of groups, and this function should request data
12265 on all those groups. How it does it is of no concern to Gnus, but it
12266 should attempt to do this in a speedy fashion.
12268 The return value of this function can be either @code{active} or
12269 @code{group}, which says what the format of the result data is. The
12270 former is in the same format as the data from
12271 @code{nnchoke-request-list}, while the latter is a buffer full of lines
12272 in the same format as @code{nnchoke-request-group} gives.
12275 group-buffer = *active-line / *group-status
12279 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
12281 A Gnus group info (@pxref{Group Info}) is handed to the backend for
12282 alterations. This comes in handy if the backend really carries all the
12283 information (as is the case with virtual an imap groups). This function
12284 may alter the info in any manner it sees fit, and should return the
12285 (altered) group info. This function may alter the group info
12286 destructively, so no copying is needed before boogeying.
12288 There should be no result data from this function.
12291 @item (nnchoke-request-type GROUP &optional ARTICLE)
12293 When the user issues commands for ``sending news'' (@kbd{F} in the
12294 summary buffer, for instance), Gnus has to know whether the article the
12295 user is following up is news or mail. This function should return
12296 @code{news} if @var{article} in @var{group} is news, @code{mail} if it
12297 is mail and @code{unknown} if the type can't be decided. (The
12298 @var{article} parameter is necessary in @code{nnvirtual} groups which
12299 might very well combine mail groups and news groups.)
12301 There should be no result data from this function.
12304 @item (nnchoke-request-update-mark GROUP ARTICLE MARK)
12306 If the user tries to set a mark that the backend doesn't like, this
12307 function may change the mark. Gnus will use whatever this function
12308 returns as the mark for @var{article} instead of the original
12309 @var{mark}. If the backend doesn't care, it must return the original
12310 @var{mark}, and not @code{nil} or any other type of garbage.
12312 The only use for this that I can see is what @code{nnvirtual} does with
12313 it---if a component group is auto-expirable, marking an article as read
12314 in the virtual group should result in the article being marked as
12317 There should be no result data from this function.
12320 @item (nnchoke-request-scan &optional GROUP SERVER)
12322 This function may be called at any time (by Gnus or anything else) to
12323 request that the backend check for incoming articles, in one way or
12324 another. A mail backend will typically read the spool file or query the
12325 POP server when this function is invoked. The @var{group} doesn't have
12326 to be heeded---if the backend decides that it is too much work just
12327 scanning for a single group, it may do a total scan of all groups. It
12328 would be nice, however, to keep things local if that's practical.
12330 There should be no result data from this function.
12333 @item (nnchoke-request-asynchronous GROUP &optional SERVER ARTICLES)
12335 This is a request to fetch articles asynchronously later.
12336 @var{articles} is an alist of @var{(article-number line-number)}. One
12337 would generally expect that if one later fetches article number 4, for
12338 instance, some sort of asynchronous fetching of the articles after 4
12339 (which might be 5, 6, 7 or 11, 3, 909 depending on the order in that
12340 alist) would be fetched asynchronously, but that is left up to the
12341 backend. Gnus doesn't care.
12343 There should be no result data from this function.
12346 @item (nnchoke-request-group-description GROUP &optional SERVER)
12348 The result data from this function should be a description of
12352 description-line = name <TAB> description eol
12354 description = <text>
12357 @item (nnchoke-request-list-newsgroups &optional SERVER)
12359 The result data from this function should be the description of all
12360 groups available on the server.
12363 description-buffer = *description-line
12367 @item (nnchoke-request-newgroups DATE &optional SERVER)
12369 The result data from this function should be all groups that were
12370 created after @samp{date}, which is in normal human-readable date
12371 format. The data should be in the active buffer format.
12374 @item (nnchoke-request-create-group GROUP &optional SERVER)
12376 This function should create an empty group with name @var{group}.
12378 There should be no return data.
12381 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
12383 This function should run the expiry process on all articles in the
12384 @var{articles} range (which is currently a simple list of article
12385 numbers.) It is left up to the backend to decide how old articles
12386 should be before they are removed by this function. If @var{force} is
12387 non-@code{nil}, all @var{articles} should be deleted, no matter how new
12390 This function should return a list of articles that it did not/was not
12393 There should be no result data returned.
12396 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
12399 This function should move @var{article} (which is a number) from
12400 @var{group} by calling @var{accept-form}.
12402 This function should ready the article in question for moving by
12403 removing any header lines it has added to the article, and generally
12404 should ``tidy up'' the article. Then it should @code{eval}
12405 @var{accept-form} in the buffer where the ``tidy'' article is. This
12406 will do the actual copying. If this @code{eval} returns a
12407 non-@code{nil} value, the article should be removed.
12409 If @var{last} is @code{nil}, that means that there is a high likelihood
12410 that there will be more requests issued shortly, so that allows some
12413 The function should return a cons where the car is the group name and
12414 the cdr is the article number that the article was entered as.
12416 There should be no data returned.
12419 @item (nnchoke-request-accept-article GROUP &optional SERVER LAST)
12421 This function takes the current buffer and inserts it into @var{group}.
12422 If @var{last} in @code{nil}, that means that there will be more calls to
12423 this function in short order.
12425 The function should return a cons where the car is the group name and
12426 the cdr is the article number that the article was entered as.
12428 There should be no data returned.
12431 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
12433 This function should remove @var{article} (which is a number) from
12434 @var{group} and insert @var{buffer} there instead.
12436 There should be no data returned.
12439 @item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
12441 This function should delete @var{group}. If @var{force}, it should
12442 really delete all the articles in the group, and then delete the group
12443 itself. (If there is such a thing as ``the group itself''.)
12445 There should be no data returned.
12448 @item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
12450 This function should rename @var{group} into @var{new-name}. All
12451 articles that are in @var{group} should move to @var{new-name}.
12453 There should be no data returned.
12458 @node Writing New Backends
12459 @subsubsection Writing New Backends
12461 The various backends share many similarities. @code{nnml} is just like
12462 @code{nnspool}, but it allows you to edit the articles on the server.
12463 @code{nnmh} is just like @code{nnml}, but it doesn't use an active file,
12464 and it doesn't maintain overview databases. @code{nndir} is just like
12465 @code{nnml}, but it has no concept of ``groups'', and it doesn't allow
12468 It would make sense if it were possible to ``inherit'' functions from
12469 backends when writing new backends. And, indeed, you can do that if you
12470 want to. (You don't have to if you don't want to, of course.)
12472 All the backends declare their public variables and functions by using a
12473 package called @code{nnoo}.
12475 To inherit functions from other backends (and allow other backends to
12476 inherit functions from the current backend), you should use the
12483 This macro declares the first parameter to be a child of the subsequent
12484 parameters. For instance:
12487 (nnoo-declare nndir
12491 @code{nndir} has here declared that it intends to inherit functions from
12492 both @code{nnml} and @code{nnmh}.
12495 This macro is equivalent to @code{defvar}, but registers the variable as
12496 a public server variable. Most state-oriented variables should be
12497 declared with @code{defvoo} instead of @code{defvar}.
12499 In addition to the normal @code{defvar} parameters, it takes a list of
12500 variables in the parent backends to map the variable to when executing
12501 a function in those backends.
12504 (defvoo nndir-directory nil
12505 "Where nndir will look for groups."
12506 nnml-current-directory nnmh-current-directory)
12509 This means that @code{nnml-current-directory} will be set to
12510 @code{nndir-directory} when an @code{nnml} function is called on behalf
12511 of @code{nndir}. (The same with @code{nnmh}.)
12513 @item nnoo-define-basics
12514 This macro defines some common functions that almost all backends should
12518 (nnoo-define-basics nndir)
12522 This macro is just like @code{defun} and takes the same parameters. In
12523 addition to doing the normal @code{defun} things, it registers the
12524 function as being public so that other backends can inherit it.
12526 @item nnoo-map-functions
12527 This macro allows mapping of functions from the current backend to
12528 functions from the parent backends.
12531 (nnoo-map-functions nndir
12532 (nnml-retrieve-headers 0 nndir-current-group 0 0)
12533 (nnmh-request-article 0 nndir-current-group 0 0))
12536 This means that when @code{nndir-retrieve-headers} is called, the first,
12537 third, and fourth parameters will be passed on to
12538 @code{nnml-retrieve-headers}, while the second parameter is set to the
12539 value of @code{nndir-current-group}.
12542 This macro allows importing functions from backends. It should be the
12543 last thing in the source file, since it will only define functions that
12544 haven't already been defined.
12550 nnmh-request-newgroups)
12554 This means that calls to @code{nndir-request-list} should just be passed
12555 on to @code{nnmh-request-list}, while all public functions from
12556 @code{nnml} that haven't been defined in @code{nndir} yet should be
12561 Below is a slightly shortened version of the @code{nndir} backend.
12564 ;;; nndir.el --- single directory newsgroup access for Gnus
12565 ;; Copyright (C) 1995,96 Free Software Foundation, Inc.
12569 (require 'nnheader)
12573 (eval-when-compile (require 'cl))
12575 (nnoo-declare nndir
12578 (defvoo nndir-directory nil
12579 "Where nndir will look for groups."
12580 nnml-current-directory nnmh-current-directory)
12582 (defvoo nndir-nov-is-evil nil
12583 "*Non-nil means that nndir will never retrieve NOV headers."
12586 (defvoo nndir-current-group "" nil nnml-current-group nnmh-current-group)
12587 (defvoo nndir-top-directory nil nil nnml-directory nnmh-directory)
12588 (defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail)
12590 (defvoo nndir-status-string "" nil nnmh-status-string)
12591 (defconst nndir-version "nndir 1.0")
12593 ;;; Interface functions.
12595 (nnoo-define-basics nndir)
12597 (deffoo nndir-open-server (server &optional defs)
12598 (setq nndir-directory
12599 (or (cadr (assq 'nndir-directory defs))
12601 (unless (assq 'nndir-directory defs)
12602 (push `(nndir-directory ,server) defs))
12603 (push `(nndir-current-group
12604 ,(file-name-nondirectory (directory-file-name nndir-directory)))
12606 (push `(nndir-top-directory
12607 ,(file-name-directory (directory-file-name nndir-directory)))
12609 (nnoo-change-server 'nndir server defs))
12611 (nnoo-map-functions nndir
12612 (nnml-retrieve-headers 0 nndir-current-group 0 0)
12613 (nnmh-request-article 0 nndir-current-group 0 0)
12614 (nnmh-request-group nndir-current-group 0 0)
12615 (nnmh-close-group nndir-current-group 0))
12619 nnmh-status-message
12621 nnmh-request-newgroups))
12628 @node Score File Syntax
12629 @subsection Score File Syntax
12631 Score files are meant to be easily parsable, but yet extremely
12632 mallable. It was decided that something that had the same read syntax
12633 as an Emacs Lisp list would fit that spec.
12635 Here's a typical score file:
12639 ("win95" -10000 nil s)
12646 BNF definition of a score file:
12649 score-file = "" / "(" *element ")"
12650 element = rule / atom
12651 rule = string-rule / number-rule / date-rule
12652 string-rule = "(" quote string-header quote space *string-match ")"
12653 number-rule = "(" quote number-header quote space *number-match ")"
12654 date-rule = "(" quote date-header quote space *date-match ")"
12656 string-header = "subject" / "from" / "references" / "message-id" /
12657 "xref" / "body" / "head" / "all" / "followup"
12658 number-header = "lines" / "chars"
12659 date-header = "date"
12660 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
12661 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
12662 score = "nil" / <integer>
12663 date = "nil" / <natural number>
12664 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
12665 "r" / "regex" / "R" / "Regex" /
12666 "e" / "exact" / "E" / "Exact" /
12667 "f" / "fuzzy" / "F" / "Fuzzy"
12668 number-match = "(" <integer> [ "" / [ space score [ "" /
12669 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
12670 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
12671 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
12672 space date [ "" / [ space date-match-t ] ] ] ] ")"
12673 date-match-t = "nil" / "at" / "before" / "after"
12674 atom = "(" [ required-atom / optional-atom ] ")"
12675 required-atom = mark / expunge / mark-and-expunge / files /
12676 exclude-files / read-only / touched
12677 optional-atom = adapt / local / eval
12678 mark = "mark" space nil-or-number
12679 nil-or-number = "nil" / <integer>
12680 expunge = "expunge" space nil-or-number
12681 mark-and-expunge = "mark-and-expunge" space nil-or-number
12682 files = "files" *[ space <string> ]
12683 exclude-files = "exclude-files" *[ space <string> ]
12684 read-only = "read-only" [ space "nil" / space "t" ]
12685 adapt = "adapt" [ space "nil" / space "t" / space adapt-rule ]
12686 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
12687 local = "local" *[ space "(" <string> space <form> ")" ]
12688 eval = "eval" space <form>
12689 space = *[ " " / <TAB> / <NEWLINE> ]
12692 Any unrecognized elements in a score file should be ignored, but not
12695 As you can see, white space is needed, but the type and amount of white
12696 space is irrelevant. This means that formatting of the score file is
12697 left up to the programmer---if it's simpler to just spew it all out on
12698 one looong line, then that's ok.
12700 The meaning of the various atoms are explained elsewhere in this
12705 @subsection Headers
12707 Gnus uses internally a format for storing article headers that
12708 corresponds to the @sc{nov} format in a mysterious fashion. One could
12709 almost suspect that the author looked at the @sc{nov} specification and
12710 just shamelessly @emph{stole} the entire thing, and one would be right.
12712 @dfn{Header} is a severely overloaded term. ``Header'' is used in
12713 RFC1036 to talk about lines in the head of an article (eg.,
12714 @code{From}). It is used by many people as a synonym for
12715 ``head''---``the header and the body''. (That should be avoided, in my
12716 opinion.) And Gnus uses a format internally that it calls ``header'',
12717 which is what I'm talking about here. This is a 9-element vector,
12718 basically, with each header (ouch) having one slot.
12720 These slots are, in order: @code{number}, @code{subject}, @code{from},
12721 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
12722 @code{xref}. There are macros for accessing and setting these slots --
12723 they all have predictable names beginning with @code{mail-header-} and
12724 @code{mail-header-set-}, respectively.
12726 The @code{xref} slot is really a @code{misc} slot. Any extra info will
12733 @sc{gnus} introduced a concept that I found so useful that I've started
12734 using it a lot and have elaborated on it greatly.
12736 The question is simple: If you have a large amount of objects that are
12737 identified by numbers (say, articles, to take a @emph{wild} example)
12738 that you want to callify as being ``included'', a normal sequence isn't
12739 very useful. (A 200,000 length sequence is a bit long-winded.)
12741 The solution is as simple as the question: You just collapse the
12745 (1 2 3 4 5 6 10 11 12)
12748 is transformed into
12751 ((1 . 6) (10 . 12))
12754 To avoid having those nasty @samp{(13 . 13)} elements to denote a
12755 lonesome object, a @samp{13} is a valid element:
12758 ((1 . 6) 7 (10 . 12))
12761 This means that comparing two ranges to find out whether they are equal
12762 is slightly tricky:
12765 ((1 . 5) 7 8 (10 . 12))
12771 ((1 . 5) (7 . 8) (10 . 12))
12774 are equal. In fact, any non-descending list is a range:
12780 is a perfectly valid range, although a pretty long-winded one. This is
12787 and is equal to the previous range.
12789 Here's a BNF definition of ranges. Of course, one must remember the
12790 semantic requirement that the numbers are non-descending. (Any number
12791 of repetition of the same number is allowed, but apt to disappear in
12795 range = simple-range / normal-range
12796 simple-range = "(" number " . " number ")"
12797 normal-range = "(" start-contents ")"
12798 contents = "" / simple-range *[ " " contents ] /
12799 number *[ " " contents ]
12802 Gnus currently uses ranges to keep track of read articles and article
12803 marks. I plan on implementing a number of range operators in C if The
12804 Powers That Be are willing to let me. (I haven't asked yet, because I
12805 need to do some more thinking on what operators I need to make life
12806 totally range-based without ever having to convert back to normal
12811 @subsection Group Info
12813 Gnus stores all permanent info on groups in a @dfn{group info} list.
12814 This list is from three to six elements (or more) long and exhaustively
12815 describes the group.
12817 Here are two example group infos; one is a very simple group while the
12818 second is a more complex one:
12821 ("no.group" 5 (1 . 54324))
12823 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
12824 ((tick (15 . 19)) (replied 3 6 (19 . 3)))
12826 (auto-expire (to-address "ding@@ifi.uio.no")))
12829 The first element is the group name as Gnus knows the group; the second
12830 is the group level; the third is the read articles in range format; the
12831 fourth is a list of article marks lists; the fifth is the select method;
12832 and the sixth contains the group parameters.
12834 Here's a BNF definition of the group info format:
12837 info = "(" group space level space read
12838 [ "" / [ space marks-list [ "" / [ space method [ "" /
12839 space parameters ] ] ] ] ] ")"
12840 group = quote <string> quote
12841 level = <integer in the range of 1 to inf>
12843 marks-lists = nil / "(" *marks ")"
12844 marks = "(" <string> range ")"
12845 method = "(" <string> *elisp-forms ")"
12846 parameters = "(" *elisp-forms ")"
12849 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
12850 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
12854 @node Emacs/XEmacs Code
12855 @subsection Emacs/XEmacs Code
12859 While Gnus runs under Emacs, XEmacs and Mule, I decided that one of the
12860 platforms must be the primary one. I chose Emacs. Not because I don't
12861 like XEmacs or Mule, but because it comes first alphabetically.
12863 This means that Gnus will byte-compile under Emacs with nary a warning,
12864 while XEmacs will pump out gigabytes of warnings while byte-compiling.
12865 As I use byte-compilation warnings to help me root out trivial errors in
12866 Gnus, that's very useful.
12868 I've also consistently used Emacs function interfaces, but have used
12869 Gnusey aliases for the functions. To take an example: Emacs defines a
12870 @code{run-at-time} function while XEmacs defines a @code{start-itimer}
12871 function. I then define a function called @code{gnus-run-at-time} that
12872 takes the same parameters as the Emacs @code{run-at-time}. When running
12873 Gnus under Emacs, the former function is just an alias for the latter.
12874 However, when running under XEmacs, the former is an alias for the
12875 following function:
12878 (defun gnus-xmas-run-at-time (time repeat function &rest args)
12882 (,function ,@@args))
12886 This sort of thing has been done for bunches of functions. Gnus does
12887 not redefine any native Emacs functions while running under XEmacs -- it
12888 does this @code{defalias} thing with Gnus equivalents instead. Cleaner
12891 Of course, I could have chosen XEmacs as my native platform and done
12892 mapping functions the other way around. But I didn't. The performance
12893 hit these indirections impose on Gnus under XEmacs should be slight.
12896 @node Various File Formats
12897 @subsection Various File Formats
12900 * Active File Format:: Information on articles and groups available.
12901 * Newsgroups File Format:: Group descriptions.
12905 @node Active File Format
12906 @subsubsection Active File Format
12908 The active file lists all groups that are available on the server in
12909 question. It also lists the highest and lowest current article numbers
12912 Here's an excerpt from a typical active file:
12915 soc.motss 296030 293865 y
12916 alt.binaries.pictures.fractals 3922 3913 n
12917 comp.sources.unix 1605 1593 m
12918 comp.binaries.ibm.pc 5097 5089 y
12919 no.general 1000 900 y
12922 Here's a pseudo-BNF definition of this file:
12925 active = *group-line
12926 group-line = group space high-number space low-number space flag <NEWLINE>
12927 group = <non-white-space string>
12929 high-number = <non-negative integer>
12930 low-number = <positive integer>
12931 flag = "y" / "n" / "m" / "j" / "x" / "=" group
12935 @node Newsgroups File Format
12936 @subsubsection Newsgroups File Format
12938 The newsgroups file lists groups along with their descriptions. Not all
12939 groups on the server have to be listed, and not all groups in the file
12940 have to exist on the server. The file is meant purely as information to
12943 The format is quite simple; a group name, a tab, and the description.
12944 Here's the definition:
12948 line = group tab description <NEWLINE>
12949 group = <non-white-space string>
12951 description = <string>
12955 @node Emacs for Heathens
12956 @section Emacs for Heathens
12958 Believe it or not, but some people who use Gnus haven't really used
12959 Emacs much before they embarked on their journey on the Gnus Love Boat.
12960 If you are one of those unfortunates whom ``@kbd{M-C-a}'', ``kill the
12961 region'', and ``set @code{gnus-flargblossen} to an alist where the key
12962 is a regexp that is used for matching on the group name'' are magical
12963 phrases with little or no meaning, then this appendix is for you. If
12964 you are already familiar with Emacs, just ignore this and go fondle your
12968 * Keystrokes:: Entering text and executing commands.
12969 * Emacs Lisp:: The built-in Emacs programming language.
12974 @subsection Keystrokes
12978 Q: What is an experienced Emacs user?
12981 A: A person who wishes that the terminal had pedals.
12984 Yes, when you use Emacs, you are apt to use the control key, the shift
12985 key and the meta key a lot. This is very annoying to some people
12986 (notably @code{vi}le users), and the rest of us just love the hell out
12987 of it. Just give up and submit. Emacs really does stand for
12988 ``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you
12989 may have heard from other disreputable sources (like the Emacs author).
12991 The shift key is normally located near your pinky fingers, and are
12992 normally used to get capital letters and stuff. You probably use it all
12993 the time. The control key is normally marked ``CTRL'' or something like
12994 that. The meta key is, funnily enough, never marked as such on any
12995 keyboards. The one I'm currently at has a key that's marked ``Alt'',
12996 which is the meta key on this keyboard. It's usually located somewhere
12997 to the left hand side of the keyboard, usually on the bottom row.
12999 Now, us Emacs people doesn't say ``press the meta-control-m key'',
13000 because that's just too inconvenient. We say ``press the @kbd{M-C-m}
13001 key''. @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the
13002 prefix that means ``control''. So ``press @kbd{C-k}'' means ``press
13003 down the control key, and hold it down while you press @kbd{k}''.
13004 ``Press @kbd{M-C-k}'' means ``press down and hold down the meta key and
13005 the control key and then press @kbd{k}''. Simple, ay?
13007 This is somewhat complicated by the fact that not all keyboards have a
13008 meta key. In that case you can use the ``escape'' key. Then @kbd{M-k}
13009 means ``press escape, release escape, press @kbd{k}''. That's much more
13010 work than if you have a meta key, so if that's the case, I respectfully
13011 suggest you get a real keyboard with a meta key. You can't live without
13017 @subsection Emacs Lisp
13019 Emacs is the King of Editors because it's really a Lisp interpreter.
13020 Each and every key you tap runs some Emacs Lisp code snippet, and since
13021 Emacs Lisp is an interpreted language, that means that you can configure
13022 any key to run any arbitrary code. You just, like, do it.
13024 Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
13025 functions. (These are byte-compiled for speed, but it's still
13026 interpreted.) If you decide that you don't like the way Gnus does
13027 certain things, it's trivial to have it do something a different way.
13028 (Well, at least if you know how to write Lisp code.) However, that's
13029 beyond the scope of this manual, so we are simply going to talk about
13030 some common constructs that you normally use in your @file{.emacs} file
13033 If you want to set the variable @code{gnus-florgbnize} to four (4), you
13034 write the following:
13037 (setq gnus-florgbnize 4)
13040 This function (really ``special form'') @code{setq} is the one that can
13041 set a variable to some value. This is really all you need to know. Now
13042 you can go and fill your @code{.emacs} file with lots of these to change
13045 If you have put that thing in your @code{.emacs} file, it will be read
13046 and @code{eval}ed (which is lisp-ese for ``run'') the next time you
13047 start Emacs. If you want to change the variable right away, simply say
13048 @kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
13049 previous ``form'', which here is a simple @code{setq} statement.
13051 Go ahead---just try it, if you're located at your Emacs. After you
13052 @kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
13053 is the return value of the form you @code{eval}ed.
13057 If the manual says ``set @code{gnus-read-active-file} to @code{some}'',
13061 (setq gnus-read-active-file 'some)
13064 On the other hand, if the manual says ``set @code{gnus-nntp-server} to
13065 @samp{nntp.ifi.uio.no}'', that means:
13068 (setq gnus-nntp-server "nntp.ifi.uio.no")
13071 So be careful not to mix up strings (the latter) with symbols (the
13072 former). The manual is unambiguous, but it can be confusing.
13075 @include gnus-faq.texi