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 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 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 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 * Message:: Message sending interface.
304 * Composing Messages:: Information on sending mail and news.
305 * Select Methods:: Gnus reads all messages from various select methods.
306 * Scoring:: Assigning values to articles.
307 * Various:: General purpose settings.
308 * The End:: Farewell and goodbye.
309 * Appendices:: Terminology, Emacs intro, FAQ, History, Internals.
310 * Index:: Variable, function and concept index.
311 * Key Index:: Key Index.
316 @chapter Starting Gnus
321 If your system administrator has set things up properly, starting Gnus
322 and reading news is extremely easy---you just type @kbd{M-x gnus} in
325 @findex gnus-other-frame
326 @kindex M-x gnus-other-frame
327 If you want to start Gnus in a different frame, you can use the command
328 @kbd{M-x gnus-other-frame} instead.
330 If things do not go smoothly at startup, you have to twiddle some
334 * Finding the News:: Choosing a method for getting news.
335 * The First Time:: What does Gnus do the first time you start it?
336 * The Server is Down:: How can I read my mail then?
337 * Slave Gnusii:: You can have more than one Gnus active at a time.
338 * Fetching a Group:: Starting Gnus just to read a group.
339 * New Groups:: What is Gnus supposed to do with new groups?
340 * Startup Files:: Those pesky startup files---@file{.newsrc}.
341 * Auto Save:: Recovering from a crash.
342 * The Active File:: Reading the active file over a slow line Takes Time.
343 * Startup Variables:: Other variables you might change.
347 @node Finding the News
348 @section Finding the News
350 @vindex gnus-select-method
352 The @code{gnus-select-method} variable says where Gnus should look for
353 news. This variable should be a list where the first element says
354 @dfn{how} and the second element says @dfn{where}. This method is your
355 native method. All groups that are not fetched with this method are
358 For instance, if the @samp{news.somewhere.edu} @sc{nntp} server is where
359 you want to get your daily dosage of news from, you'd say:
362 (setq gnus-select-method '(nntp "news.somewhere.edu"))
365 If you want to read directly from the local spool, say:
368 (setq gnus-select-method '(nnspool ""))
371 If you can use a local spool, you probably should, as it will almost
372 certainly be much faster.
374 @vindex gnus-nntpserver-file
376 @cindex @sc{nntp} server
377 If this variable is not set, Gnus will take a look at the
378 @code{NNTPSERVER} environment variable. If that variable isn't set,
379 Gnus will see whether @code{gnus-nntpserver-file}
380 (@file{/etc/nntpserver} by default) has any opinions on the matter. If
381 that fails as well, Gnus will will try to use the machine that is
382 running Emacs as an @sc{nntp} server. That's a long-shot, though.
384 @vindex gnus-nntp-server
385 If @code{gnus-nntp-server} is set, this variable will override
386 @code{gnus-select-method}. You should therefore set
387 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
389 @vindex gnus-secondary-servers
390 You can also make Gnus prompt you interactively for the name of an
391 @sc{nntp} server. If you give a non-numerical prefix to @code{gnus}
392 (i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
393 in the @code{gnus-secondary-servers} list (if any). You can also just
394 type in the name of any server you feel like visiting.
396 @findex gnus-group-browse-foreign-server
398 However, if you use one @sc{nntp} server regularly and are just
399 interested in a couple of groups from a different server, you would be
400 better served by using the @kbd{B} command in the group buffer. It will
401 let you have a look at what groups are available, and you can subscribe
402 to any of the groups you want to. This also makes @file{.newsrc}
403 maintenance much tidier. @xref{Foreign Groups}.
405 @vindex gnus-secondary-select-methods
407 A slightly different approach to foreign groups is to set the
408 @code{gnus-secondary-select-methods} variable. The select methods
409 listed in this variable are in many ways just as native as the
410 @code{gnus-select-method} server. They will also be queried for active
411 files during startup (if that's required), and new newsgroups that
412 appear on these servers will be subscribed (or not) just as native
415 For instance, if you use the @code{nnmbox} backend to read your mail, you
416 would typically set this variable to
419 (setq gnus-secondary-select-methods '((nnmbox "")))
424 @section The First Time
425 @cindex first time usage
427 If no startup files exist, Gnus will try to determine what groups should
428 be subscribed by default.
430 @vindex gnus-default-subscribed-newsgroups
431 If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
432 will subscribe you to just those groups in that list, leaving the rest
433 killed. Your system administrator should have set this variable to
436 Since she hasn't, Gnus will just subscribe you to a few arbitrarily
437 picked groups (i.e., @samp{*.newusers}). (@dfn{Arbitrary} is here
438 defined as @dfn{whatever Lars thinks you should read}.)
440 You'll also be subscribed to the Gnus documentation group, which should
441 help you with most common problems.
443 If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
444 use the normal functions for handling new groups, and not do anything
448 @node The Server is Down
449 @section The Server is Down
450 @cindex server errors
452 If the default server is down, Gnus will understandably have some
453 problems starting. However, if you have some mail groups in addition to
454 the news groups, you may want to start Gnus anyway.
456 Gnus, being the trusting sort of program, will ask whether to proceed
457 without a native select method if that server can't be contacted. This
458 will happen whether the server doesn't actually exist (i.e., you have
459 given the wrong address) or the server has just momentarily taken ill
460 for some reason or other. If you decide to continue and have no foreign
461 groups, you'll find it difficult to actually do anything in the group
462 buffer. But, hey, that's your problem. Blllrph!
464 @findex gnus-no-server
466 If you know that the server is definitely down, or you just want to read
467 your mail without bothering with the server at all, you can use the
468 @code{gnus-no-server} command to start Gnus. That might come in handy
469 if you're in a hurry as well.
473 @section Slave Gnusiï
476 You might want to run more than one Emacs with more than one Gnus at the
477 same time. If you are using different @file{.newsrc} files (eg., if you
478 are using the two different Gnusiï to read from two different servers),
479 that is no problem whatsoever. You just do it.
481 The problem appears when you want to run two Gnusiï that use the same
484 To work around that problem some, we here at the Think-Tank at the Gnus
485 Towers have come up with a new concept: @dfn{Masters} and
486 @dfn{servants}. (We have applied for a patent on this concept, and have
487 taken out a copyright on those words. If you wish to use those words in
488 conjunction with each other, you have to send $1 per usage instance to
489 me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
490 Applications}) will be much more expensive, of course.)
492 Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
493 however you do it). Each subsequent slave Gnusiï should be started with
494 @kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
495 files, but instead save @dfn{slave files} that contains information only
496 on what groups have been read in the slave session. When a master Gnus
497 starts, it will read (and delete) these slave files, incorporating all
498 information from them. (The slave files will be read in the sequence
499 they were created, so the latest changes will have precedence.)
501 Information from the slave files has, of course, precedence over the
502 information in the normal (i. e., master) @code{.newsrc} file.
505 @node Fetching a Group
506 @section Fetching a Group
508 @findex gnus-fetch-group
509 It it sometime convenient to be able to just say ``I want to read this
510 group and I don't care whether Gnus has been started or not''. This is
511 perhaps more useful for people who write code than for users, but the
512 command @code{gnus-fetch-group} provides this functionality in any case.
513 It takes the group name as a parameter.
520 @vindex gnus-subscribe-newsgroup-method
521 What Gnus does when it encounters a new group is determined by the
522 @code{gnus-subscribe-newsgroup-method} variable.
524 This variable should contain a function. Some handy pre-fab values
529 @item gnus-subscribe-zombies
530 @vindex gnus-subscribe-zombies
531 Make all new groups zombies. You can browse the zombies later (with
532 @kbd{A z}) and either kill them all off properly, or subscribe to them.
535 @item gnus-subscribe-randomly
536 @vindex gnus-subscribe-randomly
537 Subscribe all new groups randomly.
539 @item gnus-subscribe-alphabetically
540 @vindex gnus-subscribe-alphabetically
541 Subscribe all new groups alphabetically.
543 @item gnus-subscribe-hierarchically
544 @vindex gnus-subscribe-hierarchically
545 Subscribe all new groups hierarchically.
547 @item gnus-subscribe-interactively
548 @vindex gnus-subscribe-interactively
549 Subscribe new groups interactively. This means that Gnus will ask
550 you about @strong{all} new groups.
552 @item gnus-subscribe-killed
553 @vindex gnus-subscribe-killed
558 @vindex gnus-subscribe-hierarchical-interactive
559 A closely related variable is
560 @code{gnus-subscribe-hierarchical-interactive}. (That's quite a
561 mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a
562 hierarchical fashion whether to subscribe to new groups or not. Gnus
563 will ask you for each sub-hierarchy whether you want to descend the
566 One common mistake is to set the variable a few paragraphs above to
567 @code{gnus-subscribe-hierarchical-interactive}. This is an error. This
568 will not work. This is ga-ga. So don't do it.
570 A nice and portable way to control which new newsgroups should be
571 subscribed (or ignored) is to put an @dfn{options} line at the start of
572 the @file{.newsrc} file. Here's an example:
575 options -n !alt.all !rec.all sci.all
578 @vindex gnus-subscribe-options-newsgroup-method
579 This line obviously belongs to a serious-minded intellectual scientific
580 person (or she may just be plain old boring), because it says that all
581 groups that have names beginning with @samp{alt} and @samp{rec} should
582 be ignored, and all groups with names beginning with @samp{sci} should
583 be subscribed. Gnus will not use the normal subscription method for
584 subscribing these groups.
585 @code{gnus-subscribe-options-newsgroup-method} is used instead. This
586 variable defaults to @code{gnus-subscribe-alphabetically}.
588 @vindex gnus-options-not-subscribe
589 @vindex gnus-options-subscribe
590 If you don't want to mess with your @file{.newsrc} file, you can just
591 set the two variables @code{gnus-options-subscribe} and
592 @code{gnus-options-not-subscribe}. These two variables do exactly the
593 same as the @file{.newsrc} @samp{options -n} trick. Both are regexps,
594 and if the the new group matches the former, it will be unconditionally
595 subscribed, and if it matches the latter, it will be ignored.
597 @vindex gnus-auto-subscribed-groups
598 Yet another variable that meddles here is
599 @code{gnus-auto-subscribed-groups}. It works exactly like
600 @code{gnus-options-subscribe}, and is therefore really superfluous, but I
601 thought it would be nice to have two of these. This variable is more
602 meant for setting some ground rules, while the other variable is used
603 more for user fiddling. By default this variable makes all new groups
604 that come from mail backends (@code{nnml}, @code{nnbabyl},
605 @code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you
606 don't like that, just set this variable to @code{nil}.
608 @vindex gnus-check-new-newsgroups
609 If you are satisfied that you really never want to see any new groups,
610 you could set @code{gnus-check-new-newsgroups} to @code{nil}. This will
611 also save you some time at startup. Even if this variable is
612 @code{nil}, you can always subscribe to the new groups just by pressing
613 @kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
614 is @code{t} by default.
616 Gnus normally determines whether a group is new or not by comparing the
617 list of groups from the active file(s) with the lists of subscribed and
618 dead groups. This isn't a particularly fast method. If
619 @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
620 server for new groups since the last time. This is both faster &
621 cheaper. This also means that you can get rid of the list of killed
622 groups altogether, so you may set @code{gnus-save-killed-list} to
623 @code{nil}, which will save time both at startup, at exit, and all over.
624 Saves disk space, too. Why isn't this the default, then?
625 Unfortunately, not all servers support this command.
627 I bet I know what you're thinking now: How do I find out whether my
628 server supports @code{ask-server}? No? Good, because I don't have a
629 fail-safe answer. I would suggest just setting this variable to
630 @code{ask-server} and see whether any new groups appear within the next
631 few days. If any do, then it works. If any don't, then it doesn't
632 work. I could write a function to make Gnus guess whether the server
633 supports @code{ask-server}, but it would just be a guess. So I won't.
634 You could @code{telnet} to the server and say @code{HELP} and see
635 whether it lists @samp{NEWGROUPS} among the commands it understands. If
636 it does, then it might work. (But there are servers that lists
637 @samp{NEWGROUPS} without supporting the function properly.)
639 This variable can also be a list of select methods. If so, Gnus will
640 issue an @code{ask-server} command to each of the select methods, and
641 subscribe them (or not) using the normal methods. This might be handy
642 if you are monitoring a few servers for new groups. A side effect is
643 that startup will take much longer, so you can meditate while waiting.
644 Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss.
648 @section Startup Files
649 @cindex startup files
652 Now, you all know about the @file{.newsrc} file. All subscription
653 information is traditionally stored in this file.
655 Things got a bit more complicated with @sc{gnus}. In addition to
656 keeping the @file{.newsrc} file updated, it also used a file called
657 @file{.newsrc.el} for storing all the information that didn't fit into
658 the @file{.newsrc} file. (Actually, it also duplicated everything in
659 the @file{.newsrc} file.) @sc{gnus} would read whichever one of these
660 files was the most recently saved, which enabled people to swap between
661 @sc{gnus} and other newsreaders.
663 That was kinda silly, so Gnus went one better: In addition to the
664 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
665 @file{.newsrc.eld}. It will read whichever of these files that are most
666 recent, but it will never write a @file{.newsrc.el} file.
668 @vindex gnus-save-newsrc-file
669 You can turn off writing the @file{.newsrc} file by setting
670 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
671 the file and save some space, as well as making exit from Gnus faster.
672 However, this will make it impossible to use other newsreaders than
673 Gnus. But hey, who would want to, right?
675 @vindex gnus-save-killed-list
676 If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus
677 will not save the list of killed groups to the startup file. This will
678 save both time (when starting and quitting) and space (on disk). It
679 will also means that Gnus has no record of what groups are new or old,
680 so the automatic new groups subscription methods become meaningless.
681 You should always set @code{gnus-check-new-newsgroups} to @code{nil} or
682 @code{ask-server} if you set this variable to @code{nil} (@pxref{New
685 @vindex gnus-startup-file
686 The @code{gnus-startup-file} variable says where the startup files are.
687 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
688 file being whatever that one is with a @samp{.eld} appended.
690 @vindex gnus-save-newsrc-hook
691 @vindex gnus-save-quick-newsrc-hook
692 @vindex gnus-save-standard-newsrc-hook
693 @code{gnus-save-newsrc-hook} is called before saving any of the newsrc
694 files, while @code{gnus-save-quick-newsrc-hook} is called just before
695 saving the @file{.newsrc.eld} file, and
696 @code{gnus-save-standard-newsrc-hook} is called just before saving the
697 @file{.newsrc} file. The latter two are commonly used to turn version
698 control on or off. Version control is off by default when saving the
707 Whenever you do something that changes the Gnus data (reading articles,
708 catching up, killing/subscribing groups), the change is added to a
709 special @dfn{dribble buffer}. This buffer is auto-saved the normal
710 Emacs way. If your Emacs should crash before you have saved the
711 @file{.newsrc} files, all changes you have made can be recovered from
714 If Gnus detects this file at startup, it will ask the user whether to
715 read it. The auto save file is deleted whenever the real startup file is
718 @vindex gnus-use-dribble-file
719 If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
720 maintain a dribble buffer. The default is @code{t}.
722 @vindex gnus-dribble-directory
723 Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
724 this variable is @code{nil}, which it is by default, Gnus will dribble
725 into the directory where the @file{.newsrc} file is located. (This is
726 normally the user's home directory.) The dribble file will get the same
727 file permissions as the @code{.newsrc} file.
730 @node The Active File
731 @section The Active File
733 @cindex ignored groups
735 When Gnus starts, or indeed whenever it tries to determine whether new
736 articles have arrived, it reads the active file. This is a very large
737 file that lists all the active groups and articles on the server.
739 @vindex gnus-ignored-newsgroups
740 Before examining the active file, Gnus deletes all lines that match the
741 regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject
742 any groups with bogus names, but you can use this variable to make Gnus
743 ignore hierarchies you aren't ever interested in. However, this is not
744 recommended. In fact, it's highly discouraged. Instead, @pxref{New
745 Groups} for an overview of other variables that can be used instead.
748 @c @code{nil} by default, and will slow down active file handling somewhat
749 @c if you set it to anything else.
751 @vindex gnus-read-active-file
753 The active file can be rather Huge, so if you have a slow network, you
754 can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
755 reading the active file. This variable is @code{t} by default.
757 Gnus will try to make do by getting information just on the groups that
758 you actually subscribe to.
760 Note that if you subscribe to lots and lots of groups, setting this
761 variable to @code{nil} will probably make Gnus slower, not faster. At
762 present, having this variable @code{nil} will slow Gnus down
763 considerably, unless you read news over a 2400 baud modem.
765 This variable can also have the value @code{some}. Gnus will then
766 attempt to read active info only on the subscribed groups. On some
767 servers this is quite fast (on sparkling, brand new INN servers that
768 support the @code{LIST ACTIVE group} command), on others this isn't fast
769 at all. In any case, @code{some} should be faster than @code{nil}, and
770 is certainly faster than @code{t} over slow lines.
772 If this variable is @code{nil}, Gnus will ask for group info in total
773 lock-step, which isn't very fast. If it is @code{some} and you use an
774 @sc{nntp} server, Gnus will pump out commands as fast as it can, and
775 read all the replies in one swoop. This will normally result in better
776 performance, but if the server does not support the aforementioned
777 @code{LIST ACTIVE group} command, this isn't very nice to the server.
779 In any case, if you use @code{some} or @code{nil}, you should definitely
780 kill all groups that you aren't interested in to speed things up.
783 @node Startup Variables
784 @section Startup Variables
789 @vindex gnus-load-hook
790 A hook that is run while Gnus is being loaded. Note that this hook will
791 normally be run just once in each Emacs session, no matter how many
792 times you start Gnus.
794 @item gnus-startup-hook
795 @vindex gnus-startup-hook
796 A hook that is run after starting up Gnus successfully.
798 @item gnus-check-bogus-newsgroups
799 @vindex gnus-check-bogus-newsgroups
800 If non-@code{nil}, Gnus will check for and delete all bogus groups at
801 startup. A @dfn{bogus group} is a group that you have in your
802 @file{.newsrc} file, but doesn't exist on the news server. Checking for
803 bogus groups can take quite a while, so to save time and resources it's
804 best to leave this option off, and do the checking for bogus groups once
805 in a while from the group buffer instead (@pxref{Group Maintenance}).
807 @item gnus-inhibit-startup-message
808 @vindex gnus-inhibit-startup-message
809 If non-@code{nil}, the startup message won't be displayed. That way,
810 your boss might not notice that you are reading news instead of doing
813 @item gnus-no-groups-message
814 @vindex gnus-no-groups-message
815 Message displayed by Gnus when no groups are available.
819 @node The Group Buffer
820 @chapter The Group Buffer
823 The @dfn{group buffer} lists all (or parts) of the available groups. It
824 is the first buffer shown when Gnus starts, and will never be killed as
825 long as Gnus is active.
828 * Group Buffer Format:: Information listed and how you can change it.
829 * Group Maneuvering:: Commands for moving in the group buffer.
830 * Selecting a Group:: Actually reading news.
831 * Subscription Commands:: Unsubscribing, killing, subscribing.
832 * Group Levels:: Levels? What are those, then?
833 * Group Score:: A mechanism for finding out what groups you like.
834 * Marking Groups:: You can mark groups for later processing.
835 * Foreign Groups:: Creating and editing groups.
836 * Group Parameters:: Each group may have different parameters set.
837 * Listing Groups:: Gnus can list various subsets of the groups.
838 * Sorting Groups:: Re-arrange the group order.
839 * Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
840 * Browse Foreign Server:: You can browse a server. See what it has to offer.
841 * Exiting Gnus:: Stop reading news and get some work done.
842 * Group Topics:: A folding group mode divided into topics.
843 * Misc Group Stuff:: Other stuff that you can to do.
847 @node Group Buffer Format
848 @section Group Buffer Format
849 @cindex group buffer format
852 * Group Line Specification:: Deciding how the group buffer is to look.
853 * Group Modeline Specification:: The group buffer modeline.
854 * Group Highlighting:: Having nice colors in the group buffer.
858 @node Group Line Specification
859 @subsection Group Line Specification
861 The default format of the group buffer is nice and dull, but you can
862 make it as exciting and ugly as you feel like.
864 Here's a couple of example group lines:
867 25: news.announce.newusers
868 * 0: alt.fan.andrea-dworkin
873 You can see that there are 25 unread articles in
874 @samp{news.announce.newusers}. There are no unread articles, but some
875 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
876 asterisk at the beginning of the line?)
878 @vindex gnus-group-line-format
879 You can change that format to whatever you want by fiddling with the
880 @code{gnus-group-line-format} variable. This variable works along the
881 lines of a @code{format} specification, which is pretty much the same as
882 a @code{printf} specifications, for those of you who use (feh!) C.
883 @xref{Formatting Variables}.
885 The default value that produced those lines above is
886 @samp{%M%S%5y: %(%g%)\n}.
888 There should always be a colon on the line; the cursor always moves to
889 the colon after performing an operation. Nothing else is required---not
890 even the group name. All displayed text is just window dressing, and is
891 never examined by Gnus. Gnus stores all real information it needs using
894 (Note that if you make a really strange, wonderful, spreadsheet-like
895 layout, everybody will believe you are hard at work with the accounting
896 instead of wasting time reading news.)
898 Here's a list of all available format characters:
903 Only marked articles.
906 Whether the group is subscribed.
909 Level of subscribedness.
912 Number of unread articles.
915 Number of dormant articles.
918 Number of ticked articles.
921 Number of read articles.
924 Total number of articles.
927 Number of unread, unticked, non-dormant articles.
930 Number of ticked and dormant articles.
939 Newsgroup description.
942 @samp{m} if moderated.
945 @samp{(m)} if moderated.
954 A string that looks like @samp{<%s:%n>} if a foreign select method is
958 Indentation based on the level of the topic (@pxref{Group Topics}).
961 @vindex gnus-group-uncollapsed-levels
962 Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels}
963 variable says how many levels to leave at the end of the group name.
964 The default is @code{1}.
967 User defined specifier. The next character in the format string should
968 be a letter. @sc{gnus} will call the function
969 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
970 following @samp{%u}. The function will be passed the current headers as
971 argument. The function should return a string, which will be inserted
972 into the buffer just like information from any other specifier.
976 All the ``number-of'' specs will be filled with an asterisk (@samp{*})
977 if no info is available---for instance, if it is a non-activated foreign
978 group, or a bogus (or semi-bogus) native group.
981 @node Group Modeline Specification
982 @subsection Group Modeline Specification
984 @vindex gnus-group-mode-line-format
985 The mode line can be changed by setting
986 (@code{gnus-group-mode-line-format}). It doesn't understand that many
991 The native news server.
993 The native select method.
997 @node Group Highlighting
998 @subsection Group Highlighting
1000 @vindex gnus-group-highlight
1001 Highlighting in the group buffer is controlled by the
1002 @code{gnus-group-highlight} variable. This is an alist with elements
1003 that look like @var{(form . face)}. If @var{form} evaluates to
1004 something non-@code{nil}, the @var{face} will be used on the line.
1006 Here's an example value for this variable that might look nice if the
1010 (setq gnus-group-highlight
1012 ,(custom-face-lookup "Red" nil nil t nil nil))
1013 ((and (< level 3) (zerop unread)) .
1014 ,(custom-face-lookup "SeaGreen" nil nil t nil nil))
1016 ,(custom-face-lookup "SpringGreen" nil nil t nil nil))
1018 ,(custom-face-lookup "SteelBlue" nil nil t nil nil))
1020 ,(custom-face-lookup "SkyBlue" nil nil t nil nil))
1024 Variables that are dynamically bound when the forms are evaluated
1031 The number of unread articles in the group.
1035 Whether the group is a mail group.
1037 The level of the group.
1039 The score of the group.
1041 The number of ticked articles in the group.
1043 When using the topic minor mode, this variable is bound to the current
1044 topic being inserted.
1047 When the forms are @code{eval}ed, point is at the beginning of the line
1048 of the group in question, so you can use many of the normal Gnus
1049 functions for snarfing info on the group.
1051 @vindex gnus-group-update-hook
1052 @findex gnus-group-highlight-line
1053 @code{gnus-group-update-hook} is called when a group line is changed.
1054 It will not be called when @code{gnus-visual} is @code{nil}. This hook
1055 calls @code{gnus-group-highlight-line} by default.
1058 @node Group Maneuvering
1059 @section Group Maneuvering
1060 @cindex group movement
1062 All movement commands understand the numeric prefix and will behave as
1063 expected, hopefully.
1069 @findex gnus-group-next-unread-group
1070 Go to the next group that has unread articles
1071 (@code{gnus-group-next-unread-group}).
1078 @findex gnus-group-prev-unread-group
1079 Go to the previous group group that has unread articles
1080 (@code{gnus-group-prev-unread-group}).
1084 @findex gnus-group-next-group
1085 Go to the next group (@code{gnus-group-next-group}).
1089 @findex gnus-group-prev-group
1090 Go to the previous group (@code{gnus-group-prev-group}).
1094 @findex gnus-group-next-unread-group-same-level
1095 Go to the next unread group on the same level (or lower)
1096 (@code{gnus-group-next-unread-group-same-level}).
1100 @findex gnus-group-prev-unread-group-same-level
1101 Go to the previous unread group on the same level (or lower)
1102 (@code{gnus-group-prev-unread-group-same-level}).
1105 Three commands for jumping to groups:
1111 @findex gnus-group-jump-to-group
1112 Jump to a group (and make it visible if it isn't already)
1113 (@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
1118 @findex gnus-group-best-unread-group
1119 Jump to the unread group with the lowest level
1120 (@code{gnus-group-best-unread-group}).
1124 @findex gnus-group-first-unread-group
1125 Jump to the first group with unread articles
1126 (@code{gnus-group-first-unread-group}).
1129 @vindex gnus-group-goto-unread
1130 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
1131 commands will move to the next group, not the next unread group. Even
1132 the commands that say they move to the next unread group. The default
1136 @node Selecting a Group
1137 @section Selecting a Group
1138 @cindex group selection
1143 @kindex SPACE (Group)
1144 @findex gnus-group-read-group
1145 Select the current group, switch to the summary buffer and display the
1146 first unread article (@code{gnus-group-read-group}). If there are no
1147 unread articles in the group, or if you give a non-numerical prefix to
1148 this command, Gnus will offer to fetch all the old articles in this
1149 group from the server. If you give a numerical prefix @var{N}, Gnus
1150 will fetch @var{N} number of articles. If @var{N} is positive, fetch
1151 the @var{N} newest articles, if @var{N} is negative, fetch the
1152 @var{abs(N)} oldest articles.
1156 @findex gnus-group-select-group
1157 Select the current group and switch to the summary buffer
1158 (@code{gnus-group-select-group}). Takes the same arguments as
1159 @code{gnus-group-read-group}---the only difference is that this command
1160 does not display the first unread article automatically upon group
1164 @kindex M-RET (Group)
1165 @findex gnus-group-quick-select-group
1166 This does the same as the command above, but tries to do it with the
1167 minimum amount off fuzz (@code{gnus-group-quick-select-group}). No
1168 scoring/killing will be performed, there will be no highlights and no
1169 expunging. This might be useful if you're in a real hurry and have to
1170 enter some humongous group.
1173 @kindex M-RET (Group)
1174 @findex gnus-group-visible-select-group
1175 This is yet one more command that does the same as the one above, but
1176 this one does it without expunging and hiding dormants
1177 (@code{gnus-group-visible-select-group}).
1181 @findex gnus-group-catchup-current
1182 @vindex gnus-group-catchup-group-hook
1183 Mark all unticked articles in this group as read
1184 (@code{gnus-group-catchup-current}).
1185 @code{gnus-group-catchup-group-hook} is when catching up a group from
1190 @findex gnus-group-catchup-current-all
1191 Mark all articles in this group, even the ticked ones, as read
1192 (@code{gnus-group-catchup-current-all}).
1195 @vindex gnus-large-newsgroup
1196 The @code{gnus-large-newsgroup} variable says what Gnus should consider
1197 to be a big group. This is 200 by default. If the group has more
1198 unread articles than this, Gnus will query the user before entering the
1199 group. The user can then specify how many articles should be fetched
1200 from the server. If the user specifies a negative number (@code{-n}),
1201 the @code{n} oldest articles will be fetched. If it is positive, the
1202 @code{n} articles that have arrived most recently will be fetched.
1204 @vindex gnus-select-group-hook
1205 @vindex gnus-auto-select-first
1206 @code{gnus-auto-select-first} control whether any articles are selected
1207 automatically when entering a group.
1212 Don't select any articles when entering the group. Just display the
1213 full summary buffer.
1216 Select the first unread article when entering the group.
1219 Select the most high-scored article in the group when entering the
1223 If you want to prevent automatic selection in some group (say, in a
1224 binary group with Huge articles) you can set this variable to @code{nil}
1225 in @code{gnus-select-group-hook}, which is called when a group is
1228 @findex gnus-thread-sort-by-total-score
1229 @findex gnus-thread-sort-by-date
1230 @findex gnus-thread-sort-by-score
1231 @findex gnus-thread-sort-by-subject
1232 @findex gnus-thread-sort-by-author
1233 @findex gnus-thread-sort-by-number
1234 @vindex gnus-thread-sort-functions
1235 If you are using a threaded summary display, you can sort the threads by
1236 setting @code{gnus-thread-sort-functions}, which is a list of functions.
1237 By default, sorting is done on article numbers. Ready-made sorting
1238 predicate functions include @code{gnus-thread-sort-by-number},
1239 @code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
1240 @code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and
1241 @code{gnus-thread-sort-by-total-score}.
1243 Each function takes two threads and return non-@code{nil} if the first
1244 thread should be sorted before the other. Note that sorting really is
1245 normally done by looking only at the roots of each thread. If you use
1246 more than one function, the primary sort key should be the last function
1247 in the list. You should probably always include
1248 @code{gnus-thread-sort-by-number} in the list of sorting
1249 functions---preferably first. This will ensure that threads that are
1250 equal with respect to the other sort criteria will be displayed in
1251 ascending article order.
1253 If you would like to sort by score, then by subject, and finally by
1254 number, you could do something like:
1257 (setq gnus-thread-sort-functions
1258 '(gnus-thread-sort-by-number
1259 gnus-thread-sort-by-subject
1260 gnus-thread-sort-by-score))
1263 The threads that have highest score will be displayed first in the
1264 summary buffer. When threads have the same score, they will be sorted
1265 alphabetically. The threads that have the same score and the same
1266 subject will be sorted by number, which is (normally) the sequence in
1267 which the articles arrived.
1269 If you want to sort by score and then reverse arrival order, you could
1273 (setq gnus-thread-sort-functions
1275 (not (gnus-thread-sort-by-number t1 t2)))
1276 gnus-thread-sort-by-score))
1279 @vindex gnus-thread-score-function
1280 The function in the @code{gnus-thread-score-function} variable (default
1281 @code{+}) is used for calculating the total score of a thread. Useful
1282 functions might be @code{max}, @code{min}, or squared means, or whatever
1285 @findex gnus-article-sort-functions
1286 @findex gnus-article-sort-by-date
1287 @findex gnus-article-sort-by-score
1288 @findex gnus-article-sort-by-subject
1289 @findex gnus-article-sort-by-author
1290 @findex gnus-article-sort-by-number
1291 If you are using an unthreaded display for some strange reason or other,
1292 you have to fiddle with the @code{gnus-article-sort-functions} variable.
1293 It is very similar to the @code{gnus-thread-sort-functions}, except that
1294 is uses slightly different functions for article comparison. Available
1295 sorting predicate functions are @code{gnus-article-sort-by-number},
1296 @code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject},
1297 @code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}.
1299 If you want to sort an unthreaded summary display by subject, you could
1303 (setq gnus-article-sort-functions
1304 '(gnus-article-sort-by-number
1305 gnus-article-sort-by-subject))
1309 @node Subscription Commands
1310 @section Subscription Commands
1319 @findex gnus-group-unsubscribe-current-group
1320 Toggle subscription to the current group
1321 (@code{gnus-group-unsubscribe-current-group}).
1327 @findex gnus-group-unsubscribe-group
1328 Prompt for a group to subscribe, and then subscribe it. If it was
1329 subscribed already, unsubscribe it instead
1330 (@code{gnus-group-unsubscribe-group}).
1336 @findex gnus-group-kill-group
1337 Kill the current group (@code{gnus-group-kill-group}).
1343 @findex gnus-group-yank-group
1344 Yank the last killed group (@code{gnus-group-yank-group}).
1347 @kindex C-x C-t (Group)
1348 @findex gnus-group-transpose-groups
1349 Transpose two groups (@code{gnus-group-transpose-groups}). This isn't
1350 really a subscription command, but you can use it instead of a
1351 kill-and-yank sequence sometimes.
1357 @findex gnus-group-kill-region
1358 Kill all groups in the region (@code{gnus-group-kill-region}).
1362 @findex gnus-group-kill-all-zombies
1363 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
1366 @kindex S C-k (Group)
1367 @findex gnus-group-kill-level
1368 Kill all groups on a certain level (@code{gnus-group-kill-level}).
1369 These groups can't be yanked back after killing, so this command should
1370 be used with some caution. The only thing where this command comes in
1371 really handy is when you have a @file{.newsrc} with lots of unsubscribed
1372 groups that you want to get rid off. @kbd{S C-k} on level @code{7} will
1373 kill off all unsubscribed groups that do not have message numbers in the
1374 @file{.newsrc} file.
1378 Also @pxref{Group Levels}.
1382 @section Group Levels
1385 All groups have a level of @dfn{subscribedness}. For instance, if a
1386 group is on level 2, it is more subscribed than a group on level 5. You
1387 can ask Gnus to just list groups on a given level or lower
1388 (@pxref{Listing Groups}), or to just check for new articles in groups on
1389 a given level or lower (@pxref{Scanning New Messages}).
1395 @findex gnus-group-set-current-level
1396 Set the level of the current group. If a numeric prefix is given, the
1397 next @var{n} groups will have their levels set. The user will be
1398 prompted for a level.
1401 @vindex gnus-level-killed
1402 @vindex gnus-level-zombie
1403 @vindex gnus-level-unsubscribed
1404 @vindex gnus-level-subscribed
1405 Gnus considers groups on between levels 1 and
1406 @code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed,
1407 @code{gnus-level-subscribed} (exclusive) and
1408 @code{gnus-level-unsubscribed} (inclusive) (default 7) to be
1409 unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
1410 (default 8) and @code{gnus-level-killed} to be killed (default 9),
1411 completely dead. Gnus treats subscribed and unsubscribed groups exactly
1412 the same, but zombie and killed groups have no information on what
1413 articles you have read, etc, stored. This distinction between dead and
1414 living groups isn't done because it is nice or clever, it is done purely
1415 for reasons of efficiency.
1417 It is recommended that you keep all your mail groups (if any) on quite
1418 low levels (eg. 1 or 2).
1420 If you want to play with the level variables, you should show some care.
1421 Set them once, and don't touch them ever again. Better yet, don't touch
1422 them at all unless you know exactly what you're doing.
1424 @vindex gnus-level-default-unsubscribed
1425 @vindex gnus-level-default-subscribed
1426 Two closely related variables are @code{gnus-level-default-subscribed}
1427 (default 3) and @code{gnus-level-default-unsubscribed} (default 6),
1428 which are the levels that new groups will be put on if they are
1429 (un)subscribed. These two variables should, of course, be inside the
1430 relevant legal ranges.
1432 @vindex gnus-keep-same-level
1433 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
1434 will only move to groups that are of the same level (or lower). In
1435 particular, going from the last article in one group to the next group
1436 will go to the next group of the same level (or lower). This might be
1437 handy if you want to read the most important groups before you read the
1440 @vindex gnus-group-default-list-level
1441 All groups with a level less than or equal to
1442 @code{gnus-group-default-list-level} will be listed in the group buffer
1445 @vindex gnus-group-list-inactive-groups
1446 If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active
1447 groups will be listed along with the unread groups. This variable is
1448 @code{t} by default. If it is @code{nil}, inactive groups won't be
1451 @vindex gnus-group-use-permanent-levels
1452 If @code{gnus-group-use-permanent-levels} is non-@code{nil}, once you
1453 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
1454 use this level as the ``work'' level.
1456 @vindex gnus-activate-level
1457 Gnus will normally just activate groups that are on level
1458 @code{gnus-activate-level} or less. If you don't want to activate
1459 unsubscribed groups, for instance, you might set this variable to
1464 @section Group Score
1467 You would normally keep important groups on high levels, but that scheme
1468 is somewhat restrictive. Don't you wish you could have Gnus sort the
1469 group buffer according to how often you read groups, perhaps? Within
1472 This is what @dfn{group score} is for. You can assign a score to each
1473 group. You can then sort the group buffer based on this score.
1474 Alternatively, you can sort on score and then level. (Taken together,
1475 the level and the score is called the @dfn{rank} of the group. A group
1476 that is on level 4 and has a score of 1 has a higher rank than a group
1477 on level 5 that has a score of 300. (The level is the most significant
1478 part and the score is the least significant part.)
1480 @findex gnus-summary-bubble-group
1481 If you want groups you read often to get higher scores than groups you
1482 read seldom you can add the @code{gnus-summary-bubble-group} function to
1483 the @code{gnus-summary-exit-hook} hook. This will result (after
1484 sorting) in a bubbling sort of action. If you want to see that in
1485 action after each summary exit, you can add
1486 @code{gnus-group-sort-groups-by-rank} or
1487 @code{gnus-group-sort-groups-by-score} to the same hook, but that will
1488 slow things down somewhat.
1491 @node Marking Groups
1492 @section Marking Groups
1493 @cindex marking groups
1495 If you want to perform some command on several groups, and they appear
1496 subsequently in the group buffer, you would normally just give a
1497 numerical prefix to the command. Most group commands will then do your
1498 bidding on those groups.
1500 However, if the groups are not in sequential order, you can still
1501 perform a command on several groups. You simply mark the groups first
1502 with the process mark and then execute the command.
1510 @findex gnus-group-mark-group
1511 Set the mark on the current group (@code{gnus-group-mark-group}).
1517 @findex gnus-group-unmark-group
1518 Remove the mark from the current group
1519 (@code{gnus-group-unmark-group}).
1523 @findex gnus-group-unmark-all-groups
1524 Remove the mark from all groups (@code{gnus-group-unmark-all-groups}).
1528 @findex gnus-group-mark-region
1529 Mark all groups between point and mark (@code{gnus-group-mark-region}).
1533 @findex gnus-group-mark-buffer
1534 Mark all groups in the buffer (@code{gnus-group-mark-buffer}).
1538 @findex gnus-group-mark-regexp
1539 Mark all groups that match some regular expression
1540 (@code{gnus-group-mark-regexp}).
1543 Also @pxref{Process/Prefix}.
1545 @findex gnus-group-universal-argument
1546 If you want to execute some command on all groups that have been marked
1547 with the process mark, you can use the @kbd{M-&}
1548 (@code{gnus-group-universal-argument}) command. It will prompt you for
1549 the command to be executed.
1552 @node Foreign Groups
1553 @section Foreign Groups
1555 Here are some group mode commands for making and editing general foreign
1556 groups, as well as commands to ease the creation of a few
1557 special-purpose groups:
1563 @findex gnus-group-make-group
1564 Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
1565 for a name, a method and possibly an @dfn{address}. For an easier way
1566 to subscribe to @sc{nntp} groups, @pxref{Browse Foreign Server}.
1570 @findex gnus-group-rename-group
1571 Rename the current group to something else
1572 (@code{gnus-group-rename-group}). This is legal only on some groups --
1573 mail groups mostly. This command might very well be quite slow on some
1578 @findex gnus-group-edit-group-method
1579 Enter a buffer where you can edit the select method of the current
1580 group (@code{gnus-group-edit-group-method}).
1584 @findex gnus-group-edit-group-parameters
1585 Enter a buffer where you can edit the group parameters
1586 (@code{gnus-group-edit-group-parameters}).
1590 @findex gnus-group-edit-group
1591 Enter a buffer where you can edit the group info
1592 (@code{gnus-group-edit-group}).
1596 @findex gnus-group-make-directory-group
1597 Make a directory group. You will be prompted for a directory name
1598 (@code{gnus-group-make-directory-group}).
1602 @findex gnus-group-make-help-group
1603 Make the Gnus help group (@code{gnus-group-make-help-group}).
1607 @findex gnus-group-make-archive-group
1608 @vindex gnus-group-archive-directory
1609 @vindex gnus-group-recent-archive-directory
1610 Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
1611 default a group pointing to the most recent articles will be created
1612 (@code{gnus-group-recent-archive-directory}), but given a prefix, a full
1613 group will be created from from @code{gnus-group-archive-directory}.
1617 @findex gnus-group-make-kiboze-group
1618 Make a kiboze group. You will be prompted for a name, for a regexp to
1619 match groups to be ``included'' in the kiboze group, and a series of
1620 strings to match on headers (@code{gnus-group-make-kiboze-group}).
1624 @findex gnus-group-enter-directory
1625 Read an arbitrary directory as if with were a newsgroup with the
1626 @code{nneething} backend (@code{gnus-group-enter-directory}).
1630 @findex gnus-group-make-doc-group
1631 @cindex ClariNet Briefs
1632 Make a group based on some file or other
1633 (@code{gnus-group-make-doc-group}). If you give a prefix to this
1634 command, you will be prompted for a file name and a file type.
1635 Currently supported types are @code{babyl}, @code{mbox}, @code{digest},
1636 @code{mmdf}, @code{news}, @code{rnews}, @code{clari-briefs}, and
1637 @code{forward}. If you run this command without a prefix, Gnus will
1638 guess at the file type.
1641 @kindex G DEL (Group)
1642 @findex gnus-group-delete-group
1643 This function will delete the current group
1644 (@code{gnus-group-delete-group}). If given a prefix, this function will
1645 actually delete all the articles in the group, and forcibly remove the
1646 group itself from the face of the Earth. Use a prefix only if you are
1647 absolutely sure of what you are doing.
1651 @findex gnus-group-make-empty-virtual
1652 Make a new, fresh, empty @code{nnvirtual} group
1653 (@code{gnus-group-make-empty-virtual}).
1657 @findex gnus-group-add-to-virtual
1658 Add the current group to an @code{nnvirtual} group
1659 (@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
1662 @xref{Select Methods} for more information on the various select
1665 @vindex gnus-activate-foreign-newsgroups
1666 If the @code{gnus-activate-foreign-newsgroups} is a positive number,
1667 Gnus will check all foreign groups with this level or lower at startup.
1668 This might take quite a while, especially if you subscribe to lots of
1669 groups from different @sc{nntp} servers.
1672 @node Group Parameters
1673 @section Group Parameters
1674 @cindex group parameters
1676 Gnus stores all information on a group in a list that is usually known
1677 as the @dfn{group info}. This list has from three to six elements.
1678 Here's an example info.
1681 ("nnml:mail.ding" 3 ((1 . 232) 244 (256 . 270)) ((tick 246 249))
1682 (nnml "private") ((to-address . "ding@@ifi.uio.no")))
1685 The first element is the @dfn{group name}, as Gnus knows the group,
1686 anyway. The second element is the @dfn{subscription level}, which
1687 normally is a small integer. The third element is a list of ranges of
1688 read articles. The fourth element is a list of lists of article marks
1689 of various kinds. The fifth element is the select method (or virtual
1690 server, if you like). The sixth element is a list of @dfn{group
1691 parameters}, which is what this section is about.
1693 Any of the last three elements may be missing if they are not required.
1694 In fact, the vast majority of groups will normally only have the first
1695 three elements, which saves quite a lot of cons cells.
1697 The group parameters store information local to a particular group:
1702 If the group parameter list contains an element that looks like
1703 @code{(to-address . "some@@where.com")}, that address will be used by
1704 the backend when doing followups and posts. This is primarily useful in
1705 mail groups that represent closed mailing lists---mailing lists where
1706 it's expected that everybody that writes to the mailing list is
1707 subscribed to it. Since using this parameter ensures that the mail only
1708 goes to the mailing list itself, it means that members won't receive two
1709 copies of your followups.
1711 Using @code{to-address} will actually work whether the group is foreign
1712 or not. Let's say there's a group on the server that is called
1713 @samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten
1714 the articles from a mail-to-news gateway. Posting directly to this
1715 group is therefore impossible---you have to send mail to the mailing
1716 list address instead.
1720 If the group parameter list has an element that looks like
1721 @code{(to-list . "some@@where.com")}, that address will be used when
1722 doing a @kbd{a} in any group. It is totally ignored when doing a
1723 followup---except that if it is present in a news group, you'll get mail
1724 group semantics when doing @kbd{f}.
1726 @item broken-reply-to
1727 @cindex broken-reply-to
1728 Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To}
1729 headers in this group are to be ignored. This can be useful if you're
1730 reading a mailing list group where the listserv has inserted
1731 @code{Reply-To} headers that point back to the listserv itself. This is
1732 broken behavior. So there!
1736 If the group parameter list contains an element like @code{(to-group
1737 . "some.group.name")}, all posts will be sent to that group.
1741 If this symbol is present in the group parameter list, all articles that
1742 are read will be marked as expirable. For an alternative approach,
1743 @pxref{Expiring Mail}.
1746 @cindex total-expire
1747 If this symbol is present, all read articles will be put through the
1748 expiry process, even if they are not marked as expirable. Use with
1753 @vindex nnmail-expiry-wait-function
1754 If the group parameter has an element that looks like @code{(expiry-wait
1755 . 10)}, this value will override any @code{nnmail-expiry-wait} and
1756 @code{nnmail-expiry-wait-function} when expiring expirable messages.
1757 The value can either be a number of days (not necessarily an integer) or
1758 the symbols @code{never} or @code{immediate}.
1761 Elements that look like @code{(score-file . "file")} will make
1762 @samp{file} into the current score file for the group in question. This
1763 means that all score commands you issue will end up in that file.
1766 When unsubscribing to a mailing list you should never send the
1767 unsubscription notice to the mailing list itself. Instead, you'd send
1768 messages to the administrative address. This parameter allows you to
1769 put the admin address somewhere convenient.
1772 This parameter allows you to enter a arbitrary comment on the group.
1774 @item @var{(variable form)}
1775 You can use the group parameters to set variables local to the group you
1776 are entering. Say you want to turn threading off in
1777 @samp{news.answers}. You'd then put @code{(gnus-show-threads nil)} in
1778 the group parameters of that group. @code{gnus-show-threads} will be
1779 made into a local variable in the summary buffer you enter, and the form
1780 @code{nil} will be @code{eval}ed there.
1782 This can also be used as a group-specific hook function, if you'd like.
1783 If you want to hear a beep when you enter the group
1784 @samp{alt.binaries.pictures.furniture}, you could put something like
1785 @code{(dummy-variable (ding))} in the parameters of that group.
1786 @code{dummy-variable} will be set to the result of the @code{(ding)}
1787 form, but who cares?
1791 If you want to change the group info you can use the @kbd{G E} command
1792 to enter a buffer where you can edit it.
1794 You usually don't want to edit the entire group info, so you'd be better
1795 off using the @kbd{G p} command to just edit the group parameters.
1798 @node Listing Groups
1799 @section Listing Groups
1800 @cindex group listing
1802 These commands all list various slices of the groups that are available.
1810 @findex gnus-group-list-groups
1811 List all groups that have unread articles
1812 (@code{gnus-group-list-groups}). If the numeric prefix is used, this
1813 command will list only groups of level ARG and lower. By default, it
1814 only lists groups of level five or lower (i.e., just subscribed groups).
1820 @findex gnus-group-list-all-groups
1821 List all groups, whether they have unread articles or not
1822 (@code{gnus-group-list-all-groups}). If the numeric prefix is used,
1823 this command will list only groups of level ARG and lower. By default,
1824 it lists groups of level seven or lower (i.e., just subscribed and
1825 unsubscribed groups).
1829 @findex gnus-group-list-level
1830 List all unread groups on a specific level
1831 (@code{gnus-group-list-level}). If given a prefix, also list the groups
1832 with no unread articles.
1836 @findex gnus-group-list-killed
1837 List all killed groups (@code{gnus-group-list-killed}). If given a
1838 prefix argument, really list all groups that are available, but aren't
1839 currently (un)subscribed. This could entail reading the active file
1844 @findex gnus-group-list-zombies
1845 List all zombie groups (@code{gnus-group-list-zombies}).
1849 @findex gnus-group-list-matching
1850 List all subscribed groups with unread articles that match a regexp
1851 (@code{gnus-group-list-matching}).
1855 @findex gnus-group-list-all-matching
1856 List groups that match a regexp (@code{gnus-group-list-all-matching}).
1860 @findex gnus-group-list-active
1861 List absolutely all groups that are in the active file(s) of the
1862 server(s) you are connected to (@code{gnus-group-list-active}). This
1863 might very well take quite a while. It might actually be a better idea
1864 to do a @kbd{A m} to list all matching, and just give @samp{.} as the
1869 @findex gnus-group-apropos
1870 List all groups that have names that match a regexp
1871 (@code{gnus-group-apropos}).
1875 @findex gnus-group-description-apropos
1876 List all groups that have names or descriptions that match a regexp
1877 (@code{gnus-group-description-apropos}).
1881 @vindex gnus-permanently-visible-groups
1882 @cindex visible group parameter
1883 Groups that match the @code{gnus-permanently-visible-groups} regexp will
1884 always be shown, whether they have unread articles or not. You can also
1885 add the @code{visible} element to the group parameters in question to
1886 get the same effect.
1888 @vindex gnus-list-groups-with-ticked-articles
1889 Groups that have just ticked articles in it are normally listed in the
1890 group buffer. If @code{gnus-list-groups-with-ticked-articles} is
1891 @code{nil}, these groups will be treated just like totally empty
1892 groups. It is @code{t} by default.
1895 @node Sorting Groups
1896 @section Sorting Groups
1897 @cindex sorting groups
1899 @kindex C-c C-s (Group)
1900 @findex gnus-group-sort-groups
1901 @vindex gnus-group-sort-function
1902 The @kbd{C-c C-s} (@code{gnus-group-sort-groups}) command sorts the
1903 group buffer according to the function(s) given by the
1904 @code{gnus-group-sort-function} variable. Available sorting functions
1909 @item gnus-group-sort-by-alphabet
1910 @findex gnus-group-sort-by-alphabet
1911 Sort the group names alphabetically. This is the default.
1913 @item gnus-group-sort-by-level
1914 @findex gnus-group-sort-by-level
1915 Sort by group level.
1917 @item gnus-group-sort-by-score
1918 @findex gnus-group-sort-by-score
1919 Sort by group score.
1921 @item gnus-group-sort-by-rank
1922 @findex gnus-group-sort-by-rank
1923 Sort by group score and then the group level. The level and the score
1924 are, when taken together, the group's @dfn{rank}.
1926 @item gnus-group-sort-by-unread
1927 @findex gnus-group-sort-by-unread
1928 Sort by number of unread articles.
1930 @item gnus-group-sort-by-method
1931 @findex gnus-group-sort-by-method
1932 Sort by alphabetically on the select method.
1937 @code{gnus-group-sort-function} can also be a list of sorting
1938 functions. In that case, the most significant sort key function must be
1942 There are also a number of commands for sorting directly according to
1943 some sorting criteria:
1947 @kindex G S a (Group)
1948 @findex gnus-group-sort-groups-by-alphabet
1949 Sort the group buffer alphabetically by group name
1950 (@code{gnus-group-sort-groups-by-alphabet}).
1953 @kindex G S u (Group)
1954 @findex gnus-group-sort-groups-by-unread
1955 Sort the group buffer by the number of unread articles
1956 (@code{gnus-group-sort-groups-by-unread}).
1959 @kindex G S l (Group)
1960 @findex gnus-group-sort-groups-by-level
1961 Sort the group buffer by group level
1962 (@code{gnus-group-sort-groups-by-level}).
1965 @kindex G S v (Group)
1966 @findex gnus-group-sort-groups-by-score
1967 Sort the group buffer by group score
1968 (@code{gnus-group-sort-groups-by-score}).
1971 @kindex G S r (Group)
1972 @findex gnus-group-sort-groups-by-rank
1973 Sort the group buffer by group level
1974 (@code{gnus-group-sort-groups-by-rank}).
1977 @kindex G S m (Group)
1978 @findex gnus-group-sort-groups-by-method
1979 Sort the group buffer alphabetically by backend name
1980 (@code{gnus-group-sort-groups-by-method}).
1984 When given a prefix, all these commands will sort in reverse order.
1987 @node Group Maintenance
1988 @section Group Maintenance
1989 @cindex bogus groups
1994 @findex gnus-group-check-bogus-groups
1995 Find bogus groups and delete them
1996 (@code{gnus-group-check-bogus-groups}).
2000 @findex gnus-find-new-newsgroups
2001 Find new groups and process them (@code{gnus-find-new-newsgroups}). If
2002 given a prefix, use the @code{ask-server} method to query the server for
2006 @kindex C-c C-x (Group)
2007 @findex gnus-group-expire-articles
2008 Run all expirable articles in the current group through the expiry
2009 process (if any) (@code{gnus-group-expire-articles}).
2012 @kindex C-c M-C-x (Group)
2013 @findex gnus-group-expire-all-groups
2014 Run all articles in all groups through the expiry process
2015 (@code{gnus-group-expire-all-groups}).
2020 @node Browse Foreign Server
2021 @section Browse Foreign Server
2022 @cindex foreign servers
2023 @cindex browsing servers
2028 @findex gnus-group-browse-foreign-server
2029 You will be queried for a select method and a server name. Gnus will
2030 then attempt to contact this server and let you browse the groups there
2031 (@code{gnus-group-browse-foreign-server}).
2034 @findex gnus-browse-server-mode
2035 A new buffer with a list of available groups will appear. This buffer
2036 will be use the @code{gnus-browse-server-mode}. This buffer looks a bit
2037 (well, a lot) like a normal group buffer, but with one major difference
2038 - you can't enter any of the groups. If you want to read any of the
2039 news available on that server, you have to subscribe to the groups you
2040 think may be interesting, and then you have to exit this buffer. The
2041 new groups will be added to the group buffer, and then you can read them
2042 as you would any other group.
2044 Future versions of Gnus may possibly permit reading groups straight from
2047 Here's a list of keystrokes available in the browse mode:
2052 @findex gnus-group-next-group
2053 Go to the next group (@code{gnus-group-next-group}).
2057 @findex gnus-group-prev-group
2058 Go to the previous group (@code{gnus-group-prev-group}).
2061 @kindex SPACE (Browse)
2062 @findex gnus-browse-read-group
2063 Enter the current group and display the first article
2064 (@code{gnus-browse-read-group}).
2067 @kindex RET (Browse)
2068 @findex gnus-browse-select-group
2069 Enter the current group (@code{gnus-browse-select-group}).
2073 @findex gnus-browse-unsubscribe-current-group
2074 Unsubscribe to the current group, or, as will be the case here,
2075 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
2081 @findex gnus-browse-exit
2082 Exit browse mode (@code{gnus-browse-exit}).
2086 @findex gnus-browse-describe-briefly
2087 Describe browse mode briefly (well, there's not much to describe, is
2088 there) (@code{gnus-browse-describe-briefly}).
2093 @section Exiting Gnus
2094 @cindex exiting Gnus
2096 Yes, Gnus is ex(c)iting.
2101 @findex gnus-group-suspend
2102 Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
2103 but it kills all buffers except the Group buffer. I'm not sure why this
2104 is a gain, but then who am I to judge?
2108 @findex gnus-group-exit
2109 Quit Gnus (@code{gnus-group-exit}).
2113 @findex gnus-group-quit
2114 Quit Gnus without saving any startup files (@code{gnus-group-quit}).
2117 @vindex gnus-exit-gnus-hook
2118 @vindex gnus-suspend-gnus-hook
2119 @code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
2120 @code{gnus-exit-gnus-hook} is called when you quit Gnus, while
2121 @code{gnus-after-exiting-gnus-hook} is called as the final item when
2126 If you wish to completely unload Gnus and all its adherents, you can use
2127 the @code{gnus-unload} command. This command is also very handy when
2128 trying to customize meta-variables.
2133 Miss Lisa Cannifax, while sitting in English class, feels her feet go
2134 numbly heavy and herself fall into a hazy trance as the boy sitting
2135 behind her drew repeated lines with his pencil across the back of her
2141 @section Group Topics
2144 If you read lots and lots of groups, it might be convenient to group
2145 them hierarchically according to topics. You put your Emacs groups over
2146 here, your sex groups over there, and the rest (what, two groups or so?)
2147 you put in some misc section that you never bother with anyway. You can
2148 even group the Emacs sex groups as a sub-topic to either the Emacs
2149 groups or the sex groups---or both! Go wild!
2151 @findex gnus-topic-mode
2153 To get this @emph{fab} functionality you simply turn on (ooh!) the
2154 @code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This
2155 is a toggling command.)
2157 Go ahead, just try it. I'll still be here when you get back. La de
2158 dum... Nice tune, that... la la la... What, you're back? Yes, and now
2159 press @kbd{l}. There. All your groups are now listed under
2160 @samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
2163 If you want this permanently enabled, you should add that minor mode to
2164 the hook for the group mode:
2167 (add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
2171 * Topic Variables:: How to customize the topics the Lisp Way.
2172 * Topic Commands:: Interactive E-Z commands.
2173 * Topic Topology:: A map of the world.
2177 @node Topic Variables
2178 @subsection Topic Variables
2179 @cindex topic variables
2181 @vindex gnus-topic-unique
2182 If @code{gnus-topic-unique} is non-@code{nil}, each group will be member
2183 of (tops) one topic each. If this is @code{nil}, each group might end
2184 up being a member of several topics.
2186 Now, if you select a topic, if will fold/unfold that topic, which is
2187 really neat, I think.
2189 @vindex gnus-topic-line-format
2190 The topic lines themselves are created according to the
2191 @code{gnus-topic-line-format} variable. @xref{Formatting Variables}.
2192 Elements allowed are:
2204 Number of groups in the topic.
2206 Number of unread articles in the topic.
2208 Number of unread articles in the topic and all its subtopics.
2211 @vindex gnus-topic-indent-level
2212 Each sub-topic (and the groups in the sub-topics) will be indented with
2213 @code{gnus-topic-indent-level} times the topic level number of spaces.
2214 The default is @code{2}.
2216 @vindex gnus-topic-mode-hook
2217 @code{gnus-topic-mode-hook} is called in topic minor mode buffers.
2220 @node Topic Commands
2221 @subsection Topic Commands
2222 @cindex topic commands
2224 When the topic minor mode is turned on, a new @kbd{T} submap will be
2225 available. In addition, a few of the standard keys change their
2226 definitions slightly.
2232 @findex gnus-topic-create-topic
2233 Prompt for a new topic name and create it
2234 (@code{gnus-topic-create-topic}).
2238 @findex gnus-topic-move-group
2239 Move the current group to some other topic
2240 (@code{gnus-topic-move-group}). This command understands the
2241 process/prefix convention (@pxref{Process/Prefix}).
2245 @findex gnus-topic-copy-group
2246 Copy the current group to some other topic
2247 (@code{gnus-topic-copy-group}). This command understands the
2248 process/prefix convention (@pxref{Process/Prefix}).
2252 @findex gnus-topic-remove-group
2253 Remove a group from the current topic (@code{gnus-topic-remove-group}).
2254 This command understands the process/prefix convention
2255 (@pxref{Process/Prefix}).
2259 @findex gnus-topic-move-matching
2260 Move all groups that match some regular expression to a topic
2261 (@code{gnus-topic-move-matching}).
2265 @findex gnus-topic-copy-matching
2266 Copy all groups that match some regular expression to a topic
2267 (@code{gnus-topic-copy-matching}).
2271 @findex gnus-topic-mark-topic
2272 Mark all groups in the current topic with the process mark
2273 (@code{gnus-topic-mark-topic}).
2276 @kindex T M-# (Group)
2277 @findex gnus-topic-unmark-topic
2278 Remove the process mark from all groups in the current topic
2279 (@code{gnus-topic-unmark-topic}).
2283 @findex gnus-topic-select-group
2285 Either select a group or fold a topic (@code{gnus-topic-select-group}).
2286 When you perform this command on a group, you'll enter the group, as
2287 usual. When done on a topic line, the topic will be folded (if it was
2288 visible) or unfolded (if it was folded already). So it's basically a
2289 toggling command on topics. In addition, if you give a numerical
2290 prefix, group on that level (and lower) will be displayed.
2293 @kindex T TAB (Group)
2294 @findex gnus-topic-indent
2295 ``Indent'' the current topic so that it becomes a sub-topic of the
2296 previous topic (@code{gnus-topic-indent}). If given a prefix,
2297 ``un-indent'' the topic instead.
2301 @findex gnus-topic-kill-group
2302 Kill a group or topic (@code{gnus-topic-kill-group}).
2306 @findex gnus-topic-yank-group
2307 Yank the previously killed group or topic (@code{gnus-topic-yank-group}).
2308 Note that all topics will be yanked before all groups.
2312 @findex gnus-topic-rename
2313 Rename a topic (@code{gnus-topic-rename}).
2316 @kindex T DEL (Group)
2317 @findex gnus-topic-delete
2318 Delete an empty topic (@code{gnus-topic-delete}).
2322 @findex gnus-topic-list-active
2323 List all groups that Gnus knows about in a topics-ified way
2324 (@code{gnus-topic-list-active}).
2329 @node Topic Topology
2330 @subsection Topic Topology
2331 @cindex topic topology
2334 So, let's have a look at an example group buffer:
2340 2: alt.religion.emacs
2343 0: comp.talk.emacs.recovery
2345 8: comp.binaries.fractals
2346 13: comp.sources.unix
2349 So, here we have one top-level topic, two topics under that, and one
2350 sub-topic under one of the sub-topics. (There is always just one (1)
2351 top-level topic). This topology can be expressed as follows:
2355 (("Emacs -- I wuw it!" visible)
2356 (("Naughty Emacs" visible)))
2360 @vindex gnus-topic-topology
2361 This is in fact how the variable @code{gnus-topic-topology} would look
2362 for the display above. That variable is saved in the @file{.newsrc.eld}
2363 file, and shouldn't be messed with manually---unless you really want
2364 to. Since this variable is read from the @file{.newsrc.eld} file,
2365 setting it in any other startup files will have no effect.
2367 This topology shows what topics are sub-topics of what topics (right),
2368 and which topics are visible. Two settings are currently
2369 allowed---@code{visible} and @code{invisible}.
2372 @node Misc Group Stuff
2373 @section Misc Group Stuff
2376 * Scanning New Messages:: Asking Gnus to see whether new messages have arrived.
2377 * Group Information:: Information and help on groups and Gnus.
2378 * File Commands:: Reading and writing the Gnus files.
2385 @findex gnus-group-enter-server-mode
2386 Enter the server buffer (@code{gnus-group-enter-server-mode}). @xref{The
2391 @findex gnus-group-post-news
2392 Post an article to a group (@code{gnus-group-post-news}). The current
2393 group name will be used as the default.
2397 @findex gnus-group-mail
2398 Mail a message somewhere (@code{gnus-group-mail}).
2402 Variables for the group buffer:
2406 @item gnus-group-mode-hook
2407 @vindex gnus-group-mode-hook
2408 @code{gnus-group-mode-hook} is called after the group buffer has been
2411 @item gnus-group-prepare-hook
2412 @vindex gnus-group-prepare-hook
2413 @code{gnus-group-prepare-hook} is called after the group buffer is
2414 generated. It may be used to modify the buffer in some strange,
2417 @item gnus-permanently-visible-groups
2418 @vindex gnus-permanently-visible-groups
2419 Groups matching this regexp will always be listed in the group buffer,
2420 whether they are empty or not.
2425 @node Scanning New Messages
2426 @subsection Scanning New Messages
2427 @cindex new messages
2428 @cindex scanning new news
2434 @findex gnus-group-get-new-news
2435 Check the server(s) for new articles. If the numerical prefix is used,
2436 this command will check only groups of level @var{arg} and lower
2437 (@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
2438 command will force a total rereading of the active file(s) from the
2443 @findex gnus-group-get-new-news-this-group
2444 @vindex gnus-goto-next-group-when-activating
2445 Check whether new articles have arrived in the current group
2446 (@code{gnus-group-get-new-news-this-group}). The
2447 @code{gnus-goto-next-group-when-activating} variable controls whether
2448 this command is to move point to the next group or not. It is @code{t}
2451 @findex gnus-activate-all-groups
2452 @cindex activating groups
2454 @kindex C-c M-g (Group)
2455 Activate absolutely all groups (@code{gnus-activate-all-groups}).
2460 @findex gnus-group-restart
2461 Restart Gnus (@code{gnus-group-restart}).
2465 @vindex gnus-get-new-news-hook
2466 @code{gnus-get-new-news-hook} is run just before checking for new news.
2468 @vindex gnus-after-getting-new-news-hook
2469 @code{gnus-after-getting-new-news-hook} is run after checking for new
2473 @node Group Information
2474 @subsection Group Information
2475 @cindex group information
2476 @cindex information on groups
2482 @findex gnus-group-fetch-faq
2485 Try to fetch the FAQ for the current group
2486 (@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
2487 @code{gnus-group-faq-directory}, which is usually a directory on a
2488 remote machine. @code{ange-ftp} will be used for fetching the file.
2492 @cindex describing groups
2493 @cindex group description
2494 @findex gnus-group-describe-group
2495 Describe the current group (@code{gnus-group-describe-group}). If given
2496 a prefix, force Gnus to re-read the description from the server.
2500 @findex gnus-group-describe-all-groups
2501 Describe all groups (@code{gnus-group-describe-all-groups}). If given a
2502 prefix, force Gnus to re-read the description file from the server.
2507 @findex gnus-version
2508 Display current Gnus version numbers (@code{gnus-version}).
2512 @findex gnus-group-describe-briefly
2513 Give a very short help message (@code{gnus-group-describe-briefly}).
2516 @kindex C-c C-i (Group)
2519 @findex gnus-info-find-node
2520 Go to the Gnus info node (@code{gnus-info-find-node}).
2525 @subsection File Commands
2526 @cindex file commands
2532 @findex gnus-group-read-init-file
2533 @vindex gnus-init-file
2534 @cindex reading init file
2535 Read the init file (@code{gnus-init-file}, which defaults to
2536 @file{~/.gnus}) (@code{gnus-group-read-init-file}).
2540 @findex gnus-group-save-newsrc
2541 @cindex saving .newsrc
2542 Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
2543 (@code{gnus-group-save-newsrc}). If given a prefix, force saving the
2544 file(s) whether Gnus thinks it is necessary or not.
2548 @findex gnus-group-clear-dribble
2549 Clear the dribble buffer (@code{gnus-group-clear-dribble}).
2554 @node The Summary Buffer
2555 @chapter The Summary Buffer
2556 @cindex summary buffer
2558 A line for each article is displayed in the summary buffer. You can
2559 move around, read articles, post articles and reply to articles.
2562 * Summary Buffer Format:: Deciding how the summary buffer is to look.
2563 * Summary Maneuvering:: Moving around the summary buffer.
2564 * Choosing Articles:: Reading articles.
2565 * Paging the Article:: Scrolling the current article.
2566 * Reply Followup and Post:: Posting articles.
2567 * Canceling and Superseding:: ``Whoops, I shouldn't have called him that.''
2568 * Marking Articles:: Marking articles as read, expirable, etc.
2569 * Limiting:: You can limit the summary buffer.
2570 * Threading:: How threads are made.
2571 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
2572 * Article Caching:: You may store articles in a cache.
2573 * Persistent Articles:: Making articles expiry-resistant.
2574 * Article Backlog:: Having already read articles hang around.
2575 * Saving Articles:: Ways of customizing article saving.
2576 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
2577 * Article Treatment:: The article buffer can be mangled at will.
2578 * Summary Sorting:: Sorting the summary buffer in various ways.
2579 * Finding the Parent:: No child support? Get the parent.
2580 * Alternative Approaches:: Reading using non-default summaries.
2581 * Tree Display:: A more visual display of threads.
2582 * Mail Group Commands:: Some commands can only be used in mail groups.
2583 * Various Summary Stuff:: What didn't fit anywhere else.
2584 * Exiting the Summary Buffer:: Returning to the Group buffer.
2588 @node Summary Buffer Format
2589 @section Summary Buffer Format
2590 @cindex summary buffer format
2593 * Summary Buffer Lines:: You can specify how summary lines should look.
2594 * Summary Buffer Mode Line:: You can say how the mode line should look.
2595 * Summary Highlighting:: Making the summary buffer all pretty and nice.
2598 @findex mail-extract-address-components
2599 @findex gnus-extract-address-components
2600 @vindex gnus-extract-address-components
2601 Gnus will use the value of the @code{gnus-extract-address-components}
2602 variable as a function for getting the name and address parts of a
2603 @code{From} header. Two pre-defined function exist:
2604 @code{gnus-extract-address-components}, which is the default, quite
2605 fast, and too simplistic solution; and
2606 @code{mail-extract-address-components}, which works very nicely, but is
2609 @vindex gnus-summary-same-subject
2610 @code{gnus-summary-same-subject} is a string indicating that the current
2611 article has the same subject as the previous. This string will be used
2612 with those specs that require it. The default is @samp{}.
2615 @node Summary Buffer Lines
2616 @subsection Summary Buffer Lines
2618 @vindex gnus-summary-line-format
2619 You can change the format of the lines in the summary buffer by changing
2620 the @code{gnus-summary-line-format} variable. It works along the same
2621 lines a a normal @code{format} string, with some extensions.
2623 The default string is @samp{%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n}.
2625 The following format specification characters are understood:
2633 Subject if the article is the root, @code{gnus-summary-same-subject}
2636 Full @code{From} line.
2638 The name (from the @code{From} header).
2640 The name (from the @code{From} header). This differs from the @code{n}
2641 spec in that it uses @code{gnus-extract-address-components}, which is
2642 slower, but may be more thorough.
2644 The address (from the @code{From} header). This works the same way as
2647 Number of lines in the article.
2649 Number of characters in the article.
2651 Indentation based on thread level (@pxref{Customizing Threading}).
2653 Nothing if the article is a root and lots of spaces if it isn't (it
2654 pushes everything after it off the screen).
2656 Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
2657 for adopted articles.
2659 Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
2660 for adopted articles.
2662 One space for each thread level.
2664 Twenty minus thread level spaces.
2672 @vindex gnus-summary-zcore-fuzz
2673 Zcore, @samp{+} if above the default level and @samp{-} if below the
2674 default level. If the difference between
2675 @code{gnus-summary-default-level} and the score is less than
2676 @code{gnus-summary-zcore-fuzz}, this spec will not be used.
2688 Number of articles in the current sub-thread. Using this spec will slow
2689 down summary buffer generation somewhat.
2691 A single character will be displayed if the article has any children.
2693 User defined specifier. The next character in the format string should
2694 be a letter. @sc{gnus} will call the function
2695 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
2696 following @samp{%u}. The function will be passed the current header as
2697 argument. The function should return a string, which will be inserted
2698 into the summary just like information from any other summary specifier.
2701 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
2702 have to be handled with care. For reasons of efficiency, Gnus will
2703 compute what column these characters will end up in, and ``hard-code''
2704 that. This means that it is illegal to have these specs after a
2705 variable-length spec. Well, you might not be arrested, but your summary
2706 buffer will look strange, which is bad enough.
2708 The smart choice is to have these specs as far to the left as possible.
2709 (Isn't that the case with everything, though? But I digress.)
2711 This restriction may disappear in later versions of Gnus.
2714 @node Summary Buffer Mode Line
2715 @subsection Summary Buffer Mode Line
2717 @vindex gnus-summary-mode-line-format
2718 You can also change the format of the summary mode bar. Set
2719 @code{gnus-summary-mode-line-format} to whatever you like. Here are the
2720 elements you can play with:
2726 Unprefixed group name.
2728 Current article number.
2732 Number of unread articles in this group.
2734 Number of unselected articles in this group.
2736 A string with the number of unread and unselected articles represented
2737 either as @samp{<%U(+%u) more>} if there are both unread and unselected
2738 articles, and just as @samp{<%U more>} if there are just unread articles
2739 and no unselected ones.
2741 Shortish group name. For instance, @samp{rec.arts.anime} will be
2742 shortened to @samp{r.a.anime}.
2744 Subject of the current article.
2748 Name of the current score file.
2750 Number of dormant articles.
2752 Number of ticked articles.
2754 Number of articles that have been marked as read in this session.
2756 Number of articles expunged by the score files.
2760 @node Summary Highlighting
2761 @subsection Summary Highlighting
2765 @item gnus-visual-mark-article-hook
2766 @vindex gnus-visual-mark-article-hook
2767 This hook is run after selecting an article. It is meant to be used for
2768 highlighting the article in some way. It is not run if
2769 @code{gnus-visual} is @code{nil}.
2771 @item gnus-summary-update-hook
2772 @vindex gnus-summary-update-hook
2773 This hook is called when a summary line is changed. It is not run if
2774 @code{gnus-visual} is @code{nil}.
2776 @item gnus-summary-selected-face
2777 @vindex gnus-summary-selected-face
2778 This is the face (or @dfn{font} as some people call it) that is used to
2779 highlight the current article in the summary buffer.
2781 @item gnus-summary-highlight
2782 @vindex gnus-summary-highlight
2783 Summary lines are highlighted according to this variable, which is a
2784 list where the elements are on the format @code{(FORM . FACE)}. If you
2785 would, for instance, like ticked articles to be italic and high-scored
2786 articles to be bold, you could set this variable to something like
2788 (((eq mark gnus-ticked-mark) . italic)
2789 ((> score default) . bold))
2791 As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
2792 @var{FACE} will be applied to the line.
2796 @node Summary Maneuvering
2797 @section Summary Maneuvering
2798 @cindex summary movement
2800 All the straight movement commands understand the numeric prefix and
2801 behave pretty much as you'd expect.
2803 None of these commands select articles.
2808 @kindex M-n (Summary)
2809 @kindex G M-n (Summary)
2810 @findex gnus-summary-next-unread-subject
2811 Go to the next summary line of an unread article
2812 (@code{gnus-summary-next-unread-subject}).
2816 @kindex M-p (Summary)
2817 @kindex G M-p (Summary)
2818 @findex gnus-summary-prev-unread-subject
2819 Go to the previous summary line of an unread article
2820 (@code{gnus-summary-prev-unread-subject}).
2825 @kindex G j (Summary)
2826 @findex gnus-summary-goto-article
2827 Ask for an article number and then go that article
2828 (@code{gnus-summary-goto-article}).
2831 @kindex G g (Summary)
2832 @findex gnus-summary-goto-subject
2833 Ask for an article number and then go the summary line of that article
2834 (@code{gnus-summary-goto-subject}).
2837 If Gnus asks you to press a key to confirm going to the next group, you
2838 can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
2839 buffer, searching for the next group to read without actually returning
2840 to the group buffer.
2842 Variables related to summary movement:
2846 @vindex gnus-auto-select-next
2847 @item gnus-auto-select-next
2848 If you are at the end of the group and issue one of the movement
2849 commands, Gnus will offer to go to the next group. If this variable is
2850 @code{t} and the next group is empty, Gnus will exit summary mode and
2851 return to the group buffer. If this variable is neither @code{t} nor
2852 @code{nil}, Gnus will select the next group, no matter whether it has
2853 any unread articles or not. As a special case, if this variable is
2854 @code{quietly}, Gnus will select the next group without asking for
2855 confirmation. If this variable is @code{almost-quietly}, the same will
2856 happen only if you are located on the last article in the group.
2857 Finally, if this variable is @code{slightly-quietly}, the @kbd{Z n}
2858 command will go to the next group without confirmation. Also
2859 @pxref{Group Levels}.
2861 @item gnus-auto-select-same
2862 @vindex gnus-auto-select-same
2863 If non-@code{nil}, all the movement commands will try to go to the next
2864 article with the same subject as the current. This variable is not
2865 particularly useful if you use a threaded display.
2867 @item gnus-summary-check-current
2868 @vindex gnus-summary-check-current
2869 If non-@code{nil}, all the ``unread'' movement commands will not proceed
2870 to the next (or previous) article if the current article is unread.
2871 Instead, they will choose the current article.
2873 @item gnus-auto-center-summary
2874 @vindex gnus-auto-center-summary
2875 If non-@code{nil}, Gnus will keep the point in the summary buffer
2876 centered at all times. This makes things quite tidy, but if you have a
2877 slow network connection, or simply do not like this un-Emacsism, you can
2878 set this variable to @code{nil} to get the normal Emacs scrolling
2879 action. This will also inhibit horizontal re-centering of the summary
2880 buffer, which might make it more inconvenient to read extremely long
2886 @node Choosing Articles
2887 @section Choosing Articles
2888 @cindex selecting articles
2890 None of the following movement commands understand the numeric prefix,
2891 and they all select and display an article.
2895 @kindex SPACE (Summary)
2896 @findex gnus-summary-next-page
2897 Select the current article, or, if that one's read already, the next
2898 unread article (@code{gnus-summary-next-page}).
2903 @kindex G n (Summary)
2904 @findex gnus-summary-next-unread-article
2905 Go to next unread article (@code{gnus-summary-next-unread-article}).
2910 @findex gnus-summary-prev-unread-article
2911 Go to previous unread article (@code{gnus-summary-prev-unread-article}).
2916 @kindex G N (Summary)
2917 @findex gnus-summary-next-article
2918 Go to the next article (@code{gnus-summary-next-article}).
2923 @kindex G P (Summary)
2924 @findex gnus-summary-prev-article
2925 Go to the previous article (@code{gnus-summary-prev-article}).
2928 @kindex G C-n (Summary)
2929 @findex gnus-summary-next-same-subject
2930 Go to the next article with the same subject
2931 (@code{gnus-summary-next-same-subject}).
2934 @kindex G C-p (Summary)
2935 @findex gnus-summary-prev-same-subject
2936 Go to the previous article with the same subject
2937 (@code{gnus-summary-prev-same-subject}).
2941 @kindex G f (Summary)
2943 @findex gnus-summary-first-unread-article
2944 Go to the first unread article
2945 (@code{gnus-summary-first-unread-article}).
2949 @kindex G b (Summary)
2951 @findex gnus-summary-best-unread-article
2952 Go to the article with the highest score
2953 (@code{gnus-summary-best-unread-article}).
2958 @kindex G l (Summary)
2959 @findex gnus-summary-goto-last-article
2960 Go to the previous article read (@code{gnus-summary-goto-last-article}).
2963 @kindex G p (Summary)
2964 @findex gnus-summary-pop-article
2965 Pop an article off the summary history and go to this article
2966 (@code{gnus-summary-pop-article}). This command differs from the
2967 command above in that you can pop as many previous articles off the
2968 history as you like.
2971 Some variables that are relevant for moving and selecting articles:
2974 @item gnus-auto-extend-newsgroup
2975 @vindex gnus-auto-extend-newsgroup
2976 All the movement commands will try to go to the previous (or next)
2977 article, even if that article isn't displayed in the Summary buffer if
2978 this variable is non-@code{nil}. Gnus will then fetch the article from
2979 the server and display it in the article buffer.
2981 @item gnus-select-article-hook
2982 @vindex gnus-select-article-hook
2983 This hook is called whenever an article is selected. By default it
2984 exposes any threads hidden under the selected article.
2986 @item gnus-mark-article-hook
2987 @vindex gnus-mark-article-hook
2988 @findex gnus-summary-mark-unread-as-read
2989 @findex gnus-summary-mark-read-and-unread-as-read
2990 @findex gnus-unread-mark
2991 This hook is called whenever an article is selected. It is intended to
2992 be used for marking articles as read. The default value is
2993 @code{gnus-summary-mark-read-and-unread-as-read}, and will change the
2994 mark of almost any article you read to @code{gnus-unread-mark}. The
2995 only articles not affected by this function are ticked, dormant, and
2996 expirable articles. If you'd instead like to just have unread articles
2997 marked as read, you can use @code{gnus-summary-mark-unread-as-read}
2998 instead. It will leave marks like @code{gnus-low-score-mark},
2999 @code{gnus-del-mark} (and so on) alone.
3004 @node Paging the Article
3005 @section Scrolling the Article
3006 @cindex article scrolling
3011 @kindex SPACE (Summary)
3012 @findex gnus-summary-next-page
3013 Pressing @kbd{SPACE} will scroll the current article forward one page,
3014 or, if you have come to the end of the current article, will choose the
3015 next article (@code{gnus-summary-next-page}).
3018 @kindex DEL (Summary)
3019 @findex gnus-summary-prev-page
3020 Scroll the current article back one page (@code{gnus-summary-prev-page}).
3023 @kindex RET (Summary)
3024 @findex gnus-summary-scroll-up
3025 Scroll the current article one line forward
3026 (@code{gnus-summary-scroll-up}).
3031 @kindex A < (Summary)
3032 @findex gnus-summary-beginning-of-article
3033 Scroll to the beginning of the article
3034 (@code{gnus-summary-beginning-of-article}).
3039 @kindex A > (Summary)
3040 @findex gnus-summary-end-of-article
3041 Scroll to the end of the article (@code{gnus-summary-end-of-article}).
3044 @kindex A s (Summary)
3045 @findex gnus-summary-isearch-article
3046 Perform an isearch in the article buffer
3047 (@code{gnus-summary-isearch-article}).
3052 @node Reply Followup and Post
3053 @section Reply, Followup and Post
3056 * Summary Mail Commands:: Sending mail.
3057 * Summary Post Commands:: Sending news.
3058 * Summary Mail and Post Commands:: Sending both news and mail.
3062 @node Summary Mail Commands
3063 @subsection Summary Mail Commands
3065 @cindex composing mail
3067 Commands for composing a mail message:
3073 @kindex S r (Summary)
3075 @findex gnus-summary-reply
3076 Mail a reply to the author of the current article
3077 (@code{gnus-summary-reply}).
3082 @kindex S R (Summary)
3083 @findex gnus-summary-reply-with-original
3084 Mail a reply to the author of the current article and include the
3085 original message (@code{gnus-summary-reply-with-original}). This
3086 command uses the process/prefix convention.
3089 @kindex S o m (Summary)
3090 @findex gnus-summary-mail-forward
3091 Forward the current article to some other person
3092 (@code{gnus-summary-mail-forward}).
3095 @kindex S o p (Summary)
3096 @findex gnus-summary-post-forward
3097 Forward the current article to a newsgroup
3098 (@code{gnus-summary-post-forward}).
3103 @kindex S m (Summary)
3104 @findex gnus-summary-mail-other-window
3105 Send a mail to some other person
3106 (@code{gnus-summary-mail-other-window}).
3109 @kindex S D b (Summary)
3110 @findex gnus-summary-resend-bounced-mail
3111 @vindex gnus-bounced-headers-junk
3112 @cindex bouncing mail
3113 If you have sent a mail, but the mail was bounced back to you for some
3114 reason (wrong address, transient failure), you can use this command to
3115 resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
3116 will be popped into a mail buffer where you can edit the headers before
3117 sending the mail off again. The headers that match the regexp
3118 @code{gnus-bounced-headers-junk} (default @samp{^Received:}) are
3119 automatically deleted first. If you give a prefix to this command, and
3120 the bounced mail is a reply to some other mail, Gnus will try to fetch
3121 that mail and display it for easy perusal of its headers. This might
3122 very well fail, though.
3125 @kindex S D r (Summary)
3126 @findex gnus-summary-resend-message
3127 @vindex gnus-ignored-resent-headers
3128 Not to be confused with the previous command,
3129 @code{gnus-summary-resend-message} will prompt you for an address to
3130 send the current message off to, and then send it to that place. The
3131 headers of the message won't be altered---but lots of headers that say
3132 @code{Resent-To}, @code{Resent-From} and so on will be added. This
3133 means that you actually send a mail to someone that has a @code{To}
3134 header that (probably) points to yourself. This will confuse people.
3135 So, natcherly you'll only do that if you're really eVIl. All old
3136 headers that match the regular expression
3137 @code{gnus-ignored-resent-headers} will be deleted before resending the
3138 message. The default is @samp{"^Return-receipt"}.
3140 This command is mainly used if you have several accounts and want to
3141 ship a mail to a different account of yours. (If you're both
3142 @code{root} and @code{postmaster} and get a mail for @code{postmaster}
3143 to the @code{root} account, you may want to resend it to
3144 @code{postmaster}. Ordnung muss sein!
3147 @kindex S O m (Summary)
3148 @findex gnus-uu-digest-mail-forward
3149 Digest the current series and forward the result using mail
3150 (@code{gnus-uu-digest-mail-forward}). This command uses the
3151 process/prefix convention (@pxref{Process/Prefix}).
3154 @kindex S O p (Summary)
3155 @findex gnus-uu-digest-post-forward
3156 Digest the current series and forward the result to a newsgroup
3157 (@code{gnus-uu-digest-mail-forward}).
3161 @node Summary Post Commands
3162 @subsection Summary Post Commands
3164 @cindex composing news
3166 Commands for posting an article:
3172 @kindex S p (Summary)
3173 @findex gnus-summary-post-news
3174 Post an article to the current group
3175 (@code{gnus-summary-post-news}).
3180 @kindex S f (Summary)
3181 @findex gnus-summary-followup
3182 Post a followup to the current article (@code{gnus-summary-followup}).
3186 @kindex S F (Summary)
3188 @findex gnus-summary-followup-with-original
3189 Post a followup to the current article and include the original message
3190 (@code{gnus-summary-followup-with-original}). This command uses the
3191 process/prefix convention.
3194 @kindex S u (Summary)
3195 @findex gnus-uu-post-news
3196 Uuencode a file, split it into parts, and post it as a series
3197 (@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}).
3201 @node Summary Mail and Post Commands
3202 @subsection Summary Mail and Post Commands
3203 @cindex mail and post
3204 @cindex post and mail
3206 Commands for sending mail and post at the same time:
3210 @kindex S b (Summary)
3211 @findex gnus-summary-followup-and-reply
3212 Post a followup and send a reply to the current article
3213 (@code{gnus-summary-followup-and-reply}).
3216 @kindex S B (Summary)
3217 @findex gnus-summary-followup-and-reply-with-original
3218 Post a followup and send a reply to the current article and include the
3219 original message (@code{gnus-summary-followup-and-reply-with-original}).
3220 This command uses the process/prefix convention.
3224 @node Canceling and Superseding
3225 @section Canceling Articles
3226 @cindex canceling articles
3227 @cindex superseding articles
3229 Have you ever written something, and then decided that you really,
3230 really, really wish you hadn't posted that?
3232 Well, you can't cancel mail, but you can cancel posts.
3234 @findex gnus-summary-cancel-article
3236 Find the article you wish to cancel (you can only cancel your own
3237 articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
3238 c} (@code{gnus-summary-cancel-article}). Your article will be
3239 canceled---machines all over the world will be deleting your article.
3241 Be aware, however, that not all sites honor cancels, so your article may
3242 live on here and there, while most sites will delete the article in
3245 If you discover that you have made some mistakes and want to do some
3246 corrections, you can post a @dfn{superseding} article that will replace
3247 your original article.
3249 @findex gnus-summary-supersede-article
3251 Go to the original article and press @kbd{S s}
3252 (@code{gnus-summary-supersede-article}). You will be put in a buffer
3253 where you can edit the article all you want before sending it off the
3256 @vindex gnus-delete-supersedes-headers
3257 You probably want to delete some of the old headers before sending the
3258 superseding article---@code{Path} and @code{Date} are probably
3259 incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
3260 match the lines you want removed. The default is
3261 @samp{^Path:\\|^Date}.
3263 The same goes for superseding as for canceling, only more so: Some
3264 sites do not honor superseding. On those sites, it will appear that you
3265 have posted almost the same article twice.
3267 If you have just posted the article, and change your mind right away,
3268 there is a trick you can use to cancel/supersede the article without
3269 waiting for the article to appear on your site first. You simply return
3270 to the post buffer (which is called @code{*post-buf*}). There you will
3271 find the article you just posted, with all the headers intact. Change
3272 the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes}
3273 header by substituting one of those words for @code{Message-ID}. Then
3274 just press @kbd{C-c C-c} to send the article as you would do normally.
3275 The previous article will be canceled/superseded.
3277 Just remember, kids: There is no 'c' in 'supersede'.
3280 @node Marking Articles
3281 @section Marking Articles
3282 @cindex article marking
3283 @cindex article ticking
3286 There are several marks you can set on an article.
3288 You have marks that decide the @dfn{readedness} (whoo, neato-keano
3289 neologism ohoy!) of the article. Alphabetic marks generally mean
3290 @dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
3292 In addition, you also have marks that do not affect readedness.
3295 * Unread Articles:: Marks for unread articles.
3296 * Read Articles:: Marks for read articles.
3297 * Other Marks:: Marks that do not affect readedness.
3301 There's a plethora of commands for manipulating these marks:
3305 * Setting Marks:: How to set and remove marks.
3306 * Setting Process Marks:: How to mark articles for later processing.
3310 @node Unread Articles
3311 @subsection Unread Articles
3313 The following marks mark articles as unread, in one form or other.
3315 @vindex gnus-dormant-mark
3316 @vindex gnus-ticked-mark
3319 @dfn{Ticked articles} are articles that will remain visible always. If
3320 you see an article that you find interesting, or you want to put off
3321 reading it, or replying to it, until sometime later, you'd typically
3322 tick it. However, articles can be expired, so if you want to keep an
3323 article forever, you'll have to save it. Ticked articles have a
3324 @samp{!} (@code{gnus-ticked-mark}) in the first column.
3327 @vindex gnus-dormant-mark
3328 A @dfn{dormant} article is marked with a @samp{?}
3329 (@code{gnus-dormant-mark}), and will only appear in the summary buffer
3330 if there are followups to it.
3333 @vindex gnus-unread-mark
3334 An @dfn{unread} article is marked with a @samp{SPACE}
3335 (@code{gnus-unread-mark}). These are articles that haven't been read at
3341 @subsection Read Articles
3342 @cindex expirable mark
3344 All the following marks mark articles as read.
3349 @vindex gnus-del-mark
3350 Articles that are marked as read. They have a @samp{r}
3351 (@code{gnus-del-mark}) in the first column. These are articles that the
3352 user has marked as read more or less manually.
3355 @vindex gnus-read-mark
3356 Articles that are actually read are marked with @samp{R}
3357 (@code{gnus-read-mark}).
3360 @vindex gnus-ancient-mark
3361 Articles that were marked as read in previous sessions are now
3362 @dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
3365 @vindex gnus-killed-mark
3366 Marked as killed (@code{gnus-killed-mark}).
3369 @vindex gnus-kill-file-mark
3370 Marked as killed by kill files (@code{gnus-kill-file-mark}).
3373 @vindex gnus-low-score-mark
3374 Marked as read by having a too low score (@code{gnus-low-score-mark}).
3377 @vindex gnus-catchup-mark
3378 Marked as read by a catchup (@code{gnus-catchup-mark}).
3381 @vindex gnus-canceled-mark
3382 Canceled article (@code{gnus-canceled-mark})
3385 @vindex gnus-souped-mark
3386 @sc{SOUP}ed article (@code{gnus-souped-mark}).
3389 @vindex gnus-sparse-mark
3390 Sparsely reffed article (@code{gnus-sparse-mark}).
3393 All these marks just mean that the article is marked as read, really.
3394 They are interpreted differently by the adaptive scoring scheme,
3397 One more special mark, though:
3401 @vindex gnus-expirable-mark
3402 You can also mark articles as @dfn{expirable} (or have them marked as
3403 such automatically). That doesn't make much sense in normal groups,
3404 because a user does not control the expiring of news articles, but in
3405 mail groups, for instance, articles that are marked as @dfn{expirable}
3406 can be deleted by Gnus at any time. Expirable articles are marked with
3407 @samp{E} (@code{gnus-expirable-mark}).
3412 @subsection Other Marks
3413 @cindex process mark
3416 There are some marks that have nothing to do with whether the article is
3422 You can set a bookmark in the current article. Say you are reading a
3423 long thesis on cats' urinary tracts, and have to go home for dinner
3424 before you've finished reading the thesis. You can then set a bookmark
3425 in the article, and Gnus will jump to this bookmark the next time it
3426 encounters the article.
3429 @vindex gnus-replied-mark
3430 All articles that you have replied to or made a followup to (i.e., have
3431 answered) will be marked with an @samp{A} in the second column
3432 (@code{gnus-replied-mark}).
3435 @vindex gnus-cached-mark
3436 Articles that are stored in the article cache will be marked with an
3437 @samp{*} in the second column (@code{gnus-cached-mark}).
3440 @vindex gnus-saved-mark
3441 Articles that are ``saved'' (in some manner or other; not necessarily
3442 religiously) are marked with an @samp{S} in the second column
3443 (@code{gnus-saved-mark}.
3446 @vindex gnus-not-empty-thread-mark
3447 @vindex gnus-empty-thread-mark
3448 It the @samp{%e} spec is used, the presence of threads or not will be
3449 marked with @code{gnus-not-empty-thread-mark} and
3450 @code{gnus-empty-thread-mark} in the third column, respectively.
3453 @vindex gnus-process-mark
3454 Finally we have the @dfn{process mark} (@code{gnus-process-mark}. A
3455 variety of commands react to the presence of the process mark. For
3456 instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
3457 all articles that have been marked with the process mark. Articles
3458 marked with the process mark have a @samp{#} in the second column.
3462 You might have noticed that most of these ``non-readedness'' marks
3463 appear in the second column by default. So if you have a cached, saved,
3464 replied article that you have process-marked, what will that look like?
3466 Nothing much. The precedence rules go as follows: process -> cache ->
3467 replied -> saved. So if the article is in the cache and is replied,
3468 you'll only see the cache mark and not the replied mark.
3472 @subsection Setting Marks
3473 @cindex setting marks
3475 All the marking commands understand the numeric prefix.
3481 @kindex M t (Summary)
3482 @findex gnus-summary-tick-article-forward
3483 Tick the current article (@code{gnus-summary-tick-article-forward}).
3488 @kindex M ? (Summary)
3489 @findex gnus-summary-mark-as-dormant
3490 Mark the current article as dormant
3491 (@code{gnus-summary-mark-as-dormant}).
3495 @kindex M d (Summary)
3497 @findex gnus-summary-mark-as-read-forward
3498 Mark the current article as read
3499 (@code{gnus-summary-mark-as-read-forward}).
3504 @kindex M k (Summary)
3505 @findex gnus-summary-kill-same-subject-and-select
3506 Mark all articles that have the same subject as the current one as read,
3507 and then select the next unread article
3508 (@code{gnus-summary-kill-same-subject-and-select}).
3512 @kindex M K (Summary)
3513 @kindex C-k (Summary)
3514 @findex gnus-summary-kill-same-subject
3515 Mark all articles that have the same subject as the current one as read
3516 (@code{gnus-summary-kill-same-subject}).
3519 @kindex M C (Summary)
3520 @findex gnus-summary-catchup
3521 Mark all unread articles in the group as read
3522 (@code{gnus-summary-catchup}).
3525 @kindex M C-c (Summary)
3526 @findex gnus-summary-catchup-all
3527 Mark all articles in the group as read---even the ticked and dormant
3528 articles (@code{gnus-summary-catchup-all}).
3531 @kindex M H (Summary)
3532 @findex gnus-summary-catchup-to-here
3533 Catchup the current group to point
3534 (@code{gnus-summary-catchup-to-here}).
3537 @kindex C-w (Summary)
3538 @findex gnus-summary-mark-region-as-read
3539 Mark all articles between point and mark as read
3540 (@code{gnus-summary-mark-region-as-read}).
3543 @kindex M V k (Summary)
3544 @findex gnus-summary-kill-below
3545 Kill all articles with scores below the default score (or below the
3546 numeric prefix) (@code{gnus-summary-kill-below}).
3550 @kindex M c (Summary)
3551 @kindex M-u (Summary)
3552 @findex gnus-summary-clear-mark-forward
3553 Clear all readedness-marks from the current article
3554 (@code{gnus-summary-clear-mark-forward}).
3558 @kindex M e (Summary)
3560 @findex gnus-summary-mark-as-expirable
3561 Mark the current article as expirable
3562 (@code{gnus-summary-mark-as-expirable}).
3565 @kindex M b (Summary)
3566 @findex gnus-summary-set-bookmark
3567 Set a bookmark in the current article
3568 (@code{gnus-summary-set-bookmark}).
3571 @kindex M B (Summary)
3572 @findex gnus-summary-remove-bookmark
3573 Remove the bookmark from the current article
3574 (@code{gnus-summary-remove-bookmark}).
3577 @kindex M V c (Summary)
3578 @findex gnus-summary-clear-above
3579 Clear all marks from articles with scores over the default score (or
3580 over the numeric prefix) (@code{gnus-summary-clear-above}).
3583 @kindex M V u (Summary)
3584 @findex gnus-summary-tick-above
3585 Tick all articles with scores over the default score (or over the
3586 numeric prefix) (@code{gnus-summary-tick-above}).
3589 @kindex M V m (Summary)
3590 @findex gnus-summary-mark-above
3591 Prompt for a mark, and mark all articles with scores over the default
3592 score (or over the numeric prefix) with this mark
3593 (@code{gnus-summary-clear-above}).
3596 @vindex gnus-summary-goto-unread
3597 The @code{gnus-summary-goto-unread} variable controls what action should
3598 be taken after setting a mark. If non-@code{nil}, point will move to
3599 the next/previous unread article. If @code{nil}, point will just move
3600 one line up or down. As a special case, if this variable is
3601 @code{never}, all the marking commands as well as other commands (like
3602 @kbd{SPACE}) will move to the next article, whether it is unread or not.
3603 The default is @code{t}.
3606 @node Setting Process Marks
3607 @subsection Setting Process Marks
3608 @cindex setting process marks
3615 @kindex M P p (Summary)
3616 @findex gnus-summary-mark-as-processable
3617 Mark the current article with the process mark
3618 (@code{gnus-summary-mark-as-processable}).
3619 @findex gnus-summary-unmark-as-processable
3623 @kindex M P u (Summary)
3624 @kindex M-# (Summary)
3625 Remove the process mark, if any, from the current article
3626 (@code{gnus-summary-unmark-as-processable}).
3629 @kindex M P U (Summary)
3630 @findex gnus-summary-unmark-all-processable
3631 Remove the process mark from all articles
3632 (@code{gnus-summary-unmark-all-processable}).
3635 @kindex M P R (Summary)
3636 @findex gnus-uu-mark-by-regexp
3637 Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
3640 @kindex M P r (Summary)
3641 @findex gnus-uu-mark-region
3642 Mark articles in region (@code{gnus-uu-mark-region}).
3645 @kindex M P t (Summary)
3646 @findex gnus-uu-mark-thread
3647 Mark all articles in the current (sub)thread
3648 (@code{gnus-uu-mark-thread}).
3651 @kindex M P T (Summary)
3652 @findex gnus-uu-unmark-thread
3653 Unmark all articles in the current (sub)thread
3654 (@code{gnus-uu-unmark-thread}).
3657 @kindex M P v (Summary)
3658 @findex gnus-uu-mark-over
3659 Mark all articles that have a score above the prefix argument
3660 (@code{gnus-uu-mark-over}).
3663 @kindex M P s (Summary)
3664 @findex gnus-uu-mark-series
3665 Mark all articles in the current series (@code{gnus-uu-mark-series}).
3668 @kindex M P S (Summary)
3669 @findex gnus-uu-mark-sparse
3670 Mark all series that have already had some articles marked
3671 (@code{gnus-uu-mark-sparse}).
3674 @kindex M P a (Summary)
3675 @findex gnus-uu-mark-all
3676 Mark all articles in series order (@code{gnus-uu-mark-series}).
3679 @kindex M P b (Summary)
3680 @findex gnus-uu-mark-buffer
3681 Mark all articles in the buffer in the order they appear
3682 (@code{gnus-uu-mark-buffer}).
3690 It can be convenient to limit the summary buffer to just show some
3691 subset of the articles currently in the group. The effect most limit
3692 commands have is to remove a few (or many) articles from the summary
3699 @kindex / / (Summary)
3700 @findex gnus-summary-limit-to-subject
3701 Limit the summary buffer to articles that match some subject
3702 (@code{gnus-summary-limit-to-subject}).
3705 @kindex / a (Summary)
3706 @findex gnus-summary-limit-to-author
3707 Limit the summary buffer to articles that match some author
3708 (@code{gnus-summary-limit-to-author}).
3712 @kindex / u (Summary)
3714 @findex gnus-summary-limit-to-unread
3715 Limit the summary buffer to articles that are not marked as read
3716 (@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
3717 buffer to articles that are strictly unread. This means that ticked and
3718 dormant articles will also be excluded.
3721 @kindex / m (Summary)
3722 @findex gnus-summary-limit-to-marks
3723 Ask for a mark and then limit to all articles that have not been marked
3724 with that mark (@code{gnus-summary-limit-to-marks}).
3727 @kindex / n (Summary)
3728 @findex gnus-summary-limit-to-articles
3729 Limit the summary buffer to the current article
3730 (@code{gnus-summary-limit-to-articles}). Uses the process/prefix
3731 convention (@pxref{Process/Prefix}).
3734 @kindex / w (Summary)
3735 @findex gnus-summary-pop-limit
3736 Pop the previous limit off the stack and restore it
3737 (@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
3741 @kindex / v (Summary)
3742 @findex gnus-summary-limit-to-score
3743 Limit the summary buffer to articles that have a score at or above some
3744 score (@code{gnus-summary-limit-to-score}).
3748 @kindex M S (Summary)
3749 @kindex / E (Summary)
3750 @findex gnus-summary-limit-include-expunged
3751 Display all expunged articles
3752 (@code{gnus-summary-limit-include-expunged}).
3755 @kindex / D (Summary)
3756 @findex gnus-summary-limit-include-dormant
3757 Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
3760 @kindex / d (Summary)
3761 @findex gnus-summary-limit-exclude-dormant
3762 Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
3765 @kindex / c (Summary)
3766 @findex gnus-summary-limit-exclude-childless-dormant
3767 Hide all dormant articles that have no children
3768 (@code{gnus-summary-limit-exclude-childless-dormant}).
3771 @kindex / C (Summary)
3772 @findex gnus-summary-limit-mark-excluded-as-read
3773 Mark all excluded unread articles as read
3774 (@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix,
3775 also mark excluded ticked and dormant articles as read.
3783 @cindex article threading
3785 Gnus threads articles by default. @dfn{To thread} is to put replies to
3786 articles directly after the articles they reply to---in a hierarchical
3790 * Customizing Threading:: Variables you can change to affect the threading.
3791 * Thread Commands:: Thread based commands in the summary buffer.
3795 @node Customizing Threading
3796 @subsection Customizing Threading
3797 @cindex customizing threading
3803 @item gnus-show-threads
3804 @vindex gnus-show-threads
3805 If this variable is @code{nil}, no threading will be done, and all of
3806 the rest of the variables here will have no effect. Turning threading
3807 off will speed group selection up a bit, but it is sure to make reading
3808 slower and more awkward.
3810 @item gnus-fetch-old-headers
3811 @vindex gnus-fetch-old-headers
3812 If non-@code{nil}, Gnus will attempt to build old threads by fetching
3813 more old headers---headers to articles that are marked as read. If you
3814 would like to display as few summary lines as possible, but still
3815 connect as many loose threads as possible, you should set this variable
3816 to @code{some} or a number. If you set it to a number, no more than
3817 that number of extra old headers will be fetched. In either case,
3818 fetching old headers only works if the backend you are using carries
3819 overview files---this would normally be @code{nntp}, @code{nnspool} and
3820 @code{nnml}. Also remember that if the root of the thread has been
3821 expired by the server, there's not much Gnus can do about that.
3823 @item gnus-build-sparse-threads
3824 @vindex gnus-build-sparse-threads
3825 Fetching old headers can be slow. A low-rent similar effect can be
3826 gotten by setting this variable to @code{some}. Gnus will then look at
3827 the complete @code{References} headers of all articles and try to string
3828 articles that belong in the same thread together. This will leave
3829 @dfn{gaps} in the threading display where Gnus guesses that an article
3830 is missing from the thread. (These gaps appear like normal summary
3831 lines. If you select a gap, Gnus will try to fetch the article in
3832 question.) If this variable is @code{t}, Gnus will display all these
3833 ``gaps'' without regard for whether they are useful for completing the
3834 thread or not. Finally, if this variable is @code{more}, Gnus won't cut
3835 off sparse leaf nodes that don't lead anywhere. This variable is
3836 @code{nil} by default.
3838 @item gnus-summary-gather-subject-limit
3839 @vindex gnus-summary-gather-subject-limit
3840 Loose threads are gathered by comparing subjects of articles. If this
3841 variable is @code{nil}, Gnus requires an exact match between the
3842 subjects of the loose threads before gathering them into one big
3843 super-thread. This might be too strict a requirement, what with the
3844 presence of stupid newsreaders that chop off long subjects lines. If
3845 you think so, set this variable to, say, 20 to require that only the
3846 first 20 characters of the subjects have to match. If you set this
3847 variable to a really low number, you'll find that Gnus will gather
3848 everything in sight into one thread, which isn't very helpful.
3850 @cindex fuzzy article gathering
3851 If you set this variable to the special value @code{fuzzy}, Gnus will
3852 use a fuzzy string comparison algorithm on the subjects.
3854 @item gnus-simplify-subject-fuzzy-regexp
3855 @vindex gnus-simplify-subject-fuzzy-regexp
3856 This can either be a regular expression or list of regular expressions
3857 that match strings that will be removed from subjects if fuzzy subject
3858 simplification is used.
3860 @item gnus-simplify-ignored-prefixes
3861 @vindex gnus-simplify-ignored-prefixes
3862 If you set @code{gnus-summary-gather-subject-limit} to something as low
3863 as 10, you might consider setting this variable to something sensible:
3865 @c Written by Michael Ernst <mernst@cs.rice.edu>
3867 (setq gnus-simplify-ignored-prefixes
3870 (mapconcat 'identity
3872 "wanted" "followup" "summary\\( of\\)?"
3873 "help" "query" "problem" "question"
3874 "answer" "reference" "announce"
3875 "How can I" "How to" "Comparison of"
3880 (mapconcat 'identity
3881 '("for" "for reference" "with" "about")
3883 "\\)?\\]?:?[ \t]*"))
3886 All words that match this regexp will be removed before comparing two
3889 @item gnus-summary-gather-exclude-subject
3890 @vindex gnus-summary-gather-exclude-subject
3891 Since loose thread gathering is done on subjects only, that might lead
3892 to many false hits, especially with certain common subjects like
3893 @samp{} and @samp{(none)}. To make the situation slightly better,
3894 you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
3895 what subjects should be excluded from the gathering process. The
3896 default is @samp{^ *$\\|^(none)$}.
3898 @item gnus-summary-thread-gathering-function
3899 @vindex gnus-summary-thread-gathering-function
3900 Gnus gathers threads by looking at @code{Subject} headers. This means
3901 that totally unrelated articles may end up in the same ``thread'', which
3902 is confusing. An alternate approach is to look at all the
3903 @code{Message-ID}s in all the @code{References} headers to find matches.
3904 This will ensure that no gathered threads ever includes unrelated
3905 articles, but it's also means that people who have posted with broken
3906 newsreaders won't be gathered properly. The choice is yours---plague or
3910 @item gnus-gather-threads-by-subject
3911 @findex gnus-gather-threads-by-subject
3912 This function is the default gathering function and looks at
3913 @code{Subject}s exclusively.
3915 @item gnus-gather-threads-by-references
3916 @findex gnus-gather-threads-by-references
3917 This function looks at @code{References} headers exclusively.
3920 If you want to test gathering by @code{References}, you could say
3924 (setq gnus-summary-thread-gathering-function
3925 'gnus-gather-threads-by-references)
3928 @item gnus-summary-make-false-root
3929 @vindex gnus-summary-make-false-root
3930 If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
3931 and create a dummy root at the top. (Wait a minute. Root at the top?
3932 Yup.) Loose subtrees occur when the real root has expired, or you've
3933 read or killed the root in a previous session.
3935 When there is no real root of a thread, Gnus will have to fudge
3936 something. This variable says what fudging method Gnus should use.
3937 There are four possible values:
3939 @cindex adopting articles
3944 Gnus will make the first of the orphaned articles the parent. This
3945 parent will adopt all the other articles. The adopted articles will be
3946 marked as such by pointy brackets (@samp{<>}) instead of the standard
3947 square brackets (@samp{[]}). This is the default method.
3950 @vindex gnus-summary-dummy-line-format
3951 Gnus will create a dummy summary line that will pretend to be the
3952 parent. This dummy line does not correspond to any real article, so
3953 selecting it will just select the first real article after the dummy
3954 article. @code{gnus-summary-dummy-line-format} is used to specify the
3955 format of the dummy roots. It accepts only one format spec: @samp{S},
3956 which is the subject of the article. @xref{Formatting Variables}.
3959 Gnus won't actually make any article the parent, but simply leave the
3960 subject field of all orphans except the first empty. (Actually, it will
3961 use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
3965 Don't make any article parent at all. Just gather the threads and
3966 display them after one another.
3969 Don't gather loose threads.
3972 @item gnus-thread-hide-subtree
3973 @vindex gnus-thread-hide-subtree
3974 If non-@code{nil}, all threads will be hidden when the summary buffer is
3977 @item gnus-thread-hide-killed
3978 @vindex gnus-thread-hide-killed
3979 if you kill a thread and this variable is non-@code{nil}, the subtree
3982 @item gnus-thread-ignore-subject
3983 @vindex gnus-thread-ignore-subject
3984 Sometimes somebody changes the subject in the middle of a thread. If
3985 this variable is non-@code{nil}, the subject change is ignored. If it
3986 is @code{nil}, which is the default, a change in the subject will result
3989 @item gnus-thread-indent-level
3990 @vindex gnus-thread-indent-level
3991 This is a number that says how much each sub-thread should be indented.
3992 The default is @code{4}.
3996 @node Thread Commands
3997 @subsection Thread Commands
3998 @cindex thread commands
4004 @kindex T k (Summary)
4005 @kindex M-C-k (Summary)
4006 @findex gnus-summary-kill-thread
4007 Mark all articles in the current sub-thread as read
4008 (@code{gnus-summary-kill-thread}). If the prefix argument is positive,
4009 remove all marks instead. If the prefix argument is negative, tick
4014 @kindex T l (Summary)
4015 @kindex M-C-l (Summary)
4016 @findex gnus-summary-lower-thread
4017 Lower the score of the current thread
4018 (@code{gnus-summary-lower-thread}).
4021 @kindex T i (Summary)
4022 @findex gnus-summary-raise-thread
4023 Increase the score of the current thread
4024 (@code{gnus-summary-raise-thread}).
4027 @kindex T # (Summary)
4028 @findex gnus-uu-mark-thread
4029 Set the process mark on the current thread
4030 (@code{gnus-uu-mark-thread}).
4033 @kindex T M-# (Summary)
4034 @findex gnus-uu-unmark-thread
4035 Remove the process mark from the current thread
4036 (@code{gnus-uu-unmark-thread}).
4039 @kindex T T (Summary)
4040 @findex gnus-summary-toggle-threads
4041 Toggle threading (@code{gnus-summary-toggle-threads}).
4044 @kindex T s (Summary)
4045 @findex gnus-summary-show-thread
4046 Expose the thread hidden under the current article, if any
4047 (@code{gnus-summary-show-thread}).
4050 @kindex T h (Summary)
4051 @findex gnus-summary-hide-thread
4052 Hide the current (sub)thread (@code{gnus-summary-hide-thread}).
4055 @kindex T S (Summary)
4056 @findex gnus-summary-show-all-threads
4057 Expose all hidden threads (@code{gnus-summary-show-all-threads}).
4060 @kindex T H (Summary)
4061 @findex gnus-summary-hide-all-threads
4062 Hide all threads (@code{gnus-summary-hide-all-threads}).
4065 @kindex T t (Summary)
4066 @findex gnus-summary-rethread-current
4067 Re-thread the thread the current article is part of
4068 (@code{gnus-summary-rethread-current}). This works even when the
4069 summary buffer is otherwise unthreaded.
4072 @kindex T ^ (Summary)
4073 @findex gnus-summary-reparent-thread
4074 Make the current article the child of the marked (or previous) article
4075 (@code{gnus-summary-reparent-thread}.
4079 The following commands are thread movement commands. They all
4080 understand the numeric prefix.
4085 @kindex T n (Summary)
4086 @findex gnus-summary-next-thread
4087 Go to the next thread (@code{gnus-summary-next-thread}).
4090 @kindex T p (Summary)
4091 @findex gnus-summary-prev-thread
4092 Go to the previous thread (@code{gnus-summary-prev-thread}).
4095 @kindex T d (Summary)
4096 @findex gnus-summary-down-thread
4097 Descend the thread (@code{gnus-summary-down-thread}).
4100 @kindex T u (Summary)
4101 @findex gnus-summary-up-thread
4102 Ascend the thread (@code{gnus-summary-up-thread}).
4105 @kindex T o (Summary)
4106 @findex gnus-summary-top-thread
4107 Go to the top of the thread (@code{gnus-summary-top-thread}).
4110 @vindex gnus-thread-operation-ignore-subject
4111 If you ignore subject while threading, you'll naturally end up with
4112 threads that have several different subjects in them. If you then issue
4113 a command like `T k' (@code{gnus-summary-kill-thread}) you might not
4114 wish to kill the entire thread, but just those parts of the thread that
4115 have the same subject as the current article. If you like this idea,
4116 you can fiddle with @code{gnus-thread-operation-ignore-subject}. If is
4117 is non-@code{nil} (which it is by default), subjects will be ignored
4118 when doing thread commands. If this variable is @code{nil}, articles in
4119 the same thread with different subjects will not be included in the
4120 operation in question. If this variable is @code{fuzzy}, only articles
4121 that have subjects that are fuzzily equal will be included.
4124 @node Asynchronous Fetching
4125 @section Asynchronous Article Fetching
4126 @cindex asynchronous article fetching
4128 If you read your news from an @sc{nntp} server that's far away, the
4129 network latencies may make reading articles a chore. You have to wait
4130 for a while after pressing @kbd{n} to go to the next article before the
4131 article appears. Why can't Gnus just go ahead and fetch the article
4132 while you are reading the previous one? Why not, indeed.
4134 First, some caveats. There are some pitfalls to using asynchronous
4135 article fetching, especially the way Gnus does it.
4137 Let's say you are reading article 1, which is short, and article 2 is
4138 quite long, and you are not interested in reading that. Gnus does not
4139 know this, so it goes ahead and fetches article 2. You decide to read
4140 article 3, but since Gnus is in the process of fetching article 2, the
4141 connection is blocked.
4143 To avoid these situations, Gnus will open two (count 'em two)
4144 connections to the server. Some people may think this isn't a very nice
4145 thing to do, but I don't see any real alternatives. Setting up that
4146 extra connection takes some time, so Gnus startup will be slower.
4148 Gnus will fetch more articles than you will read. This will mean that
4149 the link between your machine and the @sc{nntp} server will become more
4150 loaded than if you didn't use article pre-fetch. The server itself will
4151 also become more loaded---both with the extra article requests, and the
4154 Ok, so now you know that you shouldn't really use this thing... unless
4157 @vindex gnus-asynchronous
4158 Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
4159 happen automatically.
4161 @vindex nntp-async-number
4162 You can control how many articles that are to be pre-fetched by setting
4163 @code{nntp-async-number}. This is five by default, which means that when
4164 you read an article in the group, @code{nntp} will pre-fetch the next
4165 five articles. If this variable is @code{t}, @code{nntp} will pre-fetch
4166 all the articles that it can without bound. If it is @code{nil}, no
4167 pre-fetching will be made.
4169 @vindex gnus-asynchronous-article-function
4170 You may wish to create some sort of scheme for choosing which articles
4171 that @code{nntp} should consider as candidates for pre-fetching. For
4172 instance, you may wish to pre-fetch all articles with high scores, and
4173 not pre-fetch low-scored articles. You can do that by setting the
4174 @code{gnus-asynchronous-article-function}, which will be called with an
4175 alist where the keys are the article numbers. Your function should
4176 return an alist where the articles you are not interested in have been
4177 removed. You could also do sorting on article score and the like.
4180 @node Article Caching
4181 @section Article Caching
4182 @cindex article caching
4185 If you have an @emph{extremely} slow @sc{nntp} connection, you may
4186 consider turning article caching on. Each article will then be stored
4187 locally under your home directory. As you may surmise, this could
4188 potentially use @emph{huge} amounts of disk space, as well as eat up all
4189 your inodes so fast it will make your head swim. In vodka.
4191 Used carefully, though, it could be just an easier way to save articles.
4193 @vindex gnus-use-long-file-name
4194 @vindex gnus-cache-directory
4195 @vindex gnus-use-cache
4196 To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
4197 all articles that are ticked or marked as dormant will then be copied
4198 over to your local cache (@code{gnus-cache-directory}). Whether this
4199 cache is flat or hierarchal is controlled by the
4200 @code{gnus-use-long-file-name} variable, as usual.
4202 When re-select a ticked or dormant article, it will be fetched from the
4203 cache instead of from the server. As articles in your cache will never
4204 expire, this might serve as a method of saving articles while still
4205 keeping them where they belong. Just mark all articles you want to save
4206 as dormant, and don't worry.
4208 When an article is marked as read, is it removed from the cache.
4210 @vindex gnus-cache-remove-articles
4211 @vindex gnus-cache-enter-articles
4212 The entering/removal of articles from the cache is controlled by the
4213 @code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
4214 variables. Both are lists of symbols. The first is @code{(ticked
4215 dormant)} by default, meaning that ticked and dormant articles will be
4216 put in the cache. The latter is @code{(read)} by default, meaning that
4217 articles that are marked as read are removed from the cache. Possibly
4218 symbols in these two lists are @code{ticked}, @code{dormant},
4219 @code{unread} and @code{read}.
4221 @findex gnus-jog-cache
4222 So where does the massive article-fetching and storing come into the
4223 picture? The @code{gnus-jog-cache} command will go through all
4224 subscribed newsgroups, request all unread articles, and store them in
4225 the cache. You should only ever, ever ever ever, use this command if 1)
4226 your connection to the @sc{nntp} server is really, really, really slow
4227 and 2) you have a really, really, really huge disk. Seriously.
4229 @vindex gnus-uncacheable-groups
4230 It is likely that you do not want caching on some groups. For instance,
4231 if your @code{nnml} mail is located under your home directory, it makes no
4232 sense to cache it somewhere else under your home directory. Unless you
4233 feel that it's neat to use twice as much space. To limit the caching,
4234 you could set the @code{gnus-uncacheable-groups} regexp to
4235 @samp{^nnml}, for instance. This variable is @code{nil} by
4238 @findex gnus-cache-generate-nov-databases
4239 @findex gnus-cache-generate-active
4240 @vindex gnus-cache-active-file
4241 The cache stores information on what articles it contains in its active
4242 file (@code{gnus-cache-active-file}). If this file (or any other parts
4243 of the cache) becomes all messed up for some reason or other, Gnus
4244 offers two functions that will try to set things right. @kbd{M-x
4245 gnus-cache-generate-nov-databases} will (re)build all the @sc{nov}
4246 files, and @kbd{gnus-cache-generate-active} will (re)generate the active
4250 @node Persistent Articles
4251 @section Persistent Articles
4252 @cindex persistent articles
4254 Closely related to article caching, we have @dfn{persistent articles}.
4255 In fact, it's just a different way of looking at caching, and much more
4256 useful in my opinion.
4258 Say you're reading a newsgroup, and you happen on to some valuable gem
4259 that you want to keep and treasure forever. You'd normally just save it
4260 (using one of the many saving commands) in some file. The problem with
4261 that is that it's just, well, yucky. Ideally you'd prefer just having
4262 the article remain in the group where you found it forever; untouched by
4263 the expiry going on at the news server.
4265 This is what a @dfn{persistent article} is---an article that just won't
4266 be deleted. It's implemented using the normal cache functions, but
4267 you use two explicit commands for managing persistent articles:
4273 @findex gnus-cache-enter-article
4274 Make the current article persistent (@code{gnus-cache-enter-article}).
4277 @kindex M-* (Summary)
4278 @findex gnus-cache-remove-article
4279 Remove the current article from the persistent articles
4280 (@code{gnus-cache-remove-article}). This will normally delete the
4284 Both these commands understand the process/prefix convention.
4286 To avoid having all ticked articles (and stuff) entered into the cache,
4287 you should set @code{gnus-use-cache} to @code{passive} if you're just
4288 interested in persistent articles:
4291 (setq gnus-use-cache 'passive)
4295 @node Article Backlog
4296 @section Article Backlog
4298 @cindex article backlog
4300 If you have a slow connection, but the idea of using caching seems
4301 unappealing to you (and it is, really), you can help the situation some
4302 by switching on the @dfn{backlog}. This is where Gnus will buffer
4303 already read articles so that it doesn't have to re-fetch articles
4304 you've already read. This only helps if you are in the habit of
4305 re-selecting articles you've recently read, of course. If you never do
4306 that, turning the backlog on will slow Gnus down a little bit, and
4307 increase memory usage some.
4309 @vindex gnus-keep-backlog
4310 If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store
4311 at most @var{n} old articles in a buffer for later re-fetching. If this
4312 variable is non-@code{nil} and is not a number, Gnus will store
4313 @emph{all} read articles, which means that your Emacs will grow without
4314 bound before exploding and taking your machine down with you. I put
4315 that in there just to keep y'all on your toes.
4317 This variable is @code{nil} by default.
4320 @node Saving Articles
4321 @section Saving Articles
4322 @cindex saving articles
4324 Gnus can save articles in a number of ways. Below is the documentation
4325 for saving articles in a fairly straight-forward fashion (i.e., little
4326 processing of the article is done before it is saved). For a different
4327 approach (uudecoding, unsharing) you should use @code{gnus-uu}
4328 (@pxref{Decoding Articles}).
4330 @vindex gnus-save-all-headers
4331 If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
4332 unwanted headers before saving the article.
4334 @vindex gnus-saved-headers
4335 If the preceding variable is @code{nil}, all headers that match the
4336 @code{gnus-saved-headers} regexp will be kept, while the rest will be
4337 deleted before saving.
4343 @kindex O o (Summary)
4345 @findex gnus-summary-save-article
4346 Save the current article using the default article saver
4347 (@code{gnus-summary-save-article}).
4350 @kindex O m (Summary)
4351 @findex gnus-summary-save-article-mail
4352 Save the current article in mail format
4353 (@code{gnus-summary-save-article-mail}).
4356 @kindex O r (Summary)
4357 @findex gnus-summary-save-article-rmail
4358 Save the current article in rmail format
4359 (@code{gnus-summary-save-article-rmail}).
4362 @kindex O f (Summary)
4363 @findex gnus-summary-save-article-file
4364 Save the current article in plain file format
4365 (@code{gnus-summary-save-article-file}).
4368 @kindex O b (Summary)
4369 @findex gnus-summary-save-article-body-file
4370 Save the current article body in plain file format
4371 (@code{gnus-summary-save-article-body-file}).
4374 @kindex O h (Summary)
4375 @findex gnus-summary-save-article-folder
4376 Save the current article in mh folder format
4377 (@code{gnus-summary-save-article-folder}).
4380 @kindex O v (Summary)
4381 @findex gnus-summary-save-article-vm
4382 Save the current article in a VM folder
4383 (@code{gnus-summary-save-article-vm}).
4386 @kindex O p (Summary)
4387 @findex gnus-summary-pipe-output
4388 Save the current article in a pipe. Uhm, like, what I mean is---Pipe
4389 the current article to a process (@code{gnus-summary-pipe-output}).
4392 @vindex gnus-prompt-before-saving
4393 All these commands use the process/prefix convention
4394 (@pxref{Process/Prefix}). If you save bunches of articles using these
4395 functions, you might get tired of being prompted for files to save each
4396 and every article in. The prompting action is controlled by
4397 the @code{gnus-prompt-before-saving} variable, which is @code{always} by
4398 default, giving you that excessive prompting action you know and
4399 loathe. If you set this variable to @code{t} instead, you'll be prompted
4400 just once for each series of articles you save. If you like to really
4401 have Gnus do all your thinking for you, you can even set this variable
4402 to @code{nil}, which means that you will never be prompted for files to
4403 save articles in. Gnus will simply save all the articles in the default
4407 @vindex gnus-default-article-saver
4408 You can customize the @code{gnus-default-article-saver} variable to make
4409 Gnus do what you want it to. You can use any of the four ready-made
4410 functions below, or you can create your own.
4414 @item gnus-summary-save-in-rmail
4415 @findex gnus-summary-save-in-rmail
4416 @vindex gnus-rmail-save-name
4417 @findex gnus-plain-save-name
4418 This is the default format, @dfn{babyl}. Uses the function in the
4419 @code{gnus-rmail-save-name} variable to get a file name to save the
4420 article in. The default is @code{gnus-plain-save-name}.
4422 @item gnus-summary-save-in-mail
4423 @findex gnus-summary-save-in-mail
4424 @vindex gnus-mail-save-name
4425 Save in a Unix mail (mbox) file. Uses the function in the
4426 @code{gnus-mail-save-name} variable to get a file name to save the
4427 article in. The default is @code{gnus-plain-save-name}.
4429 @item gnus-summary-save-in-file
4430 @findex gnus-summary-save-in-file
4431 @vindex gnus-file-save-name
4432 @findex gnus-numeric-save-name
4433 Append the article straight to an ordinary file. Uses the function in
4434 the @code{gnus-file-save-name} variable to get a file name to save the
4435 article in. The default is @code{gnus-numeric-save-name}.
4437 @item gnus-summary-save-body-in-file
4438 @findex gnus-summary-save-body-in-file
4439 Append the article body to an ordinary file. Uses the function in the
4440 @code{gnus-file-save-name} variable to get a file name to save the
4441 article in. The default is @code{gnus-numeric-save-name}.
4443 @item gnus-summary-save-in-folder
4444 @findex gnus-summary-save-in-folder
4445 @findex gnus-folder-save-name
4446 @findex gnus-Folder-save-name
4447 @vindex gnus-folder-save-name
4450 Save the article to an MH folder using @code{rcvstore} from the MH
4451 library. Uses the function in the @code{gnus-folder-save-name} variable
4452 to get a file name to save the article in. The default is
4453 @code{gnus-folder-save-name}, but you can also use
4454 @code{gnus-Folder-save-name}. The former creates capitalized names, and
4455 the latter does not.
4457 @item gnus-summary-save-in-vm
4458 @findex gnus-summary-save-in-vm
4459 Save the article in a VM folder. You have to have the VM mail
4460 reader to use this setting.
4463 @vindex gnus-article-save-directory
4464 All of these functions, except for the last one, will save the article
4465 in the @code{gnus-article-save-directory}, which is initialized from the
4466 @code{SAVEDIR} environment variable. This is @file{~/News/} by
4469 As you can see above, the functions use different functions to find a
4470 suitable name of a file to save the article in. Below is a list of
4471 available functions that generate names:
4475 @item gnus-Numeric-save-name
4476 @findex gnus-Numeric-save-name
4477 Generates file names that look like @file{~/News/Alt.andrea-dworkin/45}.
4479 @item gnus-numeric-save-name
4480 @findex gnus-numeric-save-name
4481 Generates file names that look like @file{~/News/alt.andrea-dworkin/45}.
4483 @item gnus-Plain-save-name
4484 @findex gnus-Plain-save-name
4485 Generates file names that look like @file{~/News/Alt.andrea-dworkin}.
4487 @item gnus-plain-save-name
4488 @findex gnus-plain-save-name
4489 Generates file names that look like @file{~/News/alt.andrea-dworkin}.
4492 @vindex gnus-split-methods
4493 You can have Gnus suggest where to save articles by plonking a regexp into
4494 the @code{gnus-split-methods} alist. For instance, if you would like to
4495 save articles related to Gnus in the file @file{gnus-stuff}, and articles
4496 related to VM in @code{vm-stuff}, you could set this variable to something
4500 (("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
4501 ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff")
4502 (my-choosing-function "../other-dir/my-stuff")
4503 ((equal gnus-newsgroup-name "mail.misc") "mail-stuff"))
4506 We see that this is a list where each element is a list that has two
4507 elements---the @dfn{match} and the @dfn{file}. The match can either be
4508 a string (in which case it is used as a regexp to match on the article
4509 head); it can be a symbol (which will be called as a function); or it
4510 can be a list (which will be @code{eval}ed). If any of these actions
4511 have a non-@code{nil} result, the @dfn{file} will be used as a default
4512 prompt. In addition, the result of the operation itself will be used if
4513 the function or form called returns a string or a list of strings.
4515 You basically end up with a list of file names that might be used when
4516 saving the current article. (All ``matches'' will be used.) You will
4517 then be prompted for what you really want to use as a name, with file
4518 name completion over the results from applying this variable.
4520 This variable is @code{((gnus-article-archive-name))} by default, which
4521 means that Gnus will look at the articles it saves for an
4522 @code{Archive-name} line and use that as a suggestion for the file
4525 @vindex gnus-use-long-file-name
4526 Finally, you have the @code{gnus-use-long-file-name} variable. If it is
4527 @code{nil}, all the preceding functions will replace all periods
4528 (@samp{.}) in the group names with slashes (@samp{/})---which means that
4529 the functions will generate hierarchies of directories instead of having
4530 all the files in the toplevel directory
4531 (@file{~/News/alt/andrea-dworkin} instead of
4532 @file{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default
4533 on most systems. However, for historical reasons, this is @code{nil} on
4534 Xenix and usg-unix-v machines by default.
4536 This function also affects kill and score file names. If this variable
4537 is a list, and the list contains the element @code{not-score}, long file
4538 names will not be used for score files, if it contains the element
4539 @code{not-save}, long file names will not be used for saving, and if it
4540 contains the element @code{not-kill}, long file names will not be used
4543 If you'd like to save articles in a hierarchy that looks something like
4547 (setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
4548 (setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
4551 Then just save with @kbd{o}. You'd then read this hierarchy with
4552 ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
4553 the toplevel directory as the argument (@file{~/News/}). Then just walk
4554 around to the groups/directories with @code{nneething}.
4557 @node Decoding Articles
4558 @section Decoding Articles
4559 @cindex decoding articles
4561 Sometime users post articles (or series of articles) that have been
4562 encoded in some way or other. Gnus can decode them for you.
4565 * Uuencoded Articles:: Uudecode articles.
4566 * Shared Articles:: Unshar articles.
4567 * PostScript Files:: Split PostScript.
4568 * Decoding Variables:: Variables for a happy decoding.
4569 * Viewing Files:: You want to look at the result of the decoding?
4572 All these functions use the process/prefix convention
4573 (@pxref{Process/Prefix}) for finding out what articles to work on, with
4574 the extension that a ``single article'' means ``a single series''. Gnus
4575 can find out by itself what articles belong to a series, decode all the
4576 articles and unpack/view/save the resulting file(s).
4578 Gnus guesses what articles are in the series according to the following
4579 simplish rule: The subjects must be (nearly) identical, except for the
4580 last two numbers of the line. (Spaces are largely ignored, however.)
4582 For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus
4583 will find all the articles that match the regexp @samp{^cat.gif
4584 ([0-9]+/[0-9]+).*$}.
4586 Subjects that are nonstandard, like @samp{cat.gif (2/3) Part 6 of a
4587 series}, will not be properly recognized by any of the automatic viewing
4588 commands, and you have to mark the articles manually with @kbd{#}.
4591 @node Uuencoded Articles
4592 @subsection Uuencoded Articles
4594 @cindex uuencoded articles
4599 @kindex X u (Summary)
4600 @findex gnus-uu-decode-uu
4601 Uudecodes the current series (@code{gnus-uu-decode-uu}).
4604 @kindex X U (Summary)
4605 @findex gnus-uu-decode-uu-and-save
4606 Uudecodes and saves the current series
4607 (@code{gnus-uu-decode-uu-and-save}).
4610 @kindex X v u (Summary)
4611 @findex gnus-uu-decode-uu-view
4612 Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
4615 @kindex X v U (Summary)
4616 @findex gnus-uu-decode-uu-and-save-view
4617 Uudecodes, views and saves the current series
4618 (@code{gnus-uu-decode-uu-and-save-view}).
4621 Remember that these all react to the presence of articles marked with
4622 the process mark. If, for instance, you'd like to decode and save an
4623 entire newsgroup, you'd typically do @kbd{M P a}
4624 (@code{gnus-uu-mark-all}) and then @kbd{X U}
4625 (@code{gnus-uu-decode-uu-and-save}).
4627 All this is very much different from how @code{gnus-uu} worked with
4628 @sc{gnus 4.1}, where you had explicit keystrokes for everything under
4629 the sun. This version of @code{gnus-uu} generally assumes that you mark
4630 articles in some way (@pxref{Setting Process Marks}) and then press
4633 @vindex gnus-uu-notify-files
4634 Note: When trying to decode articles that have names matching
4635 @code{gnus-uu-notify-files}, which is hard-coded to
4636 @samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
4637 automatically post an article on @samp{comp.unix.wizards} saying that
4638 you have just viewed the file in question. This feature can't be turned
4642 @node Shared Articles
4643 @subsection Shared Articles
4645 @cindex shared articles
4650 @kindex X s (Summary)
4651 @findex gnus-uu-decode-unshar
4652 Unshars the current series (@code{gnus-uu-decode-unshar}).
4655 @kindex X S (Summary)
4656 @findex gnus-uu-decode-unshar-and-save
4657 Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
4660 @kindex X v s (Summary)
4661 @findex gnus-uu-decode-unshar-view
4662 Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
4665 @kindex X v S (Summary)
4666 @findex gnus-uu-decode-unshar-and-save-view
4667 Unshars, views and saves the current series
4668 (@code{gnus-uu-decode-unshar-and-save-view}).
4672 @node PostScript Files
4673 @subsection PostScript Files
4679 @kindex X p (Summary)
4680 @findex gnus-uu-decode-postscript
4681 Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
4684 @kindex X P (Summary)
4685 @findex gnus-uu-decode-postscript-and-save
4686 Unpack and save the current PostScript series
4687 (@code{gnus-uu-decode-postscript-and-save}).
4690 @kindex X v p (Summary)
4691 @findex gnus-uu-decode-postscript-view
4692 View the current PostScript series
4693 (@code{gnus-uu-decode-postscript-view}).
4696 @kindex X v P (Summary)
4697 @findex gnus-uu-decode-postscript-and-save-view
4698 View and save the current PostScript series
4699 (@code{gnus-uu-decode-postscript-and-save-view}).
4703 @node Decoding Variables
4704 @subsection Decoding Variables
4706 Adjective, not verb.
4709 * Rule Variables:: Variables that say how a file is to be viewed.
4710 * Other Decode Variables:: Other decode variables.
4711 * Uuencoding and Posting:: Variables for customizing uuencoding.
4715 @node Rule Variables
4716 @subsubsection Rule Variables
4717 @cindex rule variables
4719 Gnus uses @dfn{rule variables} to decide how to view a file. All these
4720 variables are on the form
4723 (list '(regexp1 command2)
4730 @item gnus-uu-user-view-rules
4731 @vindex gnus-uu-user-view-rules
4733 This variable is consulted first when viewing files. If you wish to use,
4734 for instance, @code{sox} to convert an @samp{.au} sound file, you could
4737 (setq gnus-uu-user-view-rules
4738 (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
4741 @item gnus-uu-user-view-rules-end
4742 @vindex gnus-uu-user-view-rules-end
4743 This variable is consulted if Gnus couldn't make any matches from the
4744 user and default view rules.
4746 @item gnus-uu-user-archive-rules
4747 @vindex gnus-uu-user-archive-rules
4748 This variable can be used to say what commands should be used to unpack
4753 @node Other Decode Variables
4754 @subsubsection Other Decode Variables
4757 @vindex gnus-uu-grabbed-file-functions
4759 @item gnus-uu-grabbed-file-functions
4760 All functions in this list will be called right each file has been
4761 successfully decoded---so that you can move or view files right away,
4762 and don't have to wait for all files to be decoded before you can do
4763 anything. Ready-made functions you can put in this list are:
4767 @item gnus-uu-grab-view
4768 @findex gnus-uu-grab-view
4771 @item gnus-uu-grab-move
4772 @findex gnus-uu-grab-move
4773 Move the file (if you're using a saving function.)
4776 @item gnus-uu-ignore-files-by-name
4777 @vindex gnus-uu-ignore-files-by-name
4778 Files with name matching this regular expression won't be viewed.
4780 @item gnus-uu-ignore-files-by-type
4781 @vindex gnus-uu-ignore-files-by-type
4782 Files with a @sc{mime} type matching this variable won't be viewed.
4783 Note that Gnus tries to guess what type the file is based on the name.
4784 @code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
4787 @item gnus-uu-tmp-dir
4788 @vindex gnus-uu-tmp-dir
4789 Where @code{gnus-uu} does its work.
4791 @item gnus-uu-do-not-unpack-archives
4792 @vindex gnus-uu-do-not-unpack-archives
4793 Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
4794 looking for files to display.
4796 @item gnus-uu-view-and-save
4797 @vindex gnus-uu-view-and-save
4798 Non-@code{nil} means that the user will always be asked to save a file
4801 @item gnus-uu-ignore-default-view-rules
4802 @vindex gnus-uu-ignore-default-view-rules
4803 Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
4806 @item gnus-uu-ignore-default-archive-rules
4807 @vindex gnus-uu-ignore-default-archive-rules
4808 Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
4811 @item gnus-uu-kill-carriage-return
4812 @vindex gnus-uu-kill-carriage-return
4813 Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
4816 @item gnus-uu-unmark-articles-not-decoded
4817 @vindex gnus-uu-unmark-articles-not-decoded
4818 Non-@code{nil} means that @code{gnus-uu} will mark articles that were
4819 unsuccessfully decoded as unread.
4821 @item gnus-uu-correct-stripped-uucode
4822 @vindex gnus-uu-correct-stripped-uucode
4823 Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
4824 uuencoded files that have had trailing spaces deleted.
4826 @item gnus-uu-view-with-metamail
4827 @vindex gnus-uu-view-with-metamail
4829 Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
4830 commands defined by the rule variables and just fudge a @sc{mime}
4831 content type based on the file name. The result will be fed to
4832 @code{metamail} for viewing.
4834 @item gnus-uu-save-in-digest
4835 @vindex gnus-uu-save-in-digest
4836 Non-@code{nil} means that @code{gnus-uu}, when asked to save without
4837 decoding, will save in digests. If this variable is @code{nil},
4838 @code{gnus-uu} will just save everything in a file without any
4839 embellishments. The digesting almost conforms to RFC1153---no easy way
4840 to specify any meaningful volume and issue numbers were found, so I
4841 simply dropped them.
4846 @node Uuencoding and Posting
4847 @subsubsection Uuencoding and Posting
4851 @item gnus-uu-post-include-before-composing
4852 @vindex gnus-uu-post-include-before-composing
4853 Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
4854 before you compose the article. If this variable is @code{t}, you can
4855 either include an encoded file with @kbd{C-c C-i} or have one included
4856 for you when you post the article.
4858 @item gnus-uu-post-length
4859 @vindex gnus-uu-post-length
4860 Maximum length of an article. The encoded file will be split into how
4861 many articles it takes to post the entire file.
4863 @item gnus-uu-post-threaded
4864 @vindex gnus-uu-post-threaded
4865 Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
4866 thread. This may not be smart, as no other decoder I have seen are able
4867 to follow threads when collecting uuencoded articles. (Well, I have
4868 seen one package that does that---@code{gnus-uu}, but somehow, I don't
4869 think that counts...) Default is @code{nil}.
4871 @item gnus-uu-post-separate-description
4872 @vindex gnus-uu-post-separate-description
4873 Non-@code{nil} means that the description will be posted in a separate
4874 article. The first article will typically be numbered (0/x). If this
4875 variable is @code{nil}, the description the user enters will be included
4876 at the beginning of the first article, which will be numbered (1/x).
4877 Default is @code{t}.
4883 @subsection Viewing Files
4884 @cindex viewing files
4885 @cindex pseudo-articles
4887 After decoding, if the file is some sort of archive, Gnus will attempt
4888 to unpack the archive and see if any of the files in the archive can be
4889 viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
4890 containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
4891 uncompress and de-tar the main file, and then view the two pictures.
4892 This unpacking process is recursive, so if the archive contains archives
4893 of archives, it'll all be unpacked.
4895 Finally, Gnus will normally insert a @dfn{pseudo-article} for each
4896 extracted file into the summary buffer. If you go to these
4897 ``articles'', you will be prompted for a command to run (usually Gnus
4898 will make a suggestion), and then the command will be run.
4900 @vindex gnus-view-pseudo-asynchronously
4901 If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
4902 until the viewing is done before proceeding.
4904 @vindex gnus-view-pseudos
4905 If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
4906 the pseudo-articles into the summary buffer, but view them
4907 immediately. If this variable is @code{not-confirm}, the user won't even
4908 be asked for a confirmation before viewing is done.
4910 @vindex gnus-view-pseudos-separately
4911 If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
4912 pseudo-article will be created for each file to be viewed. If
4913 @code{nil}, all files that use the same viewing command will be given as
4914 a list of parameters to that command.
4916 @vindex gnus-insert-pseudo-articles
4917 If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert
4918 pseudo-articles when decoding. It is @code{t} by default.
4920 So; there you are, reading your @emph{pseudo-articles} in your
4921 @emph{virtual newsgroup} from the @emph{virtual server}; and you think:
4922 Why isn't anything real anymore? How did we get here?
4925 @node Article Treatment
4926 @section Article Treatment
4928 Reading through this huge manual, you may have quite forgotten that the
4929 object of newsreaders are to actually, like, read what people have
4930 written. Reading articles. Unfortunately, people are quite bad at
4931 writing, so there are tons of functions and variables to make reading
4932 these articles easier.
4935 * Article Highlighting:: You want to make the article look like fruit salad.
4936 * Article Hiding:: You also want to make certain info go away.
4937 * Article Washing:: Lots of way-neat functions to make life better.
4938 * Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
4939 * Article Date:: Grumble, UT!
4943 @node Article Highlighting
4944 @subsection Article Highlighting
4947 Not only do you want your article buffer to look like fruit salad, but
4948 you want it to look like technicolor fruit salad.
4953 @kindex W H a (Summary)
4954 @findex gnus-article-highlight
4955 Highlight the current article (@code{gnus-article-highlight}).
4958 @kindex W H h (Summary)
4959 @findex gnus-article-highlight-headers
4960 @vindex gnus-header-face-alist
4961 Highlight the headers (@code{gnus-article-highlight-headers}). The
4962 highlighting will be done according to the @code{gnus-header-face-alist}
4963 variable, which is a list where each element has the form @var{(regexp
4964 name content)}. @var{regexp} is a regular expression for matching the
4965 header, @var{name} is the face used for highlighting the header name and
4966 @var{content} is the face for highlighting the header value. The first
4967 match made will be used. Note that @var{regexp} shouldn't have @samp{^}
4968 prepended---Gnus will add one.
4971 @kindex W H c (Summary)
4972 @findex gnus-article-highlight-citation
4973 Highlight cited text (@code{gnus-article-highlight-citation}).
4975 Some variables to customize the citation highlights:
4978 @vindex gnus-cite-parse-max-size
4980 @item gnus-cite-parse-max-size
4981 If the article size if bigger than this variable (which is 25000 by
4982 default), no citation highlighting will be performed.
4984 @item gnus-cite-prefix-regexp
4985 @vindex gnus-cite-prefix-regexp
4986 Regexp matching the longest possible citation prefix on a line.
4988 @item gnus-cite-max-prefix
4989 @vindex gnus-cite-max-prefix
4990 Maximum possible length for a citation prefix (default 20).
4992 @item gnus-cite-face-list
4993 @vindex gnus-cite-face-list
4994 List of faces used for highlighting citations. When there are citations
4995 from multiple articles in the same message, Gnus will try to give each
4996 citation from each article its own face. This should make it easier to
4999 @item gnus-supercite-regexp
5000 @vindex gnus-supercite-regexp
5001 Regexp matching normal SuperCite attribution lines.
5003 @item gnus-supercite-secondary-regexp
5004 @vindex gnus-supercite-secondary-regexp
5005 Regexp matching mangled SuperCite attribution lines.
5007 @item gnus-cite-minimum-match-count
5008 @vindex gnus-cite-minimum-match-count
5009 Minimum number of identical prefixes we have to see before we believe
5010 that it's a citation.
5012 @item gnus-cite-attribution-prefix
5013 @vindex gnus-cite-attribution-prefix
5014 Regexp matching the beginning of an attribution line.
5016 @item gnus-cite-attribution-suffix
5017 @vindex gnus-cite-attribution-suffix
5018 Regexp matching the end of an attribution line.
5020 @item gnus-cite-attribution-face
5021 @vindex gnus-cite-attribution-face
5022 Face used for attribution lines. It is merged with the face for the
5023 cited text belonging to the attribution.
5029 @kindex W H s (Summary)
5030 @vindex gnus-signature-separator
5031 @vindex gnus-signature-face
5032 @findex gnus-article-highlight-signature
5033 Highlight the signature (@code{gnus-article-highlight-signature}).
5034 Everything after @code{gnus-signature-separator} in an article will be
5035 considered a signature and will be highlighted with
5036 @code{gnus-signature-face}, which is @code{italic} by default.
5041 @node Article Hiding
5042 @subsection Article Hiding
5043 @cindex article hiding
5045 Or rather, hiding certain things in each article. There usually is much
5046 too much cruft in most articles.
5051 @kindex W W a (Summary)
5052 @findex gnus-article-hide
5053 Do maximum hiding on the summary buffer (@kbd{gnus-article-hide}).
5056 @kindex W W h (Summary)
5057 @findex gnus-article-hide-headers
5058 Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
5062 @kindex W W b (Summary)
5063 @findex gnus-article-hide-boring-headers
5064 Hide headers that aren't particularly interesting
5065 (@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}.
5068 @kindex W W s (Summary)
5069 @findex gnus-article-hide-signature
5070 Hide signature (@code{gnus-article-hide-signature}).
5073 @kindex W W p (Summary)
5074 @findex gnus-article-hide-pgp
5075 Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}).
5078 @kindex W W c (Summary)
5079 @findex gnus-article-hide-citation
5080 Hide citation (@code{gnus-article-hide-citation}). Some variables for
5081 customizing the hiding:
5085 @item gnus-cite-hide-percentage
5086 @vindex gnus-cite-hide-percentage
5087 If the cited text is of a bigger percentage than this variable (default
5088 50), hide the cited text.
5090 @item gnus-cite-hide-absolute
5091 @vindex gnus-cite-hide-absolute
5092 The cited text must be have at least this length (default 10) before it
5095 @item gnus-cited-text-button-line-format
5096 @vindex gnus-cited-text-button-line-format
5097 Gnus adds buttons show where the cited text has been hidden, and to
5098 allow toggle hiding the text. The format of the variable is specified
5099 by this format-like variable. These specs are legal:
5103 Start point of the hidden text.
5105 End point of the hidden text.
5107 Length of the hidden text.
5110 @item gnus-cited-lines-visible
5111 @vindex gnus-cited-lines-visible
5112 The number of lines at the beginning of the cited text to leave shown.
5117 @kindex W W C (Summary)
5118 @findex gnus-article-hide-citation-in-followups
5119 Hide cited text in articles that aren't roots
5120 (@code{gnus-article-hide-citation-in-followups}). This isn't very
5121 useful as an interactive command, but might be a handy function to stick
5122 in @code{gnus-article-display-hook} (@pxref{Customizing Articles}).
5126 All these ``hiding'' commands are toggles, but if you give a negative
5127 prefix to these commands, they will show what they have previously
5128 hidden. If you give a positive prefix, they will always hide.
5130 Also @pxref{Article Highlighting} for further variables for
5131 citation customization.
5133 @vindex gnus-signature-limit
5134 @code{gnus-signature-limit} provides a limit to what is considered a
5135 signature. If it is a number, no signature may not be longer (in
5136 characters) than that number. If it is a function, the function will be
5137 called without any parameters, and if it returns @code{nil}, there is no
5138 signature in the buffer. If it is a string, it will be used as a
5139 regexp. If it matches, the text in question is not a signature.
5142 @node Article Washing
5143 @subsection Article Washing
5145 @cindex article washing
5147 We call this ``article washing'' for a really good reason. Namely, the
5148 @kbd{A} key was taken, so we had to use the @kbd{W} key instead.
5150 @dfn{Washing} is defined by us as ``changing something from something to
5151 something else'', but normally results in something looking better.
5157 @kindex W l (Summary)
5158 @findex gnus-summary-stop-page-breaking
5159 Remove page breaks from the current article
5160 (@code{gnus-summary-stop-page-breaking}).
5163 @kindex W r (Summary)
5164 @findex gnus-summary-caesar-message
5165 Do a Caesar rotate (rot13) on the article buffer
5166 (@code{gnus-summary-caesar-message}).
5169 @kindex A g (Summary)
5170 @findex gnus-summary-show-article
5171 (Re)fetch the current article (@code{gnus-summary-show-article}). If
5172 given a prefix, fetch the current article, but don't run any of the
5173 article treatment functions. This will give you a ``raw'' article, just
5174 the way it came from the server.
5177 @kindex W t (Summary)
5178 @findex gnus-summary-toggle-header
5179 Toggle whether to display all headers in the article buffer
5180 (@code{gnus-summary-toggle-header}).
5183 @kindex W v (Summary)
5184 @findex gnus-summary-verbose-header
5185 Toggle whether to display all headers in the article buffer permanently
5186 (@code{gnus-summary-verbose-header}).
5189 @kindex W m (Summary)
5190 @findex gnus-summary-toggle-mime
5191 Toggle whether to run the article through @sc{mime} before displaying
5192 (@code{gnus-summary-toggle-mime}).
5195 @kindex W o (Summary)
5196 @findex gnus-article-treat-overstrike
5197 Treat overstrike (@code{gnus-article-treat-overstrike}).
5200 @kindex W w (Summary)
5201 @findex gnus-article-fill-cited-article
5202 Do word wrap (@code{gnus-article-fill-cited-article}).
5205 @kindex W c (Summary)
5206 @findex gnus-article-remove-cr
5207 Remove CR (@code{gnus-article-remove-cr}).
5210 @kindex W L (Summary)
5211 @findex gnus-article-remove-trailing-blank-lines
5212 Remove all blank lines at the end of the article
5213 (@code{gnus-article-remove-trailing-blank-lines}).
5216 @kindex W q (Summary)
5217 @findex gnus-article-de-quoted-unreadable
5218 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
5221 @kindex W f (Summary)
5223 @findex gnus-article-display-x-face
5224 @findex gnus-article-x-face-command
5225 @vindex gnus-article-x-face-command
5226 @vindex gnus-article-x-face-too-ugly
5227 Look for and display any X-Face headers
5228 (@code{gnus-article-display-x-face}). The command executed by this
5229 function is given by the @code{gnus-article-x-face-command} variable. If
5230 this variable is a string, this string will be executed in a sub-shell.
5231 If it is a function, this function will be called with the face as the
5232 argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
5233 matches the @code{From} header, the face will not be shown.
5236 @kindex W b (Summary)
5237 @findex gnus-article-add-buttons
5238 Add clickable buttons to the article (@code{gnus-article-add-buttons}).
5241 @kindex W B (Summary)
5242 @findex gnus-article-add-buttons-to-head
5243 Add clickable buttons to the article headers
5244 (@code{gnus-article-add-buttons-to-head}).
5249 @node Article Buttons
5250 @subsection Article Buttons
5253 People often include references to other stuff in articles, and it would
5254 be nice if Gnus could just fetch whatever it is that people talk about
5255 with the minimum of fuzz.
5257 Gnus adds @dfn{buttons} to certain standard references by default:
5258 Well-formed URLs, mail addresses and Message-IDs. This is controlled by
5259 two variables, one that handles article bodies and one that handles
5264 @item gnus-button-alist
5265 @vindex gnus-button-alist
5266 This is an alist where each entry has this form:
5269 (REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
5275 All text that match this regular expression will be considered an
5276 external reference. Here's a typical regexp that match embedded URLs:
5277 @samp{<URL:\\([^\n\r>]*\\)>}.
5280 Gnus has to know which parts of the match is to be highlighted. This is
5281 a number that says what sub-expression of the regexp that is to be
5282 highlighted. If you want it all highlighted, you use @code{0} here.
5285 This form will be @code{eval}ed, and if the result is non-@code{nil},
5286 this is considered a match. This is useful if you want extra sifting to
5287 avoid false matches.
5290 This function will be called when you click on this button.
5293 As with @var{button-par}, this is a sub-expression number, but this one
5294 says which part of the match is to be sent as data to @var{function}.
5298 So the full entry for buttonizing URLs is then
5301 ("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
5304 @item gnus-header-button-alist
5305 @vindex gnus-header-button-alist
5306 This is just like the other alist, except that it is applied to the
5307 article head only, and that each entry has an additional element that is
5308 used to say what headers to apply the buttonize coding to:
5311 (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
5314 @var{header} is a regular expression.
5316 @item gnus-button-url-regexp
5317 @vindex gnus-button-url-regexp
5318 A regular expression that matches embedded URLs. It is used in the
5319 default values of the variables above.
5321 @item gnus-article-button-face
5322 @vindex gnus-article-button-face
5323 Face used on bottons.
5325 @item gnus-article-mouse-face
5326 @vindex gnus-article-mouse-face
5327 Face is used when the mouse cursor is over a button.
5333 @subsection Article Date
5335 The date is most likely generated in some obscure timezone you've never
5336 heard of, so it's quite nice to be able to find out what the time was
5337 when the article was sent.
5342 @kindex W T u (Summary)
5343 @findex gnus-article-date-ut
5344 Display the date in UT (aka. GMT, aka ZULU)
5345 (@code{gnus-article-date-ut}).
5348 @kindex W T l (Summary)
5349 @findex gnus-article-date-local
5350 Display the date in the local timezone (@code{gnus-article-date-local}).
5353 @kindex W T e (Summary)
5354 @findex gnus-article-date-lapsed
5355 Say how much time has (e)lapsed between the article was posted and now
5356 (@code{gnus-article-date-lapsed}).
5359 @kindex W T o (Summary)
5360 @findex gnus-article-date-original
5361 Display the original date (@code{gnus-article-date-original}). This can
5362 be useful if you normally use some other conversion function and is
5363 worried that it might be doing something totally wrong. Say, claiming
5364 that the article was posted in 1854. Although something like that is
5365 @emph{totally} impossible. Don't you trust me? *titter*
5370 @node Summary Sorting
5371 @section Summary Sorting
5372 @cindex summary sorting
5374 You can have the summary buffer sorted in various ways, even though I
5375 can't really see why you'd want that.
5380 @kindex C-c C-s C-n (Summary)
5381 @findex gnus-summary-sort-by-number
5382 Sort by article number (@code{gnus-summary-sort-by-number}).
5385 @kindex C-c C-s C-a (Summary)
5386 @findex gnus-summary-sort-by-author
5387 Sort by author (@code{gnus-summary-sort-by-author}).
5390 @kindex C-c C-s C-s (Summary)
5391 @findex gnus-summary-sort-by-subject
5392 Sort by subject (@code{gnus-summary-sort-by-subject}).
5395 @kindex C-c C-s C-d (Summary)
5396 @findex gnus-summary-sort-by-date
5397 Sort by date (@code{gnus-summary-sort-by-date}).
5400 @kindex C-c C-s C-i (Summary)
5401 @findex gnus-summary-sort-by-score
5402 Sort by score (@code{gnus-summary-sort-by-score}).
5405 These functions will work both when you use threading and when you don't
5406 use threading. In the latter case, all summary lines will be sorted,
5407 line by line. In the former case, sorting will be done on a
5408 root-by-root basis, which might not be what you were looking for. To
5409 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
5413 @node Finding the Parent
5414 @section Finding the Parent
5415 @cindex parent articles
5416 @cindex referring articles
5418 @findex gnus-summary-refer-parent-article
5420 If you'd like to read the parent of the current article, and it is not
5421 displayed in the article buffer, you might still be able to. That is,
5422 if the current group is fetched by @sc{nntp}, the parent hasn't expired
5423 and the @code{References} in the current article are not mangled, you
5424 can just press @kbd{^} or @kbd{A r}
5425 (@code{gnus-summary-refer-parent-article}). If everything goes well,
5426 you'll get the parent. If the parent is already displayed in the
5427 summary buffer, point will just move to this article.
5429 @findex gnus-summary-refer-references
5430 @kindex A R (Summary)
5431 You can have Gnus fetch all articles mentioned in the @code{References}
5432 header of the article by pushing @kbd{A R}
5433 (@code{gnus-summary-refer-references}).
5435 @findex gnus-summary-refer-article
5436 @kindex M-^ (Summary)
5437 You can also ask the @sc{nntp} server for an arbitrary article, no
5438 matter what group it belongs to. @kbd{M-^}
5439 (@code{gnus-summary-refer-article}) will ask you for a
5440 @code{Message-ID}, which is one of those long thingies that look
5441 something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
5442 it all exactly right. No fuzzy searches, I'm afraid.
5444 @vindex gnus-refer-article-method
5445 If the group you are reading is located on a backend that does not
5446 support fetching by @code{Message-ID} very well (like @code{nnspool}),
5447 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
5448 would, perhaps, be best if the @sc{nntp} server you consult is the same
5449 as the one that keeps the spool you are reading from updated, but that's
5450 not really necessary.
5452 Most of the mail backends support fetching by @code{Message-ID}, but do
5453 not do a particularly excellent job of it. That is, @code{nnmbox} and
5454 @code{nnbabyl} are able to locate articles from any groups, while
5455 @code{nnml} and @code{nnfolder} are only able to locate articles that
5456 have been posted to the current group. (Anything else would be too time
5457 consuming.) @code{nnmh} does not support this at all.
5460 @node Alternative Approaches
5461 @section Alternative Approaches
5463 Different people like to read news using different methods. This being
5464 Gnus, we offer a small selection of minor modes for the summary buffers.
5467 * Pick and Read:: First mark articles and then read them.
5468 * Binary Groups:: Auto-decode all articles.
5473 @subsection Pick and Read
5474 @cindex pick and read
5476 Some newsreaders (like @code{nn} and, uhm, @code{nn}) use a two-phased
5477 reading interface. The user first marks the articles she wants to read
5478 from a summary buffer. Then she starts reading the articles with just
5479 an article buffer displayed.
5481 @findex gnus-pick-mode
5482 @kindex M-x gnus-pick-mode
5483 Gnus provides a summary buffer minor mode that allows
5484 this---@code{gnus-pick-mode}. This basically means that a few process
5485 mark commands become one-keystroke commands to allow easy marking, and
5486 it makes one additional command for switching to the summary buffer
5489 Here are the available keystrokes when using pick mode:
5493 @kindex SPACE (Pick)
5494 @findex gnus-summary-mark-as-processable
5495 Pick the article (@code{gnus-summary-mark-as-processable}).
5499 @findex gnus-summary-unmark-as-processable
5500 Unpick the article (@code{gnus-summary-unmark-as-processable}).
5504 @findex gnus-summary-unmark-all-processable
5505 Unpick all articles (@code{gnus-summary-unmark-all-processable}).
5509 @findex gnus-uu-mark-thread
5510 Pick the thread (@code{gnus-uu-mark-thread}).
5514 @findex gnus-uu-unmark-thread
5515 Unpick the thread (@code{gnus-uu-unmark-thread}).
5519 @findex gnus-uu-mark-region
5520 Pick the region (@code{gnus-uu-mark-region}).
5524 @findex gnus-uu-unmark-region
5525 Unpick the region (@code{gnus-uu-unmark-region}).
5529 @findex gnus-uu-unmark-regexp
5530 Pick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
5534 @findex gnus-uu-unmark-regexp
5535 Unpick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
5539 @findex gnus-uu-mark-buffer
5540 Pick the buffer (@code{gnus-uu-mark-buffer}).
5544 @findex gnus-uu-unmark-buffer
5545 Unpick the buffer (@code{gnus-uu-unmark-buffer}).
5549 @findex gnus-pick-start-reading
5550 @vindex gnus-pick-display-summary
5551 Start reading the picked articles (@code{gnus-pick-start-reading}). If
5552 given a prefix, mark all unpicked articles as read first. If
5553 @code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer
5554 will still be visible when you are reading.
5558 If this sounds like a good idea to you, you could say:
5561 (add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)
5564 @vindex gnus-pick-mode-hook
5565 @code{gnus-pick-mode-hook} is run in pick minor mode buffers.
5569 @subsection Binary Groups
5570 @cindex binary groups
5572 @findex gnus-binary-mode
5573 @kindex M-x gnus-binary-mode
5574 If you spend much time in binary groups, you may grow tired of hitting
5575 @kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode}
5576 is a minor mode for summary buffers that makes all ordinary Gnus article
5577 selection functions uudecode series of articles and display the result
5578 instead of just displaying the articles the normal way.
5581 @findex gnus-binary-show-article
5582 In fact, the only way to see the actual articles if you have turned this
5583 mode on is the @kbd{g} command (@code{gnus-binary-show-article}).
5585 @vindex gnus-binary-mode-hook
5586 @code{gnus-binary-mode-hook} is called in binary minor mode buffers.
5590 @section Tree Display
5593 @vindex gnus-use-trees
5594 If you don't like the normal Gnus summary display, you might try setting
5595 @code{gnus-use-trees} to @code{t}. This will create (by default) an
5596 additional @dfn{tree buffer}. You can execute all summary mode commands
5599 There are a few variables to customize the tree display, of course:
5602 @item gnus-tree-mode-hook
5603 @vindex gnus-tree-mode-hook
5604 A hook called in all tree mode buffers.
5606 @item gnus-tree-mode-line-format
5607 @vindex gnus-tree-mode-line-format
5608 A format string for the mode bar in the tree mode buffers. The default
5609 is @samp{Gnus: %%b [%A] %Z}. For a list of legal specs, @pxref{Summary
5612 @item gnus-selected-tree-face
5613 @vindex gnus-selected-tree-face
5614 Face used for highlighting the selected article in the tree buffer. The
5615 default is @code{modeline}.
5617 @item gnus-tree-line-format
5618 @vindex gnus-tree-line-format
5619 A format string for the tree nodes. The name is a bit of a misnomer,
5620 though---it doesn't define a line, but just the node. The default value
5621 is @samp{%(%[%3,3n%]%)}, which displays the first three characters of
5622 the name of the poster. It is vital that all nodes are of the same
5623 length, so you @emph{must} use @samp{%4,4n}-like specifiers.
5629 The name of the poster.
5631 The @code{From} header.
5633 The number of the article.
5635 The opening bracket.
5637 The closing bracket.
5642 @xref{Formatting Variables}.
5644 Variables related to the display are:
5647 @item gnus-tree-brackets
5648 @vindex gnus-tree-brackets
5649 This is used for differentiating between ``real'' articles and
5650 ``sparse'' articles. The format is @var{((real-open . real-close)
5651 (sparse-open . sparse-close) (dummy-open . dummy-close))}, and the
5652 default is @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}))}.
5654 @item gnus-tree-parent-child-edges
5655 @vindex gnus-tree-parent-child-edges
5656 This is a list that contains the characters used for connecting parent
5657 nodes to their children. The default is @code{(?- ?\\ ?|)}.
5661 @item gnus-tree-minimize-window
5662 @vindex gnus-tree-minimize-window
5663 If this variable is non-@code{nil}, Gnus will try to keep the tree
5664 buffer as small as possible to allow more room for the other Gnus
5665 windows. If this variable is a number, the tree buffer will never be
5666 higher than that number. The default is @code{t}.
5668 @item gnus-generate-tree-function
5669 @vindex gnus-generate-tree-function
5670 @findex gnus-generate-horizontal-tree
5671 @findex gnus-generate-vertical-tree
5672 The function that actually generates the thread tree. Two predefined
5673 functions are available: @code{gnus-generate-horizontal-tree} and
5674 @code{gnus-generate-vertical-tree} (which is the default).
5678 Here's and example from a horizontal tree buffer:
5681 @{***@}-(***)-[odd]-[Gun]
5691 Here's the same thread displayed in a vertical tree buffer:
5695 |--------------------------\-----\-----\
5696 (***) [Bjo] [Gun] [Gun]
5698 [odd] [Jan] [odd] (***) [Jor]
5700 [Gun] [Eri] [Eri] [odd]
5706 @node Mail Group Commands
5707 @section Mail Group Commands
5708 @cindex mail group commands
5710 Some commands only make sense in mail groups. If these commands are
5711 illegal in the current group, they will raise a hell and let you know.
5713 All these commands (except the expiry and edit commands) use the
5714 process/prefix convention (@pxref{Process/Prefix}).
5719 @kindex B e (Summary)
5720 @findex gnus-summary-expire-articles
5721 Expire all expirable articles in the group
5722 (@code{gnus-summary-expire-articles}).
5725 @kindex B M-C-e (Summary)
5726 @findex gnus-summary-expire-articles-now
5727 Expunge all the expirable articles in the group
5728 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
5729 articles that are eligible for expiry in the current group will
5730 disappear forever into that big @file{/dev/null} in the sky.
5733 @kindex B DEL (Summary)
5734 @findex gnus-summary-delete-articles
5735 Delete the mail article. This is ``delete'' as in ``delete it from your
5736 disk forever and ever, never to return again.'' Use with caution.
5737 (@code{gnus-summary-delete-article}).
5740 @kindex B m (Summary)
5742 @findex gnus-summary-move-article
5743 Move the article from one mail group to another
5744 (@code{gnus-summary-move-article}).
5747 @kindex B c (Summary)
5749 @findex gnus-summary-copy-article
5750 Copy the article from one group (mail group or not) to a mail group
5751 (@code{gnus-summary-copy-article}).
5754 @kindex B C (Summary)
5755 @cindex crosspost mail
5756 @findex gnus-summary-crosspost-article
5757 Crosspost the current article to some other group
5758 (@code{gnus-summary-crosspost-article}). This will create a new copy of
5759 the article in the other group, and the Xref headers of the article will
5760 be properly updated.
5763 @kindex B i (Summary)
5764 @findex gnus-summary-import-article
5765 Import an arbitrary file into the current mail newsgroup
5766 (@code{gnus-summary-import-article}). You will be prompted for a file
5767 name, a @code{From} header and a @code{Subject} header.
5769 Something similar can be done by just starting to compose a mail
5770 message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
5771 @kbd{C-c M-C-p} instead. This will put the message you have just created
5772 into the current mail group.
5775 @kindex B r (Summary)
5776 @findex gnus-summary-respool-article
5777 Respool the mail article (@code{gnus-summary-move-article}).
5781 @kindex B w (Summary)
5783 @findex gnus-summary-edit-article
5784 @kindex C-c C-c (Article)
5785 Edit the current article (@code{gnus-summary-edit-article}). To finish
5786 editing and make the changes permanent, type @kbd{C-c C-c}
5787 (@kbd{gnus-summary-edit-article-done}).
5790 @kindex B q (Summary)
5791 @findex gnus-summary-respool-query
5792 If you want to re-spool an article, you might be curious as to what group
5793 the article will end up in before you do the re-spooling. This command
5794 will tell you (@code{gnus-summary-respool-query}).
5797 @vindex gnus-move-split-methods
5798 @cindex moving articles
5799 If you move (or copy) articles regularly, you might wish to have Gnus
5800 suggest where to put the articles. @code{gnus-move-split-methods} is a
5801 variable that uses the same syntax as @code{gnus-split-methods}
5802 (@pxref{Saving Articles}). You may customize that variable to create
5803 suggestions you find reasonable.
5806 @node Various Summary Stuff
5807 @section Various Summary Stuff
5810 * Summary Group Information:: Information oriented commands.
5811 * Searching for Articles:: Multiple article commands.
5812 * Really Various Summary Commands:: Those pesky non-conformant commands.
5816 @vindex gnus-summary-mode-hook
5817 @item gnus-summary-mode-hook
5818 This hook is called when creating a summary mode buffer.
5820 @vindex gnus-summary-generate-hook
5821 @item gnus-summary-generate-hook
5822 This is called as the last thing before doing the threading and the
5823 generation of the summary buffer. It's quite convenient for customizing
5824 the threading variables based on what data the newsgroup has. This hook
5825 is called from the summary buffer after most summary buffer variables
5828 @vindex gnus-summary-prepare-hook
5829 @item gnus-summary-prepare-hook
5830 Is is called after the summary buffer has been generated. You might use
5831 it to, for instance, highlight lines or modify the look of the buffer in
5832 some other ungodly manner. I don't care.
5837 @node Summary Group Information
5838 @subsection Summary Group Information
5843 @kindex H f (Summary)
5844 @findex gnus-summary-fetch-faq
5845 @vindex gnus-group-faq-directory
5846 Try to fetch the FAQ (list of frequently asked questions) for the
5847 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
5848 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
5849 on a remote machine. This variable can also be a list of directories.
5850 In that case, giving a prefix to this command will allow you to choose
5851 between the various sites. @code{ange-ftp} probably will be used for
5855 @kindex H d (Summary)
5856 @findex gnus-summary-describe-group
5857 Give a brief description of the current group
5858 (@code{gnus-summary-describe-group}). If given a prefix, force
5859 rereading the description from the server.
5862 @kindex H h (Summary)
5863 @findex gnus-summary-describe-briefly
5864 Give a very brief description of the most important summary keystrokes
5865 (@code{gnus-summary-describe-briefly}).
5868 @kindex H i (Summary)
5869 @findex gnus-info-find-node
5870 Go to the Gnus info node (@code{gnus-info-find-node}).
5874 @node Searching for Articles
5875 @subsection Searching for Articles
5880 @kindex M-s (Summary)
5881 @findex gnus-summary-search-article-forward
5882 Search through all subsequent articles for a regexp
5883 (@code{gnus-summary-search-article-forward}).
5886 @kindex M-r (Summary)
5887 @findex gnus-summary-search-article-backward
5888 Search through all previous articles for a regexp
5889 (@code{gnus-summary-search-article-backward}).
5893 @findex gnus-summary-execute-command
5894 This command will prompt you for a header field, a regular expression to
5895 match on this field, and a command to be executed if the match is made
5896 (@code{gnus-summary-execute-command}).
5899 @kindex M-& (Summary)
5900 @findex gnus-summary-universal-argument
5901 Perform any operation on all articles that have been marked with
5902 the process mark (@code{gnus-summary-universal-argument}).
5906 @node Really Various Summary Commands
5907 @subsection Really Various Summary Commands
5912 @kindex A D (Summary)
5913 @findex gnus-summary-enter-digest-group
5914 If the current article is a collection of other articles (for instance,
5915 a digest), you might use this command to enter a group based on the that
5916 article (@code{gnus-summary-enter-digest-group}). Gnus will try to
5917 guess what article type is currently displayed unless you give a prefix
5918 to this command, which forces a ``digest'' interpretation. Basically,
5919 whenever you see a message that is a collection of other messages on
5920 some format, you @kbd{A D} and read these messages in a more convenient
5924 @kindex C-t (Summary)
5925 @findex gnus-summary-toggle-truncation
5926 Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
5930 @findex gnus-summary-expand-window
5931 Expand the summary buffer window (@code{gnus-summary-expand-window}).
5932 If given a prefix, force an @code{article} window configuration.
5936 @node Exiting the Summary Buffer
5937 @section Exiting the Summary Buffer
5938 @cindex summary exit
5939 @cindex exiting groups
5941 Exiting from the summary buffer will normally update all info on the
5942 group and return you to the group buffer.
5948 @kindex Z Z (Summary)
5950 @findex gnus-summary-exit
5951 @vindex gnus-summary-exit-hook
5952 @vindex gnus-summary-prepare-exit-hook
5953 Exit the current group and update all information on the group
5954 (@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
5955 called before doing much of the exiting, and calls
5956 @code{gnus-summary-expire-articles} by default.
5957 @code{gnus-summary-exit-hook} is called after finishing the exiting
5962 @kindex Z E (Summary)
5964 @findex gnus-summary-exit-no-update
5965 Exit the current group without updating any information on the group
5966 (@code{gnus-summary-exit-no-update}).
5970 @kindex Z c (Summary)
5972 @findex gnus-summary-catchup-and-exit
5973 Mark all unticked articles in the group as read and then exit
5974 (@code{gnus-summary-catchup-and-exit}).
5977 @kindex Z C (Summary)
5978 @findex gnus-summary-catchup-all-and-exit
5979 Mark all articles, even the ticked ones, as read and then exit
5980 (@code{gnus-summary-catchup-all-and-exit}).
5983 @kindex Z n (Summary)
5984 @findex gnus-summary-catchup-and-goto-next-group
5985 Mark all articles as read and go to the next group
5986 (@code{gnus-summary-catchup-and-goto-next-group}).
5989 @kindex Z R (Summary)
5990 @findex gnus-summary-reselect-current-group
5991 Exit this group, and then enter it again
5992 (@code{gnus-summary-reselect-current-group}). If given a prefix, select
5993 all articles, both read and unread.
5997 @kindex Z G (Summary)
5998 @kindex M-g (Summary)
5999 @findex gnus-summary-rescan-group
6000 Exit the group, check for new articles in the group, and select the
6001 group (@code{gnus-summary-rescan-group}). If given a prefix, select all
6002 articles, both read and unread.
6005 @kindex Z N (Summary)
6006 @findex gnus-summary-next-group
6007 Exit the group and go to the next group
6008 (@code{gnus-summary-next-group}).
6011 @kindex Z P (Summary)
6012 @findex gnus-summary-prev-group
6013 Exit the group and go to the previous group
6014 (@code{gnus-summary-prev-group}).
6017 @vindex gnus-exit-group-hook
6018 @code{gnus-exit-group-hook} is called when you exit the current
6021 @findex gnus-summary-wake-up-the-dead
6022 @findex gnus-dead-summary-mode
6023 @vindex gnus-kill-summary-on-exit
6024 If you're in the habit of exiting groups, and then changing your mind
6025 about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}.
6026 If you do that, Gnus won't kill the summary buffer when you exit it.
6027 (Quelle surprise!) Instead it will change the name of the buffer to
6028 something like @samp{*Dead Summary ... *} and install a minor mode
6029 called @code{gnus-dead-summary-mode}. Now, if you switch back to this
6030 buffer, you'll find that all keys are mapped to a function called
6031 @code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead
6032 summary buffer will result in a live, normal summary buffer.
6034 There will never be more than one dead summary buffer at any one time.
6036 @vindex gnus-use-cross-reference
6037 The data on the current group will be updated (which articles you have
6038 read, which articles you have replied to, etc.) when you exit the
6039 summary buffer. If the @code{gnus-use-cross-reference} variable is
6040 @code{t} (which is the default), articles that are cross-referenced to
6041 this group and are marked as read, will also be marked as read in the
6042 other subscribed groups they were cross-posted to. If this variable is
6043 neither @code{nil} nor @code{t}, the article will be marked as read in
6044 both subscribed and unsubscribed groups.
6048 Marking cross-posted articles as read ensures that you'll never have to
6049 read the same article more than once. Unless, of course, somebody has
6050 posted it to several groups separately. Posting the same article to
6051 several groups (not cross-posting) is called @dfn{spamming}, and you are
6052 by law required to send nasty-grams to anyone who perpetrates such a
6055 Remember: Cross-posting is kinda ok, but posting the same article
6056 separately to several groups is not.
6058 @cindex cross-posting
6061 One thing that may cause Gnus to not do the cross-posting thing
6062 correctly is if you use an @sc{nntp} server that supports @sc{xover}
6063 (which is very nice, because it speeds things up considerably) which
6064 does not include the @code{Xref} header in its @sc{nov} lines. This is
6065 Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
6066 even with @sc{xover} by registering the @code{Xref} lines of all
6067 articles you actually read, but if you kill the articles, or just mark
6068 them as read without reading them, Gnus will not get a chance to snoop
6069 the @code{Xref} lines out of these articles, and will be unable to use
6070 the cross reference mechanism.
6072 @cindex LIST overview.fmt
6073 @cindex overview.fmt
6074 To check whether your @sc{nntp} server includes the @code{Xref} header
6075 in its overview files, try @samp{telnet your.nntp.server nntp},
6076 @samp{MODE READER} on @code{inn} servers, and then say @samp{LIST
6077 overview.fmt}. This may not work, but if it does, and the last line you
6078 get does not read @samp{Xref:full}, then you should shout and whine at
6079 your news admin until she includes the @code{Xref} header in the
6082 @vindex gnus-nov-is-evil
6083 If you want Gnus to get the @code{Xref}s right all the time, you have to
6084 set @code{gnus-nov-is-evil} to @code{t}, which slows things down
6090 @node The Article Buffer
6091 @chapter The Article Buffer
6092 @cindex article buffer
6094 The articles are displayed in the article buffer, of which there is only
6095 one. All the summary buffers share the same article buffer unless you
6096 tell Gnus otherwise.
6099 * Hiding Headers:: Deciding what headers should be displayed.
6100 * Using MIME:: Pushing articles through @sc{mime} before reading them.
6101 * Customizing Articles:: Tailoring the look of the articles.
6102 * Article Keymap:: Keystrokes available in the article buffer
6103 * Misc Article:: Other stuff.
6107 @node Hiding Headers
6108 @section Hiding Headers
6109 @cindex hiding headers
6110 @cindex deleting headers
6112 The top section of each article is the @dfn{head}. (The rest is the
6113 @dfn{body}, but you may have guessed that already.)
6115 @vindex gnus-show-all-headers
6116 There is a lot of useful information in the head: the name of the person
6117 who wrote the article, the date it was written and the subject of the
6118 article. That's well and nice, but there's also lots of information
6119 most people do not want to see---what systems the article has passed
6120 through before reaching you, the @code{Message-ID}, the
6121 @code{References}, etc. ad nauseum---and you'll probably want to get rid
6122 of some of those lines. If you want to keep all those lines in the
6123 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
6125 Gnus provides you with two variables for sifting headers:
6129 @item gnus-visible-headers
6130 @vindex gnus-visible-headers
6131 If this variable is non-@code{nil}, it should be a regular expression
6132 that says what headers you wish to keep in the article buffer. All
6133 headers that do not match this variable will be hidden.
6135 For instance, if you only want to see the name of the person who wrote
6136 the article and the subject, you'd say:
6139 (setq gnus-visible-headers "^From:\\|^Subject:")
6142 This variable can also be a list of regexps to match headers that are to
6145 @item gnus-ignored-headers
6146 @vindex gnus-ignored-headers
6147 This variable is the reverse of @code{gnus-visible-headers}. If this
6148 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
6149 should be a regular expression that matches all lines that you want to
6150 hide. All lines that do not match this variable will remain visible.
6152 For instance, if you just want to get rid of the @code{References} line
6153 and the @code{Xref} line, you might say:
6156 (setq gnus-ignored-headers "^References:\\|^Xref:")
6159 This variable can also be a list of regexps to match headers that are to
6162 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
6163 variable will have no effect.
6167 @vindex gnus-sorted-header-list
6168 Gnus can also sort the headers for you. (It does this by default.) You
6169 can control the sorting by setting the @code{gnus-sorted-header-list}
6170 variable. It is a list of regular expressions that says in what order
6171 the headers are to be displayed.
6173 For instance, if you want the name of the author of the article first,
6174 and then the subject, you might say something like:
6177 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
6180 Any headers that are to remain visible, but are not listed in this
6181 variable, will be displayed in random order after all the headers that
6182 are listed in this variable.
6184 @findex gnus-article-hide-boring-headers
6185 @vindex gnus-article-display-hook
6186 @vindex gnus-boring-article-headers
6187 You can hide further boring headers by entering
6188 @code{gnus-article-hide-boring-headers} into
6189 @code{gnus-article-display-hook}. What this function does depends on
6190 the @code{gnus-boring-article-headers} variable. It's a list, but this
6191 list doesn't actually contain header names. Instead is lists various
6192 @dfn{boring conditions} that Gnus can check and remove from sight.
6194 These conditions are:
6197 Remove all empty headers.
6199 Remove the @code{Newsgroups} header if it only contains the current group
6202 Remove the @code{Followup-To} header if it is identical to the
6203 @code{Newsgroups} header.
6205 Remove the @code{Reply-To} header if it lists the same address as the
6208 Remove the @code{Date} header if the article is less than three days
6212 To include the four first elements, you could say something like;
6215 (setq gnus-boring-article-headers
6216 '(empty newsgroups followup-to reply-to))
6219 This is also the default value for this variable.
6223 @section Using @sc{mime}
6226 Mime is a standard for waving your hands through the air, aimlessly,
6227 while people stand around yawning.
6229 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
6230 while all newsreaders die of fear.
6232 @sc{mime} may specify what character set the article uses, the encoding
6233 of the characters, and it also makes it possible to embed pictures and
6234 other naughty stuff in innocent-looking articles.
6236 @vindex gnus-show-mime
6237 @vindex gnus-show-mime-method
6238 @vindex gnus-strict-mime
6239 @findex metamail-buffer
6240 Gnus handles @sc{mime} by shoving the articles through
6241 @code{gnus-show-mime-method}, which is @code{metamail-buffer} by
6242 default. Set @code{gnus-show-mime} to @code{t} if you want to use
6243 @sc{mime} all the time. However, if @code{gnus-strict-mime} is
6244 non-@code{nil}, the @sc{mime} method will only be used if there are
6245 @sc{mime} headers in the article.
6247 It might be best to just use the toggling functions from the summary
6248 buffer to avoid getting nasty surprises. (For instance, you enter the
6249 group @samp{alt.sing-a-long} and, before you know it, @sc{mime} has
6250 decoded the sound file in the article and some horrible sing-a-long song
6251 comes streaming out out your speakers, and you can't find the volume
6252 button, because there isn't one, and people are starting to look at you,
6253 and you try to stop the program, but you can't, and you can't find the
6254 program to control the volume, and everybody else in the room suddenly
6255 decides to look at you disdainfully, and you'll feel rather stupid.)
6257 Any similarity to real events and people is purely coincidental. Ahem.
6260 @node Customizing Articles
6261 @section Customizing Articles
6262 @cindex article customization
6264 @vindex gnus-article-display-hook
6265 The @code{gnus-article-display-hook} is called after the article has
6266 been inserted into the article buffer. It is meant to handle all
6267 treatment of the article before it is displayed.
6269 @findex gnus-article-maybe-highlight
6270 By default it contains @code{gnus-article-hide-headers},
6271 @code{gnus-article-treat-overstrike}, and
6272 @code{gnus-article-maybe-highlight}, but there are thousands, nay
6273 millions, of functions you can put in this hook. For an overview of
6274 functions @pxref{Article Highlighting}, @pxref{Article Hiding},
6275 @pxref{Article Washing}, @pxref{Article Buttons} and @pxref{Article
6278 You can, of course, write your own functions. The functions are called
6279 from the article buffer, and you can do anything you like, pretty much.
6280 There is no information that you have to keep in the buffer---you can
6281 change everything. However, you shouldn't delete any headers. Instead
6282 make them invisible if you want to make them go away.
6285 @node Article Keymap
6286 @section Article Keymap
6288 Most of the keystrokes in the summary buffer can also be used in the
6289 article buffer. They should behave as if you typed them in the summary
6290 buffer, which means that you don't actually have to have a summary
6291 buffer displayed while reading. You can do it all from the article
6294 A few additional keystrokes are available:
6299 @kindex SPACE (Article)
6300 @findex gnus-article-next-page
6301 Scroll forwards one page (@code{gnus-article-next-page}).
6304 @kindex DEL (Article)
6305 @findex gnus-article-prev-page
6306 Scroll backwards one page (@code{gnus-article-prev-page}).
6309 @kindex C-c ^ (Article)
6310 @findex gnus-article-refer-article
6311 If point is in the neighborhood of a @code{Message-ID} and you press
6312 @kbd{r}, Gnus will try to get that article from the server
6313 (@code{gnus-article-refer-article}).
6316 @kindex C-c C-m (Article)
6317 @findex gnus-article-mail
6318 Send a reply to the address near point (@code{gnus-article-mail}). If
6319 given a prefix, include the mail.
6323 @findex gnus-article-show-summary
6324 Reconfigure the buffers so that the summary buffer becomes visible
6325 (@code{gnus-article-show-summary}).
6329 @findex gnus-article-describe-briefly
6330 Give a very brief description of the available keystrokes
6331 (@code{gnus-article-describe-briefly}).
6334 @kindex TAB (Article)
6335 @findex gnus-article-next-button
6336 Go to the next button, if any (@code{gnus-article-next-button}. This
6337 only makes sense if you have buttonizing turned on.
6340 @kindex M-TAB (Article)
6341 @findex gnus-article-prev-button
6342 Go to the previous button, if any (@code{gnus-article-prev-button}.
6348 @section Misc Article
6352 @item gnus-single-article-buffer
6353 @vindex gnus-single-article-buffer
6354 If non-@code{nil}, use the same article buffer for all the groups.
6355 (This is the default.) If @code{nil}, each group will have its own
6358 @vindex gnus-article-prepare-hook
6359 @item gnus-article-prepare-hook
6360 This hook is called right after the article has been inserted into the
6361 article buffer. It is mainly intended for functions that do something
6362 depending on the contents; it should probably not be used for changing
6363 the contents of the article buffer.
6365 @vindex gnus-article-display-hook
6366 @item gnus-article-display-hook
6367 This hook is called as the last thing when displaying an article, and is
6368 intended for modifying the contents of the buffer, doing highlights,
6369 hiding headers, and the like.
6371 @item gnus-article-mode-hook
6372 @vindex gnus-article-mode-hook
6373 Hook called in article mode buffers.
6375 @vindex gnus-article-mode-line-format
6376 @item gnus-article-mode-line-format
6377 This variable is a format string along the same lines as
6378 @code{gnus-summary-mode-line-format}. It accepts exactly the same
6379 format specifications as that variable.
6380 @vindex gnus-break-pages
6382 @item gnus-break-pages
6383 Controls whether @dfn{page breaking} is to take place. If this variable
6384 is non-@code{nil}, the articles will be divided into pages whenever a
6385 page delimiter appears in the article. If this variable is @code{nil},
6386 paging will not be done.
6388 @item gnus-page-delimiter
6389 @vindex gnus-page-delimiter
6390 This is the delimiter mentioned above. By default, it is @samp{^L}
6401 All message composition (both mail and news) takes place in
6402 @code{message} mode buffers.
6405 * Message Interface:: Setting up message buffers.
6406 * Message Commands:: Commands you can execute in message mode buffers.
6407 * Message Variables:: Customizing the message buffers.
6411 @node Message Interface
6412 @section Message Interface
6414 When a program (or a person) wants to respond to a message -- reply,
6415 follow up, forward, cancel -- the program (or person) should just put
6416 point in the buffer where the message is and call the required command.
6417 @code{Message} will then pop up a new @code{message} mode buffer with
6418 appropriate headers filled out, and the user can edit the message before
6422 * New Mail Message::
6423 * New News Message::
6435 @node New Mail Message
6436 @subsection New Mail Message
6438 @findex message-mail
6439 The @code{message-mail} command pops up a new message buffer.
6441 Two optional parameters are accepted: The first will be used as the
6442 @code{To} header and the second as the @code{Subject} header. If these
6443 aren't present, those two headers will be empty.
6446 @node New News Message
6447 @subsection New News Message
6449 @findex message-news
6450 The @code{message-news} command pops up a new message buffer.
6452 This function accepts two optional parameters. The first will be used
6453 as the @code{Newsgroups} header and the second as the @code{Subject}
6454 header. If these aren't present, those two headers will be empty.
6460 @findex message-reply
6461 The @code{message-reply} function pops up a message buffer that's a
6462 reply to the message in the current buffer.
6464 @vindex message-reply-to-function
6465 Message uses the normal methods to determine where replies are to go,
6466 but you can change the behavior to suit your needs by fiddling with the
6467 @code{message-reply-to-function} variable.
6469 If you want the replies to go to the @code{Sender} instead of the
6470 @code{From}, you could do something like this:
6473 (setq message-reply-to-function
6475 (cond ((equal (mail-fetch-field "from") "somebody")
6476 (mail-fetch-field "sender"))
6481 This function will be called narrowed to the head of the article that is
6484 As you can see, this function should return a string if it has an
6485 opinion as to what the To header should be. If it does not, it should
6486 just return @code{nil}, and the normal methods for determining the To
6487 header will be used.
6489 This function can also return a list. In that case, each list element
6490 should be a cons, where the car should be the name of an header
6491 (eg. @code{Cc}) and the cdr should be the header value
6492 (eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into
6493 the head of the outgoing mail.
6497 @subsection Wide Reply
6499 @findex message-wide-reply
6500 The @code{message-wide-reply} pops up a message buffer that's a wide
6501 reply to the message in the current buffer.
6503 @vindex message-wide-reply-to-function
6504 Message uses the normal methods to determine where wide replies are to go,
6505 but you can change the behavior to suit your needs by fiddling with the
6506 @code{message-wide-reply-to-function}. It is used in the same way as
6507 @code{message-reply-to-function} (@pxref{Reply}).
6511 @subsection Followup
6513 @findex message-followup
6514 The @code{message-followup} command pops up a message buffer that's a
6515 followup to the message in the current buffer.
6517 @vindex message-followup-to-function
6518 Message uses the normal methods to determine where followups are to go,
6519 but you can change the behavior to suit your needs by fiddling with the
6520 @code{message-followup-to-function}. It is used in the same way as
6521 @code{message-reply-to-function} (@pxref{Reply}).
6523 @vindex message-use-followup-to
6524 The @code{message-use-followup-to} variable says what to do about
6525 @code{Followup-To} headers. If it is @code{use}, always use the value.
6526 If it is @code{ask} (which is the default), ask whether to use the
6527 value. If it is @code{t}, use the value unless it is @samp{poster}. If
6528 it is @code{nil}, don't use the value.
6531 @node Canceling News
6532 @subsection Canceling News
6534 @findex message-cancel-news
6535 The @code{message-cancel-news} command cancels the article in the
6540 @subsection Superseding
6542 @findex message-supersede
6543 The @code{message-supersede} command pops up a message buffer that will
6544 supersede the message in the current buffer.
6546 @vindex message-ignored-supersedes-headers
6547 Headers matching the @code{message-ignored-supersedes-headers} are
6548 removed before popping up the new message buffer. The default is
6549 @samp{^Path:\\|^Date\\|^NNTP-Posting-Host:\\|^Xref:\\|^Lines:\\|^Received:\\|^X-From-Line:\\|Return-Path:}.
6554 @subsection Forwarding
6556 @findex message-forward
6557 The @code{message-forward} command pops up a message buffer to forward
6558 the message in the current buffer. If given a prefix, forward using
6562 @item message-forward-start-separator
6563 @vindex message-forward-start-separator
6564 Delimiter inserted before forwarded messages. The default is
6565 @samp{------- Start of forwarded message -------\n}.
6567 @vindex message-forward-end-separator
6568 @item message-forward-end-separator
6569 @vindex message-forward-end-separator
6570 Delimiter inserted after forwarded messages. The default is
6571 @samp{------- End of forwarded message -------\n}.
6573 @item message-signature-before-forwarded-message
6574 @vindex message-signature-before-forwarded-message
6575 If this variable is @code{t}, which it is by default, your personal
6576 signature will be inserted before the forwarded message. If not, the
6577 forwarded message will be inserted first in the new mail.
6579 @item message-forward-included-headers
6580 @vindex message-forward-included-headers
6581 Regexp matching header lines to be included in forwarded messages.
6587 @subsection Resending
6589 @findex message-resend
6590 The @code{message-resend} command will prompt the user for an address
6591 and resend the message in the current buffer to that address.
6593 @vindex message-ignored-resent-headers
6594 Headers the match the @code{message-ignored-resent-headers} regexp will
6595 be removed before sending the message. The default is
6596 @samp{^Return-receipt}.
6600 @subsection Bouncing
6602 @findex message-bounce
6603 The @code{message-bounce} command will, if the current buffer contains a
6604 bounced mail message, pop up a message buffer stripped of the bounce
6607 @vindex message-ignored-bounced-headers
6608 Headers that match the @code{message-ignored-bounced-headers} regexp
6609 will be removed before popping up the buffer. The default is
6613 @node Message Commands
6614 @section Message Commands
6617 * Message Header Commands:: Commands for moving to headers.
6618 * Message Movement:: Moving around in message buffers.
6619 * Message Insertion:: Inserting things into message buffers.
6620 * Various Message:: Various things.
6621 * Sending Messages:: Actually sending the message.
6625 @node Message Header Commands
6626 @subsection Message Header Commands
6628 All these commands move to the header in question. If it doesn't exist,
6629 it will be inserted.
6634 @kindex C-c ? (Message)
6635 @findex message-goto-to
6636 Describe the message mode.
6639 @kindex C-c C-f C-t (Message)
6640 @findex message-goto-to
6641 Go to the @code{To} header (@code{message-goto-to}).
6644 @kindex C-c C-f C-b (Message)
6645 @findex message-goto-bcc
6646 Go to the @code{Bcc} header (@code{message-goto-bcc}).
6649 @kindex C-c C-f C-f (Message)
6650 @findex message-goto-fcc
6651 Go to the @code{Fcc} header (@code{message-goto-fcc}).
6654 @kindex C-c C-f C-c (Message)
6655 @findex message-goto-cc
6656 Go to the @code{Cc} header (@code{message-goto-cc}).
6659 @kindex C-c C-f C-s (Message)
6660 @findex message-goto-subject
6661 Go to the @code{Subject} header (@code{message-goto-subject}).
6664 @kindex C-c C-f C-r (Message)
6665 @findex message-goto-reply-to
6666 Go to the @code{Reply-To} header (@code{message-goto-reply-to}).
6669 @kindex C-c C-f C-n (Message)
6670 @findex message-goto-newsgroups
6671 Go to the @code{Newsgroups} header (@code{message-goto-newsgroups}).
6674 @kindex C-c C-f C-d (Message)
6675 @findex message-goto-distribution
6676 Go to the @code{Distribution} header (@code{message-goto-distribution}).
6679 @kindex C-c C-f C-o (Message)
6680 @findex message-goto-followup-to
6681 Go to the @code{Followup-To} header (@code{message-goto-followup-to}).
6684 @kindex C-c C-f C-k (Message)
6685 @findex message-goto-keywords
6686 Go to the @code{Keywords} header (@code{message-goto-keywords}).
6689 @kindex C-c C-f C-u (Message)
6690 @findex message-goto-summary
6691 Go to the @code{Summary} header (@code{message-goto-summary}).
6696 @node Message Movement
6697 @subsection Message Movement
6701 @kindex C-c C-b (Message)
6702 @findex message-goto-body
6703 Move to the beginning of the body of the message
6704 (@code{message-goto-body}).
6707 @kindex C-c C-i (Message)
6708 @findex message-goto-signature
6709 Move to the signature of the message (@code{message-goto-signature}).
6714 @node Message Insertion
6715 @subsection Message Insertion
6720 @kindex C-c C-y (Message)
6721 @findex message-yank-original
6722 Yank the message that's being replied to into the message buffer
6723 (@code{message-yank-original}).
6726 @kindex C-c C-q (Message)
6727 @findex message-fill-yanked-message
6728 Fill the yanked message (@code{message-fill-yanked-message}).
6731 @kindex C-c C-w (Message)
6732 @findex message-insert-signature
6733 Insert a signature at the end of the buffer
6734 (@code{message-insert-signature}).
6739 @item message-ignored-cited-headers
6740 @vindex message-ignored-cited-headers
6741 All headers that match this regexp will be removed from yanked
6742 messages. The default is @samp{.}, which means that all headers will be
6745 @item message-citation-line-function
6746 @vindex message-citation-line-function
6747 Function called to insert the citation line. The default is
6748 @code{message-insert-citation-line}.
6750 @item message-yank-prefix
6751 @vindex message-yank-prefix
6754 When you are replying to or following up an article, you normally want
6755 to quote the person you are answering. Inserting quoted text is done by
6756 @dfn{yanking}, and each quoted line you yank will have
6757 @code{message-yank-prefix} prepended to it. The default is @samp{> }.
6758 If it is @code{nil}, just indent the message.
6760 @item message-indentation-spaces
6761 @vindex message-indentation-spaces
6762 Number of spaces to indent yanked messages.
6764 @item message-cite-function
6765 @vindex message-cite-function
6766 Function for citing an original message. The default is
6767 @code{message-cite-original}.
6769 @item message-indent-citation-function
6770 @vindex message-indent-citation-function
6771 Function for modifying a citation just inserted in the mail buffer.
6772 This can also be a list of functions. Each function can find the
6773 citation between @code{(point)} and @code{(mark t)}. And each function
6774 should leave point and mark around the citation text as modified.
6776 @item message-signature
6777 @vindex message-signature
6778 String to be inserted at the end of the message buffer. If @code{t}
6779 (which is the default), the @code{message-signature-file} file will be
6780 inserted instead. If a function, the result from the function will be
6781 used instead. If a form, the result from the form will be used instead.
6782 If this variable is @code{nil}, no signature will be inserted at all.
6784 @item message-signature-file
6785 @vindex message-signature-file
6786 File containing the signature to be inserted at the end of the buffer.
6787 The default is @samp{~/.signature}.
6791 Note that RFC1036 says that a signature should be preceded by the three
6792 characters @samp{-- } on a line by themselves. This is to make it
6793 easier for the recipient to automatically recognize and process the
6794 signature. So don't remove those characters, even though you might feel
6795 that they ruin you beautiful design, like, totally.
6797 Also note that no signature should be more than four lines long.
6798 Including ASCII graphics is an efficient way to get everybody to believe
6799 that you are silly and have nothing important to say.
6803 @node Various Message
6804 @subsection Various Message
6809 @kindex C-c C-r (Message)
6810 @findex message-caesar-buffer-body
6811 Caesar rotate (aka. rot13) the current message
6812 (@code{message-caesar-buffer-body}). If narrowing is in effect, just
6813 rotate the visible portion of the buffer. A numerical prefix says how
6814 many places to rotate the text. The default is 13.
6817 @kindex C-c C-t (Message)
6818 @findex message-insert-to
6819 Insert a @code{To} header that contains the @code{Reply-To} or
6820 @code{From} header of the message you're following up
6821 (@code{message-insert-to}).
6824 @kindex C-c C-n (Message)
6825 @findex message-insert-newsgroups
6826 Insert a @code{Newsgroups} header that reflects the @code{Followup-To}
6827 or @code{Newsgroups} header of the article you're replying to
6828 (@code{message-insert-newsgroups}).
6833 @node Sending Messages
6834 @subsection Sending Messages
6838 @kindex C-c C-c (Message)
6839 @findex message-send-and-exit
6840 Send the message and bury the current buffer
6841 (@code{message-send-and-exit}).
6844 @kindex C-c C-s (Message)
6845 @findex message-send
6846 Send the message (@code{message-send}).
6851 @node Message Variables
6852 @section Message Variables
6860 * Various Message Variables::
6861 * Sending Variables::
6865 @node Message Headers
6866 @subsection Message Headers
6868 Message is a quite aggressive on the message generation front. It has
6869 to be -- it's a combined news and mail agent. To be able to send
6870 combined messages, it has to generate all headers itself to ensure that
6871 mail and news copies of messages look sufficiently similar.
6875 @item message-generate-headers-first
6876 @vindex message-generate-headers-first
6877 If non-@code{nil}, generate all headers before starting to compose the
6880 @item message-from-style
6881 @vindex message-from-style
6882 Specifies how @code{From} headers should look. There are four legal
6887 Just the address -- @samp{king@@grassland.com}.
6890 @samp{king@@grassland.com (Elvis Parsley)}.
6893 @samp{Elvis Parsley <king@@grassland.com>}.
6896 Look like @code{angles} if that doesn't require quoting, and
6897 @code{parens} if it does. If even @code{parens} requires quoting, use
6898 @code{angles} anyway.
6902 @item message-deletable-headers
6903 @vindex message-deletable-headers
6904 Headers in this list that were previously generated by Gnus will be
6905 deleted before posting. Let's say you post an article. Then you decide
6906 to post it again to some other group, you naughty boy, so you jump back
6907 to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
6908 ship it off again. By default, this variable makes sure that the old
6909 generated @code{Message-ID} is deleted, and a new one generated. If
6910 this isn't done, the entire empire would probably crumble, anarchy would
6911 prevail, and cats would start walking on two legs and rule the world.
6914 @item message-default-headers
6915 @vindex message-default-headers
6916 This string is inserted at the end of the headers in all message
6923 @subsection Mail Headers
6926 @item message-required-mail-headers
6927 @vindex message-required-mail-headers
6928 See @pxref{News Headers} for the syntax of this variable. It is
6929 @code{(From Date Subject (optional . In-Reply-To) Message-ID Lines
6930 (optional . X-Mailer))} by default.
6932 @item message-ignored-mail-headers
6933 @vindex message-ignored-mail-headers
6934 Regexp of headers to be removed before mailing. The default is
6935 @samp{^Gcc:\\|^Fcc:}.
6937 @item message-default-mail-headers
6938 @vindex message-default-mail-headers
6939 This string is inserted at the end of the headers in all message
6940 buffers that are initialized as mail.
6945 @node Mail Variables
6946 @subsection Mail Variables
6949 @item message-send-mail-function
6950 @vindex message-send-mail-function
6951 Function used to send the current buffer as mail. The default is
6952 @code{message-send-mail}.
6958 @subsection News Headers
6960 @vindex message-required-news-headers
6961 @code{message-required-news-headers} a list of header symbols. These
6962 headers will either be automatically generated, or, if that's
6963 impossible, they will be prompted for. The following symbols are legal:
6969 This required header will be filled out with the result of the
6970 @code{message-make-from} function, which depends on the
6971 @code{message-from-style}, @code{user-full-name},
6972 @code{user-mail-address} variables.
6976 This required header will be prompted for if not present already.
6980 This required header says which newsgroups the article is to be posted
6981 to. If it isn't present already, it will be prompted for.
6984 @cindex organization
6985 This optional header will be filled out depending on the
6986 @code{message-user-organization} variable.
6987 @code{message-user-organization-file} will be used if that variable is
6992 This optional header will be computed by Gnus.
6996 This required header will be generated by Gnus. A unique ID will be
6997 created based on date, time, user name and system name.
7000 @cindex X-Newsreader
7001 This optional header will be filled out according to the
7002 @code{message-newsreader} local variable.
7005 This optional header will be filled out according to the
7006 @code{message-mailer} local variable, unless there already is an
7007 @code{X-Newsreader} header present.
7010 This optional header is filled out using the @code{Date} and @code{From}
7011 header of the article being replied.
7015 This extremely optional header will be inserted according to the
7016 @code{message-expires} variable. It is highly deprecated and shouldn't
7017 be used unless you know what you're doing.
7020 @cindex Distribution
7021 This optional header is filled out according to the
7022 @code{message-distribution-function} variable. It is a deprecated and
7023 much misunderstood header.
7027 This extremely optional header should probably not ever be used.
7028 However, some @emph{very} old servers require that this header is
7029 present. @code{message-user-path} further controls how this
7030 @code{Path} header is to look. If is is @code{nil}, the the server name
7031 as the leaf node. If is is a string, use the string. If it is neither
7032 a string nor @code{nil}, use the user name only. However, it is highly
7033 unlikely that you should need to fiddle with this variable at all.
7037 @cindex Mime-Version
7038 In addition, you can enter conses into this list. The car of this cons
7039 should be a symbol. This symbol's name is the name of the header, and
7040 the cdr can either be a string to be entered verbatim as the value of
7041 this header, or it can be a function to be called. This function should
7042 return a string to be inserted. For instance, if you want to insert
7043 @code{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
7044 into the list. If you want to insert a funny quote, you could enter
7045 something like @code{(X-Yow . yow)} into the list. The function
7046 @code{yow} will then be called without any arguments.
7048 If the list contains a cons where the car of the cons is
7049 @code{optional}, the cdr of this cons will only be inserted if it is
7052 Other variables for customizing outgoing news articles:
7056 @item message-syntax-checks
7057 @vindex message-syntax-checks
7058 If non-@code{nil}, message will attempt to check the legality of the
7059 headers, as well as some other stuff, before posting. You can control
7060 the granularity of the check by adding or removing elements from this
7061 list. Legal elements are:
7065 Check the subject for commands.
7068 Insert a new @code{Sender} header if the @code{From} header looks odd.
7069 @item multiple-headers
7070 Check for the existence of multiple equal headers.
7073 Check for the existence of version and sendsys commands.
7075 Check whether the @code{Message-ID} looks ok.
7077 Check whether the @code{From} header seems nice.
7080 Check for too long lines.
7082 Check for illegal characters.
7084 Check for excessive size.
7086 Check whether there is any new text in the messages.
7088 Check the length of the signature.
7091 Check whether the article has an @code{Approved} header, which is
7092 something only moderators should include.
7094 Check whether the article is empty.
7096 Check whether any of the headers are empty.
7099 All these conditions are checked by default.
7101 @item message-ignored-news-headers
7102 @vindex message-ignored-news-headers
7103 Regexp of headers to be removed before posting. The default is
7104 @samp{^NNTP-Posting-Host:\\|^Xref:\\|^Bcc:\\|^Gcc:\\|^Fcc:}.
7106 @item message-default-news-headers
7107 @vindex message-default-news-headers
7108 This string is inserted at the end of the headers in all message
7109 buffers that are initialized as news.
7114 @node News Variables
7115 @subsection News Variables
7118 @item message-send-news-function
7119 @vindex message-send-news-function
7120 Function used to send the current buffer as news. The default is
7121 @code{message-send-news}.
7123 @item message-post-method
7124 @vindex message-post-method
7125 Method used for posting a prepared news message.
7130 @node Various Message Variables
7131 @subsection Various Message Variables
7134 @item message-signature-separator
7135 @vindex message-signature-separator
7136 Regexp matching the signature separator. It is @samp{^-- *$} by
7139 @item mail-header-separator
7140 @vindex mail-header-separator
7141 String used to separate the headers from the body. It is @samp{--text
7142 follows this line--} by default.
7144 @item message-autosave-directory
7145 @vindex message-autosave-directory
7146 Directory where message buffers will be autosaved to.
7148 @item message-setup-hook
7149 @vindex message-setup-hook
7150 Hook run when the message buffer has been initialized.
7152 @item message-header-setup-hook
7153 @vindex message-header-setup-hook
7154 Hook called narrowed to the headers after initializing the headers.
7156 @item message-send-hook
7157 @vindex message-send-hook
7158 Hook run before sending messages.
7160 @item message-sent-hook
7161 @vindex message-sent-hook
7162 Hook run after sending messages.
7164 @item message-mode-syntax-table
7165 @vindex message-mode-syntax-table
7166 Syntax table used in message mode buffers.
7172 @node Sending Variables
7173 @subsection Sending Variables
7177 @item message-fcc-handler-function
7178 @vindex message-fcc-handler-function
7179 A function called to save outgoing articles. This function will be
7180 called with the name of the file to store the article in. The default
7181 function is @code{rmail-output} which saves in Unix mailbox format.
7183 @item message-courtesy-message
7184 @vindex message-courtesy-message
7185 When sending combined messages, this string is inserted at the start of
7186 the mailed copy. If this variable is @code{nil}, no such courtesy
7187 message will be added.
7195 @node Composing Messages
7196 @chapter Composing Messages
7201 @kindex C-c C-c (Post)
7202 All commands for posting and mailing will put you in a message buffer
7203 where you can edit the article all you like, before you send the article
7204 by pressing @kbd{C-c C-c}. If you are in a foreign news group, and you
7205 wish to post the article using the foreign server, you can give a prefix
7206 to @kbd{C-c C-c} to make Gnus try to post using the foreign server.
7209 * Mail:: Mailing and replying.
7210 * Post:: Posting and following up.
7211 * Posting Server:: What server should you post via?
7212 * Mail and Post:: Mailing and posting at the same time.
7213 * Archived Messages:: Where Gnus stores the messages you've sent.
7214 * Posting Styles:: An easier way to configure some key elements.
7215 @c * Drafts:: Postponing messages and rejected messages.
7216 * Rejected Articles:: What happens if the server doesn't like your article?
7219 Also see @pxref{Canceling and Superseding} for information on how to
7220 remove articles you shouldn't have posted.
7226 Variables for customizing outgoing mail:
7229 @item gnus-uu-digest-headers
7230 @vindex gnus-uu-digest-headers
7231 List of regexps to match headers included in digested messages. The
7232 headers will be included in the sequence they are matched.
7240 Variables for composing news articles:
7243 @item gnus-sent-message-ids-file
7244 @vindex gnus-sent-message-ids-file
7245 Gnus will keep a @code{Message-ID} history file of all the mails it has
7246 sent. If it discovers that it has already sent a mail, it will ask the
7247 user whether to re-send the mail. (This is primarily useful when
7248 dealing with @sc{soup} packets and the like where one is apt to sent the
7249 same packet multiple times.) This variable says what the name of this
7250 history file is. It is @file{~/News/Sent-Message-IDs} by default. Set
7251 this variable to @code{nil} if you don't want Gnus to keep a history
7254 @item gnus-sent-message-ids-length
7255 @vindex gnus-sent-message-ids-length
7256 This variable says how many @code{Message-ID}s to keep in the history
7257 file. It is 1000 by default.
7262 @node Posting Server
7263 @section Posting Server
7265 When you press those magical @kbd{C-c C-c} keys to ship off your latest
7266 (extremely intelligent, of course) article, where does it go?
7268 Thank you for asking. I hate you.
7270 @vindex gnus-post-method
7272 It can be quite complicated. Normally, Gnus will use the same native
7273 server. However. If your native server doesn't allow posting, just
7274 reading, you probably want to use some other server to post your
7275 (extremely intelligent and fabulously interesting) articles. You can
7276 then set the @code{gnus-post-method} to some other method:
7279 (setq gnus-post-method '(nnspool ""))
7282 Now, if you've done this, and then this server rejects your article, or
7283 this server is down, what do you do then? To override this variable you
7284 can use a non-zero prefix to the @kbd{C-c C-c} command to force using
7285 the ``current'' server for posting.
7287 If you give a zero prefix (i. e., @kbd{C-u 0 C-c C-c}) to that command,
7288 Gnus will prompt you for what method to use for posting.
7290 You can also set @code{gnus-post-method} to a list of select methods.
7291 If that's the case, Gnus will always prompt you for what method to use
7296 @section Mail and Post
7298 Here's a list of variables that are relevant to both mailing and
7302 @item gnus-mailing-list-groups
7303 @findex gnus-mailing-list-groups
7304 @cindex mailing lists
7306 If your news server offers groups that are really mailing lists that are
7307 gatewayed to the @sc{nntp} server, you can read those groups without
7308 problems, but you can't post/followup to them without some difficulty.
7309 One solution is to add a @code{to-address} to the group parameters
7310 (@pxref{Group Parameters}). An easier thing to do is set the
7311 @code{gnus-mailing-list-groups} to a regexp that match the groups that
7312 really are mailing lists. Then, at least, followups to the mailing
7313 lists will work most of the time. Posting to these groups (@kbd{a}) is
7314 still a pain, though.
7318 You may want to do spell-checking on messages that you send out. Or, if
7319 you don't want to spell-check by hand, you could add automatic
7320 spell-checking via the @code{ispell} package:
7322 @vindex news-inews-hook
7324 @findex ispell-message
7326 (add-hook 'message-send-hook 'ispell-message)
7330 @node Archived Messages
7331 @section Archived Messages
7332 @cindex archived messages
7333 @cindex sent messages
7335 Gnus provides a few different methods for storing the mail you send.
7336 The default method is to use the @dfn{archive virtual server} to store
7337 the mail. If you want to disable this completely, you should set
7338 @code{gnus-message-archive-group} to @code{nil}.
7340 @vindex gnus-message-archive-method
7341 @code{gnus-message-archive-method} says what virtual server Gnus is to
7342 use to store sent messages. It is @code{(nnfolder "archive"
7343 (nnfolder-directory "~/Mail/archive/"))} by default, but you can use any
7344 mail select method (@code{nnml}, @code{nnmbox}, etc.). However,
7345 @code{nnfolder} is a quite likeable select method for doing this sort of
7346 thing. If you don't like the default directory chosen, you could say
7350 (setq gnus-message-archive-method
7351 '(nnfolder "archive"
7352 (nnfolder-inhibit-expiry t)
7353 (nnfolder-active-file "~/News/sent-mail/active")
7354 (nnfolder-directory "~/News/sent-mail/")))
7357 @vindex gnus-message-archive-group
7359 Gnus will insert @code{Gcc} headers in all outgoing messages that point
7360 to one or more group(s) on that server. Which group to use is
7361 determined by the @code{gnus-message-archive-group} variable.
7363 This variable can be:
7367 Messages will be saved in that group.
7368 @item a list of strings
7369 Messages will be saved in all those groups.
7370 @item an alist of regexps, functions and forms
7371 When a key ``matches'', the result is used.
7376 Just saving to a single group called @samp{MisK}:
7378 (setq gnus-message-archive-group "MisK")
7381 Saving to two groups, @samp{MisK} and @samp{safe}:
7383 (setq gnus-message-archive-group '("MisK" "safe"))
7386 Save to different groups based on what group you are in:
7388 (setq gnus-message-archive-group
7389 '(("^alt" "sent-to-alt")
7390 ("mail" "sent-to-mail")
7391 (".*" "sent-to-misc")))
7396 (setq gnus-message-archive-group
7397 '((if (message-news-p)
7402 This is the default.
7404 How about storing all news messages in one file, but storing all mail
7405 messages in one file per month:
7408 (setq gnus-message-archive-group
7409 '((if (message-news-p)
7411 (concat "mail." (format-time-string
7412 "%Y-%m" (current-time))))))
7415 Now, when you send a message off, it will be stored in the appropriate
7416 group. (If you want to disable storing for just one particular message,
7417 you can just remove the @code{Gcc} header that has been inserted.) The
7418 archive group will appear in the group buffer the next time you start
7419 Gnus, or the next time you press @kbd{F} in the group buffer. You can
7420 enter it and read the articles in it just like you'd read any other
7421 group. If the group gets really big and annoying, you can simply rename
7422 if (using @kbd{G r} in the group buffer) to something nice --
7423 @samp{misc-mail-september-1995}, or whatever. New messages will
7424 continue to be stored in the old (now empty) group.
7426 That's the default method of archiving sent mail. Gnus also offers two
7427 other variables for the people who don't like the default method. In
7428 that case you should set @code{gnus-message-archive-group} to
7429 @code{nil}; this will disable archiving.
7432 @item gnus-author-copy
7433 @vindex gnus-author-copy
7435 This is a file name, and all outgoing articles will be saved in that
7436 file. Initialized from the @code{AUTHORCOPY} environment variable.
7438 If this variable begins with the character @samp{|}, outgoing articles
7439 will be piped to the named program. It is possible to save an article in
7440 an MH folder as follows:
7443 (setq gnus-author-copy
7444 "|/usr/local/lib/mh/rcvstore +Article")
7447 If the first character is not a pipe, articles are saved using the
7448 function specified by the @code{gnus-author-copy-saver} variable.
7450 @item gnus-author-copy-saver
7451 @vindex gnus-author-copy-saver
7452 @findex rmail-output
7453 A function called to save outgoing articles. This function will be
7454 called with the same of the file to store the article in. The default
7455 function is @code{rmail-output} which saves in the Unix mailbox format.
7457 @item gnus-outgoing-message-group
7458 @vindex gnus-outgoing-message-group
7459 All outgoing messages will be put in this group. If you want to store
7460 all your outgoing mail and articles in the group @samp{nnml:archive},
7461 you set this variable to that value. This variable can also be a list of
7464 If you want to have greater control over what group to put each
7465 message in, you can set this variable to a function that checks the
7466 current newsgroup name and then returns a suitable group name (or list
7471 @node Posting Styles
7472 @section Posting Styles
7473 @cindex posting styles
7476 All them variables, they make my head swim.
7478 So what if you want a different @code{Organization} and signature based
7479 on what groups you post to? And you post both from your home machine
7480 and your work machine, and you want different @code{From} lines, and so
7483 @vindex gnus-posting-styles
7484 One way to do stuff like that is to write clever hooks that change the
7485 variables you need to have changed. That's a bit boring, so somebody
7486 came up with the bright idea of letting the user specify these things in
7487 a handy alist. Here's an example of a @code{gnus-posting-styles}
7492 (signature . "Peace and happiness")
7493 (organization . "What me?"))
7495 (signature . "Death to everybody"))
7496 ("comp.emacs.i-love-it"
7497 (organization . "Emacs is it")))
7500 As you might surmise from this example, this alist consists of several
7501 @dfn{styles}. Each style will be applicable if the first element
7502 ``matches'', in some form or other. The entire alist will be iterated
7503 over, from the beginning towards the end, and each match will be
7504 applied, which means that attributes in later styles that match override
7505 the same attributes in earlier matching styles. So
7506 @samp{comp.programming.literate} will have the @samp{Death to everybody}
7507 signature and the @samp{What me?} @code{Organization} header.
7509 The first element in each style is called the @code{match}. If it's a
7510 string, then Gnus will try to regexp match it against the group name.
7511 If it's a function symbol, that function will be called with no
7512 arguments. If it's a variable symbol, then the variable will be
7513 referenced. If it's a list, then that list will be @code{eval}ed. In
7514 any case, if this returns a non-@code{nil} value, then the style is said
7517 Each style may contain a arbitrary amount of @dfn{attributes}. Each
7518 attribute consists of a @var{(name . value)} pair. The attribute name
7519 can be one of @code{signature}, @code{organization} or @code{from}. The
7520 attribute name can also be a string. In that case, this will be used as
7521 a header name, and the value will be inserted in the headers of the
7524 The attribute value can be a string (used verbatim), a function (the
7525 return value will be used), a variable (its value will be used) or a
7526 list (it will be @code{eval}ed and the return value will be used).
7528 So here's a new example:
7531 (setq gnus-posting-styles
7533 (signature . "~/.signature")
7534 (from . "user@@foo (user)")
7535 ("X-Home-Page" . (getenv "WWW_HOME"))
7536 (organization . "People's Front Against MWM"))
7538 (signature . my-funny-signature-randomizer))
7539 ((equal (system-name) "gnarly")
7540 (signature . my-quote-randomizer))
7541 (posting-from-work-p
7542 (signature . "~/.work-signature")
7543 (from . "user@@bar.foo (user)")
7544 (organization . "Important Work, Inc"))
7546 (signature . "~/.mail-signature"))))
7554 @c If you are writing a message (mail or news) and suddenly remember that
7555 @c you have a steak in the oven (or some pesto in the food processor, you
7556 @c craazy vegetarians), you'll probably wish there was a method to save the
7557 @c message you are writing so that you can continue editing it some other
7558 @c day, and send it when you feel its finished.
7560 @c Well, don't worry about it. Whenever you start composing a message of
7561 @c some sort using the Gnus mail and post commands, the buffer you get will
7562 @c automatically associate to an article in a special @dfn{draft} group.
7563 @c If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the
7564 @c article will be saved there. (Auto-save files also go to the draft
7568 @c @vindex gnus-draft-group-directory
7569 @c The draft group is a special group (which is implemented as an
7570 @c @code{nndraft} group, if you absolutely have to know) called
7571 @c @samp{nndraft:drafts}. The variable @code{gnus-draft-group-directory}
7572 @c controls both the name of the group and the location---the leaf element
7573 @c in the path will be used as the name of the group. What makes this
7574 @c group special is that you can't tick any articles in it or mark any
7575 @c articles as read---all articles in the group are permanently unread.
7577 @c If the group doesn't exist, it will be created and you'll be subscribed
7580 @c @findex gnus-dissociate-buffer-from-draft
7581 @c @kindex C-c M-d (Mail)
7582 @c @kindex C-c M-d (Post)
7583 @c @findex gnus-associate-buffer-with-draft
7584 @c @kindex C-c C-d (Mail)
7585 @c @kindex C-c C-d (Post)
7586 @c If you're writing some super-secret message that you later want to
7587 @c encode with PGP before sending, you may wish to turn the auto-saving
7588 @c (and association with the draft group) off. You never know who might be
7589 @c interested in reading all your extremely valuable and terribly horrible
7590 @c and interesting secrets. The @kbd{C-c M-d}
7591 @c (@code{gnus-dissociate-buffer-from-draft}) command does that for you.
7592 @c If you change your mind and want to turn the auto-saving back on again,
7593 @c @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that.
7595 @c @vindex gnus-use-draft
7596 @c To leave association with the draft group off by default, set
7597 @c @code{gnus-use-draft} to @code{nil}. It is @code{t} by default.
7599 @c @findex gnus-summary-send-draft
7600 @c @kindex S D c (Summary)
7601 @c When you want to continue editing the article, you simply enter the
7602 @c draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
7603 @c that. You will be placed in a buffer where you left off.
7605 @c Rejected articles will also be put in this draft group (@pxref{Rejected
7608 @c @findex gnus-summary-send-all-drafts
7609 @c If you have lots of rejected messages you want to post (or mail) without
7610 @c doing further editing, you can use the @kbd{S D a} command
7611 @c (@code{gnus-summary-send-all-drafts}). This command understands the
7612 @c process/prefix convention (@pxref{Process/Prefix}).
7615 @c @node Rejected Articles
7616 @c @section Rejected Articles
7617 @c @cindex rejected articles
7619 @c Sometimes a news server will reject an article. Perhaps the server
7620 @c doesn't like your face. Perhaps it just feels miserable. Perhaps
7621 @c @emph{there be demons}. Perhaps you have included too much cited text.
7622 @c Perhaps the disk is full. Perhaps the server is down.
7624 @c These situations are, of course, totally beyond the control of Gnus.
7625 @c (Gnus, of course, loves the way you look, always feels great, has angels
7626 @c fluttering around inside of it, doesn't care about how much cited text
7627 @c you include, never runs full and never goes down.) So Gnus saves these
7628 @c articles until some later time when the server feels better.
7630 @c The rejected articles will automatically be put in a special draft group
7631 @c (@pxref{Drafts}). When the server comes back up again, you'd then
7632 @c typically enter that group and send all the articles off.
7635 @node Select Methods
7636 @chapter Select Methods
7637 @cindex foreign groups
7638 @cindex select methods
7640 A @dfn{foreign group} is a group that is not read by the usual (or
7641 default) means. It could be, for instance, a group from a different
7642 @sc{nntp} server, it could be a virtual group, or it could be your own
7643 personal mail group.
7645 A foreign group (or any group, really) is specified by a @dfn{name} and
7646 a @dfn{select method}. To take the latter first, a select method is a
7647 list where the first element says what backend to use (eg. @code{nntp},
7648 @code{nnspool}, @code{nnml}) and the second element is the @dfn{server
7649 name}. There may be additional elements in the select method, where the
7650 value may have special meaning for the backend in question.
7652 One could say that a select method defines a @dfn{virtual server}---so
7653 we do just that (@pxref{The Server Buffer}).
7655 The @dfn{name} of the group is the name the backend will recognize the
7658 For instance, the group @samp{soc.motss} on the @sc{nntp} server
7659 @samp{some.where.edu} will have the name @samp{soc.motss} and select
7660 method @code{(nntp "some.where.edu")}. Gnus will call this group, in
7661 all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
7662 @code{nntp} backend just knows this group as @samp{soc.motss}.
7664 The different methods all have their peculiarities, of course.
7667 * The Server Buffer:: Making and editing virtual servers.
7668 * Getting News:: Reading USENET news with Gnus.
7669 * Getting Mail:: Reading your personal mail with Gnus.
7670 * Other Sources:: Reading directories, files, SOUP packets.
7671 * Combined Groups:: Combining groups into one group.
7675 @node The Server Buffer
7676 @section The Server Buffer
7678 Traditionally, a @dfn{server} is a machine or a piece of software that
7679 one connects to, and then requests information from. Gnus does not
7680 connect directly to any real servers, but does all transactions through
7681 one backend or other. But that's just putting one layer more between
7682 the actual media and Gnus, so we might just as well say that each
7683 backend represents a virtual server.
7685 For instance, the @code{nntp} backend may be used to connect to several
7686 different actual @sc{nntp} servers, or, perhaps, to many different ports
7687 on the same actual @sc{nntp} server. You tell Gnus which backend to
7688 use, and what parameters to set by specifying a @dfn{select method}.
7690 These select methods specifications can sometimes become quite
7691 complicated---say, for instance, that you want to read from the
7692 @sc{nntp} server @samp{news.funet.fi} on port number @code{13}, which
7693 hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
7694 Anyways, if you had to specify that for each group that used this
7695 server, that would be too much work, so Gnus offers a way of naming
7696 select methods, which is what you do in the server buffer.
7698 To enter the server buffer, user the @kbd{^}
7699 (@code{gnus-group-enter-server-mode}) command in the group buffer.
7702 * Server Buffer Format:: You can customize the look of this buffer.
7703 * Server Commands:: Commands to manipulate servers.
7704 * Example Methods:: Examples server specifications.
7705 * Creating a Virtual Server:: An example session.
7706 * Servers and Methods:: You can use server names as select methods.
7707 * Unavailable Servers:: Some servers you try to contact may be down.
7710 @vindex gnus-server-mode-hook
7711 @code{gnus-server-mode-hook} is run when creating the server buffer.
7714 @node Server Buffer Format
7715 @subsection Server Buffer Format
7716 @cindex server buffer format
7718 @vindex gnus-server-line-format
7719 You can change the look of the server buffer lines by changing the
7720 @code{gnus-server-line-format} variable. This is a @code{format}-like
7721 variable, with some simple extensions:
7726 How the news is fetched---the backend name.
7729 The name of this server.
7732 Where the news is to be fetched from---the address.
7735 The opened/closed/denied status of the server.
7738 @vindex gnus-server-mode-line-format
7739 The mode line can also be customized by using the
7740 @code{gnus-server-mode-line-format} variable. The following specs are
7751 Also @pxref{Formatting Variables}.
7754 @node Server Commands
7755 @subsection Server Commands
7756 @cindex server commands
7762 @findex gnus-server-add-server
7763 Add a new server (@code{gnus-server-add-server}).
7767 @findex gnus-server-edit-server
7768 Edit a server (@code{gnus-server-edit-server}).
7771 @kindex SPACE (Server)
7772 @findex gnus-server-read-server
7773 Browse the current server (@code{gnus-server-read-server}).
7777 @findex gnus-server-exit
7778 Return to the group buffer (@code{gnus-server-exit}).
7782 @findex gnus-server-kill-server
7783 Kill the current server (@code{gnus-server-kill-server}).
7787 @findex gnus-server-yank-server
7788 Yank the previously killed server (@code{gnus-server-yank-server}).
7792 @findex gnus-server-copy-server
7793 Copy the current server (@code{gnus-server-copy-server}).
7797 @findex gnus-server-list-servers
7798 List all servers (@code{gnus-server-list-servers}).
7803 @node Example Methods
7804 @subsection Example Methods
7806 Most select methods are pretty simple and self-explanatory:
7809 (nntp "news.funet.fi")
7812 Reading directly from the spool is even simpler:
7818 As you can see, the first element in a select method is the name of the
7819 backend, and the second is the @dfn{address}, or @dfn{name}, if you
7822 After these two elements, there may be a arbitrary number of
7823 @var{(variable form)} pairs.
7825 To go back to the first example---imagine that you want to read from
7826 port @code{15} from that machine. This is what the select method should
7830 (nntp "news.funet.fi" (nntp-port-number 15))
7833 You should read the documentation to each backend to find out what
7834 variables are relevant, but here's an @code{nnmh} example.
7836 @code{nnmh} is a mail backend that reads a spool-like structure. Say
7837 you have two structures that you wish to access: One is your private
7838 mail spool, and the other is a public one. Here's the possible spec for
7842 (nnmh "private" (nnmh-directory "~/private/mail/"))
7845 (This server is then called @samp{private}, but you may have guessed
7848 Here's the method for a public spool:
7852 (nnmh-directory "/usr/information/spool/")
7853 (nnmh-get-new-mail nil))
7857 @node Creating a Virtual Server
7858 @subsection Creating a Virtual Server
7860 If you're saving lots of articles in the cache by using persistent
7861 articles, you may want to create a virtual server to read the cache.
7863 First you need to add a new server. The @kbd{a} command does that. It
7864 would probably be best to use @code{nnspool} to read the cache. You
7865 could also use @code{nnml} or @code{nnmh}, though.
7867 Type @kbd{a nnspool RET cache RET}.
7869 You should now have a brand new @code{nnspool} virtual server called
7870 @samp{cache}. You now need to edit it to have the right definitions.
7871 Type @kbd{e} to edit the server. You'll be entered into a buffer that
7872 will contain the following:
7882 (nnspool-spool-directory "~/News/cache/")
7883 (nnspool-nov-directory "~/News/cache/")
7884 (nnspool-active-file "~/News/cache/active"))
7887 Type @kbd{C-c C-c} to return to the server buffer. If you now press
7888 @kbd{RET} over this virtual server, you should be entered into a browse
7889 buffer, and you should be able to enter any of the groups displayed.
7892 @node Servers and Methods
7893 @subsection Servers and Methods
7895 Wherever you would normally use a select method
7896 (eg. @code{gnus-secondary-select-method}, in the group select method,
7897 when browsing a foreign server) you can use a virtual server name
7898 instead. This could potentially save lots of typing. And it's nice all
7902 @node Unavailable Servers
7903 @subsection Unavailable Servers
7905 If a server seems to be unreachable, Gnus will mark that server as
7906 @code{denied}. That means that any subsequent attempt to make contact
7907 with that server will just be ignored. ``It can't be opened,'' Gnus
7908 will tell you, without making the least effort to see whether that is
7909 actually the case or not.
7911 That might seem quite naughty, but it does make sense most of the time.
7912 Let's say you have 10 groups subscribed to the server
7913 @samp{nepholococcygia.com}. This server is located somewhere quite far
7914 away from you, the machine is quite, so it takes 1 minute just to find
7915 out that it refuses connection from you today. If Gnus were to attempt
7916 to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
7917 that. Once it has gotten a single ``connection refused'', it will
7918 regard that server as ``down''.
7920 So, what happens if the machine was only feeling unwell temporarily?
7921 How do you test to see whether the machine has come up again?
7923 You jump to the server buffer (@pxref{The Server Buffer}) and poke it
7924 with the following commands:
7930 @findex gnus-server-open-server
7931 Try to establish connection to the server on the current line
7932 (@code{gnus-server-open-server}).
7936 @findex gnus-server-close-server
7937 Close the connection (if any) to the server
7938 (@code{gnus-server-close-server}).
7942 @findex gnus-server-deny-server
7943 Mark the current server as unreachable
7944 (@code{gnus-server-deny-server}).
7948 @findex gnus-server-remove-denials
7949 Remove all marks to whether Gnus was denied connection from all servers
7950 (@code{gnus-server-remove-denials}).
7956 @section Getting News
7957 @cindex reading news
7958 @cindex news backends
7960 A newsreader is normally used for reading news. Gnus currently provides
7961 only two methods of getting news -- it can read from an @sc{nntp}
7962 server, or it can read from a local spool.
7965 * NNTP:: Reading news from an @sc{nntp} server.
7966 * News Spool:: Reading news from the local spool.
7971 @subsection @sc{nntp}
7974 Subscribing to a foreign group from an @sc{nntp} server is rather easy.
7975 You just specify @code{nntp} as method and the address of the @sc{nntp}
7976 server as the, uhm, address.
7978 If the @sc{nntp} server is located at a non-standard port, setting the
7979 third element of the select method to this port number should allow you
7980 to connect to the right port. You'll have to edit the group info for
7981 that (@pxref{Foreign Groups}).
7983 The name of the foreign group can be the same as a native group. In
7984 fact, you can subscribe to the same group from as many different servers
7985 you feel like. There will be no name collisions.
7987 The following variables can be used to create a virtual @code{nntp}
7992 @item nntp-server-opened-hook
7993 @vindex nntp-server-opened-hook
7994 @cindex @sc{mode reader}
7996 @cindex authentification
7997 @cindex nntp authentification
7998 @findex nntp-send-authinfo
7999 @findex nntp-send-mode-reader
8000 @code{nntp-server-opened-hook} is run after a connection has been made.
8001 It can be used to send commands to the @sc{nntp} server after it has
8002 been contacted. By default is sends the command @code{MODE READER} to
8003 the server with the @code{nntp-send-mode-reader} function. Another
8004 popular function is @code{nntp-send-authinfo}, which will prompt you for
8005 an @sc{nntp} password and stuff.
8007 @item nntp-server-action-alist
8008 @vindex nntp-server-action-alist
8009 This is an list of regexps to match on server types and actions to be
8010 taken when matches are made. For instance, if you want Gnus to beep
8011 every time you connect to innd, you could say something like:
8014 (setq nntp-server-action-alist
8018 You probably don't want to do that, though.
8020 The default value is
8023 '(("nntpd 1\\.5\\.11t"
8024 (remove-hook 'nntp-server-opened-hook nntp-send-mode-reader)))
8027 This ensures that Gnus doesn't send the @code{MODE READER} command to
8028 nntpd 1.5.11t, since that command chokes that server, I've been told.
8030 @item nntp-maximum-request
8031 @vindex nntp-maximum-request
8032 If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
8033 will collect headers by sending a series of @code{head} commands. To
8034 speed things up, the backend sends lots of these commands without
8035 waiting for reply, and then reads all the replies. This is controlled
8036 by the @code{nntp-maximum-request} variable, and is 400 by default. If
8037 your network is buggy, you should set this to 1.
8039 @item nntp-connection-timeout
8040 @vindex nntp-connection-timeout
8041 If you have lots of foreign @code{nntp} groups that you connect to
8042 regularly, you're sure to have problems with @sc{nntp} servers not
8043 responding properly, or being too loaded to reply within reasonable
8044 time. This is can lead to awkward problems, which can be helped
8045 somewhat by setting @code{nntp-connection-timeout}. This is an integer
8046 that says how many seconds the @code{nntp} backend should wait for a
8047 connection before giving up. If it is @code{nil}, which is the default,
8048 no timeouts are done.
8050 @item nntp-command-timeout
8051 @vindex nntp-command-timeout
8052 @cindex PPP connections
8053 @cindex dynamic IP addresses
8054 If you're running Gnus on a machine that has a dynamically assigned
8055 address, Gnus may become confused. If the address of your machine
8056 changes after connecting to the @sc{nntp} server, Gnus will simply sit
8057 waiting forever for replies from the server. To help with this
8058 unfortunate problem, you can set this command to a number. Gnus will
8059 then, if it sits waiting longer than that number of seconds for a reply
8060 from the server, shut down the connection, start a new one, and resend
8061 the command. This should hopefully be transparent to the user. A
8062 likely number is 30 seconds.
8064 @item nntp-retry-on-break
8065 @vindex nntp-retry-on-break
8066 If this variable is non-@code{nil}, you can also @kbd{C-g} if Gnus
8067 hangs. This will have much the same effect as the command timeout
8070 @item nntp-server-hook
8071 @vindex nntp-server-hook
8072 This hook is run as the last step when connecting to an @sc{nntp}
8075 @findex nntp-open-rlogin
8076 @findex nntp-open-network-stream
8077 @item nntp-open-server-function
8078 @vindex nntp-open-server-function
8079 This function is used to connect to the remote system. Two pre-made
8080 functions are @code{nntp-open-network-stream}, which is the default, and
8081 simply connects to some port or other on the remote system. The other
8082 is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
8083 and then does a telnet to the @sc{nntp} server available there.
8085 @item nntp-rlogin-parameters
8086 @vindex nntp-rlogin-parameters
8087 If you use @code{nntp-open-rlogin} as the
8088 @code{nntp-open-server-function}, this list will be used as the
8089 parameter list given to @code{rsh}.
8091 @item nntp-end-of-line
8092 @vindex nntp-end-of-line
8093 String to use as end-of-line markers when talking to the @sc{nntp}
8094 server. This is @samp{\r\n} by default, but should be @samp{\n} when
8095 using @code{rlogin} to talk to the server.
8097 @item nntp-rlogin-user-name
8098 @vindex nntp-rlogin-user-name
8099 User name on the remote system when using the @code{rlogin} connect
8103 @vindex nntp-address
8104 The address of the remote system running the @sc{nntp} server.
8106 @item nntp-port-number
8107 @vindex nntp-port-number
8108 Port number to connect to when using the @code{nntp-open-network-stream}
8111 @item nntp-buggy-select
8112 @vindex nntp-buggy-select
8113 Set this to non-@code{nil} if your select routine is buggy.
8115 @item nntp-nov-is-evil
8116 @vindex nntp-nov-is-evil
8117 If the @sc{nntp} server does not support @sc{nov}, you could set this
8118 variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
8119 can be used automatically.
8121 @item nntp-xover-commands
8122 @vindex nntp-xover-commands
8125 List of strings that are used as commands to fetch @sc{nov} lines from a
8126 server. The default value of this variable is @code{("XOVER"
8130 @vindex nntp-nov-gap
8131 @code{nntp} normally sends just one big request for @sc{nov} lines to
8132 the server. The server responds with one huge list of lines. However,
8133 if you have read articles 2-5000 in the group, and only want to read
8134 article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
8135 lines that you do not want, and will not use. This variable says how
8136 big a gap between two consecutive articles is allowed to be before the
8137 @code{XOVER} request is split into several request. Note that if your
8138 network is fast, setting this variable to a really small number means
8139 that fetching will probably be slower. If this variable is @code{nil},
8140 @code{nntp} will never split requests.
8142 @item nntp-prepare-server-hook
8143 @vindex nntp-prepare-server-hook
8144 A hook run before attempting to connect to an @sc{nntp} server.
8146 @item nntp-async-number
8147 @vindex nntp-async-number
8148 How many articles should be pre-fetched when in asynchronous mode. If
8149 this variable is @code{t}, @code{nntp} will pre-fetch all the articles
8150 that it can without bound. If it is @code{nil}, no pre-fetching will be
8153 @item nntp-warn-about-losing-connection
8154 @vindex nntp-warn-about-losing-connection
8155 If this variable is non-@code{nil}, some noise will be made when a
8156 server closes connection.
8162 @subsection News Spool
8166 Subscribing to a foreign group from the local spool is extremely easy,
8167 and might be useful, for instance, to speed up reading groups like
8168 @samp{alt.binaries.pictures.furniture}.
8170 Anyways, you just specify @code{nnspool} as the method and @samp{} (or
8171 anything else) as the address.
8173 If you have access to a local spool, you should probably use that as the
8174 native select method (@pxref{Finding the News}). It is normally faster
8175 than using an @code{nntp} select method, but might not be. It depends.
8176 You just have to try to find out what's best at your site.
8180 @item nnspool-inews-program
8181 @vindex nnspool-inews-program
8182 Program used to post an article.
8184 @item nnspool-inews-switches
8185 @vindex nnspool-inews-switches
8186 Parameters given to the inews program when posting an article.
8188 @item nnspool-spool-directory
8189 @vindex nnspool-spool-directory
8190 Where @code{nnspool} looks for the articles. This is normally
8191 @file{/usr/spool/news/}.
8193 @item nnspool-nov-directory
8194 @vindex nnspool-nov-directory
8195 Where @code{nnspool} will look for @sc{nov} files. This is normally
8196 @file{/usr/spool/news/over.view/}.
8198 @item nnspool-lib-dir
8199 @vindex nnspool-lib-dir
8200 Where the news lib dir is (@file{/usr/lib/news/} by default).
8202 @item nnspool-active-file
8203 @vindex nnspool-active-file
8204 The path of the active file.
8206 @item nnspool-newsgroups-file
8207 @vindex nnspool-newsgroups-file
8208 The path of the group descriptions file.
8210 @item nnspool-history-file
8211 @vindex nnspool-history-file
8212 The path of the news history file.
8214 @item nnspool-active-times-file
8215 @vindex nnspool-active-times-file
8216 The path of the active date file.
8218 @item nnspool-nov-is-evil
8219 @vindex nnspool-nov-is-evil
8220 If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
8223 @item nnspool-sift-nov-with-sed
8224 @vindex nnspool-sift-nov-with-sed
8226 If non-@code{nil}, which is the default, use @code{sed} to get the
8227 relevant portion from the overview file. If nil, @code{nnspool} will
8228 load the entire file into a buffer and process it there.
8234 @section Getting Mail
8235 @cindex reading mail
8238 Reading mail with a newsreader---isn't that just plain WeIrD? But of
8242 * Getting Started Reading Mail:: A simple cookbook example.
8243 * Splitting Mail:: How to create mail groups.
8244 * Mail Backend Variables:: Variables for customizing mail handling.
8245 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
8246 * Mail and Procmail:: Reading mail groups that procmail create.
8247 * Incorporating Old Mail:: What about the old mail you have?
8248 * Expiring Mail:: Getting rid of unwanted mail.
8249 * Duplicates:: Dealing with duplicated mail.
8250 * Not Reading Mail:: Using mail backends for reading other files.
8251 * Choosing a Mail Backend:: Gnus can read a variety of mail formats.
8255 @node Getting Started Reading Mail
8256 @subsection Getting Started Reading Mail
8258 It's quite easy to use Gnus to read your new mail. You just plonk the
8259 mail backend of your choice into @code{gnus-secondary-select-methods},
8260 and things will happen automatically.
8262 For instance, if you want to use @code{nnml} (which is a one file per
8263 mail backend), you could put the following in your @file{.gnus} file:
8266 (setq gnus-secondary-select-methods
8267 '((nnml "private")))
8270 Now, the next time you start Gnus, this backend will be queried for new
8271 articles, and it will move all the messages in your spool file to its
8272 directory, which is @code{~/Mail/} by default. The new group that will
8273 be created (@samp{mail.misc}) will be subscribed, and you can read it
8274 like any other group.
8276 You will probably want to split the mail into several groups, though:
8279 (setq nnmail-split-methods
8280 '(("junk" "^From:.*Lars Ingebrigtsen")
8281 ("crazy" "^Subject:.*die\\|^Organization:.*flabby")
8285 This will result in three new mail groups being created:
8286 @samp{nnml:junk}, @samp{nnml:crazy}, and @samp{nnml:other}. All the
8287 mail that doesn't fit into the first two groups will be placed in the
8290 This should be sufficient for reading mail with Gnus. You might want to
8291 give the other sections in this part of the manual a perusal, though,
8292 especially @pxref{Choosing a Mail Backend} and @pxref{Expiring Mail}.
8295 @node Splitting Mail
8296 @subsection Splitting Mail
8297 @cindex splitting mail
8298 @cindex mail splitting
8300 @vindex nnmail-split-methods
8301 The @code{nnmail-split-methods} variable says how the incoming mail is
8302 to be split into groups.
8305 (setq nnmail-split-methods
8306 '(("mail.junk" "^From:.*Lars Ingebrigtsen")
8307 ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
8311 This variable is a list of lists, where the first element of each of
8312 these lists is the name of the mail group (they do not have to be called
8313 something beginning with @samp{mail}, by the way), and the second
8314 element is a regular expression used on the header of each mail to
8315 determine if it belongs in this mail group.
8317 The second element can also be a function. In that case, it will be
8318 called narrowed to the headers with the first element of the rule as the
8319 argument. It should return a non-@code{nil} value if it thinks that the
8320 mail belongs in that group.
8322 The last of these groups should always be a general one, and the regular
8323 expression should @emph{always} be @samp{} so that it matches any
8324 mails that haven't been matched by any of the other regexps.
8326 If you like to tinker with this yourself, you can set this variable to a
8327 function of your choice. This function will be called without any
8328 arguments in a buffer narrowed to the headers of an incoming mail
8329 message. The function should return a list of groups names that it
8330 thinks should carry this mail message.
8332 Note that the mail backends are free to maul the poor, innocent
8333 incoming headers all they want to. They all add @code{Lines} headers;
8334 some add @code{X-Gnus-Group} headers; most rename the Unix mbox
8335 @code{From<SPACE>} line to something else.
8337 @vindex nnmail-crosspost
8338 The mail backends all support cross-posting. If several regexps match,
8339 the mail will be ``cross-posted'' to all those groups.
8340 @code{nnmail-crosspost} says whether to use this mechanism or not. Note
8341 that no articles are crossposted to the general (@samp{}) group.
8343 @vindex nnmail-crosspost-link-function
8346 @code{nnmh} and @code{nnml} makes crossposts by creating hard links to
8347 the crossposted articles. However, not all files systems support hard
8348 links. If that's the case for you, set
8349 @code{nnmail-crosspost-link-function} to @code{copy-file}. (This
8350 variable is @code{add-name-to-file} by default.)
8352 Gnus gives you all the opportunity you could possibly want for shooting
8353 yourself in the foot. Let's say you create a group that will contain
8354 all the mail you get from your boss. And then you accidentally
8355 unsubscribe from the group. Gnus will still put all the mail from your
8356 boss in the unsubscribed group, and so, when your boss mails you ``Have
8357 that report ready by Monday or you're fired!'', you'll never see it and,
8358 come Tuesday, you'll still believe that you're gainfully employed while
8359 you really should be out collecting empty bottles to save up for next
8363 @node Mail Backend Variables
8364 @subsection Mail Backend Variables
8366 These variables are (for the most part) pertinent to all the various
8370 @vindex nnmail-read-incoming-hook
8371 @item nnmail-read-incoming-hook
8372 The mail backends all call this hook after reading new mail. You can
8373 use this hook to notify any mail watch programs, if you want to.
8375 @vindex nnmail-spool-file
8376 @item nnmail-spool-file
8380 The backends will look for new mail in this file. If this variable is
8381 @code{nil}, the mail backends will never attempt to fetch mail by
8382 themselves. If you are using a POP mail server and your name is
8383 @samp{larsi}, you should set this variable to @samp{po:larsi}. If
8384 your name is not @samp{larsi}, you should probably modify that
8385 slightly, but you may have guessed that already, you smart & handsome
8386 devil! You can also set this variable to @code{pop}, and Gnus will try
8387 to figure out the POP mail string by itself. In any case, Gnus will
8388 call @code{movemail} which will contact the POP server named in the
8389 @code{MAILHOST} environment variable.
8391 When you use a mail backend, Gnus will slurp all your mail from your
8392 inbox and plonk it down in your home directory. Gnus doesn't move any
8393 mail if you're not using a mail backend---you have to do a lot of magic
8394 invocations first. At the time when you have finished drawing the
8395 pentagram, lightened the candles, and sacrificed the goat, you really
8396 shouldn't be too surprised when Gnus moves your mail.
8398 @vindex nnmail-use-procmail
8399 @vindex nnmail-procmail-suffix
8400 @item nnmail-use-procmail
8401 If non-@code{nil}, the mail backends will look in
8402 @code{nnmail-procmail-directory} for incoming mail. All the files in
8403 that directory that have names ending in @code{nnmail-procmail-suffix}
8404 will be considered incoming mailboxes, and will be searched for new
8407 @vindex nnmail-crash-box
8408 @item nnmail-crash-box
8409 When the mail backends read a spool file, it is first moved to this
8410 file, which is @file{~/.gnus-crash-box} by default. If this file
8411 already exists, it will always be read (and incorporated) before any
8414 @vindex nnmail-prepare-incoming-hook
8415 @item nnmail-prepare-incoming-hook
8416 This is run in a buffer that holds all the new incoming mail, and can be
8417 used for, well, anything, really.
8419 @vindex nnmail-pre-get-new-mail-hook
8420 @vindex nnmail-post-get-new-mail-hook
8421 @item nnmail-pre-get-new-mail-hook
8422 @itemx nnmail-post-get-new-mail-hook
8423 These are two useful hooks executed when treating new incoming
8424 mail---@code{nnmail-pre-get-new-mail-hook} (is called just before
8425 starting to handle the new mail) and
8426 @code{nnmail-post-get-new-mail-hook} (is called when the mail handling
8427 is done). Here's and example of using these two hooks to change the
8428 default file modes the new mail files get:
8431 (add-hook 'gnus-pre-get-new-mail-hook
8432 (lambda () (set-default-file-modes 511)))
8434 (add-hook 'gnus-post-get-new-mail-hook
8435 (lambda () (set-default-file-modes 551)))
8438 @item nnmail-tmp-directory
8439 @vindex nnmail-tmp-directory
8440 This variable says where to move the incoming mail to while processing
8441 it. This is usually done in the same directory that the mail backend
8442 inhabits (i.e., @file{~/Mail/}), but if this variable is non-@code{nil},
8443 it will be used instead.
8445 @item nnmail-movemail-program
8446 @vindex nnmail-movemail-program
8447 This program is executed to move mail from the user's inbox to her home
8448 directory. The default is @samp{movemail}.
8450 @item nnmail-delete-incoming
8451 @vindex nnmail-delete-incoming
8452 @cindex incoming mail files
8453 @cindex deleting incoming files
8454 If non-@code{nil}, the mail backends will delete the temporary incoming
8455 file after splitting mail into the proper groups. This is @code{nil} by
8456 default for reasons of security.
8458 @item nnmail-use-long-file-names
8459 @vindex nnmail-use-long-file-names
8460 If non-@code{nil}, the mail backends will use long file and directory
8461 names. Groups like @samp{mail.misc} will end up in directories like
8462 @file{mail.misc/}. If it is @code{nil}, the same group will end up in
8465 @item nnmail-delete-file-function
8466 @vindex nnmail-delete-file-function
8468 Function called to delete files. It is @code{delete-file} by default.
8473 @node Fancy Mail Splitting
8474 @subsection Fancy Mail Splitting
8475 @cindex mail splitting
8476 @cindex fancy mail splitting
8478 @vindex nnmail-split-fancy
8479 @findex nnmail-split-fancy
8480 If the rather simple, standard method for specifying how to split mail
8481 doesn't allow you to do what you want, you can set
8482 @code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
8483 play with the @code{nnmail-split-fancy} variable.
8485 Let's look at an example value of this variable first:
8488 ;; Messages from the mailer daemon are not crossposted to any of
8489 ;; the ordinary groups. Warnings are put in a separate group
8490 ;; from real errors.
8491 (| ("from" mail (| ("subject" "warn.*" "mail.warning")
8493 ;; Non-error messages are crossposted to all relevant
8494 ;; groups, but we don't crosspost between the group for the
8495 ;; (ding) list and the group for other (ding) related mail.
8496 (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
8497 ("subject" "ding" "ding.misc"))
8498 ;; Other mailing lists...
8499 (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
8500 (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
8502 (any "larsi@@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
8503 ;; Unmatched mail goes to the catch all group.
8507 This variable has the format of a @dfn{split}. A split is a (possibly)
8508 recursive structure where each split may contain other splits. Here are
8509 the four possible split syntaxes:
8514 If the split is a string, that will be taken as a group name.
8516 @item (FIELD VALUE SPLIT)
8517 If the split is a list, and the first element is a string, then that
8518 means that if header FIELD (a regexp) contains VALUE (also a regexp),
8519 then store the message as specified by SPLIT.
8522 If the split is a list, and the first element is @code{|} (vertical
8523 bar), then process each SPLIT until one of them matches. A SPLIT is
8524 said to match if it will cause the mail message to be stored in one or
8528 If the split is a list, and the first element is @code{&}, then process
8529 all SPLITs in the list.
8532 In these splits, FIELD must match a complete field name. VALUE must
8533 match a complete word according to the fundamental mode syntax table.
8534 You can use @code{.*} in the regexps to match partial field names or
8537 @vindex nnmail-split-abbrev-alist
8538 FIELD and VALUE can also be lisp symbols, in that case they are expanded
8539 as specified by the variable @code{nnmail-split-abbrev-alist}. This is
8540 an alist of cons cells, where the car of the cells contains the key, and
8541 the cdr contains a string.
8543 @vindex nnmail-split-fancy-syntax-table
8544 @code{nnmail-split-fancy-syntax-table} is the syntax table in effect
8545 when all this splitting is performed.
8548 @node Mail and Procmail
8549 @subsection Mail and Procmail
8554 Many people use @code{procmail} (or some other mail filter program or
8555 external delivery agent---@code{slocal}, @code{elm}, etc) to split
8556 incoming mail into groups. If you do that, you should set
8557 @code{nnmail-spool-file} to @code{procmail} to ensure that the mail
8558 backends never ever try to fetch mail by themselves.
8560 This also means that you probably don't want to set
8561 @code{nnmail-split-methods} either, which has some, perhaps, unexpected
8564 When a mail backend is queried for what groups it carries, it replies
8565 with the contents of that variable, along with any groups it has figured
8566 out that it carries by other means. None of the backends (except
8567 @code{nnmh}) actually go out to the disk and check what groups actually
8568 exist. (It's not trivial to distinguish between what the user thinks is
8569 a basis for a newsgroup and what is just a plain old file or directory.)
8571 This means that you have to tell Gnus (and the backends) what groups
8574 Let's take the @code{nnmh} backend as an example.
8576 The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
8577 There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
8579 Go to the group buffer and type @kbd{G m}. When prompted, answer
8580 @samp{foo} for the name and @samp{nnmh} for the method. Repeat
8581 twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
8582 to include all your mail groups.
8584 That's it. You are now set to read your mail. An active file for this
8585 method will be created automatically.
8587 @vindex nnmail-procmail-suffix
8588 @vindex nnmail-procmail-directory
8589 If you use @code{nnfolder} or any other backend that store more than a
8590 single article in each file, you should never have procmail add mails to
8591 the file that Gnus sees. Instead, procmail should put all incoming mail
8592 in @code{nnmail-procmail-directory}. To arrive at the file name to put
8593 the incoming mail in, append @code{nnmail-procmail-suffix} to the group
8594 name. The mail backends will read the mail from these files.
8596 @vindex nnmail-resplit-incoming
8597 When Gnus reads a file called @file{mail.misc.spool}, this mail will be
8598 put in the @code{mail.misc}, as one would expect. However, if you want
8599 Gnus to split the mail the normal way, you could set
8600 @code{nnmail-resplit-incoming} to @code{t}.
8602 @vindex nnmail-keep-last-article
8603 If you use @code{procmail} to split things directory into an @code{nnmh}
8604 directory (which you shouldn't do), you should set
8605 @code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
8606 ever expiring the final article in a mail newsgroup. This is quite,
8610 @node Incorporating Old Mail
8611 @subsection Incorporating Old Mail
8613 Most people have lots of old mail stored in various file formats. If
8614 you have set up Gnus to read mail using one of the spiffy Gnus mail
8615 backends, you'll probably wish to have that old mail incorporated into
8618 Doing so can be quite easy.
8620 To take an example: You're reading mail using @code{nnml}
8621 (@pxref{Mail Spool}), and have set @code{nnmail-split-methods} to a
8622 satisfactory value (@pxref{Splitting Mail}). You have an old Unix mbox
8623 file filled with important, but old, mail. You want to move it into
8624 your @code{nnml} groups.
8630 Go to the group buffer.
8633 Type `G f' and give the path of the mbox file when prompted to create an
8634 @code{nndoc} group from the mbox file (@pxref{Foreign Groups}).
8637 Type `SPACE' to enter the newly created group.
8640 Type `M P b' to process-mark all articles in this group (@pxref{Setting
8644 Type `B r' to respool all the process-marked articles, and answer
8645 @samp{nnml} when prompted (@pxref{Mail Group Commands}).
8648 All the mail messages in the mbox file will now also be spread out over
8649 all your @code{nnml} groups. Try entering them and check whether things
8650 have gone without a glitch. If things look ok, you may consider
8651 deleting the mbox file, but I wouldn't do that unless I was absolutely
8652 sure that all the mail has ended up where it should be.
8654 Respooling is also a handy thing to do if you're switching from one mail
8655 backend to another. Just respool all the mail in the old mail groups
8656 using the new mail backend.
8660 @subsection Expiring Mail
8661 @cindex article expiry
8663 Traditional mail readers have a tendency to remove mail articles when
8664 you mark them as read, in some way. Gnus takes a fundamentally
8665 different approach to mail reading.
8667 Gnus basically considers mail just to be news that has been received in
8668 a rather peculiar manner. It does not think that it has the power to
8669 actually change the mail, or delete any mail messages. If you enter a
8670 mail group, and mark articles as ``read'', or kill them in some other
8671 fashion, the mail articles will still exist on the system. I repeat:
8672 Gnus will not delete your old, read mail. Unless you ask it to, of
8675 To make Gnus get rid of your unwanted mail, you have to mark the
8676 articles as @dfn{expirable}. This does not mean that the articles will
8677 disappear right away, however. In general, a mail article will be
8678 deleted from your system if, 1) it is marked as expirable, AND 2) it is
8679 more than one week old. If you do not mark an article as expirable, it
8680 will remain on your system until hell freezes over. This bears
8681 repeating one more time, with some spurious capitalizations: IF you do
8682 NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
8684 @vindex gnus-auto-expirable-newsgroups
8685 You do not have to mark articles as expirable by hand. Groups that
8686 match the regular expression @code{gnus-auto-expirable-newsgroups} will
8687 have all articles that you read marked as expirable automatically. All
8688 articles that are marked as expirable have an @samp{E} in the first
8689 column in the summary buffer.
8691 Let's say you subscribe to a couple of mailing lists, and you want the
8692 articles you have read to disappear after a while:
8695 (setq gnus-auto-expirable-newsgroups
8696 "mail.nonsense-list\\|mail.nice-list")
8699 Another way to have auto-expiry happen is to have the element
8700 @code{auto-expire} in the group parameters of the group.
8702 @vindex nnmail-expiry-wait
8703 The @code{nnmail-expiry-wait} variable supplies the default time an
8704 expirable article has to live. The default is seven days.
8706 Gnus also supplies a function that lets you fine-tune how long articles
8707 are to live, based on what group they are in. Let's say you want to
8708 have one month expiry period in the @samp{mail.private} group, a one day
8709 expiry period in the @samp{mail.junk} group, and a six day expiry period
8712 @vindex nnmail-expiry-wait-function
8714 (setq nnmail-expiry-wait-function
8716 (cond ((string= group "mail.private")
8718 ((string= group "mail.junk")
8720 ((string= group "important")
8726 The group names that this function is fed are ``unadorned'' group
8727 names---no @samp{nnml:} prefixes and the like.
8729 The @code{nnmail-expiry-wait} variable and
8730 @code{nnmail-expiry-wait-function} function can be either a number (not
8731 necessarily an integer) or the symbols @code{immediate} or
8734 You can also use the @code{expiry-wait} group parameter to selectively
8735 change the expiry period (@pxref{Group Parameters}).
8737 @vindex nnmail-keep-last-article
8738 If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
8739 expire the final article in a mail newsgroup. This is to make life
8740 easier for procmail users.
8742 @vindex gnus-total-expirable-newsgroups
8743 By the way, that line up there about Gnus never expiring non-expirable
8744 articles is a lie. If you put @code{total-expire} in the group
8745 parameters, articles will not be marked as expirable, but all read
8746 articles will be put through the expiry process. Use with extreme
8747 caution. Even more dangerous is the
8748 @code{gnus-total-expirable-newsgroups} variable. All groups that match
8749 this regexp will have all read articles put through the expiry process,
8750 which means that @emph{all} old mail articles in the groups in question
8751 will be deleted after a while. Use with extreme caution, and don't come
8752 crying to me when you discover that the regexp you used matched the
8753 wrong group and all your important mail has disappeared. Be a
8754 @emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
8759 @subsection Duplicates
8761 @vindex nnmail-delete-duplicates
8762 @vindex nnmail-message-id-cache-length
8763 @vindex nnmail-message-id-cache-file
8764 @vindex nnmail-treat-duplicates
8765 @cindex duplicate mails
8766 If you are a member of a couple of mailing list, you will sometime
8767 receive two copies of the same mail. This can be quite annoying, so
8768 @code{nnmail} checks for and treats any duplicates it might find. To do
8769 this, it keeps a cache of old @code{Message-ID}s -
8770 @code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
8771 default. The approximate maximum number of @code{Message-ID}s stored
8772 there is controlled by the @code{nnmail-message-id-cache-length}
8773 variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
8774 stored.) If all this sounds scary to you, you can set
8775 @code{nnmail-delete-duplicates} to @code{warn} (which is what it is by
8776 default), and @code{nnmail} won't delete duplicate mails. Instead it
8777 will generate a brand new @code{Message-ID} for the mail and insert a
8778 warning into the head of the mail saying that it thinks that this is a
8779 duplicate of a different message.
8781 This variable can also be a function. If that's the case, the function
8782 will be called from a buffer narrowed to the message in question with
8783 the @code{Message-ID} as a parameter. The function must return either
8784 @code{nil}, @code{warn}, or @code{delete}.
8786 You can turn this feature off completely by setting the variable to
8789 If you want all the duplicate mails to be put into a special
8790 @dfn{duplicates} group, you could do that using the normal mail split
8794 (setq nnmail-split-fancy
8795 '(| ;; Messages duplicates go to a separate group.
8796 ("gnus-warning" "duplication of message" "duplicate")
8797 ;; Message from daemons, postmaster, and the like to another.
8798 (any mail "mail.misc")
8805 (setq nnmail-split-methods
8806 '(("duplicates" "^Gnus-Warning:")
8811 Here's a neat feature: If you know that the recipient reads her mail
8812 with Gnus, and that she has @code{nnmail-treat-duplicates} set to
8813 @code{delete}, you can send her as many insults as you like, just by
8814 using a @code{Message-ID} of a mail that you know that she's already
8815 received. Think of all the fun! She'll never see any of it! Whee!
8818 @node Not Reading Mail
8819 @subsection Not Reading Mail
8821 If you start using any of the mail backends, they have the annoying
8822 habit of assuming that you want to read mail with them. This might not
8823 be unreasonable, but it might not be what you want.
8825 If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
8826 will ever attempt to read incoming mail, which should help.
8828 @vindex nnbabyl-get-new-mail
8829 @vindex nnmbox-get-new-mail
8830 @vindex nnml-get-new-mail
8831 @vindex nnmh-get-new-mail
8832 @vindex nnfolder-get-new-mail
8833 This might be too much, if, for instance, you are reading mail quite
8834 happily with @code{nnml} and just want to peek at some old @sc{rmail}
8835 file you have stashed away with @code{nnbabyl}. All backends have
8836 variables called backend-@code{get-new-mail}. If you want to disable
8837 the @code{nnbabyl} mail reading, you edit the virtual server for the
8838 group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
8840 All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
8841 narrowed to the article to be saved before saving it when reading
8845 @node Choosing a Mail Backend
8846 @subsection Choosing a Mail Backend
8848 Gnus will read the mail spool when you activate a mail group. The mail
8849 file is first copied to your home directory. What happens after that
8850 depends on what format you want to store your mail in.
8853 * Unix Mail Box:: Using the (quite) standard Un*x mbox.
8854 * Rmail Babyl:: Emacs programs use the rmail babyl format.
8855 * Mail Spool:: Store your mail in a private spool?
8856 * MH Spool:: An mhspool-like backend.
8857 * Mail Folders:: Having one file for each group.
8862 @subsubsection Unix Mail Box
8864 @cindex unix mail box
8866 @vindex nnmbox-active-file
8867 @vindex nnmbox-mbox-file
8868 The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
8869 mail. @code{nnmbox} will add extra headers to each mail article to say
8870 which group it belongs in.
8872 Virtual server settings:
8875 @item nnmbox-mbox-file
8876 @vindex nnmbox-mbox-file
8877 The name of the mail box in the user's home directory.
8879 @item nnmbox-active-file
8880 @vindex nnmbox-active-file
8881 The name of the active file for the mail box.
8883 @item nnmbox-get-new-mail
8884 @vindex nnmbox-get-new-mail
8885 If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
8891 @subsubsection Rmail Babyl
8895 @vindex nnbabyl-active-file
8896 @vindex nnbabyl-mbox-file
8897 The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
8898 mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
8899 article to say which group it belongs in.
8901 Virtual server settings:
8904 @item nnbabyl-mbox-file
8905 @vindex nnbabyl-mbox-file
8906 The name of the rmail mbox file.
8908 @item nnbabyl-active-file
8909 @vindex nnbabyl-active-file
8910 The name of the active file for the rmail box.
8912 @item nnbabyl-get-new-mail
8913 @vindex nnbabyl-get-new-mail
8914 If non-@code{nil}, @code{nnbabyl} will read incoming mail.
8919 @subsubsection Mail Spool
8921 @cindex mail @sc{nov} spool
8923 The @dfn{nnml} spool mail format isn't compatible with any other known
8924 format. It should be used with some caution.
8926 @vindex nnml-directory
8927 If you use this backend, Gnus will split all incoming mail into files;
8928 one file for each mail, and put the articles into the correct
8929 directories under the directory specified by the @code{nnml-directory}
8930 variable. The default value is @file{~/Mail/}.
8932 You do not have to create any directories beforehand; Gnus will take
8935 If you have a strict limit as to how many files you are allowed to store
8936 in your account, you should not use this backend. As each mail gets its
8937 own file, you might very well occupy thousands of inodes within a few
8938 weeks. If this is no problem for you, and it isn't a problem for you
8939 having your friendly systems administrator walking around, madly,
8940 shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should
8941 know that this is probably the fastest format to use. You do not have
8942 to trudge through a big mbox file just to read your new mail.
8944 @code{nnml} is probably the slowest backend when it comes to article
8945 splitting. It has to create lots of files, and it also generates
8946 @sc{nov} databases for the incoming mails. This makes is the fastest
8947 backend when it comes to reading mail.
8949 Virtual server settings:
8952 @item nnml-directory
8953 @vindex nnml-directory
8954 All @code{nnml} directories will be placed under this directory.
8956 @item nnml-active-file
8957 @vindex nnml-active-file
8958 The active file for the @code{nnml} server.
8960 @item nnml-newsgroups-file
8961 @vindex nnml-newsgroups-file
8962 The @code{nnml} group descriptions file. @xref{Newsgroups File
8965 @item nnml-get-new-mail
8966 @vindex nnml-get-new-mail
8967 If non-@code{nil}, @code{nnml} will read incoming mail.
8969 @item nnml-nov-is-evil
8970 @vindex nnml-nov-is-evil
8971 If non-@code{nil}, this backend will ignore any @sc{nov} files.
8973 @item nnml-nov-file-name
8974 @vindex nnml-nov-file-name
8975 The name of the @sc{nov} files. The default is @file{.overview}.
8977 @item nnml-prepare-save-mail-hook
8978 @vindex nnml-prepare-save-mail-hook
8979 Hook run narrowed to an article before saving.
8983 @findex nnml-generate-nov-databases
8984 If your @code{nnml} groups and @sc{nov} files get totally out of whack,
8985 you can do a complete update by typing @kbd{M-x
8986 nnml-generate-nov-databases}. This command will trawl through the
8987 entire @code{nnml} hierarchy, looking at each and every article, so it
8988 might take a while to complete.
8992 @subsubsection MH Spool
8994 @cindex mh-e mail spool
8996 @code{nnmh} is just like @code{nnml}, except that is doesn't generate
8997 @sc{nov} databases and it doesn't keep an active file. This makes
8998 @code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
8999 makes it easier to write procmail scripts for.
9001 Virtual server settings:
9004 @item nnmh-directory
9005 @vindex nnmh-directory
9006 All @code{nnmh} directories will be located under this directory.
9008 @item nnmh-get-new-mail
9009 @vindex nnmh-get-new-mail
9010 If non-@code{nil}, @code{nnmh} will read incoming mail.
9013 @vindex nnmh-be-safe
9014 If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
9015 sure that the articles in the folder are actually what Gnus thinks they
9016 are. It will check date stamps and stat everything in sight, so
9017 setting this to @code{t} will mean a serious slow-down. If you never
9018 use anything but Gnus to read the @code{nnmh} articles, you do not have
9019 to set this variable to @code{t}.
9024 @subsubsection Mail Folders
9026 @cindex mbox folders
9027 @cindex mail folders
9029 @code{nnfolder} is a backend for storing each mail group in a separate
9030 file. Each file is in the standard Un*x mbox format. @code{nnfolder}
9031 will add extra headers to keep track of article numbers and arrival
9034 Virtual server settings:
9037 @item nnfolder-directory
9038 @vindex nnfolder-directory
9039 All the @code{nnfolder} mail boxes will be stored under this directory.
9041 @item nnfolder-active-file
9042 @vindex nnfolder-active-file
9043 The name of the active file.
9045 @item nnfolder-newsgroups-file
9046 @vindex nnfolder-newsgroups-file
9047 The name of the group descriptions file. @xref{Newsgroups File Format}.
9049 @item nnfolder-get-new-mail
9050 @vindex nnfolder-get-new-mail
9051 If non-@code{nil}, @code{nnfolder} will read incoming mail.
9054 @findex nnfolder-generate-active-file
9055 @kindex M-x nnfolder-generate-active-file
9056 If you have lots of @code{nnfolder}-like files you'd like to read with
9057 @code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file}
9058 command to make @code{nnfolder} aware of all likely files in
9059 @code{nnfolder-directory}.
9063 @section Other Sources
9065 Gnus can do more than just read news or mail. The methods described
9066 below allow Gnus to view directories and files as if they were
9070 * Directory Groups:: You can read a directory as if it was a newsgroup.
9071 * Anything Groups:: Dired? Who needs dired?
9072 * Document Groups:: Single files can be the basis of a group.
9073 * SOUP:: Reading @sc{SOUP} packets ``offline''.
9077 @node Directory Groups
9078 @subsection Directory Groups
9080 @cindex directory groups
9082 If you have a directory that has lots of articles in separate files in
9083 it, you might treat it as a newsgroup. The files have to have numerical
9086 This might be an opportune moment to mention @code{ange-ftp}, that most
9087 wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
9088 didn't think much about it---a backend to read directories. Big deal.
9090 @code{ange-ftp} changes that picture dramatically. For instance, if you
9091 enter @file{"/ftp.hpc.uh.edu:/pub/emacs/ding-list/"} as the the
9092 directory name, ange-ftp will actually allow you to read this directory
9093 over at @samp{sina} as a newsgroup. Distributed news ahoy!
9095 @code{nndir} will use @sc{nov} files if they are present.
9097 @code{nndir} is a ``read-only'' backend---you can't delete or expire
9098 articles with this method. You can use @code{nnmh} or @code{nnml} for
9099 whatever you use @code{nndir} for, so you could switch to any of those
9100 methods if you feel the need to have a non-read-only @code{nndir}.
9103 @node Anything Groups
9104 @subsection Anything Groups
9107 From the @code{nndir} backend (which reads a single spool-like
9108 directory), it's just a hop and a skip to @code{nneething}, which
9109 pretends that any arbitrary directory is a newsgroup. Strange, but
9112 When @code{nneething} is presented with a directory, it will scan this
9113 directory and assign article numbers to each file. When you enter such
9114 a group, @code{nneething} must create ``headers'' that Gnus can use.
9115 After all, Gnus is a newsreader, in case you're
9116 forgetting. @code{nneething} does this in a two-step process. First, it
9117 snoops each file in question. If the file looks like an article (i.e.,
9118 the first few lines look like headers), it will use this as the head.
9119 If this is just some arbitrary file without a head (eg. a C source
9120 file), @code{nneething} will cobble up a header out of thin air. It
9121 will use file ownership, name and date and do whatever it can with these
9124 All this should happen automatically for you, and you will be presented
9125 with something that looks very much like a newsgroup. Totally like a
9126 newsgroup, to be precise. If you select an article, it will be displayed
9127 in the article buffer, just as usual.
9129 If you select a line that represents a directory, Gnus will pop you into
9130 a new summary buffer for this @code{nneething} group. And so on. You can
9131 traverse the entire disk this way, if you feel like, but remember that
9132 Gnus is not dired, really, and does not intend to be, either.
9134 There are two overall modes to this action---ephemeral or solid. When
9135 doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
9136 will not store information on what files you have read, and what files
9137 are new, and so on. If you create a solid @code{nneething} group the
9138 normal way with @kbd{G m}, Gnus will store a mapping table between
9139 article numbers and file names, and you can treat this group like any
9140 other groups. When you activate a solid @code{nneething} group, you will
9141 be told how many unread articles it contains, etc., etc.
9146 @item nneething-map-file-directory
9147 @vindex nneething-map-file-directory
9148 All the mapping files for solid @code{nneething} groups will be stored
9149 in this directory, which defaults to @file{~/.nneething/}.
9151 @item nneething-exclude-files
9152 @vindex nneething-exclude-files
9153 All files that match this regexp will be ignored. Nice to use to exclude
9154 auto-save files and the like, which is what it does by default.
9156 @item nneething-map-file
9157 @vindex nneething-map-file
9158 Name of the map files.
9162 @node Document Groups
9163 @subsection Document Groups
9165 @cindex documentation group
9168 @code{nndoc} is a cute little thing that will let you read a single file
9169 as a newsgroup. Several files types are supported:
9176 The babyl (rmail) mail box.
9181 The standard Unix mbox file.
9183 @cindex MMDF mail box
9185 The MMDF mail box format.
9188 Several news articles appended into a file.
9191 @cindex rnews batch files
9192 The rnews batch transport format.
9193 @cindex forwarded messages
9202 @cindex RFC 1153 digest
9203 @cindex RFC 341 digest
9204 MIME (RFC 1341) digest format.
9206 @item standard-digest
9207 The standard (RFC 1153) digest format.
9210 Non-standard digest format---matches most things, but does it badly.
9213 You can also use the special ``file type'' @code{guess}, which means
9214 that @code{nndoc} will try to guess what file type it is looking at.
9215 @code{digest} means that @code{nndoc} should guess what digest type the
9218 @code{nndoc} will not try to change the file or insert any extra headers into
9219 it---it will simply, like, let you use the file as the basis for a
9220 group. And that's it.
9222 If you have some old archived articles that you want to insert into your
9223 new & spiffy Gnus mail backend, @code{nndoc} can probably help you with
9224 that. Say you have an old @file{RMAIL} file with mail that you now want
9225 to split into your new @code{nnml} groups. You look at that file using
9226 @code{nndoc}, set the process mark on all the articles in the buffer
9227 (@kbd{M P b}, for instance), and then re-spool (@kbd{B r}) using
9228 @code{nnml}. If all goes well, all the mail in the @file{RMAIL} file is
9229 now also stored in lots of @code{nnml} directories, and you can delete
9230 that pesky @file{RMAIL} file. If you have the guts!
9232 Virtual server variables:
9235 @item nndoc-article-type
9236 @vindex nndoc-article-type
9237 This should be one of @code{mbox}, @code{babyl}, @code{digest},
9238 @code{mmdf}, @code{forward}, @code{news}, @code{rnews},
9239 @code{mime-digest}, @code{clari-briefs}, or @code{guess}.
9241 @item nndoc-post-type
9242 @vindex nndoc-post-type
9243 This variable says whether Gnus is to consider the group a news group or
9244 a mail group. There are two legal values: @code{mail} (the default)
9254 In the PC world people often talk about ``offline'' newsreaders. These
9255 are thingies that are combined reader/news transport monstrosities.
9256 With built-in modem programs. Yecchh!
9258 Of course, us Unix Weenie types of human beans use things like
9259 @code{uucp} and, like, @code{nntpd} and set up proper news and mail
9260 transport things like Ghod intended. And then we just use normal
9263 However, it can sometimes be convenient to do something a that's a bit
9264 easier on the brain if you have a very slow modem, and you're not really
9265 that interested in doing things properly.
9267 A file format called @sc{soup} has been developed for transporting news
9268 and mail from servers to home machines and back again. It can be a bit
9274 You log in on the server and create a @sc{soup} packet. You can either
9275 use a dedicated @sc{soup} thingie, or you can use Gnus to create the
9276 packet with the @kbd{O s} command.
9279 You transfer the packet home. Rail, boat, car or modem will do fine.
9282 You put the packet in your home directory.
9285 You fire up Gnus using the @code{nnsoup} backend as the native server.
9288 You read articles and mail and answer and followup to the things you
9292 You do the @kbd{G s r} command to pack these replies into a @sc{soup}
9296 You transfer this packet to the server.
9299 You use Gnus to mail this packet out with the @kbd{G s s} command.
9302 You then repeat until you die.
9306 So you basically have a bipartite system---you use @code{nnsoup} for
9307 reading and Gnus for packing/sending these @sc{soup} packets.
9310 * SOUP Commands:: Commands for creating and sending @sc{soup} packets
9311 * SOUP Groups:: A backend for reading @sc{soup} packets.
9312 * SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
9317 @subsubsection SOUP Commands
9321 @kindex G s b (Group)
9322 @findex gnus-group-brew-soup
9323 Pack all unread articles in the current group
9324 (@code{gnus-group-brew-soup}). This command understands the
9325 process/prefix convention.
9328 @kindex G s w (Group)
9329 @findex gnus-soup-save-areas
9330 Save all data files (@code{gnus-soup-save-areas}).
9333 @kindex G s s (Group)
9334 @findex gnus-soup-send-replies
9335 Send all replies from the replies packet
9336 (@code{gnus-soup-send-replies}).
9339 @kindex G s p (Group)
9340 @findex gnus-soup-pack-packet
9341 Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
9344 @kindex G s r (Group)
9345 @findex nnsoup-pack-replies
9346 Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
9349 @kindex O s (Summary)
9350 @findex gnus-soup-add-article
9351 This summary-mode command adds the current article to a @sc{soup} packet
9352 (@code{gnus-soup-add-article}). It understands the process/prefix
9358 There are a few variables to customize where Gnus will put all these
9363 @item gnus-soup-directory
9364 @vindex gnus-soup-directory
9365 Directory where Gnus will save intermediate files while composing
9366 @sc{soup} packets. The default is @file{~/SoupBrew/}.
9368 @item gnus-soup-replies-directory
9369 @vindex gnus-soup-replies-directory
9370 This is what Gnus will use as a temporary directory while sending our
9371 reply packets. The default is @file{~/SoupBrew/SoupReplies/}.
9373 @item gnus-soup-prefix-file
9374 @vindex gnus-soup-prefix-file
9375 Name of the file where Gnus stores the last used prefix. The default is
9378 @item gnus-soup-packer
9379 @vindex gnus-soup-packer
9380 A format string command for packing a @sc{soup} packet. The default is
9381 @samp{tar cf - %s | gzip > $HOME/Soupout%d.tgz}.
9383 @item gnus-soup-unpacker
9384 @vindex gnus-soup-unpacker
9385 Format string command for unpacking a @sc{soup} packet. The default is
9386 @samp{gunzip -c %s | tar xvf -}.
9388 @item gnus-soup-packet-directory
9389 @vindex gnus-soup-packet-directory
9390 Where Gnus will look for reply packets. The default is @file{~/}.
9392 @item gnus-soup-packet-regexp
9393 @vindex gnus-soup-packet-regexp
9394 Regular expression matching @sc{soup} reply packets in
9395 @code{gnus-soup-packet-directory}.
9401 @subsubsection @sc{soup} Groups
9404 @code{nnsoup} is the backend for reading @sc{soup} packets. It will
9405 read incoming packets, unpack them, and put them in a directory where
9406 you can read them at leisure.
9408 These are the variables you can use to customize its behavior:
9412 @item nnsoup-tmp-directory
9413 @vindex nnsoup-tmp-directory
9414 When @code{nnsoup} unpacks a @sc{soup} packet, it does it in this
9415 directory. (@file{/tmp/} by default.)
9417 @item nnsoup-directory
9418 @vindex nnsoup-directory
9419 @code{nnsoup} then moves each message and index file to this directory.
9420 The default is @file{~/SOUP/}.
9422 @item nnsoup-replies-directory
9423 @vindex nnsoup-replies-directory
9424 All replies will stored in this directory before being packed into a
9425 reply packet. The default is @file{~/SOUP/replies/"}.
9427 @item nnsoup-replies-format-type
9428 @vindex nnsoup-replies-format-type
9429 The @sc{soup} format of the replies packets. The default is @samp{?n}
9430 (rnews), and I don't think you should touch that variable. I probably
9431 shouldn't even have documented it. Drats! Too late!
9433 @item nnsoup-replies-index-type
9434 @vindex nnsoup-replies-index-type
9435 The index type of the replies packet. The is @samp{?n}, which means
9436 ``none''. Don't fiddle with this one either!
9438 @item nnsoup-active-file
9439 @vindex nnsoup-active-file
9440 Where @code{nnsoup} stores lots of information. This is not an ``active
9441 file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
9442 this file or mess it up in any way, you're dead. The default is
9443 @file{~/SOUP/active}.
9446 @vindex nnsoup-packer
9447 Format string command for packing a reply @sc{soup} packet. The default
9448 is @samp{tar cf - %s | gzip > $HOME/Soupin%d.tgz}.
9450 @item nnsoup-unpacker
9451 @vindex nnsoup-unpacker
9452 Format string command for unpacking incoming @sc{soup} packets. The
9453 default is @samp{gunzip -c %s | tar xvf -}.
9455 @item nnsoup-packet-directory
9456 @vindex nnsoup-packet-directory
9457 Where @code{nnsoup} will look for incoming packets. The default is
9460 @item nnsoup-packet-regexp
9461 @vindex nnsoup-packet-regexp
9462 Regular expression matching incoming @sc{soup} packets. The default is
9469 @subsubsection SOUP Replies
9471 Just using @code{nnsoup} won't mean that your postings and mailings end
9472 up in @sc{soup} reply packets automagically. You have to work a bit
9473 more for that to happen.
9475 @findex nnsoup-set-variables
9476 The @code{nnsoup-set-variables} command will set the appropriate
9477 variables to ensure that all your followups and replies end up in the
9480 In specific, this is what it does:
9483 (setq gnus-inews-article-function 'nnsoup-request-post)
9484 (setq send-mail-function 'nnsoup-request-mail)
9487 And that's it, really. If you only want news to go into the @sc{soup}
9488 system you just use the first line. If you only want mail to be
9489 @sc{soup}ed you use the second.
9492 @node Combined Groups
9493 @section Combined Groups
9495 Gnus allows combining a mixture of all the other group types into bigger
9499 * Virtual Groups:: Combining articles from many groups.
9500 * Kibozed Groups:: Looking through parts of the newsfeed for articles.
9504 @node Virtual Groups
9505 @subsection Virtual Groups
9507 @cindex virtual groups
9509 An @dfn{nnvirtual group} is really nothing more than a collection of
9512 For instance, if you are tired of reading many small group, you can
9513 put them all in one big group, and then grow tired of reading one
9514 big, unwieldy group. The joys of computing!
9516 You specify @code{nnvirtual} as the method. The address should be a
9517 regexp to match component groups.
9519 All marks in the virtual group will stick to the articles in the
9520 component groups. So if you tick an article in a virtual group, the
9521 article will also be ticked in the component group from whence it came.
9522 (And vice versa---marks from the component groups will also be shown in
9525 Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
9526 newsgroups into one, big, happy newsgroup:
9529 (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
9532 The component groups can be native or foreign; everything should work
9533 smoothly, but if your computer explodes, it was probably my fault.
9535 Collecting the same group from several servers might actually be a good
9536 idea if users have set the Distribution header to limit distribution.
9537 If you would like to read @samp{soc.motss} both from a server in Japan
9538 and a server in Norway, you could use the following as the group regexp:
9541 "^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
9544 This should work kinda smoothly---all articles from both groups should
9545 end up in this one, and there should be no duplicates. Threading (and
9546 the rest) will still work as usual, but there might be problems with the
9547 sequence of articles. Sorting on date might be an option here
9548 (@pxref{Selecting a Group}.
9550 One limitation, however---all groups that are included in a virtual
9551 group has to be alive (i.e., subscribed or unsubscribed). Killed or
9552 zombie groups can't be component groups for @code{nnvirtual} groups.
9554 @vindex nnvirtual-always-rescan
9555 If the @code{nnvirtual-always-rescan} is non-@code{nil},
9556 @code{nnvirtual} will always scan groups for unread articles when
9557 entering a virtual group. If this variable is @code{nil} (which is the
9558 default) and you read articles in a component group after the virtual
9559 group has been activated, the read articles from the component group
9560 will show up when you enter the virtual group. You'll also see this
9561 effect if you have two virtual groups that contain the same component
9562 group. If that's the case, you should set this variable to @code{t}.
9563 Or you can just tap @code{M-g} on the virtual group every time before
9564 you enter it---it'll have much the same effect.
9567 @node Kibozed Groups
9568 @subsection Kibozed Groups
9572 @dfn{Kibozing} is defined by @sc{oed} as ``grepping through (parts of)
9573 the news feed''. @code{nnkiboze} is a backend that will do this for
9574 you. Oh joy! Now you can grind any @sc{nntp} server down to a halt
9575 with useless requests! Oh happiness!
9577 The address field of the @code{nnkiboze} method is, as with
9578 @code{nnvirtual}, a regexp to match groups to be ``included'' in the
9579 @code{nnkiboze} group. There most similarities between @code{nnkiboze}
9580 and @code{nnvirtual} ends.
9582 In addition to this regexp detailing component groups, an @code{nnkiboze} group
9583 must have a score file to say what articles that are to be included in
9584 the group (@pxref{Scoring}).
9586 @kindex M-x nnkiboze-generate-groups
9587 @findex nnkiboze-generate-groups
9588 You must run @kbd{M-x nnkiboze-generate-groups} after creating the
9589 @code{nnkiboze} groups you want to have. This command will take time. Lots of
9590 time. Oodles and oodles of time. Gnus has to fetch the headers from
9591 all the articles in all the components groups and run them through the
9592 scoring process to determine if there are any articles in the groups
9593 that are to be part of the @code{nnkiboze} groups.
9595 Please limit the number of component groups by using restrictive
9596 regexps. Otherwise your sysadmin may become annoyed with you, and the
9597 @sc{nntp} site may throw you off and never let you back in again.
9598 Stranger things have happened.
9600 @code{nnkiboze} component groups do not have to be alive---they can be dead,
9601 and they can be foreign. No restrictions.
9603 @vindex nnkiboze-directory
9604 The generation of an @code{nnkiboze} group means writing two files in
9605 @code{nnkiboze-directory}, which is @file{~/News/} by default. One
9606 contains the @sc{nov} header lines for all the articles in the group,
9607 and the other is an additional @file{.newsrc} file to store information
9608 on what groups that have been searched through to find component
9611 Articles that are marked as read in the @code{nnkiboze} group will have their
9612 @sc{nov} lines removed from the @sc{nov} file.
9619 Other people use @dfn{kill files}, but we here at Gnus Towers like
9620 scoring better than killing, so we'd rather switch than fight. They do
9621 something completely different as well, so sit up straight and pay
9624 @vindex gnus-summary-mark-below
9625 All articles have a default score (@code{gnus-summary-default-score}),
9626 which is 0 by default. This score may be raised or lowered either
9627 interactively or by score files. Articles that have a score lower than
9628 @code{gnus-summary-mark-below} are marked as read.
9630 Gnus will read any @dfn{score files} that apply to the current group
9631 before generating the summary buffer.
9633 There are several commands in the summary buffer that insert score
9634 entries based on the current article. You can, for instance, ask Gnus to
9635 lower or increase the score of all articles with a certain subject.
9637 There are two sorts of scoring entries: Permanent and temporary.
9638 Temporary score entries are self-expiring entries. Any entries that are
9639 temporary and have not been used for, say, a week, will be removed
9640 silently to help keep the sizes of the score files down.
9643 * Summary Score Commands:: Adding score entries for the current group.
9644 * Group Score Commands:: General score commands.
9645 * Score Variables:: Customize your scoring. (My, what terminology).
9646 * Score File Format:: What a score file may contain.
9647 * Score File Editing:: You can edit score files by hand as well.
9648 * Adaptive Scoring:: Big Sister Gnus *knows* what you read.
9649 * Followups To Yourself:: Having Gnus notice when people answer you.
9650 * Scoring Tips:: How to score effectively.
9651 * Reverse Scoring:: That problem child of old is not problem.
9652 * Global Score Files:: Earth-spanning, ear-splitting score files.
9653 * Kill Files:: They are still here, but they can be ignored.
9654 * GroupLens:: Getting predictions on what you like to read.
9658 @node Summary Score Commands
9659 @section Summary Score Commands
9660 @cindex score commands
9662 The score commands that alter score entries do not actually modify real
9663 score files. That would be too inefficient. Gnus maintains a cache of
9664 previously loaded score files, one of which is considered the
9665 @dfn{current score file alist}. The score commands simply insert
9666 entries into this list, and upon group exit, this list is saved.
9668 The current score file is by default the group's local score file, even
9669 if no such score file actually exists. To insert score commands into
9670 some other score file (eg. @file{all.SCORE}), you must first make this
9671 score file the current one.
9673 General score commands that don't actually change the score file:
9678 @kindex V s (Summary)
9679 @findex gnus-summary-set-score
9680 Set the score of the current article (@code{gnus-summary-set-score}).
9683 @kindex V S (Summary)
9684 @findex gnus-summary-current-score
9685 Display the score of the current article
9686 (@code{gnus-summary-current-score}).
9689 @kindex V t (Summary)
9690 @findex gnus-score-find-trace
9691 Display all score rules that have been used on the current article
9692 (@code{gnus-score-find-trace}).
9695 @cindex V R (Summary)
9696 @findex gnus-summary-rescore
9697 Run the current summary through the scoring process
9698 (@code{gnus-summary-rescore}). This might be useful if you're playing
9699 around with your score files behind Gnus' back and want to see the
9700 effect you're having.
9703 @kindex V a (Summary)
9704 @findex gnus-summary-score-entry
9705 Add a new score entry, and allow specifying all elements
9706 (@code{gnus-summary-score-entry}).
9709 @kindex V c (Summary)
9710 @findex gnus-score-change-score-file
9711 Make a different score file the current
9712 (@code{gnus-score-change-score-file}).
9715 @kindex V e (Summary)
9716 @findex gnus-score-edit-current-scores
9717 Edit the current score file (@code{gnus-score-edit-current-scores}).
9718 You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score
9722 @kindex V f (Summary)
9723 @findex gnus-score-edit-file
9724 Edit a score file and make this score file the current one
9725 (@code{gnus-score-edit-file}).
9728 @kindex V C (Summary)
9729 @findex gnus-score-customize
9730 Customize a score file in a visually pleasing manner
9731 (@code{gnus-score-customize}).
9734 @kindex I C-i (Summary)
9735 @findex gnus-summary-raise-score
9736 Increase the score of the current article
9737 (@code{gnus-summary-raise-score}).
9740 @kindex L C-l (Summary)
9741 @findex gnus-summary-lower-score
9742 Lower the score of the current article
9743 (@code{gnus-summary-lower-score}).
9746 The rest of these commands modify the local score file.
9751 @kindex V m (Summary)
9752 @findex gnus-score-set-mark-below
9753 Prompt for a score, and mark all articles with a score below this as
9754 read (@code{gnus-score-set-mark-below}).
9757 @kindex V E (Summary)
9758 @findex gnus-score-set-expunge-below
9759 Expunge all articles with a score below the default score (or the
9760 numeric prefix) (@code{gnus-score-set-expunge-below}).
9763 The keystrokes for actually making score entries follow a very regular
9764 pattern, so there's no need to list all the commands. (Hundreds of
9769 The first key is either @kbd{I} (upper case i) for increasing the score
9770 or @kbd{L} for lowering the score.
9772 The second key says what header you want to score on. The following
9777 Score on the author name.
9780 Score on the subject line.
9783 Score on the Xref line---i.e., the cross-posting line.
9786 Score on thread---the References line.
9792 Score on the number of lines.
9795 Score on the Message-ID.
9808 The third key is the match type. Which match types are legal depends on
9809 what headers you are scoring on.
9853 Greater than number.
9858 The fourth and final key says whether this is a temporary (i.e., expiring)
9859 score entry, or a permanent (i.e., non-expiring) score entry, or whether
9860 it is to be done immediately, without adding to the score file.
9864 Temporary score entry.
9867 Permanent score entry.
9870 Immediately scoring.
9875 So, let's say you want to increase the score on the current author with
9876 exact matching permanently: @kbd{I a e p}. If you want to lower the
9877 score based on the subject line, using substring matching, and make a
9878 temporary score entry: @kbd{L s s t}. Pretty easy.
9880 To make things a bit more complicated, there are shortcuts. If you use
9881 a capital letter on either the second or third keys, Gnus will use
9882 defaults for the remaining one or two keystrokes. The defaults are
9883 ``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s
9884 t}, and @kbd{I a R} is the same as @kbd{I a r t}.
9886 @vindex gnus-score-mimic-keymap
9887 The @code{gnus-score-mimic-keymap} says whether these commands will
9888 pretend they are keymaps or not.
9891 @node Group Score Commands
9892 @section Group Score Commands
9893 @cindex group score commands
9895 There aren't many of these as yet, I'm afraid.
9901 @findex gnus-score-flush-cache
9902 Gnus maintains a cache of score alists to avoid having to reload them
9903 all the time. This command will flush the cache
9904 (@code{gnus-score-flush-cache}).
9909 @node Score Variables
9910 @section Score Variables
9911 @cindex score variables
9915 @item gnus-use-scoring
9916 @vindex gnus-use-scoring
9917 If @code{nil}, Gnus will not check for score files, and will not, in
9918 general, do any score-related work. This is @code{t} by default.
9920 @item gnus-kill-killed
9921 @vindex gnus-kill-killed
9922 If this variable is @code{nil}, Gnus will never apply score files to
9923 articles that have already been through the kill process. While this
9924 may save you lots of time, it also means that if you apply a kill file
9925 to a group, and then change the kill file and want to run it over you
9926 group again to kill more articles, it won't work. You have to set this
9927 variable to @code{t} to do that. (It is @code{t} by default.)
9929 @item gnus-kill-files-directory
9930 @vindex gnus-kill-files-directory
9931 All kill and score files will be stored in this directory, which is
9932 initialized from the @code{SAVEDIR} environment variable by default.
9933 This is @file{~/News/} by default.
9935 @item gnus-score-file-suffix
9936 @vindex gnus-score-file-suffix
9937 Suffix to add to the group name to arrive at the score file name
9938 (@samp{SCORE} by default.)
9940 @item gnus-score-uncacheable-files
9941 @vindex gnus-score-uncacheable-files
9943 All score files are normally cached to avoid excessive re-loading of
9944 score files. However, if this might make you Emacs grow big and
9945 bloated, so this regexp can be used to weed out score files that are
9946 unlikely to be needed again. It would be a bad idea to deny caching of
9947 @file{all.SCORE}, while it might be a good idea to not cache
9948 @file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
9949 variable is @samp{ADAPT$} by default, so no adaptive score files will
9952 @item gnus-save-score
9953 @vindex gnus-save-score
9954 If you have really complicated score files, and do lots of batch
9955 scoring, then you might set this variable to @code{t}. This will make
9956 Gnus save the scores into the @file{.newsrc.eld} file.
9958 @item gnus-score-interactive-default-score
9959 @vindex gnus-score-interactive-default-score
9960 Score used by all the interactive raise/lower commands to raise/lower
9961 score with. Default is 1000, which may seem excessive, but this is to
9962 ensure that the adaptive scoring scheme gets enough room to play with.
9963 We don't want the small changes from the adaptive scoring to overwrite
9964 manually entered data.
9966 @item gnus-summary-default-score
9967 @vindex gnus-summary-default-score
9968 Default score of an article, which is 0 by default.
9970 @item gnus-score-over-mark
9971 @vindex gnus-score-over-mark
9972 Mark (in the third column) used for articles with a score over the
9973 default. Default is @samp{+}.
9975 @item gnus-score-below-mark
9976 @vindex gnus-score-below-mark
9977 Mark (in the third column) used for articles with a score below the
9978 default. Default is @samp{-}.
9980 @item gnus-score-find-score-files-function
9981 @vindex gnus-score-find-score-files-function
9982 Function used to find score files for the current group. This function
9983 is called with the name of the group as the argument.
9985 Predefined functions available are:
9988 @item gnus-score-find-single
9989 @findex gnus-score-find-single
9990 Only apply the group's own score file.
9992 @item gnus-score-find-bnews
9993 @findex gnus-score-find-bnews
9994 Apply all score files that match, using bnews syntax. This is the
9995 default. For instance, if the current group is @samp{gnu.emacs.gnus},
9996 @file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and
9997 @file{gnu.all.SCORE} would all apply. In short, the instances of
9998 @samp{all} in the score file names are translated into @samp{.*}, and
9999 then a regexp match is done.
10001 This means that if you have some score entries that you want to apply to
10002 all groups, then you put those entries in the @file{all.SCORE} file.
10004 @item gnus-score-find-hierarchical
10005 @findex gnus-score-find-hierarchical
10006 Apply all score files from all the parent groups. This means that you
10007 can't have score files like @file{all.SCORE} or @file{all.emacs.SCORE},
10008 but you can have @file{SCORE}, @file{comp.SCORE} and
10009 @file{comp.emacs.SCORE}.
10012 This variable can also be a list of functions. In that case, all these
10013 functions will be called, and all the returned lists of score files will
10014 be applied. These functions can also return lists of score alists
10015 directly. In that case, the functions that return these non-file score
10016 alists should probably be placed before the ``real'' score file
10017 functions, to ensure that the last score file returned is the local
10020 @item gnus-score-expiry-days
10021 @vindex gnus-score-expiry-days
10022 This variable says how many days should pass before an unused score file
10023 entry is expired. If this variable is @code{nil}, no score file entries
10024 are expired. It's 7 by default.
10026 @item gnus-update-score-entry-dates
10027 @vindex gnus-update-score-entry-dates
10028 If this variable is non-@code{nil}, matching score entries will have
10029 their dates updated. (This is how Gnus controls expiry---all
10030 non-matching entries will become too old while matching entries will
10031 stay fresh and young.) However, if you set this variable to @code{nil},
10032 even matching entries will grow old and will have to face that oh-so
10035 @item gnus-score-after-write-file-function
10036 @vindex gnus-score-after-write-file-function
10037 Function called with the name of the score file just written.
10042 @node Score File Format
10043 @section Score File Format
10044 @cindex score file format
10046 A score file is an @code{emacs-lisp} file that normally contains just a
10047 single form. Casual users are not expected to edit these files;
10048 everything can be changed from the summary buffer.
10050 Anyway, if you'd like to dig into it yourself, here's an example:
10054 ("Lars Ingebrigtsen" -10000)
10056 ("larsi\\|lmi" -50000 nil R))
10058 ("Ding is Badd" nil 728373))
10060 ("alt.politics" -1000 728372 s))
10065 (mark-and-expunge -10)
10069 (files "/hom/larsi/News/gnu.SCORE")
10070 (exclude-files "all.SCORE")
10071 (local (gnus-newsgroup-auto-expire t)
10072 (gnus-summary-make-false-root 'empty))
10076 This example demonstrates absolutely everything about a score file.
10078 Even though this looks much like lisp code, nothing here is actually
10079 @code{eval}ed. The lisp reader is used to read this form, though, so it
10080 has to be legal syntactically, if not semantically.
10082 Six keys are supported by this alist:
10087 If the key is a string, it is the name of the header to perform the
10088 match on. Scoring can only be performed on these eight headers:
10089 @code{From}, @code{Subject}, @code{References}, @code{Message-ID},
10090 @code{Xref}, @code{Lines}, @code{Chars} and @code{Date}. In addition to
10091 these headers, there are three strings to tell Gnus to fetch the entire
10092 article and do the match on larger parts of the article: @code{Body}
10093 will perform the match on the body of the article, @code{Head} will
10094 perform the match on the head of the article, and @code{All} will
10095 perform the match on the entire article. Note that using any of these
10096 last three keys will slow down group entry @emph{considerably}. The
10097 final ``header'' you can score on is @code{Followup}. These score
10098 entries will result in new score entries being added for all follow-ups
10099 to articles that matches these score entries.
10101 Following this key is a arbitrary number of score entries, where each
10102 score entry has one to four elements.
10106 The first element is the @dfn{match element}. On most headers this will
10107 be a string, but on the Lines and Chars headers, this must be an
10111 If the second element is present, it should be a number---the @dfn{score
10112 element}. This number should be an integer in the neginf to posinf
10113 interval. This number is added to the score of the article if the match
10114 is successful. If this element is not present, the
10115 @code{gnus-score-interactive-default-score} number will be used
10116 instead. This is 1000 by default.
10119 If the third element is present, it should be a number---the @dfn{date
10120 element}. This date says when the last time this score entry matched,
10121 which provides a mechanism for expiring the score entries. It this
10122 element is not present, the score entry is permanent. The date is
10123 represented by the number of days since December 31, 1 ce.
10126 If the fourth element is present, it should be a symbol---the @dfn{type
10127 element}. This element specifies what function should be used to see
10128 whether this score entry matches the article. What match types that can
10129 be used depends on what header you wish to perform the match on.
10132 @item From, Subject, References, Xref, Message-ID
10133 For most header types, there are the @code{r} and @code{R} (regexp) as
10134 well as @code{s} and @code{S} (substring) types and @code{e} and
10135 @code{E} (exact match) types. If this element is not present, Gnus will
10136 assume that substring matching should be used. @code{R} and @code{S}
10137 differ from the other two in that the matches will be done in a
10138 case-sensitive manner. All these one-letter types are really just
10139 abbreviations for the @code{regexp}, @code{string} and @code{exact}
10140 types, which you can use instead, if you feel like.
10143 These two headers use different match types: @code{<}, @code{>},
10144 @code{=}, @code{>=} and @code{<=}.
10147 For the Date header we have three match types: @code{before}, @code{at}
10148 and @code{after}. I can't really imagine this ever being useful, but,
10149 like, it would feel kinda silly not to provide this function. Just in
10150 case. You never know. Better safe than sorry. Once burnt, twice shy.
10151 Don't judge a book by its cover. Never not have sex on a first date.
10153 @item Head, Body, All
10154 These three match keys use the same match types as the @code{From} (etc)
10158 This match key will add a score entry on all articles that followup to
10159 some author. Uses the same match types as the @code{From} header uses.
10162 This match key will add a score entry on all articles that are part of
10163 a thread. Uses the same match types as the @code{References} header
10169 The value of this entry should be a number. Any articles with a score
10170 lower than this number will be marked as read.
10173 The value of this entry should be a number. Any articles with a score
10174 lower than this number will be removed from the summary buffer.
10176 @item mark-and-expunge
10177 The value of this entry should be a number. Any articles with a score
10178 lower than this number will be marked as read and removed from the
10181 @item thread-mark-and-expunge
10182 The value of this entry should be a number. All articles that belong to
10183 a thread that has a total score below this number will be marked as read
10184 and removed from the summary buffer. @code{gnus-thread-score-function}
10185 says how to compute the total score for a thread.
10188 The value of this entry should be any number of file names. These files
10189 are assumed to be score files as well, and will be loaded the same way
10192 @item exclude-files
10193 The clue of this entry should be any number of files. This files will
10194 not be loaded, even though they would normally be so, for some reason or
10198 The value of this entry will be @code{eval}el. This element will be
10199 ignored when handling global score files.
10202 Read-only score files will not be updated or saved. Global score files
10203 should feature this atom (@pxref{Global Score Files}).
10206 The value of this entry should be a number. Articles that do not have
10207 parents will get this number added to their scores. Imagine you follow
10208 some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you
10209 will only follow a few of the threads, also want to see any new threads.
10211 You can do this with the following two score file entries:
10215 (mark-and-expunge -100)
10218 When you enter the group the first time, you will only see the new
10219 threads. You then raise the score of the threads that you find
10220 interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{C y}) the
10221 rest. Next time you enter the group, you will see new articles in the
10222 interesting threads, plus any new threads.
10224 I.e. -- the orphan score atom is for high-volume groups where there
10225 exist a few interesting threads which can't be found automatically by
10226 ordinary scoring rules.
10229 This entry controls the adaptive scoring. If it is @code{t}, the
10230 default adaptive scoring rules will be used. If it is @code{ignore}, no
10231 adaptive scoring will be performed on this group. If it is a list, this
10232 list will be used as the adaptive scoring rules. If it isn't present,
10233 or is something other than @code{t} or @code{ignore}, the default
10234 adaptive scoring rules will be used. If you want to use adaptive
10235 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
10236 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
10237 not want adaptive scoring. If you only want adaptive scoring in a few
10238 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
10239 insert @code{(adapt t)} in the score files of the groups where you want
10243 All adaptive score entries will go to the file named by this entry. It
10244 will also be applied when entering the group. This atom might be handy
10245 if you want to adapt on several groups at once, using the same adaptive
10246 file for a number of groups.
10249 @cindex local variables
10250 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
10251 Each @var{var} will be made buffer-local to the current summary buffer,
10252 and set to the value specified. This is a convenient, if somewhat
10253 strange, way of setting variables in some groups if you don't like hooks
10258 @node Score File Editing
10259 @section Score File Editing
10261 You normally enter all scoring commands from the summary buffer, but you
10262 might feel the urge to edit them by hand as well, so we've supplied you
10263 with a mode for that.
10265 It's simply a slightly customized @code{emacs-lisp} mode, with these
10266 additional commands:
10271 @kindex C-c C-c (Score)
10272 @findex gnus-score-edit-done
10273 Save the changes you have made and return to the summary buffer
10274 (@code{gnus-score-edit-done}).
10277 @kindex C-c C-d (Score)
10278 @findex gnus-score-edit-insert-date
10279 Insert the current date in numerical format
10280 (@code{gnus-score-edit-insert-date}). This is really the day number, if
10281 you were wondering.
10284 @kindex C-c C-p (Score)
10285 @findex gnus-score-pretty-print
10286 The adaptive score files are saved in an unformatted fashion. If you
10287 intend to read one of these files, you want to @dfn{pretty print} it
10288 first. This command (@code{gnus-score-pretty-print}) does that for
10293 Type @kbd{M-x gnus-score-mode} to use this mode.
10295 @vindex gnus-score-mode-hook
10296 @code{gnus-score-menu-hook} is run in score mode buffers.
10298 In the summary buffer you can use commands like @kbd{V f} and @kbd{V
10299 e} to begin editing score files.
10302 @node Adaptive Scoring
10303 @section Adaptive Scoring
10304 @cindex adaptive scoring
10306 If all this scoring is getting you down, Gnus has a way of making it all
10307 happen automatically---as if by magic. Or rather, as if by artificial
10308 stupidity, to be precise.
10310 @vindex gnus-use-adaptive-scoring
10311 When you read an article, or mark an article as read, or kill an
10312 article, you leave marks behind. On exit from the group, Gnus can sniff
10313 these marks and add score elements depending on what marks it finds.
10314 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
10317 @vindex gnus-default-adaptive-score-alist
10318 To give you complete control over the scoring process, you can customize
10319 the @code{gnus-default-adaptive-score-alist} variable. For instance, it
10320 might look something like this:
10323 (defvar gnus-default-adaptive-score-alist
10324 '((gnus-unread-mark)
10325 (gnus-ticked-mark (from 4))
10326 (gnus-dormant-mark (from 5))
10327 (gnus-del-mark (from -4) (subject -1))
10328 (gnus-read-mark (from 4) (subject 2))
10329 (gnus-expirable-mark (from -1) (subject -1))
10330 (gnus-killed-mark (from -1) (subject -3))
10331 (gnus-kill-file-mark)
10332 (gnus-ancient-mark)
10333 (gnus-low-score-mark)
10334 (gnus-catchup-mark (from -1) (subject -1))))
10337 As you see, each element in this alist has a mark as a key (either a
10338 variable name or a ``real'' mark---a character). Following this key is
10339 a arbitrary number of header/score pairs. If there are no header/score
10340 pairs following the key, no adaptive scoring will be done on articles
10341 that have that key as the article mark. For instance, articles with
10342 @code{gnus-unread-mark} in the example above will not get adaptive score
10345 Each article can have only one mark, so just a single of these rules
10346 will be applied to each article.
10348 To take @code{gnus-del-mark} as an example---this alist says that all
10349 articles that have that mark (i.e., are marked with @samp{D}) will have a
10350 score entry added to lower based on the @code{From} header by -4, and
10351 lowered by @code{Subject} by -1. Change this to fit your prejudices.
10353 If you have marked 10 articles with the same subject with
10354 @code{gnus-del-mark}, the rule for that mark will be applied ten times.
10355 That means that that subject will get a score of ten times -1, which
10356 should be, unless I'm much mistaken, -10.
10358 The headers you can score on are @code{from}, @code{subject},
10359 @code{message-id}, @code{references}, @code{xref}, @code{lines},
10360 @code{chars} and @code{date}. In addition, you can score on
10361 @code{followup}, which will create an adaptive score entry that matches
10362 on the @code{References} header using the @code{Message-ID} of the
10363 current article, thereby matching the following thread.
10365 You can also score on @code{thread}, which will try to score all
10366 articles that appear in a thread. @code{thread} matches uses a
10367 @code{Message-ID} to match on the @code{References} header of the
10368 article. If the match is made, the @code{Message-ID} of the article is
10369 added to the @code{thread} rule. (Think about it. I'd recommend two
10370 aspirins afterwards.)
10372 If you use this scheme, you should set the score file atom @code{mark}
10373 to something small---like -300, perhaps, to avoid having small random
10374 changes result in articles getting marked as read.
10376 After using adaptive scoring for a week or so, Gnus should start to
10377 become properly trained and enhance the authors you like best, and kill
10378 the authors you like least, without you having to say so explicitly.
10380 You can control what groups the adaptive scoring is to be performed on
10381 by using the score files (@pxref{Score File Format}). This will also
10382 let you use different rules in different groups.
10384 @vindex gnus-adaptive-file-suffix
10385 The adaptive score entries will be put into a file where the name is the
10386 group name with @code{gnus-adaptive-file-suffix} appended. The default
10389 @vindex gnus-score-exact-adapt-limit
10390 When doing adaptive scoring, substring or fuzzy matching would probably
10391 give you the best results in most cases. However, if the header one
10392 matches is short, the possibility for false positives is great, so if
10393 the length of the match is less than
10394 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
10395 this variable is @code{nil}, exact matching will always be used to avoid
10399 @node Followups To Yourself
10400 @section Followups To Yourself
10402 Gnus offers two commands for picking out the @code{Message-ID} header in
10403 the current buffer. Gnus will then add a score rule that scores using
10404 this @code{Message-ID} on the @code{References} header of other
10405 articles. This will, in effect, increase the score of all articles that
10406 respond to the article in the current buffer. Quite useful if you want
10407 to easily note when people answer what you've said.
10411 @item gnus-score-followup-article
10412 @findex gnus-score-followup-article
10413 This will add a score to articles that directly follow up your own
10416 @item gnus-score-followup-thread
10417 @findex gnus-score-followup-thread
10418 This will add a score to all articles that appear in a thread ``below''
10422 @vindex gnus-inews-article-hook
10423 These two functions are both primarily meant to be used in hooks like
10424 @code{gnus-inews-article-hook}.
10428 @section Scoring Tips
10429 @cindex scoring tips
10435 @cindex scoring crossposts
10436 If you want to lower the score of crossposts, the line to match on is
10437 the @code{Xref} header.
10439 ("xref" (" talk.politics.misc:" -1000))
10442 @item Multiple crossposts
10443 If you want to lower the score of articles that have been crossposted to
10444 more than, say, 3 groups:
10446 ("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
10449 @item Matching on the body
10450 This is generally not a very good idea---it takes a very long time.
10451 Gnus actually has to fetch each individual article from the server. But
10452 you might want to anyway, I guess. Even though there are three match
10453 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
10454 and stick with it in each score file. If you use any two, each article
10455 will be fetched @emph{twice}. If you want to match a bit on the
10456 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
10459 @item Marking as read
10460 You will probably want to mark articles that has a score below a certain
10461 number as read. This is most easily achieved by putting the following
10462 in your @file{all.SCORE} file:
10466 You may also consider doing something similar with @code{expunge}.
10468 @item Negated character classes
10469 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
10470 That will match newlines, which might lead to, well, The Unknown. Say
10471 @code{[^abcd\n]*} instead.
10475 @node Reverse Scoring
10476 @section Reverse Scoring
10477 @cindex reverse scoring
10479 If you want to keep just articles that have @samp{Sex with Emacs} in the
10480 subject header, and expunge all other articles, you could put something
10481 like this in your score file:
10485 ("Sex with Emacs" 2))
10490 So, you raise all articles that match @samp{Sex with Emacs} and mark the
10491 rest as read, and expunge them to boot.
10494 @node Global Score Files
10495 @section Global Score Files
10496 @cindex global score files
10498 Sure, other newsreaders have ``global kill files''. These are usually
10499 nothing more than a single kill file that applies to all groups, stored
10500 in the user's home directory. Bah! Puny, weak newsreaders!
10502 What I'm talking about here are Global Score Files. Score files from
10503 all over the world, from users everywhere, uniting all nations in one
10504 big, happy score file union! Ange-score! New and untested!
10506 @vindex gnus-global-score-files
10507 All you have to do to use other people's score files is to set the
10508 @code{gnus-global-score-files} variable. One entry for each score file,
10509 or each score file directory. Gnus will decide by itself what score
10510 files are applicable to which group.
10512 Say you want to use all score files in the
10513 @file{/ftp@@ftp.some-where:/pub/score} directory and the single score
10514 file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
10517 (setq gnus-global-score-files
10518 '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
10519 "/ftp@@ftp.some-where:/pub/score/"))
10522 @findex gnus-score-search-global-directories
10523 Simple, eh? Directory names must end with a @samp{/}. These
10524 directories are typically scanned only once during each Gnus session.
10525 If you feel the need to manually re-scan the remote directories, you can
10526 use the @code{gnus-score-search-global-directories} command.
10528 Note that, at present, using this option will slow down group entry
10529 somewhat. (That is---a lot.)
10531 If you want to start maintaining score files for other people to use,
10532 just put your score file up for anonymous ftp and announce it to the
10533 world. Become a retro-moderator! Participate in the retro-moderator
10534 wars sure to ensue, where retro-moderators battle it out for the
10535 sympathy of the people, luring them to use their score files on false
10536 premises! Yay! The net is saved!
10538 Here are some tips for the would-be retro-moderator, off the top of my
10544 Articles that are heavily crossposted are probably junk.
10546 To lower a single inappropriate article, lower by @code{Message-ID}.
10548 Particularly brilliant authors can be raised on a permanent basis.
10550 Authors that repeatedly post off-charter for the group can safely be
10551 lowered out of existence.
10553 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
10554 articles completely.
10557 Use expiring score entries to keep the size of the file down. You
10558 should probably have a long expiry period, though, as some sites keep
10559 old articles for a long time.
10562 ... I wonder whether other newsreaders will support global score files
10563 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
10564 Wave, xrn and 1stReader are bound to implement scoring. Should we start
10565 holding our breath yet?
10569 @section Kill Files
10572 Gnus still supports those pesky old kill files. In fact, the kill file
10573 entries can now be expiring, which is something I wrote before Daniel
10574 Quinlan thought of doing score files, so I've left the code in there.
10576 In short, kill processing is a lot slower (and I do mean @emph{a lot})
10577 than score processing, so it might be a good idea to rewrite your kill
10578 files into score files.
10580 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
10581 forms into this file, which means that you can use kill files as some
10582 sort of primitive hook function to be run on group entry, even though
10583 that isn't a very good idea.
10585 XCNormal kill files look like this:
10588 (gnus-kill "From" "Lars Ingebrigtsen")
10589 (gnus-kill "Subject" "ding")
10593 This will mark every article written by me as read, and remove them from
10594 the summary buffer. Very useful, you'll agree.
10596 Other programs use a totally different kill file syntax. If Gnus
10597 encounters what looks like a @code{rn} kill file, it will take a stab at
10600 Two summary functions for editing a GNUS kill file:
10605 @kindex M-k (Summary)
10606 @findex gnus-summary-edit-local-kill
10607 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
10610 @kindex M-K (Summary)
10611 @findex gnus-summary-edit-global-kill
10612 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
10615 Two group mode functions for editing the kill files:
10620 @kindex M-k (Group)
10621 @findex gnus-group-edit-local-kill
10622 Edit this group's kill file (@code{gnus-group-edit-local-kill}).
10625 @kindex M-K (Group)
10626 @findex gnus-group-edit-global-kill
10627 Edit the general kill file (@code{gnus-group-edit-global-kill}).
10630 Kill file variables:
10633 @item gnus-kill-file-name
10634 @vindex gnus-kill-file-name
10635 A kill file for the group @samp{soc.motss} is normally called
10636 @file{soc.motss.KILL}. The suffix appended to the group name to get
10637 this file name is detailed by the @code{gnus-kill-file-name} variable.
10638 The ``global'' kill file (not in the score file sense of ``global'', of
10639 course) is called just @file{KILL}.
10641 @vindex gnus-kill-save-kill-file
10642 @item gnus-kill-save-kill-file
10643 If this variable is non-@code{nil}, Gnus will save the
10644 kill file after processing, which is necessary if you use expiring
10647 @item gnus-apply-kill-hook
10648 @vindex gnus-apply-kill-hook
10649 @findex gnus-apply-kill-file-unless-scored
10650 @findex gnus-apply-kill-file
10651 A hook called to apply kill files to a group. It is
10652 @code{(gnus-apply-kill-file)} by default. If you want to ignore the
10653 kill file if you have a score file for the same group, you can set this
10654 hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want
10655 kill files to be processed, you should set this variable to @code{nil}.
10657 @item gnus-kill-file-mode-hook
10658 @vindex gnus-kill-file-mode-hook
10659 A hook called in kill-file mode buffers.
10668 GroupLens is a collaborative filtering system that helps you work
10669 together with other people to find the quality news articles out of the
10670 huge volume of news articles generated every day.
10672 To accomplish this the GroupLens system combines your opinions about
10673 articles you have already read with the opinions of others who have done
10674 likewise and gives you a personalized prediction for each unread news
10675 article. Think of GroupLens as a matchmaker. GroupLens watches how you
10676 rate articles, and finds other people that rate articles the same way.
10677 Once it has found for you some people you agree with it tells you, in
10678 the form of a prediction, what they thought of the article. You can use
10679 this prediction to help you decide whether or not you want to read the
10683 * Using GroupLens:: How to make Gnus use GroupLens.
10684 * Rating Articles:: Letting GroupLens know how you rate articles.
10685 * Displaying Predictions:: Displaying predictions given by GroupLens.
10686 * GroupLens Variables:: Customizing GroupLens.
10690 @node Using GroupLens
10691 @subsection Using GroupLens
10693 To use GroupLens you must register a pseudonym with your local Better
10694 Bit Bureau (BBB). At the moment the only better bit in town is at
10695 @samp{http://www.cs.umn.edu/Research/GroupLens/bbb.html}.
10697 Once you have registered you'll need to set a couple of variables.
10701 @item gnus-use-grouplens
10702 @vindex gnus-use-grouplens
10703 Setting this variable to a non-@code{nil} value will make Gnus hook into
10704 all the relevant GroupLens functions.
10706 @item grouplens-pseudonym
10707 @vindex grouplens-pseudonym
10708 This variable should be set to the pseudonum you got when registering
10709 with the Better Bit Bureau.
10711 @item grouplens-newsgroups
10712 @vindex grouplens-newsgroups
10713 A list of groups that you want to get GroupLens predictions for.
10717 Thats the minimum of what you need to get up and running with GroupLens.
10718 Once you've registered, GroupLens will start giving you scores for
10719 articles based on the average of what other people think. But, to get
10720 the real benefit of GroupLens you need to start rating articles
10721 yourself. Then the scores GroupLens gives you will be personalized for
10722 you, based on how the people you usually agree with have already rated.
10725 @node Rating Articles
10726 @subsection Rating Articles
10728 In GroupLens, an article is rated on a scale from 1 to 5, inclusive.
10729 Where 1 means something like this article is a waste of bandwidth and 5
10730 means that the article was really good. The basic question to ask
10731 yourself is, "on a scale from 1 to 5 would I like to see more articles
10734 There are four ways to enter a rating for an article in GroupLens.
10739 @kindex r (GroupLens)
10740 @findex bbb-summary-rate-article
10741 This function will prompt you for a rating on a scale of one to five.
10744 @kindex k (GroupLens)
10745 @findex grouplens-score-thread
10746 This function will prompt you for a rating, and rate all the articles in
10747 the thread. This is really useful for some of those long running giant
10748 threads in rec.humor.
10752 The next two commands, @kbd{n} and @kbd{,} take a numerical prefix to be
10753 the score of the article you're reading.
10758 @kindex n (GroupLens)
10759 @findex grouplens-next-unread-article
10760 Rate the article and go to the next unread article.
10763 @kindex , (GroupLens)
10764 @findex grouplens-best-unread-article
10765 Rate the article and go to the next unread article with the highest score.
10769 If you want to give the current article a score of 4 and then go to the
10770 next article, just type @kbd{4 n}.
10773 @node Displaying Predictions
10774 @subsection Displaying Predictions
10776 GroupLens makes a prediction for you about how much you will like a
10777 news article. The predictions from GroupLens are on a scale from 1 to
10778 5, where 1 is the worst and 5 is the best. You can use the predictions
10779 from GroupLens in one of three ways controlled by the variable
10780 @code{gnus-grouplens-override-scoring}.
10782 @vindex gnus-grouplens-override-scoring
10783 There are three ways to display predictions in grouplens. You may
10784 choose to have the GroupLens scores contribute to, or override the
10785 regular gnus scoring mechanism. override is the default; however, some
10786 people prefer to see the Gnus scores plus the grouplens scores. To get
10787 the separate scoring behavior you need to set
10788 @code{gnus-grouplens-override-scoring} to @code{'separate}. To have the
10789 GroupLens predictions combined with the grouplens scores set it to
10790 @code{'override} and to combine the scores set
10791 @code{gnus-grouplens-override-scoring} to @code{'combine}. When you use
10792 the combine option you will also want to set the values for
10793 @code{grouplens-prediction-offset} and
10794 @code{grouplens-score-scale-factor}.
10796 @vindex grouplens-prediction-display
10797 In either case, GroupLens gives you a few choices for how you would like
10798 to see your predictions displayed. The display of predictions is
10799 controlled by the @code{grouplens-prediction-display} variable.
10801 The following are legal values for that variable.
10804 @item prediction-spot
10805 The higher the prediction, the further to the right an @samp{*} is
10808 @item confidence-interval
10809 A numeric confidence interval.
10811 @item prediction-bar
10812 The higher the prediction, the longer the bar.
10814 @item confidence-bar
10815 Numerical confidence.
10817 @item confidence-spot
10818 The spot gets bigger with more confidence.
10820 @item prediction-num
10821 Plain-old numeric value.
10823 @item confidence-plus-minus
10824 Prediction +/i confidence.
10829 @node GroupLens Variables
10830 @subsection GroupLens Variables
10834 @item gnus-summary-grouplens-line-format
10835 The summary line format used in summary buffers that are GroupLens
10836 enhanced. It accepts the same specs as the normal summary line format
10837 (@pxref{ Summary Buffer Lines}). The default is
10838 @samp{%U%R%z%l%I%(%[%4L: %-20,20n%]%) %s\n}.
10840 @item grouplens-bbb-host
10841 Host running the bbbd server. The default is
10842 @samp{grouplens.cs.umn.edu}.
10844 @item grouplens-bbb-port
10845 Port of the host running the bbbd server. The default is 9000.
10847 @item grouplens-score-offset
10848 Offset the prediction by this value. In other words, subtract the
10849 prediction value by this number to arrive at the effective score. The
10852 @item grouplens-score-scale-factor
10853 This variable allows the user to magnify the effect of GroupLens scores.
10854 The scale factor is applied after the offset. The default is 1.
10864 * Process/Prefix:: A convention used by many treatment commands.
10865 * Interactive:: Making Gnus ask you many questions.
10866 * Formatting Variables:: You can specify what buffers should look like.
10867 * Windows Configuration:: Configuring the Gnus buffer windows.
10868 * Compilation:: How to speed Gnus up.
10869 * Mode Lines:: Displaying information in the mode lines.
10870 * Highlighting and Menus:: Making buffers look all nice and cozy.
10871 * Buttons:: Get tendonitis in ten easy steps!
10872 * Daemons:: Gnus can do things behind your back.
10873 * NoCeM:: How to avoid spam and other fatty foods.
10874 * Picons:: How to display pictures of what your reading.
10875 * Various Various:: Things that are really various.
10879 @node Process/Prefix
10880 @section Process/Prefix
10881 @cindex process/prefix convention
10883 Many functions, among them functions for moving, decoding and saving
10884 articles, use what is known as the @dfn{Process/Prefix convention}.
10886 This is a method for figuring out what articles that the user wants the
10887 command to be performed on.
10891 If the numeric prefix is N, perform the operation on the next N
10892 articles, starting with the current one. If the numeric prefix is
10893 negative, perform the operation on the previous N articles, starting
10894 with the current one.
10896 @vindex transient-mark-mode
10897 If @code{transient-mark-mode} in non-@code{nil} and the region is
10898 active, all articles in the region will be worked upon.
10900 If there is no numeric prefix, but some articles are marked with the
10901 process mark, perform the operation on the articles that are marked with
10904 If there is neither a numeric prefix nor any articles marked with the
10905 process mark, just perform the operation on the current article.
10907 Quite simple, really, but it needs to be made clear so that surprises
10910 @vindex gnus-summary-goto-unread
10911 One thing that seems to shock & horrify lots of people is that, for
10912 instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}.
10913 Since each @kbd{d} (which marks the current article as read) by default
10914 goes to the next unread article after marking, this means that @kbd{3 d}
10915 will mark the next three unread articles as read, no matter what the
10916 summary buffer looks like. Set @code{gnus-summary-goto-unread} to
10917 @code{nil} for a more straightforward action.
10921 @section Interactive
10922 @cindex interaction
10926 @item gnus-novice-user
10927 @vindex gnus-novice-user
10928 If this variable is non-@code{nil}, you are either a newcomer to the
10929 World of Usenet, or you are very cautious, which is a nice thing to be,
10930 really. You will be given questions of the type ``Are you sure you want
10931 to do this?'' before doing anything dangerous. This is @code{t} by
10934 @item gnus-expert-user
10935 @vindex gnus-expert-user
10936 If this variable is non-@code{nil}, you will never ever be asked any
10937 questions by Gnus. It will simply assume you know what you're doing, no
10938 matter how strange.
10940 @item gnus-interactive-catchup
10941 @vindex gnus-interactive-catchup
10942 Require confirmation before catching up a group if non-@code{nil}. It
10943 is @code{t} by default.
10945 @item gnus-interactive-post
10946 @vindex gnus-interactive-post
10947 If non-@code{nil}, the user will be prompted for a group name when
10948 posting an article. It is @code{t} by default.
10950 @item gnus-interactive-exit
10951 @vindex gnus-interactive-exit
10952 Require confirmation before exiting Gnus. This variable is @code{t} by
10957 @node Formatting Variables
10958 @section Formatting Variables
10959 @cindex formatting variables
10961 Throughout this manual you've probably noticed lots of variables that
10962 are called things like @code{gnus-group-line-format} and
10963 @code{gnus-summary-mode-line-format}. These control how Gnus is to
10964 output lines in the various buffers. There's quite a lot of them.
10965 Fortunately, they all use the same syntax, so there's not that much to
10968 Here's an example format spec (from the group buffer): @samp{%M%S%5y:
10969 %(%g%)\n}. We see that it is indeed extremely ugly, and that there are
10970 lots of percentages everywhere.
10972 Each @samp{%} element will be replaced by some string or other when the
10973 buffer in question is generated. @samp{%5y} means ``insert the @samp{y}
10974 spec, and pad with spaces to get a 5-character field''. Just like a
10975 normal format spec, almost.
10977 You can also say @samp{%6,4y}, which means that the field will never be
10978 more than 6 characters wide and never less than 4 characters wide.
10980 There are also specs for highlighting, and these are shared by all the
10981 format variables. Text inside the @samp{%(} and @samp{%)} specifiers
10982 will get the special @code{mouse-face} property set, which means that it
10983 will be highlighted (with @code{gnus-mouse-face}) when you put the mouse
10986 Text inside the @samp{%[} and @samp{%]} specifiers will have their
10987 normal faces set using @code{gnus-face-0}, which is @code{bold} by
10988 default. If you say @samp{%1[} instead, you'll get @code{gnus-face-1}
10989 instead, and so on. Create as many faces as you wish. The same goes
10990 for the @code{mouse-face} specs---you can say @samp{%3(hello%)} to have
10991 @samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
10993 Here's an alternative recipe for the group buffer:
10996 ;; Create three face types.
10997 (setq gnus-face-1 'bold)
10998 (setq gnus-face-3 'italic)
11000 ;; We want the article count to be in
11001 ;; a bold and green face. So we create
11002 ;; a new face called `my-green-bold'.
11003 (copy-face 'bold 'my-green-bold)
11005 (set-face-foreground 'my-green-bold "ForestGreen")
11006 (setq gnus-face-2 'my-green-bold)
11008 ;; Set the new & fancy format.
11009 (setq gnus-group-line-format
11010 "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
11013 I'm sure you'll be able to use this scheme to create totally unreadable
11014 and extremely vulgar displays. Have fun!
11016 Currently Gnus uses the following formatting variables:
11017 @code{gnus-group-line-format}, @code{gnus-summary-line-format},
11018 @code{gnus-server-line-format}, @code{gnus-topic-line-format},
11019 @code{gnus-group-mode-line-format},
11020 @code{gnus-summary-mode-line-format},
11021 @code{gnus-article-mode-line-format},
11022 @code{gnus-server-mode-line-format}.
11024 Note that the @samp{%(} specs (and friends) do not make any sense on the
11025 mode-line variables.
11027 All these format variables can also be arbitrary elisp forms. In that
11028 case, they will be @code{eval}ed to insert the required lines.
11030 @kindex M-x gnus-update-format
11031 @findex gnus-update-format
11032 Gnus includes a command to help you while creating your own format
11033 specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
11034 update the spec in question and pop you to a buffer where you can
11035 examine the resulting lisp code to be run to generate the line.
11038 @node Windows Configuration
11039 @section Windows Configuration
11040 @cindex windows configuration
11042 No, there's nothing here about X, so be quiet.
11044 @vindex gnus-use-full-window
11045 If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all
11046 other windows and occupy the entire Emacs screen by itself. It is
11047 @code{t} by default.
11049 @vindex gnus-buffer-configuration
11050 @code{gnus-buffer-configuration} describes how much space each Gnus
11051 buffer should be given. Here's an excerpt of this variable:
11054 ((group (vertical 1.0 (group 1.0 point)
11055 (if gnus-carpal (group-carpal 4))))
11056 (article (vertical 1.0 (summary 0.25 point)
11060 This is an alist. The @dfn{key} is a symbol that names some action or
11061 other. For instance, when displaying the group buffer, the window
11062 configuration function will use @code{group} as the key. A full list of
11063 possible names is listed below.
11065 The @dfn{value} (i. e., the @dfn{split}) says how much space each buffer
11066 should occupy. To take the @code{article} split as an example -
11069 (article (vertical 1.0 (summary 0.25 point)
11073 This @dfn{split} says that the summary buffer should occupy 25% of upper
11074 half of the screen, and that it is placed over the article buffer. As
11075 you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all
11076 reaching for that calculator there). However, the special number
11077 @code{1.0} is used to signal that this buffer should soak up all the
11078 rest of the space available after the rest of the buffers have taken
11079 whatever they need. There should be only one buffer with the @code{1.0}
11080 size spec per split.
11082 Point will be put in the buffer that has the optional third element
11085 Here's a more complicated example:
11088 (article (vertical 1.0 (group 4)
11089 (summary 0.25 point)
11090 (if gnus-carpal (summary-carpal 4))
11094 If the size spec is an integer instead of a floating point number,
11095 then that number will be used to say how many lines a buffer should
11096 occupy, not a percentage.
11098 If the @dfn{split} looks like something that can be @code{eval}ed (to be
11099 precise---if the @code{car} of the split is a function or a subr), this
11100 split will be @code{eval}ed. If the result is non-@code{nil}, it will
11101 be used as a split. This means that there will be three buffers if
11102 @code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal}
11105 Not complicated enough for you? Well, try this on for size:
11108 (article (horizontal 1.0
11113 (summary 0.25 point)
11118 Whoops. Two buffers with the mystery 100% tag. And what's that
11119 @code{horizontal} thingie?
11121 If the first element in one of the split is @code{horizontal}, Gnus will
11122 split the window horizontally, giving you two windows side-by-side.
11123 Inside each of these strips you may carry on all you like in the normal
11124 fashion. The number following @code{horizontal} says what percentage of
11125 the screen is to be given to this strip.
11127 For each split, there @emph{must} be one element that has the 100% tag.
11128 The splitting is never accurate, and this buffer will eat any leftover
11129 lines from the splits.
11131 To be slightly more formal, here's a definition of what a legal split
11135 split = frame | horizontal | vertical | buffer | form
11136 frame = "(frame " size *split ")"
11137 horizontal = "(horizontal " size *split ")"
11138 vertical = "(vertical " size *split ")"
11139 buffer = "(" buffer-name " " size *[ "point" ] ")"
11140 size = number | frame-params
11141 buffer-name = group | article | summary ...
11144 The limitations are that the @code{frame} split can only appear as the
11145 top-level split. @var{form} should be an Emacs Lisp form that should
11146 return a valid split. We see that each split is fully recursive, and
11147 may contain any number of @code{vertical} and @code{horizontal} splits.
11149 @vindex gnus-window-min-width
11150 @vindex gnus-window-min-height
11151 @cindex window height
11152 @cindex window width
11153 Finding the right sizes can be a bit complicated. No window may be less
11154 than @code{gnus-window-min-height} (default 2) characters high, and all
11155 windows must be at least @code{gnus-window-min-width} (default 1)
11156 characters wide. Gnus will try to enforce this before applying the
11157 splits. If you want to use the normal Emacs window width/height limit,
11158 you can just set these two variables to @code{nil}.
11160 If you're not familiar with Emacs terminology, @code{horizontal} and
11161 @code{vertical} splits may work the opposite way of what you'd expect.
11162 Windows inside a @code{horizontal} split are shown side-by-side, and
11163 windows within a @code{vertical} split are shown above each other.
11165 @findex gnus-configure-frame
11166 If you want to experiment with window placement, a good tip is to call
11167 @code{gnus-configure-frame} directly with a split. This is the function
11168 that does all the real work when splitting buffers. Below is a pretty
11169 nonsensical configuration with 5 windows; two for the group buffer and
11170 three for the article buffer. (I said it was nonsensical.) If you
11171 @code{eval} the statement below, you can get an idea of how that would
11172 look straight away, without going through the normal Gnus channels.
11173 Play with it until you're satisfied, and then use
11174 @code{gnus-add-configuration} to add your new creation to the buffer
11175 configuration list.
11178 (gnus-configure-frame
11182 (article 0.3 point))
11190 You might want to have several frames as well. No prob---just use the
11191 @code{frame} split:
11194 (gnus-configure-frame
11197 (summary 0.25 point)
11199 (vertical ((height . 5) (width . 15)
11200 (user-position . t)
11201 (left . -1) (top . 1))
11206 This split will result in the familiar summary/article window
11207 configuration in the first (or ``main'') frame, while a small additional
11208 frame will be created where picons will be shown. As you can see,
11209 instead of the normal @code{1.0} top-level spec, each additional split
11210 should have a frame parameter alist as the size spec.
11211 @xref{(elisp)Frame Parameters}.
11213 Here's a list of all possible keys for
11214 @code{gnus-buffer-configuration}:
11216 @code{group}, @code{summary}, @code{article}, @code{server},
11217 @code{browse}, @code{group-mail}, @code{summary-mail},
11218 @code{summary-reply}, @code{info}, @code{summary-faq},
11219 @code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
11220 @code{followup}, @code{followup-yank}, @code{edit-score}.
11222 @findex gnus-add-configuration
11223 Since the @code{gnus-buffer-configuration} variable is so long and
11224 complicated, there's a function you can use to ease changing the config
11225 of a single setting: @code{gnus-add-configuration}. If, for instance,
11226 you want to change the @code{article} setting, you could say:
11229 (gnus-add-configuration
11230 '(article (vertical 1.0
11232 (summary .25 point)
11236 You'd typically stick these @code{gnus-add-configuration} calls in your
11237 @file{.gnus} file or in some startup hook -- they should be run after
11238 Gnus has been loaded.
11242 @section Compilation
11243 @cindex compilation
11244 @cindex byte-compilation
11246 @findex gnus-compile
11248 Remember all those line format specification variables?
11249 @code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
11250 on. Now, Gnus will of course heed whatever these variables are, but,
11251 unfortunately, changing them will mean a quite significant slow-down.
11252 (The default values of these variables have byte-compiled functions
11253 associated with them, while the user-generated versions do not, of
11256 To help with this, you can run @kbd{M-x gnus-compile} after you've
11257 fiddled around with the variables and feel that you're (kind of)
11258 satisfied. This will result in the new specs being byte-compiled, and
11259 you'll get top speed again.
11263 @section Mode Lines
11266 @vindex gnus-updated-mode-lines
11267 @code{gnus-updated-mode-lines} says what buffers should keep their mode
11268 lines updated. It is a list of symbols. Supported symbols include
11269 @code{group}, @code{article}, @code{summary}, @code{server},
11270 @code{browse}, and @code{tree}. If the corresponding symbol is present,
11271 Gnus will keep that mode line updated with information that may be
11272 pertinent. If this variable is @code{nil}, screen refresh may be
11275 @cindex display-time
11277 @vindex gnus-mode-non-string-length
11278 By default, Gnus displays information on the current article in the mode
11279 lines of the summary and article buffers. The information Gnus wishes
11280 to display (eg. the subject of the article) is often longer than the
11281 mode lines, and therefore have to be cut off at some point. The
11282 @code{gnus-mode-non-string-length} variable says how long the other
11283 elements on the line is (i.e., the non-info part). If you put
11284 additional elements on the mode line (eg. a clock), you should modify
11287 @c Hook written by Francesco Potorti` <pot@cnuce.cnr.it>
11289 (add-hook 'display-time-hook
11290 (lambda () (setq gnus-mode-non-string-length
11292 (if line-number-mode 5 0)
11293 (if column-number-mode 4 0)
11294 (length display-time-string)))))
11297 If this variable is @code{nil} (which is the default), the mode line
11298 strings won't be chopped off, and they won't be padded either.
11301 @node Highlighting and Menus
11302 @section Highlighting and Menus
11304 @cindex highlighting
11307 @vindex gnus-visual
11308 The @code{gnus-visual} variable controls most of the prettifying Gnus
11309 aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy
11310 colors or fonts. This will also inhibit loading the @file{gnus-vis.el}
11313 This variable can be a list of visual properties that are enabled. The
11314 following elements are legal, and are all included by default:
11317 @item group-highlight
11318 Do highlights in the group buffer.
11319 @item summary-highlight
11320 Do highlights in the summary buffer.
11321 @item article-highlight
11322 Do highlights in the article buffer.
11324 Turn on highlighting in all buffers.
11326 Create menus in the group buffer.
11328 Create menus in the summary buffers.
11330 Create menus in the article buffer.
11332 Create menus in the browse buffer.
11334 Create menus in the server buffer.
11336 Create menus in the score buffers.
11338 Create menus in all buffers.
11341 So if you only want highlighting in the article buffer and menus in all
11342 buffers, you could say something like:
11345 (setq gnus-visual '(article-highlight menu))
11348 If you want only highlighting and no menus whatsoever, you'd say:
11351 (setq gnus-visual '(highlight))
11354 If @code{gnus-visual} is @code{t}, highlighting and menus will be used
11355 in all Gnus buffers.
11357 Other general variables that influence the look of all buffers include:
11360 @item gnus-mouse-face
11361 @vindex gnus-mouse-face
11362 This is the face (i.e., font) used for mouse highlighting in Gnus. No
11363 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
11365 @item gnus-display-type
11366 @vindex gnus-display-type
11367 This variable is symbol indicating the display type Emacs is running
11368 under. The symbol should be one of @code{color}, @code{grayscale} or
11369 @code{mono}. If Gnus guesses this display attribute wrongly, either set
11370 this variable in your @file{~/.emacs} or set the resource
11371 @code{Emacs.displayType} in your @file{~/.Xdefaults}.
11373 @item gnus-background-mode
11374 @vindex gnus-background-mode
11375 This is a symbol indicating the Emacs background brightness. The symbol
11376 should be one of @code{light} or @code{dark}. If Gnus guesses this
11377 frame attribute wrongly, either set this variable in your @file{~/.emacs} or
11378 set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
11379 `gnus-display-type'.
11382 There are hooks associated with the creation of all the different menus:
11386 @item gnus-article-menu-hook
11387 @vindex gnus-article-menu-hook
11388 Hook called after creating the article mode menu.
11390 @item gnus-group-menu-hook
11391 @vindex gnus-group-menu-hook
11392 Hook called after creating the group mode menu.
11394 @item gnus-summary-menu-hook
11395 @vindex gnus-summary-menu-hook
11396 Hook called after creating the summary mode menu.
11398 @item gnus-server-menu-hook
11399 @vindex gnus-server-menu-hook
11400 Hook called after creating the server mode menu.
11402 @item gnus-browse-menu-hook
11403 @vindex gnus-browse-menu-hook
11404 Hook called after creating the browse mode menu.
11406 @item gnus-score-menu-hook
11407 @vindex gnus-score-menu-hook
11408 Hook called after creating the score mode menu.
11419 Those new-fangled @dfn{mouse} contraptions is very popular with the
11420 young, hep kids who don't want to learn the proper way to do things
11421 these days. Why, I remember way back in the summer of '89, when I was
11422 using Emacs on a Tops 20 system. Three hundred users on one single
11423 machine, and every user was running Simula compilers. Bah!
11427 @vindex gnus-carpal
11428 Well, you can make Gnus display bufferfuls of buttons you can click to
11429 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
11430 really. Tell the chiropractor I sent you.
11435 @item gnus-carpal-mode-hook
11436 @vindex gnus-carpal-mode-hook
11437 Hook run in all carpal mode buffers.
11439 @item gnus-carpal-button-face
11440 @vindex gnus-carpal-button-face
11441 Face used on buttons.
11443 @item gnus-carpal-header-face
11444 @vindex gnus-carpal-header-face
11445 Face used on carpal buffer headers.
11447 @item gnus-carpal-group-buffer-buttons
11448 @vindex gnus-carpal-group-buffer-buttons
11449 Buttons in the group buffer.
11451 @item gnus-carpal-summary-buffer-buttons
11452 @vindex gnus-carpal-summary-buffer-buttons
11453 Buttons in the summary buffer.
11455 @item gnus-carpal-server-buffer-buttons
11456 @vindex gnus-carpal-server-buffer-buttons
11457 Buttons in the server buffer.
11459 @item gnus-carpal-browse-buffer-buttons
11460 @vindex gnus-carpal-browse-buffer-buttons
11461 Buttons in the browse buffer.
11464 All the @code{buttons} variables are lists. The elements in these list
11465 is either a cons cell where the car contains a text to be displayed and
11466 the cdr contains a function symbol, or a simple string.
11474 Gnus, being larger than any program ever written (allegedly), does lots
11475 of strange stuff that you may wish to have done while you're not
11476 present. For instance, you may want it to check for new mail once in a
11477 while. Or you may want it to close down all connections to all servers
11478 when you leave Emacs idle. And stuff like that.
11480 Gnus will let you do stuff like that by defining various
11481 @dfn{handlers}. Each handler consists of three elements: A
11482 @var{function}, a @var{time}, and an @var{idle} parameter.
11484 Here's an example of a handler that closes connections when Emacs has
11485 been idle for thirty minutes:
11488 (gnus-demon-close-connections nil 30)
11491 Here's a handler that scans for PGP headers every hour when Emacs is
11495 (gnus-demon-scan-pgp 60 t)
11498 This @var{time} parameter and than @var{idle} parameter works together
11499 in a strange, but wonderful fashion. Basically, if @var{idle} is
11500 @code{nil}, then the function will be called every @var{time} minutes.
11502 If @var{idle} is @code{t}, then the function will be called after
11503 @var{time} minutes only if Emacs is idle. So if Emacs is never idle,
11504 the function will never be called. But once Emacs goes idle, the
11505 function will be called every @var{time} minutes.
11507 If @var{idle} is a number and @var{time} is a number, the function will
11508 be called every @var{time} minutes only when Emacs has been idle for
11509 @var{idle} minutes.
11511 If @var{idle} is a number and @var{time} is @code{nil}, the function
11512 will be called once every time Emacs has been idle for @var{idle}
11515 And if @var{time} is a string, it should look like @samp{07:31}, and
11516 the function will then be called once every day somewhere near that
11517 time. Modified by the @var{idle} parameter, of course.
11519 @vindex gnus-demon-timestep
11520 (When I say ``minute'' here, I really mean @code{gnus-demon-timestep}
11521 seconds. This is @code{60} by default. If you change that variable,
11522 all the timings in the handlers will be affected.)
11524 @vindex gnus-use-demon
11525 To set the whole thing in motion, though, you have to set
11526 @code{gnus-use-demon} to @code{t}.
11528 So, if you want to add a handler, you could put something like this in
11529 your @file{.gnus} file:
11531 @findex gnus-demon-add-handler
11533 (gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
11536 @findex gnus-demon-add-nocem
11537 @findex gnus-demon-add-scanmail
11538 @findex gnus-demon-add-disconnection
11539 Some ready-made functions to do this has been created:
11540 @code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, and
11541 @code{gnus-demon-add-scanmail}. Just put those functions in your
11542 @file{.gnus} if you want those abilities.
11544 @findex gnus-demon-init
11545 @findex gnus-demon-cancel
11546 @vindex gnus-demon-handlers
11547 If you add handlers to @code{gnus-demon-handlers} directly, you should
11548 run @code{gnus-demon-init} to make the changes take hold. To cancel all
11549 daemons, you can use the @code{gnus-demon-cancel} function.
11551 Note that adding daemons can be pretty naughty if you overdo it. Adding
11552 functions that scan all news and mail from all servers every two seconds
11553 is a sure-fire way of getting booted off any respectable system. So
11562 @dfn{Spamming} is posting the same article lots and lots of times.
11563 Spamming is bad. Spamming is evil.
11565 Spamming is usually canceled within a day or so by various anti-spamming
11566 agencies. These agencies usually also send out @dfn{NoCeM} messages.
11567 NoCeM is pronounced ``no see-'em'', and means what the name
11568 implies---these are messages that make the offending articles, like, go
11571 What use are these NoCeM messages if the articles are canceled anyway?
11572 Some sites do not honor cancel messages and some sites just honor cancels
11573 from a select few people. Then you may wish to make use of the NoCeM
11574 messages, which are distributed in the @samp{alt.nocem.misc} newsgroup.
11576 Gnus can read and parse the messages in this group automatically, and
11577 this will make spam disappear.
11579 There are some variables to customize, of course:
11582 @item gnus-use-nocem
11583 @vindex gnus-use-nocem
11584 Set this variable to @code{t} to set the ball rolling. It is @code{nil}
11587 @item gnus-nocem-groups
11588 @vindex gnus-nocem-groups
11589 Gnus will look for NoCeM messages in the groups in this list. The
11590 default is @code{("alt.nocem.misc" "news.admin.net-abuse.announce")}.
11592 @item gnus-nocem-issuers
11593 @vindex gnus-nocem-issuers
11594 There are many people issuing NoCeM messages. This list says what
11595 people you want to listen to. The default is @code{("Automoose-1"
11596 "clewis@@ferret.ocunix.on.ca;" "jem@@xpat.com;" "red@@redpoll.mrfs.oh.us
11597 (Richard E. Depew)")}; fine, upstanding citizens all of them.
11599 Known despammers that you can put in this list include:
11602 @item clewis@@ferret.ocunix.on.ca;
11603 @cindex Chris Lewis
11604 Chris Lewis---Major Canadian despammer who has probably canceled more
11605 usenet abuse than anybody else.
11608 @cindex CancelMoose[tm]
11609 The CancelMoose[tm] on autopilot. The CancelMoose[tm] is reputed to be
11610 Norwegian, and was the person(s) who invented NoCeM.
11612 @item jem@@xpat.com;
11614 Jem---Korean despammer who is getting very busy these days.
11616 @item red@@redpoll.mrfs.oh.us (Richard E. Depew)
11617 Richard E. Depew---lone American despammer. He mostly cancels binary
11618 postings to non-binary groups and removes spews (regurgitated articles).
11621 You do not have to heed NoCeM messages from all these people---just the
11622 ones you want to listen to.
11624 @item gnus-nocem-directory
11625 @vindex gnus-nocem-directory
11626 This is where Gnus will store its NoCeM cache files. The default is
11627 @file{~/News/NoCeM/}.
11629 @item gnus-nocem-expiry-wait
11630 @vindex gnus-nocem-expiry-wait
11631 The number of days before removing old NoCeM entries from the cache.
11632 The default is 15. If you make it shorter Gnus will be faster, but you
11633 might then see old spam.
11641 So... You want to slow down your news reader even more! This is a
11642 good way to do so. Its also a great way to impress people staring
11643 over your shoulder as you read news.
11646 * Picon Basics:: What are picons and How do I get them.
11647 * Picon Requirements:: Don't go further if you aren't using XEmacs.
11648 * Easy Picons:: Displaying Picons -- the easy way.
11649 * Hard Picons:: The way you should do it. You'll learn something.
11650 * Picon Configuration:: Other variables you can trash/tweak/munge/play with.
11655 @subsection Picon Basics
11657 What are Picons? To quote directly from the Picons Web site
11658 (@samp{http://www.cs.indiana.edu/picons/ftp/index.html}):
11661 @dfn{Picons} is short for ``personal icons''. They're small,
11662 constrained images used to represent users and domains on the net,
11663 organized into databases so that the appropriate image for a given
11664 e-mail address can be found. Besides users and domains, there are picon
11665 databases for Usenet newsgroups and weather forecasts. The picons are
11666 in either monochrome @code{XBM} format or color @code{XPM} and
11667 @code{GIF} formats.
11670 Please see the above mentioned web site for instructions on obtaining
11671 and installing the picons databases, or the following ftp site:
11672 @samp{http://www.cs.indiana.edu/picons/ftp/index.html}.
11674 @vindex gnus-picons-database
11675 Gnus expects picons to be installed into a location pointed to by
11676 @code{gnus-picons-database}.
11679 @node Picon Requirements
11680 @subsection Picon Requirements
11682 To use have Gnus display Picons for you, you must be running XEmacs
11683 19.13 or greater since all other versions of Emacs aren't yet able to
11686 Additionally, you must have @code{xpm} support compiled into XEmacs.
11688 @vindex gnus-picons-convert-x-face
11689 If you want to display faces from @code{X-Face} headers, you must have
11690 the @code{netpbm} utilities installed, or munge the
11691 @code{gnus-picons-convert-x-face} variable to use something else.
11695 @subsection Easy Picons
11697 To enable displaying picons, simply put the following line in your
11698 @file{~/.gnus} file and start Gnus.
11701 (setq gnus-use-picons t)
11702 (add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
11703 (add-hook 'gnus-summary-prepare-hook 'gnus-group-display-picons t)
11704 (add-hook 'gnus-article-display-hook 'gnus-picons-article-display-x-face)
11709 @subsection Hard Picons
11711 Gnus can display picons for you as you enter and leave groups and
11712 articles. It knows how to interact with three sections of the picons
11713 database. Namely, it can display the picons newsgroup pictures,
11714 author's face picture(s), and the authors domain. To enable this
11715 feature, you need to first decide where to display them.
11719 @item gnus-picons-display-where
11720 @vindex gnus-picons-display-where
11721 Where the picon images should be displayed. It is @code{picons} by
11722 default (which by default maps to the buffer @samp{*Picons*}). Other
11723 valid places could be @code{article}, @code{summary}, or
11724 @samp{"*scratch*"} for all I care. Just make sure that you've made the
11725 buffer visible using the standard Gnus window configuration routines --
11726 @xref{Windows Configuration}.
11730 Note: If you set @code{gnus-use-picons} to @code{t}, it will set up your
11731 window configuration for you to include the @code{picons} buffer.
11733 Now that you've made that decision, you need to add the following
11734 functions to the appropriate hooks so these pictures will get
11735 displayed at the right time.
11737 @vindex gnus-article-display-hook
11738 @vindex gnus-picons-display-where
11740 @item gnus-article-display-picons
11741 @findex gnus-article-display-picons
11742 Looks up and display the picons for the author and the author's domain
11743 in the @code{gnus-picons-display-where} buffer. Should be added to
11744 the @code{gnus-article-display-hook}.
11746 @item gnus-group-display-picons
11747 @findex gnus-article-display-picons
11748 Displays picons representing the current group. This function should
11749 be added to the @code{gnus-summary-prepare-hook} or to the
11750 @code{gnus-article-display-hook} if @code{gnus-picons-display-where}
11751 is set to @code{article}.
11753 @item gnus-picons-article-display-x-face
11754 @findex gnus-article-display-picons
11755 Decodes and displays the X-Face header if present. This function
11756 should be added to @code{gnus-article-display-hook}.
11760 Note: You must append them to the hook, so make sure to specify 't'
11761 to the append flag of @code{add-hook}:
11764 (add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
11768 @node Picon Configuration
11769 @subsection Picon Configuration
11771 The following variables offer further control over how things are
11772 done, where things are located, and other useless stuff you really
11773 don't need to worry about.
11776 @item gnus-picons-database
11777 @vindex gnus-picons-database
11778 The location of the picons database. Should point to a directory
11779 containing the @file{news}, @file{domains}, @file{users} (and so on)
11780 subdirectories. Defaults to @file{/usr/local/faces}.
11782 @item gnus-picons-news-directory
11783 @vindex gnus-picons-news-directory
11784 Sub-directory of the faces database containing the icons for
11787 @item gnus-picons-user-directories
11788 @vindex gnus-picons-user-directories
11789 List of subdirectories to search in @code{gnus-picons-database} for user
11790 faces. Defaults to @code{("local" "users" "usenix" "misc/MISC")}.
11792 @item gnus-picons-domain-directories
11793 @vindex gnus-picons-domain-directories
11794 List of subdirectories to search in @code{gnus-picons-database} for
11795 domain name faces. Defaults to @code{("domains")}. Some people may
11796 want to add @samp{unknown} to this list.
11798 @item gnus-picons-convert-x-face
11799 @vindex gnus-picons-convert-x-face
11800 The command to use to convert the @code{X-Face} header to an X bitmap
11801 (@code{xbm}). Defaults to @code{(format "@{ echo '/* Width=48,
11802 Height=48 */'; uncompface; @} | icontopbm | pbmtoxbm > %s"
11803 gnus-picons-x-face-file-name)}
11805 @item gnus-picons-x-face-file-name
11806 @vindex gnus-picons-x-face-file-name
11807 Names a temporary file to store the @code{X-Face} bitmap in. Defaults
11808 to @code{(format "/tmp/picon-xface.%s.xbm" (user-login-name))}.
11810 @item gnus-picons-buffer
11811 @vindex gnus-picons-buffer
11812 The name of the buffer that @code{picons} points to. Defaults to
11813 @samp{*Icon Buffer*}.
11818 @node Various Various
11819 @section Various Various
11826 @vindex gnus-verbose
11827 This variable is an integer between zero and ten. The higher the value,
11828 the more messages will be displayed. If this variable is zero, Gnus
11829 will never flash any messages, if it is seven (which is the default),
11830 most important messages will be shown, and if it is ten, Gnus won't ever
11831 shut up, but will flash so many messages it will make your head swim.
11833 @item gnus-verbose-backends
11834 @vindex gnus-verbose-backends
11835 This variable works the same way as @code{gnus-verbose}, but it applies
11836 to the Gnus backends instead of Gnus proper.
11838 @item nnheader-max-head-length
11839 @vindex nnheader-max-head-length
11840 When the backends read straight heads of articles, they all try to read
11841 as little as possible. This variable (default @code{4096}) specifies
11842 the absolute max length the backends will try to read before giving up
11843 on finding a separator line between the head and the body. If this
11844 variable is @code{nil}, there is no upper read bound. If it is
11845 @code{t}, the backends won't try to read the articles piece by piece,
11846 but read the entire articles. This makes sense with some versions of
11849 @item nnheader-file-name-translation-alist
11850 @vindex nnheader-file-name-translation-alist
11852 @cindex illegal characters in file names
11853 @cindex characters in file names
11854 This is an alist that says how to translate characters in file names.
11855 For instance, if @samp{:} is illegal as a file character in file names
11856 on your system (you OS/2 user you), you could say something like:
11859 (setq nnheader-file-name-translation-alist
11863 In fact, this is the default value for this variable on OS/2 and MS
11864 Windows (phooey) systems.
11866 @item gnus-hidden-properties
11867 @vindex gnus-hidden-properties
11868 This is a list of properties to use to hide ``invisible'' text. It is
11869 @code{(invisible t intangible t)} by default on most systems, which
11870 makes invisible text invisible and intangible.
11872 @item gnus-parse-header-hook
11873 @vindex gnus-parse-header-hook
11874 A hook called before parsing headers. It can be used, for instance, to
11875 gather statistics on the headers fetched, or perhaps you'd like to prune
11876 some headers. I don't see why you'd want that, though.
11884 Well, that's the manual---you can get on with your life now. Keep in
11885 touch. Say hello to your cats from me.
11887 My @strong{ghod}---I just can't stand goodbyes. Sniffle.
11889 Ol' Charles Reznikoff said it pretty well, so I leave the floor to him:
11894 Not because of victories @*
11897 but for the common sunshine,@*
11899 the largess of the spring.
11902 but for the day's work done@*
11903 as well as I was able;@*
11904 not for a seat upon the dais@*
11905 but at the common table.@*
11910 @chapter Appendices
11913 * History:: How Gnus got where it is today.
11914 * Terminology:: We use really difficult, like, words here.
11915 * Customization:: Tailoring Gnus to your needs.
11916 * Troubleshooting:: What you might try if things do not work.
11917 * A Programmers Guide to Gnus:: Rilly, rilly technical stuff.
11918 * Emacs for Heathens:: A short introduction to Emacsian terms.
11919 * Frequently Asked Questions:: A question-and-answer session.
11927 @sc{gnus} was written by Masanobu @sc{Umeda}. When autumn crept up in
11928 '94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
11930 If you want to investigate the person responsible for this outrage, you
11931 can point your (feh!) web browser to
11932 @file{http://www.ifi.uio.no/~larsi/}. This is also the primary
11933 distribution point for the new and spiffy versions of Gnus, and is known
11934 as The Site That Destroys Newsrcs And Drives People Mad.
11936 During the first extended alpha period of development, the new Gnus was
11937 called ``(ding) Gnus''. @dfn{(ding)}, is, of course, short for
11938 @dfn{ding is not Gnus}, which is a total and utter lie, but who cares?
11939 (Besides, the ``Gnus'' in this abbreviation should probably be
11940 pronounced ``news'' as @sc{Umeda} intended, which makes it a more
11941 appropriate name, don't you think?)
11943 In any case, after spending all that energy on coming up with a new and
11944 spunky name, we decided that the name was @emph{too} spunky, so we
11945 renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs.
11946 ``@sc{gnus}''. New vs. old.
11948 The first ``proper'' release of Gnus 5 was done in November 1995 when it
11949 was included in the Emacs 19.30 distribution.
11951 Incidentally, the next Gnus generation will be called ``September
11952 Gnus'', and won't be released until April 1996. Confused? You will be.
11955 * Why?:: What's the point of Gnus?
11956 * Compatibility:: Just how compatible is Gnus with @sc{gnus}?
11957 * Conformity:: Gnus tries to conform to all standards.
11958 * Emacsen:: Gnus can be run on a few modern Emacsen.
11959 * Contributors:: Oodles of people.
11960 * New Features:: Pointers to some of the new stuff in Gnus.
11961 * Newest Features:: Features so new that they haven't been written yet.
11962 * Censorship:: This manual has been censored.
11969 What's the point of Gnus?
11971 I want to provide a ``rad'', ``happening'', ``way cool'' and ``hep''
11972 newsreader, that lets you do anything you can think of. That was my
11973 original motivation, but while working on Gnus, it has become clear to
11974 me that this generation of newsreaders really belong in the stone age.
11975 Newsreaders haven't developed much since the infancy of the net. If the
11976 volume continues to rise with the current rate of increase, all current
11977 newsreaders will be pretty much useless. How do you deal with
11978 newsgroups that have thousands of new articles each day? How do you
11979 keep track of millions of people who post?
11981 Gnus offers no real solutions to these questions, but I would very much
11982 like to see Gnus being used as a testing ground for new methods of
11983 reading and fetching news. Expanding on @sc{Umeda}-san's wise decision
11984 to separate the newsreader from the backends, Gnus now offers a simple
11985 interface for anybody who wants to write new backends for fetching mail
11986 and news from different sources. I have added hooks for customizations
11987 everywhere I could imagine useful. By doing so, I'm inviting every one
11988 of you to explore and invent.
11990 May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
11993 @node Compatibility
11994 @subsection Compatibility
11996 @cindex compatibility
11997 Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
11998 bindings have been kept. More key bindings have been added, of course,
11999 but only in one or two obscure cases have old bindings been changed.
12004 @center In a cloud bones of steel.
12008 All commands have kept their names. Some internal functions have changed
12011 The @code{gnus-uu} package has changed drastically. @pxref{Decoding
12014 One major compatibility question is the presence of several summary
12015 buffers. All variables that are relevant while reading a group are
12016 buffer-local to the summary buffer they belong in. Although many
12017 important variables have their values copied into their global
12018 counterparts whenever a command is executed in the summary buffer, this
12019 change might lead to incorrect values being used unless you are careful.
12021 All code that relies on knowledge of @sc{gnus} internals will probably
12022 fail. To take two examples: Sorting @code{gnus-newsrc-alist} (or
12023 changing it in any way, as a matter of fact) is strictly verboten. Gnus
12024 maintains a hash table that points to the entries in this alist (which
12025 speeds up many functions), and changing the alist directly will lead to
12029 @cindex highlighting
12030 Old hilit19 code does not work at all. In fact, you should probably
12031 remove all hilit code from all Gnus hooks
12032 (@code{gnus-group-prepare-hook} and @code{gnus-summary-prepare-hook}).
12033 Gnus provides various integrated functions for highlighting. These are
12034 faster and more accurate. To make life easier for everybody, Gnus will
12035 by default remove all hilit calls from all hilit hooks. Uncleanliness!
12038 Packages like @code{expire-kill} will no longer work. As a matter of
12039 fact, you should probably remove all old @sc{gnus} packages (and other
12040 code) when you start using Gnus. More likely than not, Gnus already
12041 does what you have written code to make @sc{gnus} do. (Snicker.)
12043 Even though old methods of doing things are still supported, only the
12044 new methods are documented in this manual. If you detect a new method of
12045 doing something while reading this manual, that does not mean you have
12046 to stop doing it the old way.
12048 Gnus understands all @sc{gnus} startup files.
12050 @kindex M-x gnus-bug
12052 @cindex reporting bugs
12054 Overall, a casual user who hasn't written much code that depends on
12055 @sc{gnus} internals should suffer no problems. If problems occur,
12056 please let me know by issuing that magic command @kbd{M-x gnus-bug}.
12060 @subsection Conformity
12062 No rebels without a clue here, ma'am. We conform to all standards known
12063 to (wo)man. Except for those standards and/or conventions we disagree
12070 There are no known breaches of this standard.
12074 There are no known breaches of this standard, either.
12076 @item Usenet Seal of Approval
12077 @cindex Usenet Seal of Approval
12078 Gnus hasn't been formally through the Seal process, but I have read
12079 through the Seal text and I think Gnus would pass.
12081 @item Son-of-RFC 1036
12082 @cindex Son-of-RFC 1036
12083 We do have some breaches to this one.
12088 Gnus does no MIME handling, and this standard-to-be seems to think that
12089 MIME is the bees' knees, so we have major breakage here.
12092 This is considered to be a ``vanity header'', while I consider it to be
12093 consumer information. After seeing so many badly formatted articles
12094 coming from @code{tin} and @code{Netscape} I know not to use either of
12095 those for posting articles. I would not have known that if it wasn't
12096 for the @code{X-Newsreader} header.
12099 Gnus does line breaking on this header. I infer from RFC1036 that being
12100 conservative in what you output is not creating 5000-character lines, so
12101 it seems like a good idea to me. However, this standard-to-be says that
12102 whitespace in the @code{References} header is to be preserved, so... It
12103 doesn't matter one way or the other to Gnus, so if somebody tells me
12104 what The Way is, I'll change it. Or not.
12109 If you ever notice Gnus acting non-compliantly with regards to the texts
12110 mentioned above, don't hesitate to drop a note to Gnus Towers and let us
12115 @subsection Emacsen
12121 Gnus should work on :
12126 Emacs 19.30 and up.
12129 XEmacs 19.13 and up.
12132 Mule versions based on Emacs 19.30 and up.
12136 Gnus will absolutely not work on any Emacsen older than that. Not
12137 reliably, at least.
12139 There are some vague differences between Gnus on the various platforms:
12144 The mouse-face on Gnus lines under Emacs and Mule is delimited to
12145 certain parts of the lines while they cover the entire line under
12149 The same with current-article marking---XEmacs puts an underline under
12150 the entire summary line while Emacs and Mule are nicer and kinder.
12153 XEmacs features more graphics---a logo and a toolbar.
12156 Citation highlighting us better under Emacs and Mule than under XEmacs.
12159 Emacs 19.26-19.28 have tangible hidden headers, which can be a bit
12166 @subsection Contributors
12167 @cindex contributors
12169 The new Gnus version couldn't have been done without the help of all the
12170 people on the (ding) mailing list. Every day for over a year I have
12171 gotten billions of nice bug reports from them, filling me with joy,
12172 every single one of them. Smooches. The people on the list have been
12173 tried beyond endurance, what with my ``oh, that's a neat idea <type
12174 type>, yup, I'll release it right away <ship off> no wait, that doesn't
12175 work at all <type type>, yup, I'll ship that one off right away <ship
12176 off> no, wait, that absolutely does not work'' policy for releases.
12177 Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that
12178 ``worser''? ``much worser''? ``worsest''?)
12180 I would like to take this opportunity to thank the Academy for... oops,
12185 @item Masanobu @sc{Umeda}
12186 The writer of the original @sc{gnus}.
12188 @item Per Abrahamsen
12189 Custom, scoring, highlighting and @sc{soup} code (as well as numerous
12192 @item Luis Fernandes
12193 Design and graphics.
12196 @file{gnus-picon.el} and the manual section on @dfn{picons}
12200 @file{gnus-gl.el} and the GroupLens manual section (@pxref{GroupLens}).
12202 @item Sudish Joseph
12203 Innumerable bug fixes.
12206 @file{gnus-topic.el}.
12208 @item Steven L. Baur
12209 Lots and lots of bugs detections and fixes.
12211 @item Vladimir Alexiev
12212 The refcard and reference booklets.
12214 @item Felix Lee & JWZ
12215 I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
12218 @file{nnfolder.el} enhancements & rewrite.
12220 @item Peter Mutsaers
12221 Orphan article scoring code.
12226 @item Hallvard B Furuseth
12227 Various bits and pieces, especially dealing with .newsrc files.
12229 @item Brian Edmonds
12230 @file{gnus-bbdb.el}.
12232 @item Ricardo Nassif and Mark Borges
12235 @item Kevin Davidson
12236 Came up with the name @dfn{ding}, so blame him.
12240 Peter Arius, Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel
12241 Quinlan, Frank D. Cringle, Geoffrey T. Dairiki, Fabrice Popineau and
12242 Andrew Eskilsson have all contributed code and suggestions.
12246 @subsection New Features
12247 @cindex new features
12252 The look of all buffers can be changed by setting format-like variables
12253 (@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
12256 Local spool and several @sc{nntp} servers can be used at once
12257 (@pxref{Select Methods}).
12260 You can combine groups into virtual groups (@pxref{Virtual Groups}).
12263 You can read a number of different mail formats (@pxref{Getting Mail}).
12264 All the mail backends implement a convenient mail expiry scheme
12265 (@pxref{Expiring Mail}).
12268 Gnus can use various strategies for gathering threads that have lost
12269 their roots (thereby gathering loose sub-threads into one thread) or it
12270 can go back and retrieve enough headers to build a complete thread
12271 (@pxref{Customizing Threading}).
12274 Killed groups can be displayed in the group buffer, and you can read
12275 them as well (@pxref{Listing Groups}).
12278 Gnus can do partial group updates---you do not have to retrieve the
12279 entire active file just to check for new articles in a few groups
12280 (@pxref{The Active File}).
12283 Gnus implements a sliding scale of subscribedness to groups
12284 (@pxref{Group Levels}).
12287 You can score articles according to any number of criteria
12288 (@pxref{Scoring}). You can even get Gnus to find out how to score
12289 articles for you (@pxref{Adaptive Scoring}).
12292 Gnus maintains a dribble buffer that is auto-saved the normal Emacs
12293 manner, so it should be difficult to lose much data on what you have
12294 read if your machine should go down (@pxref{Auto Save}).
12297 Gnus now has its own startup file (@file{.gnus}) to avoid cluttering up
12298 the @file{.emacs} file.
12301 You can set the process mark on both groups and articles and perform
12302 operations on all the marked items (@pxref{Process/Prefix}).
12305 You can grep through a subset of groups and create a group from the
12306 results (@pxref{Kibozed Groups}).
12309 You can list subsets of groups according to, well, anything
12310 (@pxref{Listing Groups}).
12313 You can browse foreign servers and subscribe to groups from those
12314 servers (@pxref{Browse Foreign Server}).
12317 Gnus can fetch articles asynchronously on a second connection to the
12318 server (@pxref{Asynchronous Fetching}).
12321 You can cache articles locally (@pxref{Article Caching}).
12324 The uudecode functions have been expanded and generalized
12325 (@pxref{Decoding Articles}).
12328 You can still post uuencoded articles, which was a little-known feature
12329 of @sc{gnus}' past (@pxref{Uuencoding and Posting}).
12332 Fetching parents (and other articles) now actually works without
12333 glitches (@pxref{Finding the Parent}).
12336 Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
12339 Digests (and other files) can be used as the basis for groups
12340 (@pxref{Document Groups}).
12343 Articles can be highlighted and customized (@pxref{Customizing
12347 URLs and other external references can be buttonized (@pxref{Article
12351 You can do lots of strange stuff with the Gnus window & frame
12352 configuration (@pxref{Windows Configuration}).
12355 You can click on buttons instead of using the keyboard
12359 Gnus can use NoCeM files to weed out spam (@pxref{NoCeM}).
12363 This is, of course, just a @emph{short} overview of the @emph{most}
12364 important new features. No, really. There are tons more. Yes, we have
12365 feeping creaturism in full effect, but nothing too gratuitous, I would
12369 @node Newest Features
12370 @subsection Newest Features
12373 Also known as the @dfn{todo list}. Sure to be implemented before the
12376 Be afraid. Be very afraid.
12380 Native @sc{mime} support is something that should be done.
12382 A better and simpler method for specifying mail composing methods.
12384 Allow posting through mail-to-news gateways.
12386 Really do unbinhexing.
12389 And much, much, much more. There is more to come than has already been
12390 implemented. (But that's always true, isn't it?)
12392 @code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>} is where the actual
12393 up-to-the-second todo list is located, so if you're really curious, you
12394 could point your Web browser over that-a-way.
12398 @subsection Censorship
12401 This version of the Gnus manual (as well as Gnus itself) has been
12402 censored in accord with the Communications Decency Act. This law was
12403 described by its proponents as a ban on pornography---which was a
12404 deception, since it prohibits far more than that. This manual did not
12405 contain pornography, but part of it was prohibited nonetheless.
12407 For information on US government censorship of the Internet, and
12408 what you can do to bring back freedom of the press, see the web
12409 site @samp{http://www.vtw.org/}.
12413 @section Terminology
12415 @cindex terminology
12420 This is what you are supposed to use this thing for---reading news.
12421 News is generally fetched from a nearby @sc{nntp} server, and is
12422 generally publicly available to everybody. If you post news, the entire
12423 world is likely to read just what you have written, and they'll all
12424 snigger mischievously. Behind your back.
12428 Everything that's delivered to you personally is mail. Some news/mail
12429 readers (like Gnus) blur the distinction between mail and news, but
12430 there is a difference. Mail is private. News is public. Mailing is
12431 not posting, and replying is not following up.
12435 Send a mail to the person who has written what you are reading.
12439 Post an article to the current newsgroup responding to the article you
12444 Gnus gets fed articles from a number of backends, both news and mail
12445 backends. Gnus does not handle the underlying media, so to speak---this
12446 is all done by the backends.
12450 Gnus will always use one method (and backend) as the @dfn{native}, or
12451 default, way of getting news.
12455 You can also have any number of foreign groups active at the same time.
12456 These are groups that use different backends for getting news.
12460 Secondary backends are somewhere half-way between being native and being
12461 foreign, but they mostly act like they are native.
12465 A nessage that has been posted as news.
12468 @cindex mail message
12469 A message that has been mailed.
12473 A mail message or news article
12477 The top part of a message, where administrative information (etc.) is
12482 The rest of an article. Everything that is not in the head is in the
12487 A line from the head of an article.
12491 A collection of such lines, or a collection of heads. Or even a
12492 collection of @sc{nov} lines.
12496 When Gnus enters a group, it asks the backend for the headers of all
12497 unread articles in the group. Most servers support the News OverView
12498 format, which is more compact and much faster to read and parse than the
12499 normal @sc{head} format.
12503 Each group is subscribed at some @dfn{level} or other (1-9). The ones
12504 that have a lower level are ``more'' subscribed than the groups with a
12505 higher level. In fact, groups on levels 1-5 are considered
12506 @dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
12507 are @dfn{killed}. Commands for listing groups and scanning for new
12508 articles will all use the numeric prefix as @dfn{working level}.
12510 @item killed groups
12511 @cindex killed groups
12512 No information on killed groups is stored or updated, which makes killed
12513 groups much easier to handle than subscribed groups.
12515 @item zombie groups
12516 @cindex zombie groups
12517 Just like killed groups, only slightly less dead.
12520 @cindex active file
12521 The news server has to keep track of what articles it carries, and what
12522 groups exist. All this information in stored in the active file, which
12523 is rather large, as you might surmise.
12526 @cindex bogus groups
12527 A group that exists in the @file{.newsrc} file, but isn't known to the
12528 server (i. e., it isn't in the active file), is a @emph{bogus group}.
12529 This means that the group probably doesn't exist (any more).
12533 A machine than one can connect to and get news (or mail) from.
12535 @item select method
12536 @cindex select method
12537 A structure that specifies the backend, the server and the virtual
12540 @item virtual server
12541 @cindex virtual server
12542 A named select method. Since a select methods defines all there is to
12543 know about connecting to a (physical) server, taking the who things as a
12544 whole is a virtual server.
12549 @node Customization
12550 @section Customization
12551 @cindex general customization
12553 All variables are properly documented elsewhere in this manual. This
12554 section is designed to give general pointers on how to customize Gnus
12555 for some quite common situations.
12558 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
12559 * Slow Terminal Connection:: You run a remote Emacs.
12560 * Little Disk Space:: You feel that having large setup files is icky.
12561 * Slow Machine:: You feel like buying a faster machine.
12565 @node Slow/Expensive Connection
12566 @subsection Slow/Expensive @sc{nntp} Connection
12568 If you run Emacs on a machine locally, and get your news from a machine
12569 over some very thin strings, you want to cut down on the amount of data
12570 Gnus has to get from the @sc{nntp} server.
12574 @item gnus-read-active-file
12575 Set this to @code{nil}, which will inhibit Gnus from requesting the
12576 entire active file from the server. This file is often v. large. You
12577 also have to set @code{gnus-check-new-news} and
12578 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
12579 doesn't suddenly decide to fetch the active file anyway.
12581 @item gnus-nov-is-evil
12582 This one has to be @code{nil}. If not, grabbing article headers from
12583 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
12584 support @sc{xover}; Gnus will detect this by itself.
12588 @node Slow Terminal Connection
12589 @subsection Slow Terminal Connection
12591 Let's say you use your home computer for dialing up the system that
12592 runs Emacs and Gnus. If your modem is slow, you want to reduce the
12593 amount of data that is sent over the wires as much as possible.
12597 @item gnus-auto-center-summary
12598 Set this to @code{nil} to inhibit Gnus from re-centering the summary
12599 buffer all the time. If it is @code{vertical}, do only vertical
12600 re-centering. If it is neither @code{nil} nor @code{vertical}, do both
12601 horizontal and vertical recentering.
12603 @item gnus-visible-headers
12604 Cut down on the headers that are included in the articles to the
12605 minimum. You can, in fact, make do without them altogether---most of the
12606 useful data is in the summary buffer, anyway. Set this variable to
12607 @samp{^NEVVVVER} or @samp{From:}, or whatever you feel you need.
12609 @item gnus-article-display-hook
12610 Set this hook to all the available hiding commands:
12612 (setq gnus-article-display-hook
12613 '(gnus-article-hide-headers gnus-article-hide-signature
12614 gnus-article-hide-citation))
12617 @item gnus-use-full-window
12618 By setting this to @code{nil}, you can make all the windows smaller.
12619 While this doesn't really cut down much generally, it means that you
12620 have to see smaller portions of articles before deciding that you didn't
12621 want to read them anyway.
12623 @item gnus-thread-hide-subtree
12624 If this is non-@code{nil}, all threads in the summary buffer will be
12627 @item gnus-updated-mode-lines
12628 If this is @code{nil}, Gnus will not put information in the buffer mode
12629 lines, which might save some time.
12633 @node Little Disk Space
12634 @subsection Little Disk Space
12637 The startup files can get rather large, so you may want to cut their
12638 sizes a bit if you are running out of space.
12642 @item gnus-save-newsrc-file
12643 If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
12644 only save @file{.newsrc.eld}. This means that you will not be able to
12645 use any other newsreaders than Gnus. This variable is @code{t} by
12648 @item gnus-save-killed-list
12649 If this is @code{nil}, Gnus will not save the list of dead groups. You
12650 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
12651 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
12652 variable to @code{nil}. This variable is @code{t} by default.
12658 @subsection Slow Machine
12659 @cindex slow machine
12661 If you have a slow machine, or are just really impatient, there are a
12662 few things you can do to make Gnus run faster.
12664 Set@code{gnus-check-new-newsgroups} and
12665 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
12667 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
12668 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
12669 summary buffer faster.
12671 Set @code{gnus-article-display-hook} to @code{nil} to make article
12672 processing a bit faster.
12675 @node Troubleshooting
12676 @section Troubleshooting
12677 @cindex troubleshooting
12679 Gnus works @emph{so} well straight out of the box---I can't imagine any
12687 Make sure your computer is switched on.
12690 Make sure that you really load the current Gnus version. If you have
12691 been running @sc{gnus}, you need to exit Emacs and start it up again before
12695 Try doing an @kbd{M-x gnus-version}. If you get something that looks
12696 like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
12697 on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
12698 flee}, you have some old @file{.el} files lying around. Delete these.
12701 Read the help group (@kbd{G h} in the group buffer) for a FAQ and a
12705 If all else fails, report the problem as a bug.
12708 @cindex reporting bugs
12710 @kindex M-x gnus-bug
12712 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
12713 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
12714 me the backtrace. I will fix bugs, but I can only fix them if you send
12715 me a precise description as to how to reproduce the bug.
12717 You really can never be too detailed in a bug report. Always use the
12718 @kbd{M-x gnus-bug} command when you make bug reports, even if it creates
12719 a 10Kb mail each time you use it, and even if you have sent me your
12720 environment 500 times before. I don't care. I want the full info each
12723 It is also important to remember that I have no memory whatsoever. If
12724 you send a bug report, and I send you a reply, and then you send back
12725 just ``No, it's not! Moron!'', I will have no idea what you are
12726 insulting me about. Always over-explain everything. It's much easier
12727 for all of us---if I don't have all the information I need, I will just
12728 mail you and ask for more info, and everything takes more time.
12730 If you just need help, you are better off asking on
12731 @samp{gnu.emacs.gnus}. I'm not very helpful.
12733 @cindex gnu.emacs.gnus
12734 @cindex ding mailing list
12735 You can also ask on the ding mailing list---@samp{ding@@ifi.uio.no}.
12736 Write to @samp{ding-request@@ifi.uio.no} to subscribe.
12739 @node A Programmers Guide to Gnus
12740 @section A Programmer's Guide to Gnus
12742 It is my hope that other people will figure out smart stuff that Gnus
12743 can do, and that other people will write those smart things as well. To
12744 facilitate that I thought it would be a good idea to describe the inner
12745 workings of Gnus. And some of the not-so-inner workings, while I'm at
12748 You can never expect the internals of a program not to change, but I
12749 will be defining (in some details) the interface between Gnus and its
12750 backends (this is written in stone), the format of the score files
12751 (ditto), data structures (some are less likely to change than others)
12752 and general method of operations.
12755 * Backend Interface:: How Gnus communicates with the servers.
12756 * Score File Syntax:: A BNF definition of the score file standard.
12757 * Headers:: How Gnus stores headers internally.
12758 * Ranges:: A handy format for storing mucho numbers.
12759 * Group Info:: The group info format.
12760 * Various File Formats:: Formats of files that Gnus use.
12764 @node Backend Interface
12765 @subsection Backend Interface
12767 Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
12768 groups. It only knows how to talk to @dfn{virtual servers}. A virtual
12769 server is a @dfn{backend} and some @dfn{backend variables}. As examples
12770 of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
12771 examples of the latter we have @code{nntp-port-number} and
12772 @code{nnmbox-directory}.
12774 When Gnus asks for information from a backend---say @code{nntp}---on
12775 something, it will normally include a virtual server name in the
12776 function parameters. (If not, the backend should use the ``current''
12777 virtual server.) For instance, @code{nntp-request-list} takes a virtual
12778 server as its only (optional) parameter. If this virtual server hasn't
12779 been opened, the function should fail.
12781 Note that a virtual server name has no relation to some physical server
12782 name. Take this example:
12786 (nntp-address "ifi.uio.no")
12787 (nntp-port-number 4324))
12790 Here the virtual server name is @samp{odd-one} while the name of
12791 the physical server is @samp{ifi.uio.no}.
12793 The backends should be able to switch between several virtual servers.
12794 The standard backends implement this by keeping an alist of virtual
12795 server environments that it pulls down/pushes up when needed.
12797 There are two groups of interface functions: @dfn{required functions},
12798 which must be present, and @dfn{optional functions}, which Gnus will
12799 always check whether are present before attempting to call.
12801 All these functions are expected to return data in the buffer
12802 @code{nntp-server-buffer} (@samp{ *nntpd*}), which is somewhat
12803 unfortunately named, but we'll have to live with it. When I talk about
12804 ``resulting data'', I always refer to the data in that buffer. When I
12805 talk about ``return value'', I talk about the function value returned by
12808 Some backends could be said to be @dfn{server-forming} backends, and
12809 some might be said to not be. The latter are backends that generally
12810 only operate on one group at a time, and have no concept of ``server''
12811 -- they have a group, and they deliver info on that group and nothing
12814 In the examples and definitions I will refer to the imaginary backend
12817 @cindex @code{nnchoke}
12820 * Required Backend Functions:: Functions that must be implemented.
12821 * Optional Backend Functions:: Functions that need not be implemented.
12822 * Writing New Backends:: Extending old backends.
12826 @node Required Backend Functions
12827 @subsubsection Required Backend Functions
12831 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
12833 @var{articles} is either a range of article numbers or a list of
12834 @code{Message-ID}s. Current backends do not fully support either---only
12835 sequences (lists) of article numbers, and most backends do not support
12836 retrieval of @code{Message-ID}s. But they should try for both.
12838 The result data should either be HEADs or NOV lines, and the result
12839 value should either be @code{headers} or @code{nov} to reflect this.
12840 This might later be expanded to @code{various}, which will be a mixture
12841 of HEADs and NOV lines, but this is currently not supported by Gnus.
12843 If @var{fetch-old} is non-@code{nil} it says to try to fetch "extra
12844 headers, in some meaning of the word. This is generally done by
12845 fetching (at most) @var{fetch-old} extra headers less than the smallest
12846 article number in @code{articles}, and fill in the gaps as well. The
12847 presence of this parameter can be ignored if the backend finds it
12848 cumbersome to follow the request. If this is non-@code{nil} and not a
12849 number, do maximum fetches.
12851 Here's an example HEAD:
12854 221 1056 Article retrieved.
12855 Path: ifi.uio.no!sturles
12856 From: sturles@@ifi.uio.no (Sturle Sunde)
12857 Newsgroups: ifi.discussion
12858 Subject: Re: Something very droll
12859 Date: 27 Oct 1994 14:02:57 +0100
12860 Organization: Dept. of Informatics, University of Oslo, Norway
12862 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
12863 References: <38jdmq$4qu@@visbur.ifi.uio.no>
12864 NNTP-Posting-Host: holmenkollen.ifi.uio.no
12868 So a @code{headers} return value would imply that there's a number of
12869 these in the data buffer.
12871 Here's a BNF definition of such a buffer:
12875 head = error / valid-head
12876 error-message = [ "4" / "5" ] 2number " " <error message> eol
12877 valid-head = valid-message *header "." eol
12878 valid-message = "221 " <number> " Article retrieved." eol
12879 header = <text> eol
12882 If the return value is @code{nov}, the data buffer should contain
12883 @dfn{network overview database} lines. These are basically fields
12887 nov-buffer = *nov-line
12888 nov-line = 8*9 [ field <TAB> ] eol
12889 field = <text except TAB>
12892 For a closer explanation what should be in those fields,
12896 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
12898 @var{server} is here the virtual server name. @var{definitions} is a
12899 list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
12901 If the server can't be opened, no error should be signaled. The backend
12902 may then choose to refuse further attempts at connecting to this
12903 server. In fact, it should do so.
12905 If the server is opened already, this function should return a
12906 non-@code{nil} value. There should be no data returned.
12909 @item (nnchoke-close-server &optional SERVER)
12911 Close connection to @var{server} and free all resources connected
12912 to it. Return @code{nil} if the server couldn't be closed for some
12915 There should be no data returned.
12918 @item (nnchoke-request-close)
12920 Close connection to all servers and free all resources that the backend
12921 have reserved. All buffers that have been created by that backend
12922 should be killed. (Not the @code{nntp-server-buffer}, though.) This
12923 function is generally only called when Gnus is shutting down.
12925 There should be no data returned.
12928 @item (nnchoke-server-opened &optional SERVER)
12930 If @var{server} is the current virtual server, and the connection to the
12931 physical server is alive, then this function should return a
12932 non-@code{nil} vlue. This function should under no circumstances
12933 attempt to reconnect to a server that is has lost connection to.
12935 There should be no data returned.
12938 @item (nnchoke-status-message &optional SERVER)
12940 This function should return the last error message from @var{server}.
12942 There should be no data returned.
12945 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
12947 The result data from this function should be the article specified by
12948 @var{article}. This might either be a @code{Message-ID} or a number.
12949 It is optional whether to implement retrieval by @code{Message-ID}, but
12950 it would be nice if that were possible.
12952 If @var{to-buffer} is non-@code{nil}, the result data should be returned
12953 in this buffer instead of the normal data buffer. This is to make it
12954 possible to avoid copying large amounts of data from one buffer to
12955 another, and Gnus mainly request articles to be inserted directly into
12956 its article buffer.
12958 If it is at all possible, this function should return a cons cell where
12959 the car is the group name the article was fetched from, and the cdr is
12960 the article number. This will enable Gnus to find out what the real
12961 group and article numbers are when fetching articles by
12962 @code{Message-ID}. If this isn't possible, @code{t} should be returned
12963 on successful article retrievement.
12966 @item (nnchoke-open-group GROUP &optional SERVER)
12968 Make @var{group} the current group.
12970 There should be no data returned by this function.
12973 @item (nnchoke-request-group GROUP &optional SERVER)
12975 Get data on @var{group}. This function also has the side effect of
12976 making @var{group} the current group.
12978 Here's an example of some result data and a definition of the same:
12981 211 56 1000 1059 ifi.discussion
12984 The first number is the status, which should be @code{211}. Next is the
12985 total number of articles in the group, the lowest article number, the
12986 highest article number, and finally the group name. Note that the total
12987 number of articles may be less than one might think while just
12988 considering the highest and lowest article numbers, but some articles
12989 may have been canceled. Gnus just discards the total-number, so
12990 whether one should take the bother to generate it properly (if that is a
12991 problem) is left as an exercise to the reader.
12994 group-status = [ error / info ] eol
12995 error = [ "4" / "5" ] 2<number> " " <Error message>
12996 info = "211 " 3* [ <number> " " ] <string>
13000 @item (nnchoke-close-group GROUP &optional SERVER)
13002 Close @var{group} and free any resources connected to it. This will be
13003 a no-op on most backends.
13005 There should be no data returned.
13008 @item (nnchoke-request-list &optional SERVER)
13010 Return a list of all groups available on @var{server}. And that means
13013 Here's an example from a server that only carries two groups:
13016 ifi.test 0000002200 0000002000 y
13017 ifi.discussion 3324 3300 n
13020 On each line we have a group name, then the highest article number in
13021 that group, the lowest article number, and finally a flag.
13024 active-file = *active-line
13025 active-line = name " " <number> " " <number> " " flags eol
13027 flags = "n" / "y" / "m" / "x" / "j" / "=" name
13030 The flag says whether the group is read-only (@samp{n}), is moderated
13031 (@samp{m}), is dead (@samp{x}), is aliased to some other group
13032 (@samp{=other-group} or none of the above (@samp{y}).
13035 @item (nnchoke-request-post &optional SERVER)
13037 This function should post the current buffer. It might return whether
13038 the posting was successful or not, but that's not required. If, for
13039 instance, the posting is done asynchronously, it has generally not been
13040 completed by the time this function concludes. In that case, this
13041 function should set up some kind of sentinel to beep the user loud and
13042 clear if the posting could not be completed.
13044 There should be no result data from this function.
13049 @node Optional Backend Functions
13050 @subsubsection Optional Backend Functions
13054 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
13056 @var{groups} is a list of groups, and this function should request data
13057 on all those groups. How it does it is of no concern to Gnus, but it
13058 should attempt to do this in a speedy fashion.
13060 The return value of this function can be either @code{active} or
13061 @code{group}, which says what the format of the result data is. The
13062 former is in the same format as the data from
13063 @code{nnchoke-request-list}, while the latter is a buffer full of lines
13064 in the same format as @code{nnchoke-request-group} gives.
13067 group-buffer = *active-line / *group-status
13071 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
13073 A Gnus group info (@pxref{Group Info}) is handed to the backend for
13074 alterations. This comes in handy if the backend really carries all the
13075 information (as is the case with virtual an imap groups). This function
13076 may alter the info in any manner it sees fit, and should return the
13077 (altered) group info. This function may alter the group info
13078 destructively, so no copying is needed before boogeying.
13080 There should be no result data from this function.
13083 @item (nnchoke-request-type GROUP &optional ARTICLE)
13085 When the user issues commands for ``sending news'' (@kbd{F} in the
13086 summary buffer, for instance), Gnus has to know whether the article the
13087 user is following up is news or mail. This function should return
13088 @code{news} if @var{article} in @var{group} is news, @code{mail} if it
13089 is mail and @code{unknown} if the type can't be decided. (The
13090 @var{article} parameter is necessary in @code{nnvirtual} groups which
13091 might very well combine mail groups and news groups.)
13093 There should be no result data from this function.
13096 @item (nnchoke-request-update-mark GROUP ARTICLE MARK)
13098 If the user tries to set a mark that the backend doesn't like, this
13099 function may change the mark. Gnus will use whatever this function
13100 returns as the mark for @var{article} instead of the original
13101 @var{mark}. If the backend doesn't care, it must return the original
13102 @var{mark}, and not @code{nil} or any other type of garbage.
13104 The only use for this that I can see is what @code{nnvirtual} does with
13105 it---if a component group is auto-expirable, marking an article as read
13106 in the virtual group should result in the article being marked as
13109 There should be no result data from this function.
13112 @item (nnchoke-request-scan &optional GROUP SERVER)
13114 This function may be called at any time (by Gnus or anything else) to
13115 request that the backend check for incoming articles, in one way or
13116 another. A mail backend will typically read the spool file or query the
13117 POP server when this function is invoked. The @var{group} doesn't have
13118 to be heeded---if the backend decides that it is too much work just
13119 scanning for a single group, it may do a total scan of all groups. It
13120 would be nice, however, to keep things local if that's practical.
13122 There should be no result data from this function.
13125 @item (nnchoke-request-asynchronous GROUP &optional SERVER ARTICLES)
13127 This is a request to fetch articles asynchronously later.
13128 @var{articles} is an alist of @var{(article-number line-number)}. One
13129 would generally expect that if one later fetches article number 4, for
13130 instance, some sort of asynchronous fetching of the articles after 4
13131 (which might be 5, 6, 7 or 11, 3, 909 depending on the order in that
13132 alist) would be fetched asynchronously, but that is left up to the
13133 backend. Gnus doesn't care.
13135 There should be no result data from this function.
13138 @item (nnchoke-request-group-description GROUP &optional SERVER)
13140 The result data from this function should be a description of
13144 description-line = name <TAB> description eol
13146 description = <text>
13149 @item (nnchoke-request-list-newsgroups &optional SERVER)
13151 The result data from this function should be the description of all
13152 groups available on the server.
13155 description-buffer = *description-line
13159 @item (nnchoke-request-newgroups DATE &optional SERVER)
13161 The result data from this function should be all groups that were
13162 created after @samp{date}, which is in normal human-readable date
13163 format. The data should be in the active buffer format.
13166 @item (nnchoke-request-create-group GROUP &optional SERVER)
13168 This function should create an empty group with name @var{group}.
13170 There should be no return data.
13173 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
13175 This function should run the expiry process on all articles in the
13176 @var{articles} range (which is currently a simple list of article
13177 numbers.) It is left up to the backend to decide how old articles
13178 should be before they are removed by this function. If @var{force} is
13179 non-@code{nil}, all @var{articles} should be deleted, no matter how new
13182 This function should return a list of articles that it did not/was not
13185 There should be no result data returned.
13188 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
13191 This function should move @var{article} (which is a number) from
13192 @var{group} by calling @var{accept-form}.
13194 This function should ready the article in question for moving by
13195 removing any header lines it has added to the article, and generally
13196 should ``tidy up'' the article. Then it should @code{eval}
13197 @var{accept-form} in the buffer where the ``tidy'' article is. This
13198 will do the actual copying. If this @code{eval} returns a
13199 non-@code{nil} value, the article should be removed.
13201 If @var{last} is @code{nil}, that means that there is a high likelihood
13202 that there will be more requests issued shortly, so that allows some
13205 The function should return a cons where the car is the group name and
13206 the cdr is the article number that the article was entered as.
13208 There should be no data returned.
13211 @item (nnchoke-request-accept-article GROUP &optional SERVER LAST)
13213 This function takes the current buffer and inserts it into @var{group}.
13214 If @var{last} in @code{nil}, that means that there will be more calls to
13215 this function in short order.
13217 The function should return a cons where the car is the group name and
13218 the cdr is the article number that the article was entered as.
13220 There should be no data returned.
13223 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
13225 This function should remove @var{article} (which is a number) from
13226 @var{group} and insert @var{buffer} there instead.
13228 There should be no data returned.
13231 @item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
13233 This function should delete @var{group}. If @var{force}, it should
13234 really delete all the articles in the group, and then delete the group
13235 itself. (If there is such a thing as ``the group itself''.)
13237 There should be no data returned.
13240 @item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
13242 This function should rename @var{group} into @var{new-name}. All
13243 articles that are in @var{group} should move to @var{new-name}.
13245 There should be no data returned.
13250 @node Writing New Backends
13251 @subsubsection Writing New Backends
13253 The various backends share many similarities. @code{nnml} is just like
13254 @code{nnspool}, but it allows you to edit the articles on the server.
13255 @code{nnmh} is just like @code{nnml}, but it doesn't use an active file,
13256 and it doesn't maintain overview databases. @code{nndir} is just like
13257 @code{nnml}, but it has no concept of ``groups'', and it doesn't allow
13260 It would make sense if it were possible to ``inherit'' functions from
13261 backends when writing new backends. And, indeed, you can do that if you
13262 want to. (You don't have to if you don't want to, of course.)
13264 All the backends declare their public variables and functions by using a
13265 package called @code{nnoo}.
13267 To inherit functions from other backends (and allow other backends to
13268 inherit functions from the current backend), you should use the
13275 This macro declares the first parameter to be a child of the subsequent
13276 parameters. For instance:
13279 (nnoo-declare nndir
13283 @code{nndir} has here declared that it intends to inherit functions from
13284 both @code{nnml} and @code{nnmh}.
13287 This macro is equivalent to @code{defvar}, but registers the variable as
13288 a public server variable. Most state-oriented variables should be
13289 declared with @code{defvoo} instead of @code{defvar}.
13291 In addition to the normal @code{defvar} parameters, it takes a list of
13292 variables in the parent backends to map the variable to when executing
13293 a function in those backends.
13296 (defvoo nndir-directory nil
13297 "Where nndir will look for groups."
13298 nnml-current-directory nnmh-current-directory)
13301 This means that @code{nnml-current-directory} will be set to
13302 @code{nndir-directory} when an @code{nnml} function is called on behalf
13303 of @code{nndir}. (The same with @code{nnmh}.)
13305 @item nnoo-define-basics
13306 This macro defines some common functions that almost all backends should
13310 (nnoo-define-basics nndir)
13314 This macro is just like @code{defun} and takes the same parameters. In
13315 addition to doing the normal @code{defun} things, it registers the
13316 function as being public so that other backends can inherit it.
13318 @item nnoo-map-functions
13319 This macro allows mapping of functions from the current backend to
13320 functions from the parent backends.
13323 (nnoo-map-functions nndir
13324 (nnml-retrieve-headers 0 nndir-current-group 0 0)
13325 (nnmh-request-article 0 nndir-current-group 0 0))
13328 This means that when @code{nndir-retrieve-headers} is called, the first,
13329 third, and fourth parameters will be passed on to
13330 @code{nnml-retrieve-headers}, while the second parameter is set to the
13331 value of @code{nndir-current-group}.
13334 This macro allows importing functions from backends. It should be the
13335 last thing in the source file, since it will only define functions that
13336 haven't already been defined.
13342 nnmh-request-newgroups)
13346 This means that calls to @code{nndir-request-list} should just be passed
13347 on to @code{nnmh-request-list}, while all public functions from
13348 @code{nnml} that haven't been defined in @code{nndir} yet should be
13353 Below is a slightly shortened version of the @code{nndir} backend.
13356 ;;; nndir.el --- single directory newsgroup access for Gnus
13357 ;; Copyright (C) 1995,96 Free Software Foundation, Inc.
13361 (require 'nnheader)
13365 (eval-when-compile (require 'cl))
13367 (nnoo-declare nndir
13370 (defvoo nndir-directory nil
13371 "Where nndir will look for groups."
13372 nnml-current-directory nnmh-current-directory)
13374 (defvoo nndir-nov-is-evil nil
13375 "*Non-nil means that nndir will never retrieve NOV headers."
13380 (defvoo nndir-current-group "" nil nnml-current-group nnmh-current-group)
13381 (defvoo nndir-top-directory nil nil nnml-directory nnmh-directory)
13382 (defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail)
13384 (defvoo nndir-status-string "" nil nnmh-status-string)
13385 (defconst nndir-version "nndir 1.0")
13389 ;;; Interface functions.
13391 (nnoo-define-basics nndir)
13393 (deffoo nndir-open-server (server &optional defs)
13394 (setq nndir-directory
13395 (or (cadr (assq 'nndir-directory defs))
13397 (unless (assq 'nndir-directory defs)
13398 (push `(nndir-directory ,server) defs))
13399 (push `(nndir-current-group
13400 ,(file-name-nondirectory (directory-file-name nndir-directory)))
13402 (push `(nndir-top-directory
13403 ,(file-name-directory (directory-file-name nndir-directory)))
13405 (nnoo-change-server 'nndir server defs))
13407 (nnoo-map-functions nndir
13408 (nnml-retrieve-headers 0 nndir-current-group 0 0)
13409 (nnmh-request-article 0 nndir-current-group 0 0)
13410 (nnmh-request-group nndir-current-group 0 0)
13411 (nnmh-close-group nndir-current-group 0))
13415 nnmh-status-message
13417 nnmh-request-newgroups))
13424 @node Score File Syntax
13425 @subsection Score File Syntax
13427 Score files are meant to be easily parsable, but yet extremely
13428 mallable. It was decided that something that had the same read syntax
13429 as an Emacs Lisp list would fit that spec.
13431 Here's a typical score file:
13435 ("win95" -10000 nil s)
13442 BNF definition of a score file:
13445 score-file = "" / "(" *element ")"
13446 element = rule / atom
13447 rule = string-rule / number-rule / date-rule
13448 string-rule = "(" quote string-header quote space *string-match ")"
13449 number-rule = "(" quote number-header quote space *number-match ")"
13450 date-rule = "(" quote date-header quote space *date-match ")"
13452 string-header = "subject" / "from" / "references" / "message-id" /
13453 "xref" / "body" / "head" / "all" / "followup"
13454 number-header = "lines" / "chars"
13455 date-header = "date"
13456 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
13457 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
13458 score = "nil" / <integer>
13459 date = "nil" / <natural number>
13460 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
13461 "r" / "regex" / "R" / "Regex" /
13462 "e" / "exact" / "E" / "Exact" /
13463 "f" / "fuzzy" / "F" / "Fuzzy"
13464 number-match = "(" <integer> [ "" / [ space score [ "" /
13465 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
13466 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
13467 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
13468 space date [ "" / [ space date-match-t ] ] ] ] ")"
13469 date-match-t = "nil" / "at" / "before" / "after"
13470 atom = "(" [ required-atom / optional-atom ] ")"
13471 required-atom = mark / expunge / mark-and-expunge / files /
13472 exclude-files / read-only / touched
13473 optional-atom = adapt / local / eval
13474 mark = "mark" space nil-or-number
13475 nil-or-number = "nil" / <integer>
13476 expunge = "expunge" space nil-or-number
13477 mark-and-expunge = "mark-and-expunge" space nil-or-number
13478 files = "files" *[ space <string> ]
13479 exclude-files = "exclude-files" *[ space <string> ]
13480 read-only = "read-only" [ space "nil" / space "t" ]
13481 adapt = "adapt" [ space "nil" / space "t" / space adapt-rule ]
13482 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
13483 local = "local" *[ space "(" <string> space <form> ")" ]
13484 eval = "eval" space <form>
13485 space = *[ " " / <TAB> / <NEWLINE> ]
13488 Any unrecognized elements in a score file should be ignored, but not
13491 As you can see, white space is needed, but the type and amount of white
13492 space is irrelevant. This means that formatting of the score file is
13493 left up to the programmer---if it's simpler to just spew it all out on
13494 one looong line, then that's ok.
13496 The meaning of the various atoms are explained elsewhere in this
13501 @subsection Headers
13503 Gnus uses internally a format for storing article headers that
13504 corresponds to the @sc{nov} format in a mysterious fashion. One could
13505 almost suspect that the author looked at the @sc{nov} specification and
13506 just shamelessly @emph{stole} the entire thing, and one would be right.
13508 @dfn{Header} is a severely overloaded term. ``Header'' is used in
13509 RFC1036 to talk about lines in the head of an article (eg.,
13510 @code{From}). It is used by many people as a synonym for
13511 ``head''---``the header and the body''. (That should be avoided, in my
13512 opinion.) And Gnus uses a format internally that it calls ``header'',
13513 which is what I'm talking about here. This is a 9-element vector,
13514 basically, with each header (ouch) having one slot.
13516 These slots are, in order: @code{number}, @code{subject}, @code{from},
13517 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
13518 @code{xref}. There are macros for accessing and setting these slots --
13519 they all have predictable names beginning with @code{mail-header-} and
13520 @code{mail-header-set-}, respectively.
13522 The @code{xref} slot is really a @code{misc} slot. Any extra info will
13529 @sc{gnus} introduced a concept that I found so useful that I've started
13530 using it a lot and have elaborated on it greatly.
13532 The question is simple: If you have a large amount of objects that are
13533 identified by numbers (say, articles, to take a @emph{wild} example)
13534 that you want to callify as being ``included'', a normal sequence isn't
13535 very useful. (A 200,000 length sequence is a bit long-winded.)
13537 The solution is as simple as the question: You just collapse the
13541 (1 2 3 4 5 6 10 11 12)
13544 is transformed into
13547 ((1 . 6) (10 . 12))
13550 To avoid having those nasty @samp{(13 . 13)} elements to denote a
13551 lonesome object, a @samp{13} is a valid element:
13554 ((1 . 6) 7 (10 . 12))
13557 This means that comparing two ranges to find out whether they are equal
13558 is slightly tricky:
13561 ((1 . 5) 7 8 (10 . 12))
13567 ((1 . 5) (7 . 8) (10 . 12))
13570 are equal. In fact, any non-descending list is a range:
13576 is a perfectly valid range, although a pretty long-winded one. This is
13583 and is equal to the previous range.
13585 Here's a BNF definition of ranges. Of course, one must remember the
13586 semantic requirement that the numbers are non-descending. (Any number
13587 of repetition of the same number is allowed, but apt to disappear in
13591 range = simple-range / normal-range
13592 simple-range = "(" number " . " number ")"
13593 normal-range = "(" start-contents ")"
13594 contents = "" / simple-range *[ " " contents ] /
13595 number *[ " " contents ]
13598 Gnus currently uses ranges to keep track of read articles and article
13599 marks. I plan on implementing a number of range operators in C if The
13600 Powers That Be are willing to let me. (I haven't asked yet, because I
13601 need to do some more thinking on what operators I need to make life
13602 totally range-based without ever having to convert back to normal
13607 @subsection Group Info
13609 Gnus stores all permanent info on groups in a @dfn{group info} list.
13610 This list is from three to six elements (or more) long and exhaustively
13611 describes the group.
13613 Here are two example group infos; one is a very simple group while the
13614 second is a more complex one:
13617 ("no.group" 5 (1 . 54324))
13619 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
13620 ((tick (15 . 19)) (replied 3 6 (19 . 3)))
13622 (auto-expire (to-address "ding@@ifi.uio.no")))
13625 The first element is the group name as Gnus knows the group; the second
13626 is the group level; the third is the read articles in range format; the
13627 fourth is a list of article marks lists; the fifth is the select method;
13628 and the sixth contains the group parameters.
13630 Here's a BNF definition of the group info format:
13633 info = "(" group space level space read
13634 [ "" / [ space marks-list [ "" / [ space method [ "" /
13635 space parameters ] ] ] ] ] ")"
13636 group = quote <string> quote
13637 level = <integer in the range of 1 to inf>
13639 marks-lists = nil / "(" *marks ")"
13640 marks = "(" <string> range ")"
13641 method = "(" <string> *elisp-forms ")"
13642 parameters = "(" *elisp-forms ")"
13645 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
13646 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
13650 @node Various File Formats
13651 @subsection Various File Formats
13654 * Active File Format:: Information on articles and groups available.
13655 * Newsgroups File Format:: Group descriptions.
13659 @node Active File Format
13660 @subsubsection Active File Format
13662 The active file lists all groups that are available on the server in
13663 question. It also lists the highest and lowest current article numbers
13666 Here's an excerpt from a typical active file:
13669 soc.motss 296030 293865 y
13670 alt.binaries.pictures.fractals 3922 3913 n
13671 comp.sources.unix 1605 1593 m
13672 comp.binaries.ibm.pc 5097 5089 y
13673 no.general 1000 900 y
13676 Here's a pseudo-BNF definition of this file:
13679 active = *group-line
13680 group-line = group space high-number space low-number space flag <NEWLINE>
13681 group = <non-white-space string>
13683 high-number = <non-negative integer>
13684 low-number = <positive integer>
13685 flag = "y" / "n" / "m" / "j" / "x" / "=" group
13689 @node Newsgroups File Format
13690 @subsubsection Newsgroups File Format
13692 The newsgroups file lists groups along with their descriptions. Not all
13693 groups on the server have to be listed, and not all groups in the file
13694 have to exist on the server. The file is meant purely as information to
13697 The format is quite simple; a group name, a tab, and the description.
13698 Here's the definition:
13702 line = group tab description <NEWLINE>
13703 group = <non-white-space string>
13705 description = <string>
13709 @node Emacs for Heathens
13710 @section Emacs for Heathens
13712 Believe it or not, but some people who use Gnus haven't really used
13713 Emacs much before they embarked on their journey on the Gnus Love Boat.
13714 If you are one of those unfortunates whom ``@kbd{M-C-a}'', ``kill the
13715 region'', and ``set @code{gnus-flargblossen} to an alist where the key
13716 is a regexp that is used for matching on the group name'' are magical
13717 phrases with little or no meaning, then this appendix is for you. If
13718 you are already familiar with Emacs, just ignore this and go fondle your
13722 * Keystrokes:: Entering text and executing commands.
13723 * Emacs Lisp:: The built-in Emacs programming language.
13728 @subsection Keystrokes
13732 Q: What is an experienced Emacs user?
13735 A: A person who wishes that the terminal had pedals.
13738 Yes, when you use Emacs, you are apt to use the control key, the shift
13739 key and the meta key a lot. This is very annoying to some people
13740 (notably @code{vi}le users), and the rest of us just love the hell out
13741 of it. Just give up and submit. Emacs really does stand for
13742 ``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you
13743 may have heard from other disreputable sources (like the Emacs author).
13745 The shift key is normally located near your pinky fingers, and are
13746 normally used to get capital letters and stuff. You probably use it all
13747 the time. The control key is normally marked ``CTRL'' or something like
13748 that. The meta key is, funnily enough, never marked as such on any
13749 keyboards. The one I'm currently at has a key that's marked ``Alt'',
13750 which is the meta key on this keyboard. It's usually located somewhere
13751 to the left hand side of the keyboard, usually on the bottom row.
13753 Now, us Emacs people doesn't say ``press the meta-control-m key'',
13754 because that's just too inconvenient. We say ``press the @kbd{M-C-m}
13755 key''. @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the
13756 prefix that means ``control''. So ``press @kbd{C-k}'' means ``press
13757 down the control key, and hold it down while you press @kbd{k}''.
13758 ``Press @kbd{M-C-k}'' means ``press down and hold down the meta key and
13759 the control key and then press @kbd{k}''. Simple, ay?
13761 This is somewhat complicated by the fact that not all keyboards have a
13762 meta key. In that case you can use the ``escape'' key. Then @kbd{M-k}
13763 means ``press escape, release escape, press @kbd{k}''. That's much more
13764 work than if you have a meta key, so if that's the case, I respectfully
13765 suggest you get a real keyboard with a meta key. You can't live without
13771 @subsection Emacs Lisp
13773 Emacs is the King of Editors because it's really a Lisp interpreter.
13774 Each and every key you tap runs some Emacs Lisp code snippet, and since
13775 Emacs Lisp is an interpreted language, that means that you can configure
13776 any key to run any arbitrary code. You just, like, do it.
13778 Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
13779 functions. (These are byte-compiled for speed, but it's still
13780 interpreted.) If you decide that you don't like the way Gnus does
13781 certain things, it's trivial to have it do something a different way.
13782 (Well, at least if you know how to write Lisp code.) However, that's
13783 beyond the scope of this manual, so we are simply going to talk about
13784 some common constructs that you normally use in your @file{.emacs} file
13787 If you want to set the variable @code{gnus-florgbnize} to four (4), you
13788 write the following:
13791 (setq gnus-florgbnize 4)
13794 This function (really ``special form'') @code{setq} is the one that can
13795 set a variable to some value. This is really all you need to know. Now
13796 you can go and fill your @code{.emacs} file with lots of these to change
13799 If you have put that thing in your @code{.emacs} file, it will be read
13800 and @code{eval}ed (which is lisp-ese for ``run'') the next time you
13801 start Emacs. If you want to change the variable right away, simply say
13802 @kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
13803 previous ``form'', which here is a simple @code{setq} statement.
13805 Go ahead---just try it, if you're located at your Emacs. After you
13806 @kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
13807 is the return value of the form you @code{eval}ed.
13811 If the manual says ``set @code{gnus-read-active-file} to @code{some}'',
13815 (setq gnus-read-active-file 'some)
13818 On the other hand, if the manual says ``set @code{gnus-nntp-server} to
13819 @samp{nntp.ifi.uio.no}'', that means:
13822 (setq gnus-nntp-server "nntp.ifi.uio.no")
13825 So be careful not to mix up strings (the latter) with symbols (the
13826 former). The manual is unambiguous, but it can be confusing.
13829 @include gnus-faq.texi