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.
1044 When the forms are @code{eval}ed, point is at the beginning of the line
1045 of the group in question, so you can use many of the normal Gnus
1046 functions for snarfing info on the group.
1048 @vindex gnus-group-update-hook
1049 @findex gnus-group-highlight-line
1050 @code{gnus-group-update-hook} is called when a group line is changed.
1051 It will not be called when @code{gnus-visual} is @code{nil}. This hook
1052 calls @code{gnus-group-highlight-line} by default.
1055 @node Group Maneuvering
1056 @section Group Maneuvering
1057 @cindex group movement
1059 All movement commands understand the numeric prefix and will behave as
1060 expected, hopefully.
1066 @findex gnus-group-next-unread-group
1067 Go to the next group that has unread articles
1068 (@code{gnus-group-next-unread-group}).
1075 @findex gnus-group-prev-unread-group
1076 Go to the previous group group that has unread articles
1077 (@code{gnus-group-prev-unread-group}).
1081 @findex gnus-group-next-group
1082 Go to the next group (@code{gnus-group-next-group}).
1086 @findex gnus-group-prev-group
1087 Go to the previous group (@code{gnus-group-prev-group}).
1091 @findex gnus-group-next-unread-group-same-level
1092 Go to the next unread group on the same level (or lower)
1093 (@code{gnus-group-next-unread-group-same-level}).
1097 @findex gnus-group-prev-unread-group-same-level
1098 Go to the previous unread group on the same level (or lower)
1099 (@code{gnus-group-prev-unread-group-same-level}).
1102 Three commands for jumping to groups:
1108 @findex gnus-group-jump-to-group
1109 Jump to a group (and make it visible if it isn't already)
1110 (@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
1115 @findex gnus-group-best-unread-group
1116 Jump to the unread group with the lowest level
1117 (@code{gnus-group-best-unread-group}).
1121 @findex gnus-group-first-unread-group
1122 Jump to the first group with unread articles
1123 (@code{gnus-group-first-unread-group}).
1126 @vindex gnus-group-goto-unread
1127 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
1128 commands will move to the next group, not the next unread group. Even
1129 the commands that say they move to the next unread group. The default
1133 @node Selecting a Group
1134 @section Selecting a Group
1135 @cindex group selection
1140 @kindex SPACE (Group)
1141 @findex gnus-group-read-group
1142 Select the current group, switch to the summary buffer and display the
1143 first unread article (@code{gnus-group-read-group}). If there are no
1144 unread articles in the group, or if you give a non-numerical prefix to
1145 this command, Gnus will offer to fetch all the old articles in this
1146 group from the server. If you give a numerical prefix @var{N}, Gnus
1147 will fetch @var{N} number of articles. If @var{N} is positive, fetch
1148 the @var{N} newest articles, if @var{N} is negative, fetch the
1149 @var{abs(N)} oldest articles.
1153 @findex gnus-group-select-group
1154 Select the current group and switch to the summary buffer
1155 (@code{gnus-group-select-group}). Takes the same arguments as
1156 @code{gnus-group-read-group}---the only difference is that this command
1157 does not display the first unread article automatically upon group
1161 @kindex M-RET (Group)
1162 @findex gnus-group-quick-select-group
1163 This does the same as the command above, but tries to do it with the
1164 minimum amount off fuzz (@code{gnus-group-quick-select-group}). No
1165 scoring/killing will be performed, there will be no highlights and no
1166 expunging. This might be useful if you're in a real hurry and have to
1167 enter some humongous group.
1170 @kindex M-RET (Group)
1171 @findex gnus-group-visible-select-group
1172 This is yet one more command that does the same as the one above, but
1173 this one does it without expunging and hiding dormants
1174 (@code{gnus-group-visible-select-group}).
1178 @findex gnus-group-catchup-current
1179 @vindex gnus-group-catchup-group-hook
1180 Mark all unticked articles in this group as read
1181 (@code{gnus-group-catchup-current}).
1182 @code{gnus-group-catchup-group-hook} is when catching up a group from
1187 @findex gnus-group-catchup-current-all
1188 Mark all articles in this group, even the ticked ones, as read
1189 (@code{gnus-group-catchup-current-all}).
1192 @vindex gnus-large-newsgroup
1193 The @code{gnus-large-newsgroup} variable says what Gnus should consider
1194 to be a big group. This is 200 by default. If the group has more
1195 unread articles than this, Gnus will query the user before entering the
1196 group. The user can then specify how many articles should be fetched
1197 from the server. If the user specifies a negative number (@code{-n}),
1198 the @code{n} oldest articles will be fetched. If it is positive, the
1199 @code{n} articles that have arrived most recently will be fetched.
1201 @vindex gnus-select-group-hook
1202 @vindex gnus-auto-select-first
1203 @code{gnus-auto-select-first} control whether any articles are selected
1204 automatically when entering a group.
1209 Don't select any articles when entering the group. Just display the
1210 full summary buffer.
1213 Select the first unread article when entering the group.
1216 Select the most high-scored article in the group when entering the
1220 If you want to prevent automatic selection in some group (say, in a
1221 binary group with Huge articles) you can set this variable to @code{nil}
1222 in @code{gnus-select-group-hook}, which is called when a group is
1225 @findex gnus-thread-sort-by-total-score
1226 @findex gnus-thread-sort-by-date
1227 @findex gnus-thread-sort-by-score
1228 @findex gnus-thread-sort-by-subject
1229 @findex gnus-thread-sort-by-author
1230 @findex gnus-thread-sort-by-number
1231 @vindex gnus-thread-sort-functions
1232 If you are using a threaded summary display, you can sort the threads by
1233 setting @code{gnus-thread-sort-functions}, which is a list of functions.
1234 By default, sorting is done on article numbers. Ready-made sorting
1235 predicate functions include @code{gnus-thread-sort-by-number},
1236 @code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
1237 @code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and
1238 @code{gnus-thread-sort-by-total-score}.
1240 Each function takes two threads and return non-@code{nil} if the first
1241 thread should be sorted before the other. Note that sorting really is
1242 normally done by looking only at the roots of each thread. If you use
1243 more than one function, the primary sort key should be the last function
1244 in the list. You should probably always include
1245 @code{gnus-thread-sort-by-number} in the list of sorting
1246 functions---preferably first. This will ensure that threads that are
1247 equal with respect to the other sort criteria will be displayed in
1248 ascending article order.
1250 If you would like to sort by score, then by subject, and finally by
1251 number, you could do something like:
1254 (setq gnus-thread-sort-functions
1255 '(gnus-thread-sort-by-number
1256 gnus-thread-sort-by-subject
1257 gnus-thread-sort-by-score))
1260 The threads that have highest score will be displayed first in the
1261 summary buffer. When threads have the same score, they will be sorted
1262 alphabetically. The threads that have the same score and the same
1263 subject will be sorted by number, which is (normally) the sequence in
1264 which the articles arrived.
1266 If you want to sort by score and then reverse arrival order, you could
1270 (setq gnus-thread-sort-functions
1272 (not (gnus-thread-sort-by-number t1 t2)))
1273 gnus-thread-sort-by-score))
1276 @vindex gnus-thread-score-function
1277 The function in the @code{gnus-thread-score-function} variable (default
1278 @code{+}) is used for calculating the total score of a thread. Useful
1279 functions might be @code{max}, @code{min}, or squared means, or whatever
1282 @findex gnus-article-sort-functions
1283 @findex gnus-article-sort-by-date
1284 @findex gnus-article-sort-by-score
1285 @findex gnus-article-sort-by-subject
1286 @findex gnus-article-sort-by-author
1287 @findex gnus-article-sort-by-number
1288 If you are using an unthreaded display for some strange reason or other,
1289 you have to fiddle with the @code{gnus-article-sort-functions} variable.
1290 It is very similar to the @code{gnus-thread-sort-functions}, except that
1291 is uses slightly different functions for article comparison. Available
1292 sorting predicate functions are @code{gnus-article-sort-by-number},
1293 @code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject},
1294 @code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}.
1296 If you want to sort an unthreaded summary display by subject, you could
1300 (setq gnus-article-sort-functions
1301 '(gnus-article-sort-by-number
1302 gnus-article-sort-by-subject))
1306 @node Subscription Commands
1307 @section Subscription Commands
1316 @findex gnus-group-unsubscribe-current-group
1317 Toggle subscription to the current group
1318 (@code{gnus-group-unsubscribe-current-group}).
1324 @findex gnus-group-unsubscribe-group
1325 Prompt for a group to subscribe, and then subscribe it. If it was
1326 subscribed already, unsubscribe it instead
1327 (@code{gnus-group-unsubscribe-group}).
1333 @findex gnus-group-kill-group
1334 Kill the current group (@code{gnus-group-kill-group}).
1340 @findex gnus-group-yank-group
1341 Yank the last killed group (@code{gnus-group-yank-group}).
1344 @kindex C-x C-t (Group)
1345 @findex gnus-group-transpose-groups
1346 Transpose two groups (@code{gnus-group-transpose-groups}). This isn't
1347 really a subscription command, but you can use it instead of a
1348 kill-and-yank sequence sometimes.
1354 @findex gnus-group-kill-region
1355 Kill all groups in the region (@code{gnus-group-kill-region}).
1359 @findex gnus-group-kill-all-zombies
1360 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
1363 @kindex S C-k (Group)
1364 @findex gnus-group-kill-level
1365 Kill all groups on a certain level (@code{gnus-group-kill-level}).
1366 These groups can't be yanked back after killing, so this command should
1367 be used with some caution. The only thing where this command comes in
1368 really handy is when you have a @file{.newsrc} with lots of unsubscribed
1369 groups that you want to get rid off. @kbd{S C-k} on level @code{7} will
1370 kill off all unsubscribed groups that do not have message numbers in the
1371 @file{.newsrc} file.
1375 Also @pxref{Group Levels}.
1379 @section Group Levels
1382 All groups have a level of @dfn{subscribedness}. For instance, if a
1383 group is on level 2, it is more subscribed than a group on level 5. You
1384 can ask Gnus to just list groups on a given level or lower
1385 (@pxref{Listing Groups}), or to just check for new articles in groups on
1386 a given level or lower (@pxref{Scanning New Messages}).
1392 @findex gnus-group-set-current-level
1393 Set the level of the current group. If a numeric prefix is given, the
1394 next @var{n} groups will have their levels set. The user will be
1395 prompted for a level.
1398 @vindex gnus-level-killed
1399 @vindex gnus-level-zombie
1400 @vindex gnus-level-unsubscribed
1401 @vindex gnus-level-subscribed
1402 Gnus considers groups on between levels 1 and
1403 @code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed,
1404 @code{gnus-level-subscribed} (exclusive) and
1405 @code{gnus-level-unsubscribed} (inclusive) (default 7) to be
1406 unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
1407 (default 8) and @code{gnus-level-killed} to be killed (default 9),
1408 completely dead. Gnus treats subscribed and unsubscribed groups exactly
1409 the same, but zombie and killed groups have no information on what
1410 articles you have read, etc, stored. This distinction between dead and
1411 living groups isn't done because it is nice or clever, it is done purely
1412 for reasons of efficiency.
1414 It is recommended that you keep all your mail groups (if any) on quite
1415 low levels (eg. 1 or 2).
1417 If you want to play with the level variables, you should show some care.
1418 Set them once, and don't touch them ever again. Better yet, don't touch
1419 them at all unless you know exactly what you're doing.
1421 @vindex gnus-level-default-unsubscribed
1422 @vindex gnus-level-default-subscribed
1423 Two closely related variables are @code{gnus-level-default-subscribed}
1424 (default 3) and @code{gnus-level-default-unsubscribed} (default 6),
1425 which are the levels that new groups will be put on if they are
1426 (un)subscribed. These two variables should, of course, be inside the
1427 relevant legal ranges.
1429 @vindex gnus-keep-same-level
1430 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
1431 will only move to groups that are of the same level (or lower). In
1432 particular, going from the last article in one group to the next group
1433 will go to the next group of the same level (or lower). This might be
1434 handy if you want to read the most important groups before you read the
1437 @vindex gnus-group-default-list-level
1438 All groups with a level less than or equal to
1439 @code{gnus-group-default-list-level} will be listed in the group buffer
1442 @vindex gnus-group-list-inactive-groups
1443 If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active
1444 groups will be listed along with the unread groups. This variable is
1445 @code{t} by default. If it is @code{nil}, inactive groups won't be
1448 @vindex gnus-group-use-permanent-levels
1449 If @code{gnus-group-use-permanent-levels} is non-@code{nil}, once you
1450 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
1451 use this level as the ``work'' level.
1453 @vindex gnus-activate-level
1454 Gnus will normally just activate groups that are on level
1455 @code{gnus-activate-level} or less. If you don't want to activate
1456 unsubscribed groups, for instance, you might set this variable to
1461 @section Group Score
1464 You would normally keep important groups on high levels, but that scheme
1465 is somewhat restrictive. Don't you wish you could have Gnus sort the
1466 group buffer according to how often you read groups, perhaps? Within
1469 This is what @dfn{group score} is for. You can assign a score to each
1470 group. You can then sort the group buffer based on this score.
1471 Alternatively, you can sort on score and then level. (Taken together,
1472 the level and the score is called the @dfn{rank} of the group. A group
1473 that is on level 4 and has a score of 1 has a higher rank than a group
1474 on level 5 that has a score of 300. (The level is the most significant
1475 part and the score is the least significant part.)
1477 @findex gnus-summary-bubble-group
1478 If you want groups you read often to get higher scores than groups you
1479 read seldom you can add the @code{gnus-summary-bubble-group} function to
1480 the @code{gnus-summary-exit-hook} hook. This will result (after
1481 sorting) in a bubbling sort of action. If you want to see that in
1482 action after each summary exit, you can add
1483 @code{gnus-group-sort-groups-by-rank} or
1484 @code{gnus-group-sort-groups-by-score} to the same hook, but that will
1485 slow things down somewhat.
1488 @node Marking Groups
1489 @section Marking Groups
1490 @cindex marking groups
1492 If you want to perform some command on several groups, and they appear
1493 subsequently in the group buffer, you would normally just give a
1494 numerical prefix to the command. Most group commands will then do your
1495 bidding on those groups.
1497 However, if the groups are not in sequential order, you can still
1498 perform a command on several groups. You simply mark the groups first
1499 with the process mark and then execute the command.
1507 @findex gnus-group-mark-group
1508 Set the mark on the current group (@code{gnus-group-mark-group}).
1514 @findex gnus-group-unmark-group
1515 Remove the mark from the current group
1516 (@code{gnus-group-unmark-group}).
1520 @findex gnus-group-unmark-all-groups
1521 Remove the mark from all groups (@code{gnus-group-unmark-all-groups}).
1525 @findex gnus-group-mark-region
1526 Mark all groups between point and mark (@code{gnus-group-mark-region}).
1530 @findex gnus-group-mark-buffer
1531 Mark all groups in the buffer (@code{gnus-group-mark-buffer}).
1535 @findex gnus-group-mark-regexp
1536 Mark all groups that match some regular expression
1537 (@code{gnus-group-mark-regexp}).
1540 Also @pxref{Process/Prefix}.
1542 @findex gnus-group-universal-argument
1543 If you want to execute some command on all groups that have been marked
1544 with the process mark, you can use the @kbd{M-&}
1545 (@code{gnus-group-universal-argument}) command. It will prompt you for
1546 the command to be executed.
1549 @node Foreign Groups
1550 @section Foreign Groups
1552 Here are some group mode commands for making and editing general foreign
1553 groups, as well as commands to ease the creation of a few
1554 special-purpose groups:
1560 @findex gnus-group-make-group
1561 Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
1562 for a name, a method and possibly an @dfn{address}. For an easier way
1563 to subscribe to @sc{nntp} groups, @pxref{Browse Foreign Server}.
1567 @findex gnus-group-rename-group
1568 Rename the current group to something else
1569 (@code{gnus-group-rename-group}). This is legal only on some groups --
1570 mail groups mostly. This command might very well be quite slow on some
1575 @findex gnus-group-edit-group-method
1576 Enter a buffer where you can edit the select method of the current
1577 group (@code{gnus-group-edit-group-method}).
1581 @findex gnus-group-edit-group-parameters
1582 Enter a buffer where you can edit the group parameters
1583 (@code{gnus-group-edit-group-parameters}).
1587 @findex gnus-group-edit-group
1588 Enter a buffer where you can edit the group info
1589 (@code{gnus-group-edit-group}).
1593 @findex gnus-group-make-directory-group
1594 Make a directory group. You will be prompted for a directory name
1595 (@code{gnus-group-make-directory-group}).
1599 @findex gnus-group-make-help-group
1600 Make the Gnus help group (@code{gnus-group-make-help-group}).
1604 @findex gnus-group-make-archive-group
1605 @vindex gnus-group-archive-directory
1606 @vindex gnus-group-recent-archive-directory
1607 Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
1608 default a group pointing to the most recent articles will be created
1609 (@code{gnus-group-recent-archive-directory}), but given a prefix, a full
1610 group will be created from from @code{gnus-group-archive-directory}.
1614 @findex gnus-group-make-kiboze-group
1615 Make a kiboze group. You will be prompted for a name, for a regexp to
1616 match groups to be ``included'' in the kiboze group, and a series of
1617 strings to match on headers (@code{gnus-group-make-kiboze-group}).
1621 @findex gnus-group-enter-directory
1622 Read an arbitrary directory as if with were a newsgroup with the
1623 @code{nneething} backend (@code{gnus-group-enter-directory}).
1627 @findex gnus-group-make-doc-group
1628 @cindex ClariNet Briefs
1629 Make a group based on some file or other
1630 (@code{gnus-group-make-doc-group}). If you give a prefix to this
1631 command, you will be prompted for a file name and a file type.
1632 Currently supported types are @code{babyl}, @code{mbox}, @code{digest},
1633 @code{mmdf}, @code{news}, @code{rnews}, @code{clari-briefs}, and
1634 @code{forward}. If you run this command without a prefix, Gnus will
1635 guess at the file type.
1638 @kindex G DEL (Group)
1639 @findex gnus-group-delete-group
1640 This function will delete the current group
1641 (@code{gnus-group-delete-group}). If given a prefix, this function will
1642 actually delete all the articles in the group, and forcibly remove the
1643 group itself from the face of the Earth. Use a prefix only if you are
1644 absolutely sure of what you are doing.
1648 @findex gnus-group-make-empty-virtual
1649 Make a new, fresh, empty @code{nnvirtual} group
1650 (@code{gnus-group-make-empty-virtual}).
1654 @findex gnus-group-add-to-virtual
1655 Add the current group to an @code{nnvirtual} group
1656 (@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
1659 @xref{Select Methods} for more information on the various select
1662 @vindex gnus-activate-foreign-newsgroups
1663 If the @code{gnus-activate-foreign-newsgroups} is a positive number,
1664 Gnus will check all foreign groups with this level or lower at startup.
1665 This might take quite a while, especially if you subscribe to lots of
1666 groups from different @sc{nntp} servers.
1669 @node Group Parameters
1670 @section Group Parameters
1671 @cindex group parameters
1673 Gnus stores all information on a group in a list that is usually known
1674 as the @dfn{group info}. This list has from three to six elements.
1675 Here's an example info.
1678 ("nnml:mail.ding" 3 ((1 . 232) 244 (256 . 270)) ((tick 246 249))
1679 (nnml "private") ((to-address . "ding@@ifi.uio.no")))
1682 The first element is the @dfn{group name}, as Gnus knows the group,
1683 anyway. The second element is the @dfn{subscription level}, which
1684 normally is a small integer. The third element is a list of ranges of
1685 read articles. The fourth element is a list of lists of article marks
1686 of various kinds. The fifth element is the select method (or virtual
1687 server, if you like). The sixth element is a list of @dfn{group
1688 parameters}, which is what this section is about.
1690 Any of the last three elements may be missing if they are not required.
1691 In fact, the vast majority of groups will normally only have the first
1692 three elements, which saves quite a lot of cons cells.
1694 The group parameters store information local to a particular group:
1699 If the group parameter list contains an element that looks like
1700 @code{(to-address . "some@@where.com")}, that address will be used by
1701 the backend when doing followups and posts. This is primarily useful in
1702 mail groups that represent closed mailing lists---mailing lists where
1703 it's expected that everybody that writes to the mailing list is
1704 subscribed to it. Since using this parameter ensures that the mail only
1705 goes to the mailing list itself, it means that members won't receive two
1706 copies of your followups.
1708 Using @code{to-address} will actually work whether the group is foreign
1709 or not. Let's say there's a group on the server that is called
1710 @samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten
1711 the articles from a mail-to-news gateway. Posting directly to this
1712 group is therefore impossible---you have to send mail to the mailing
1713 list address instead.
1717 If the group parameter list has an element that looks like
1718 @code{(to-list . "some@@where.com")}, that address will be used when
1719 doing a @kbd{a} in any group. It is totally ignored when doing a
1720 followup---except that if it is present in a news group, you'll get mail
1721 group semantics when doing @kbd{f}.
1723 @item broken-reply-to
1724 @cindex broken-reply-to
1725 Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To}
1726 headers in this group are to be ignored. This can be useful if you're
1727 reading a mailing list group where the listserv has inserted
1728 @code{Reply-To} headers that point back to the listserv itself. This is
1729 broken behavior. So there!
1733 If the group parameter list contains an element like @code{(to-group
1734 . "some.group.name")}, all posts will be sent to that group.
1738 If this symbol is present in the group parameter list, all articles that
1739 are read will be marked as expirable. For an alternative approach,
1740 @pxref{Expiring Mail}.
1743 @cindex total-expire
1744 If this symbol is present, all read articles will be put through the
1745 expiry process, even if they are not marked as expirable. Use with
1750 @vindex nnmail-expiry-wait-function
1751 If the group parameter has an element that looks like @code{(expiry-wait
1752 . 10)}, this value will override any @code{nnmail-expiry-wait} and
1753 @code{nnmail-expiry-wait-function} when expiring expirable messages.
1754 The value can either be a number of days (not necessarily an integer) or
1755 the symbols @code{never} or @code{immediate}.
1758 Elements that look like @code{(score-file . "file")} will make
1759 @samp{file} into the current score file for the group in question. This
1760 means that all score commands you issue will end up in that file.
1763 When unsubscribing to a mailing list you should never send the
1764 unsubscription notice to the mailing list itself. Instead, you'd send
1765 messages to the administrative address. This parameter allows you to
1766 put the admin address somewhere convenient.
1769 This parameter allows you to enter a arbitrary comment on the group.
1771 @item @var{(variable form)}
1772 You can use the group parameters to set variables local to the group you
1773 are entering. Say you want to turn threading off in
1774 @samp{news.answers}. You'd then put @code{(gnus-show-threads nil)} in
1775 the group parameters of that group. @code{gnus-show-threads} will be
1776 made into a local variable in the summary buffer you enter, and the form
1777 @code{nil} will be @code{eval}ed there.
1779 This can also be used as a group-specific hook function, if you'd like.
1780 If you want to hear a beep when you enter the group
1781 @samp{alt.binaries.pictures.furniture}, you could put something like
1782 @code{(dummy-variable (ding))} in the parameters of that group.
1783 @code{dummy-variable} will be set to the result of the @code{(ding)}
1784 form, but who cares?
1788 If you want to change the group info you can use the @kbd{G E} command
1789 to enter a buffer where you can edit it.
1791 You usually don't want to edit the entire group info, so you'd be better
1792 off using the @kbd{G p} command to just edit the group parameters.
1795 @node Listing Groups
1796 @section Listing Groups
1797 @cindex group listing
1799 These commands all list various slices of the groups that are available.
1807 @findex gnus-group-list-groups
1808 List all groups that have unread articles
1809 (@code{gnus-group-list-groups}). If the numeric prefix is used, this
1810 command will list only groups of level ARG and lower. By default, it
1811 only lists groups of level five or lower (i.e., just subscribed groups).
1817 @findex gnus-group-list-all-groups
1818 List all groups, whether they have unread articles or not
1819 (@code{gnus-group-list-all-groups}). If the numeric prefix is used,
1820 this command will list only groups of level ARG and lower. By default,
1821 it lists groups of level seven or lower (i.e., just subscribed and
1822 unsubscribed groups).
1826 @findex gnus-group-list-level
1827 List all unread groups on a specific level
1828 (@code{gnus-group-list-level}). If given a prefix, also list the groups
1829 with no unread articles.
1833 @findex gnus-group-list-killed
1834 List all killed groups (@code{gnus-group-list-killed}). If given a
1835 prefix argument, really list all groups that are available, but aren't
1836 currently (un)subscribed. This could entail reading the active file
1841 @findex gnus-group-list-zombies
1842 List all zombie groups (@code{gnus-group-list-zombies}).
1846 @findex gnus-group-list-matching
1847 List all subscribed groups with unread articles that match a regexp
1848 (@code{gnus-group-list-matching}).
1852 @findex gnus-group-list-all-matching
1853 List groups that match a regexp (@code{gnus-group-list-all-matching}).
1857 @findex gnus-group-list-active
1858 List absolutely all groups that are in the active file(s) of the
1859 server(s) you are connected to (@code{gnus-group-list-active}). This
1860 might very well take quite a while. It might actually be a better idea
1861 to do a @kbd{A m} to list all matching, and just give @samp{.} as the
1866 @findex gnus-group-apropos
1867 List all groups that have names that match a regexp
1868 (@code{gnus-group-apropos}).
1872 @findex gnus-group-description-apropos
1873 List all groups that have names or descriptions that match a regexp
1874 (@code{gnus-group-description-apropos}).
1878 @vindex gnus-permanently-visible-groups
1879 @cindex visible group parameter
1880 Groups that match the @code{gnus-permanently-visible-groups} regexp will
1881 always be shown, whether they have unread articles or not. You can also
1882 add the @code{visible} element to the group parameters in question to
1883 get the same effect.
1885 @vindex gnus-list-groups-with-ticked-articles
1886 Groups that have just ticked articles in it are normally listed in the
1887 group buffer. If @code{gnus-list-groups-with-ticked-articles} is
1888 @code{nil}, these groups will be treated just like totally empty
1889 groups. It is @code{t} by default.
1892 @node Sorting Groups
1893 @section Sorting Groups
1894 @cindex sorting groups
1896 @kindex C-c C-s (Group)
1897 @findex gnus-group-sort-groups
1898 @vindex gnus-group-sort-function
1899 The @kbd{C-c C-s} (@code{gnus-group-sort-groups}) command sorts the
1900 group buffer according to the function(s) given by the
1901 @code{gnus-group-sort-function} variable. Available sorting functions
1906 @item gnus-group-sort-by-alphabet
1907 @findex gnus-group-sort-by-alphabet
1908 Sort the group names alphabetically. This is the default.
1910 @item gnus-group-sort-by-level
1911 @findex gnus-group-sort-by-level
1912 Sort by group level.
1914 @item gnus-group-sort-by-score
1915 @findex gnus-group-sort-by-score
1916 Sort by group score.
1918 @item gnus-group-sort-by-rank
1919 @findex gnus-group-sort-by-rank
1920 Sort by group score and then the group level. The level and the score
1921 are, when taken together, the group's @dfn{rank}.
1923 @item gnus-group-sort-by-unread
1924 @findex gnus-group-sort-by-unread
1925 Sort by number of unread articles.
1927 @item gnus-group-sort-by-method
1928 @findex gnus-group-sort-by-method
1929 Sort by alphabetically on the select method.
1934 @code{gnus-group-sort-function} can also be a list of sorting
1935 functions. In that case, the most significant sort key function must be
1939 There are also a number of commands for sorting directly according to
1940 some sorting criteria:
1944 @kindex G S a (Group)
1945 @findex gnus-group-sort-groups-by-alphabet
1946 Sort the group buffer alphabetically by group name
1947 (@code{gnus-group-sort-groups-by-alphabet}).
1950 @kindex G S u (Group)
1951 @findex gnus-group-sort-groups-by-unread
1952 Sort the group buffer by the number of unread articles
1953 (@code{gnus-group-sort-groups-by-unread}).
1956 @kindex G S l (Group)
1957 @findex gnus-group-sort-groups-by-level
1958 Sort the group buffer by group level
1959 (@code{gnus-group-sort-groups-by-level}).
1962 @kindex G S v (Group)
1963 @findex gnus-group-sort-groups-by-score
1964 Sort the group buffer by group score
1965 (@code{gnus-group-sort-groups-by-score}).
1968 @kindex G S r (Group)
1969 @findex gnus-group-sort-groups-by-rank
1970 Sort the group buffer by group level
1971 (@code{gnus-group-sort-groups-by-rank}).
1974 @kindex G S m (Group)
1975 @findex gnus-group-sort-groups-by-method
1976 Sort the group buffer alphabetically by backend name
1977 (@code{gnus-group-sort-groups-by-method}).
1981 When given a prefix, all these commands will sort in reverse order.
1984 @node Group Maintenance
1985 @section Group Maintenance
1986 @cindex bogus groups
1991 @findex gnus-group-check-bogus-groups
1992 Find bogus groups and delete them
1993 (@code{gnus-group-check-bogus-groups}).
1997 @findex gnus-find-new-newsgroups
1998 Find new groups and process them (@code{gnus-find-new-newsgroups}). If
1999 given a prefix, use the @code{ask-server} method to query the server for
2003 @kindex C-c C-x (Group)
2004 @findex gnus-group-expire-articles
2005 Run all expirable articles in the current group through the expiry
2006 process (if any) (@code{gnus-group-expire-articles}).
2009 @kindex C-c M-C-x (Group)
2010 @findex gnus-group-expire-all-groups
2011 Run all articles in all groups through the expiry process
2012 (@code{gnus-group-expire-all-groups}).
2017 @node Browse Foreign Server
2018 @section Browse Foreign Server
2019 @cindex foreign servers
2020 @cindex browsing servers
2025 @findex gnus-group-browse-foreign-server
2026 You will be queried for a select method and a server name. Gnus will
2027 then attempt to contact this server and let you browse the groups there
2028 (@code{gnus-group-browse-foreign-server}).
2031 @findex gnus-browse-server-mode
2032 A new buffer with a list of available groups will appear. This buffer
2033 will be use the @code{gnus-browse-server-mode}. This buffer looks a bit
2034 (well, a lot) like a normal group buffer, but with one major difference
2035 - you can't enter any of the groups. If you want to read any of the
2036 news available on that server, you have to subscribe to the groups you
2037 think may be interesting, and then you have to exit this buffer. The
2038 new groups will be added to the group buffer, and then you can read them
2039 as you would any other group.
2041 Future versions of Gnus may possibly permit reading groups straight from
2044 Here's a list of keystrokes available in the browse mode:
2049 @findex gnus-group-next-group
2050 Go to the next group (@code{gnus-group-next-group}).
2054 @findex gnus-group-prev-group
2055 Go to the previous group (@code{gnus-group-prev-group}).
2058 @kindex SPACE (Browse)
2059 @findex gnus-browse-read-group
2060 Enter the current group and display the first article
2061 (@code{gnus-browse-read-group}).
2064 @kindex RET (Browse)
2065 @findex gnus-browse-select-group
2066 Enter the current group (@code{gnus-browse-select-group}).
2070 @findex gnus-browse-unsubscribe-current-group
2071 Unsubscribe to the current group, or, as will be the case here,
2072 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
2078 @findex gnus-browse-exit
2079 Exit browse mode (@code{gnus-browse-exit}).
2083 @findex gnus-browse-describe-briefly
2084 Describe browse mode briefly (well, there's not much to describe, is
2085 there) (@code{gnus-browse-describe-briefly}).
2090 @section Exiting Gnus
2091 @cindex exiting Gnus
2093 Yes, Gnus is ex(c)iting.
2098 @findex gnus-group-suspend
2099 Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
2100 but it kills all buffers except the Group buffer. I'm not sure why this
2101 is a gain, but then who am I to judge?
2105 @findex gnus-group-exit
2106 Quit Gnus (@code{gnus-group-exit}).
2110 @findex gnus-group-quit
2111 Quit Gnus without saving any startup files (@code{gnus-group-quit}).
2114 @vindex gnus-exit-gnus-hook
2115 @vindex gnus-suspend-gnus-hook
2116 @code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
2117 @code{gnus-exit-gnus-hook} is called when you quit Gnus, while
2118 @code{gnus-after-exiting-gnus-hook} is called as the final item when
2123 If you wish to completely unload Gnus and all its adherents, you can use
2124 the @code{gnus-unload} command. This command is also very handy when
2125 trying to customize meta-variables.
2130 Miss Lisa Cannifax, while sitting in English class, feels her feet go
2131 numbly heavy and herself fall into a hazy trance as the boy sitting
2132 behind her drew repeated lines with his pencil across the back of her
2138 @section Group Topics
2141 If you read lots and lots of groups, it might be convenient to group
2142 them hierarchically according to topics. You put your Emacs groups over
2143 here, your sex groups over there, and the rest (what, two groups or so?)
2144 you put in some misc section that you never bother with anyway. You can
2145 even group the Emacs sex groups as a sub-topic to either the Emacs
2146 groups or the sex groups---or both! Go wild!
2148 @findex gnus-topic-mode
2150 To get this @emph{fab} functionality you simply turn on (ooh!) the
2151 @code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This
2152 is a toggling command.)
2154 Go ahead, just try it. I'll still be here when you get back. La de
2155 dum... Nice tune, that... la la la... What, you're back? Yes, and now
2156 press @kbd{l}. There. All your groups are now listed under
2157 @samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
2160 If you want this permanently enabled, you should add that minor mode to
2161 the hook for the group mode:
2164 (add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
2168 * Topic Variables:: How to customize the topics the Lisp Way.
2169 * Topic Commands:: Interactive E-Z commands.
2170 * Topic Topology:: A map of the world.
2174 @node Topic Variables
2175 @subsection Topic Variables
2176 @cindex topic variables
2178 @vindex gnus-topic-unique
2179 If @code{gnus-topic-unique} is non-@code{nil}, each group will be member
2180 of (tops) one topic each. If this is @code{nil}, each group might end
2181 up being a member of several topics.
2183 Now, if you select a topic, if will fold/unfold that topic, which is
2184 really neat, I think.
2186 @vindex gnus-topic-line-format
2187 The topic lines themselves are created according to the
2188 @code{gnus-topic-line-format} variable. @xref{Formatting Variables}.
2189 Elements allowed are:
2201 Number of groups in the topic.
2203 Number of unread articles in the topic.
2205 Number of unread articles in the topic and all its subtopics.
2208 @vindex gnus-topic-indent-level
2209 Each sub-topic (and the groups in the sub-topics) will be indented with
2210 @code{gnus-topic-indent-level} times the topic level number of spaces.
2211 The default is @code{2}.
2213 @vindex gnus-topic-mode-hook
2214 @code{gnus-topic-mode-hook} is called in topic minor mode buffers.
2217 @node Topic Commands
2218 @subsection Topic Commands
2219 @cindex topic commands
2221 When the topic minor mode is turned on, a new @kbd{T} submap will be
2222 available. In addition, a few of the standard keys change their
2223 definitions slightly.
2229 @findex gnus-topic-create-topic
2230 Create a new topic (@code{gnus-topic-create-topic}). You will be
2231 prompted for a topic name and the name of the parent topic.
2235 @findex gnus-topic-move-group
2236 Move the current group to some other topic
2237 (@code{gnus-topic-move-group}). This command understands the
2238 process/prefix convention (@pxref{Process/Prefix}).
2242 @findex gnus-topic-copy-group
2243 Copy the current group to some other topic
2244 (@code{gnus-topic-copy-group}). This command understands the
2245 process/prefix convention (@pxref{Process/Prefix}).
2249 @findex gnus-topic-remove-group
2250 Remove a group from the current topic (@code{gnus-topic-remove-group}).
2251 This command understands the process/prefix convention
2252 (@pxref{Process/Prefix}).
2256 @findex gnus-topic-move-matching
2257 Move all groups that match some regular expression to a topic
2258 (@code{gnus-topic-move-matching}).
2262 @findex gnus-topic-copy-matching
2263 Copy all groups that match some regular expression to a topic
2264 (@code{gnus-topic-copy-matching}).
2268 @findex gnus-topic-mark-topic
2269 Mark all groups in the current topic with the process mark
2270 (@code{gnus-topic-mark-topic}).
2273 @kindex T M-# (Group)
2274 @findex gnus-topic-unmark-topic
2275 Remove the process mark from all groups in the current topic
2276 (@code{gnus-topic-unmark-topic}).
2280 @findex gnus-topic-select-group
2282 Either select a group or fold a topic (@code{gnus-topic-select-group}).
2283 When you perform this command on a group, you'll enter the group, as
2284 usual. When done on a topic line, the topic will be folded (if it was
2285 visible) or unfolded (if it was folded already). So it's basically a
2286 toggling command on topics. In addition, if you give a numerical
2287 prefix, group on that level (and lower) will be displayed.
2290 @kindex T TAB (Group)
2291 @findex gnus-topic-indent
2292 ``Indent'' the current topic so that it becomes a sub-topic of the
2293 previous topic (@code{gnus-topic-indent}). If given a prefix,
2294 ``un-indent'' the topic instead.
2298 @findex gnus-topic-kill-group
2299 Kill a group or topic (@code{gnus-topic-kill-group}).
2303 @findex gnus-topic-yank-group
2304 Yank the previously killed group or topic (@code{gnus-topic-yank-group}).
2305 Note that all topics will be yanked before all groups.
2309 @findex gnus-topic-rename
2310 Rename a topic (@code{gnus-topic-rename}).
2313 @kindex T DEL (Group)
2314 @findex gnus-topic-delete
2315 Delete an empty topic (@code{gnus-topic-delete}).
2319 @findex gnus-topic-list-active
2320 List all groups that Gnus knows about in a topics-ified way
2321 (@code{gnus-topic-list-active}).
2326 @node Topic Topology
2327 @subsection Topic Topology
2328 @cindex topic topology
2331 So, let's have a look at an example group buffer:
2337 2: alt.religion.emacs
2340 0: comp.talk.emacs.recovery
2342 8: comp.binaries.fractals
2343 13: comp.sources.unix
2346 So, here we have one top-level topic, two topics under that, and one
2347 sub-topic under one of the sub-topics. (There is always just one (1)
2348 top-level topic). This topology can be expressed as follows:
2352 (("Emacs -- I wuw it!" visible)
2353 (("Naughty Emacs" visible)))
2357 @vindex gnus-topic-topology
2358 This is in fact how the variable @code{gnus-topic-topology} would look
2359 for the display above. That variable is saved in the @file{.newsrc.eld}
2360 file, and shouldn't be messed with manually---unless you really want
2361 to. Since this variable is read from the @file{.newsrc.eld} file,
2362 setting it in any other startup files will have no effect.
2364 This topology shows what topics are sub-topics of what topics (right),
2365 and which topics are visible. Two settings are currently
2366 allowed---@code{visible} and @code{invisible}.
2369 @node Misc Group Stuff
2370 @section Misc Group Stuff
2373 * Scanning New Messages:: Asking Gnus to see whether new messages have arrived.
2374 * Group Information:: Information and help on groups and Gnus.
2375 * File Commands:: Reading and writing the Gnus files.
2382 @findex gnus-group-enter-server-mode
2383 Enter the server buffer (@code{gnus-group-enter-server-mode}). @xref{The
2388 @findex gnus-group-post-news
2389 Post an article to a group (@code{gnus-group-post-news}). The current
2390 group name will be used as the default.
2394 @findex gnus-group-mail
2395 Mail a message somewhere (@code{gnus-group-mail}).
2399 Variables for the group buffer:
2403 @item gnus-group-mode-hook
2404 @vindex gnus-group-mode-hook
2405 @code{gnus-group-mode-hook} is called after the group buffer has been
2408 @item gnus-group-prepare-hook
2409 @vindex gnus-group-prepare-hook
2410 @code{gnus-group-prepare-hook} is called after the group buffer is
2411 generated. It may be used to modify the buffer in some strange,
2417 @node Scanning New Messages
2418 @subsection Scanning New Messages
2419 @cindex new messages
2420 @cindex scanning new news
2426 @findex gnus-group-get-new-news
2427 Check the server(s) for new articles. If the numerical prefix is used,
2428 this command will check only groups of level @var{arg} and lower
2429 (@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
2430 command will force a total rereading of the active file(s) from the
2435 @findex gnus-group-get-new-news-this-group
2436 @vindex gnus-goto-next-group-when-activating
2437 Check whether new articles have arrived in the current group
2438 (@code{gnus-group-get-new-news-this-group}). The
2439 @code{gnus-goto-next-group-when-activating} variable controls whether
2440 this command is to move point to the next group or not. It is @code{t}
2443 @findex gnus-activate-all-groups
2444 @cindex activating groups
2446 @kindex C-c M-g (Group)
2447 Activate absolutely all groups (@code{gnus-activate-all-groups}).
2452 @findex gnus-group-restart
2453 Restart Gnus (@code{gnus-group-restart}).
2457 @vindex gnus-get-new-news-hook
2458 @code{gnus-get-new-news-hook} is run just before checking for new news.
2460 @vindex gnus-after-getting-new-news-hook
2461 @code{gnus-after-getting-new-news-hook} is run after checking for new
2465 @node Group Information
2466 @subsection Group Information
2467 @cindex group information
2468 @cindex information on groups
2474 @findex gnus-group-fetch-faq
2477 Try to fetch the FAQ for the current group
2478 (@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
2479 @code{gnus-group-faq-directory}, which is usually a directory on a
2480 remote machine. @code{ange-ftp} will be used for fetching the file.
2484 @cindex describing groups
2485 @cindex group description
2486 @findex gnus-group-describe-group
2487 Describe the current group (@code{gnus-group-describe-group}). If given
2488 a prefix, force Gnus to re-read the description from the server.
2492 @findex gnus-group-describe-all-groups
2493 Describe all groups (@code{gnus-group-describe-all-groups}). If given a
2494 prefix, force Gnus to re-read the description file from the server.
2499 @findex gnus-version
2500 Display current Gnus version numbers (@code{gnus-version}).
2504 @findex gnus-group-describe-briefly
2505 Give a very short help message (@code{gnus-group-describe-briefly}).
2508 @kindex C-c C-i (Group)
2511 @findex gnus-info-find-node
2512 Go to the Gnus info node (@code{gnus-info-find-node}).
2517 @subsection File Commands
2518 @cindex file commands
2524 @findex gnus-group-read-init-file
2525 @vindex gnus-init-file
2526 @cindex reading init file
2527 Read the init file (@code{gnus-init-file}, which defaults to
2528 @file{~/.gnus}) (@code{gnus-group-read-init-file}).
2532 @findex gnus-group-save-newsrc
2533 @cindex saving .newsrc
2534 Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
2535 (@code{gnus-group-save-newsrc}). If given a prefix, force saving the
2536 file(s) whether Gnus thinks it is necessary or not.
2540 @findex gnus-group-clear-dribble
2541 Clear the dribble buffer (@code{gnus-group-clear-dribble}).
2546 @node The Summary Buffer
2547 @chapter The Summary Buffer
2548 @cindex summary buffer
2550 A line for each article is displayed in the summary buffer. You can
2551 move around, read articles, post articles and reply to articles.
2554 * Summary Buffer Format:: Deciding how the summary buffer is to look.
2555 * Summary Maneuvering:: Moving around the summary buffer.
2556 * Choosing Articles:: Reading articles.
2557 * Paging the Article:: Scrolling the current article.
2558 * Reply Followup and Post:: Posting articles.
2559 * Canceling and Superseding:: ``Whoops, I shouldn't have called him that.''
2560 * Marking Articles:: Marking articles as read, expirable, etc.
2561 * Limiting:: You can limit the summary buffer.
2562 * Threading:: How threads are made.
2563 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
2564 * Article Caching:: You may store articles in a cache.
2565 * Persistent Articles:: Making articles expiry-resistant.
2566 * Article Backlog:: Having already read articles hang around.
2567 * Saving Articles:: Ways of customizing article saving.
2568 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
2569 * Article Treatment:: The article buffer can be mangled at will.
2570 * Summary Sorting:: Sorting the summary buffer in various ways.
2571 * Finding the Parent:: No child support? Get the parent.
2572 * Alternative Approaches:: Reading using non-default summaries.
2573 * Tree Display:: A more visual display of threads.
2574 * Mail Group Commands:: Some commands can only be used in mail groups.
2575 * Various Summary Stuff:: What didn't fit anywhere else.
2576 * Exiting the Summary Buffer:: Returning to the Group buffer.
2580 @node Summary Buffer Format
2581 @section Summary Buffer Format
2582 @cindex summary buffer format
2585 * Summary Buffer Lines:: You can specify how summary lines should look.
2586 * Summary Buffer Mode Line:: You can say how the mode line should look.
2587 * Summary Highlighting:: Making the summary buffer all pretty and nice.
2590 @findex mail-extract-address-components
2591 @findex gnus-extract-address-components
2592 @vindex gnus-extract-address-components
2593 Gnus will use the value of the @code{gnus-extract-address-components}
2594 variable as a function for getting the name and address parts of a
2595 @code{From} header. Two pre-defined function exist:
2596 @code{gnus-extract-address-components}, which is the default, quite
2597 fast, and too simplistic solution; and
2598 @code{mail-extract-address-components}, which works very nicely, but is
2601 @vindex gnus-summary-same-subject
2602 @code{gnus-summary-same-subject} is a string indicating that the current
2603 article has the same subject as the previous. This string will be used
2604 with those specs that require it. The default is @samp{}.
2607 @node Summary Buffer Lines
2608 @subsection Summary Buffer Lines
2610 @vindex gnus-summary-line-format
2611 You can change the format of the lines in the summary buffer by changing
2612 the @code{gnus-summary-line-format} variable. It works along the same
2613 lines a a normal @code{format} string, with some extensions.
2615 The default string is @samp{%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n}.
2617 The following format specification characters are understood:
2625 Subject if the article is the root, @code{gnus-summary-same-subject}
2628 Full @code{From} line.
2630 The name (from the @code{From} header).
2632 The name (from the @code{From} header). This differs from the @code{n}
2633 spec in that it uses @code{gnus-extract-address-components}, which is
2634 slower, but may be more thorough.
2636 The address (from the @code{From} header). This works the same way as
2639 Number of lines in the article.
2641 Number of characters in the article.
2643 Indentation based on thread level (@pxref{Customizing Threading}).
2645 Nothing if the article is a root and lots of spaces if it isn't (it
2646 pushes everything after it off the screen).
2648 Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
2649 for adopted articles.
2651 Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
2652 for adopted articles.
2654 One space for each thread level.
2656 Twenty minus thread level spaces.
2664 @vindex gnus-summary-zcore-fuzz
2665 Zcore, @samp{+} if above the default level and @samp{-} if below the
2666 default level. If the difference between
2667 @code{gnus-summary-default-level} and the score is less than
2668 @code{gnus-summary-zcore-fuzz}, this spec will not be used.
2680 Number of articles in the current sub-thread. Using this spec will slow
2681 down summary buffer generation somewhat.
2683 A single character will be displayed if the article has any children.
2685 User defined specifier. The next character in the format string should
2686 be a letter. @sc{gnus} will call the function
2687 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
2688 following @samp{%u}. The function will be passed the current header as
2689 argument. The function should return a string, which will be inserted
2690 into the summary just like information from any other summary specifier.
2693 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
2694 have to be handled with care. For reasons of efficiency, Gnus will
2695 compute what column these characters will end up in, and ``hard-code''
2696 that. This means that it is illegal to have these specs after a
2697 variable-length spec. Well, you might not be arrested, but your summary
2698 buffer will look strange, which is bad enough.
2700 The smart choice is to have these specs as far to the left as possible.
2701 (Isn't that the case with everything, though? But I digress.)
2703 This restriction may disappear in later versions of Gnus.
2706 @node Summary Buffer Mode Line
2707 @subsection Summary Buffer Mode Line
2709 @vindex gnus-summary-mode-line-format
2710 You can also change the format of the summary mode bar. Set
2711 @code{gnus-summary-mode-line-format} to whatever you like. Here are the
2712 elements you can play with:
2718 Unprefixed group name.
2720 Current article number.
2724 Number of unread articles in this group.
2726 Number of unselected articles in this group.
2728 A string with the number of unread and unselected articles represented
2729 either as @samp{<%U(+%u) more>} if there are both unread and unselected
2730 articles, and just as @samp{<%U more>} if there are just unread articles
2731 and no unselected ones.
2733 Shortish group name. For instance, @samp{rec.arts.anime} will be
2734 shortened to @samp{r.a.anime}.
2736 Subject of the current article.
2740 Name of the current score file.
2742 Number of dormant articles.
2744 Number of ticked articles.
2746 Number of articles that have been marked as read in this session.
2748 Number of articles expunged by the score files.
2752 @node Summary Highlighting
2753 @subsection Summary Highlighting
2757 @item gnus-visual-mark-article-hook
2758 @vindex gnus-visual-mark-article-hook
2759 This hook is run after selecting an article. It is meant to be used for
2760 highlighting the article in some way. It is not run if
2761 @code{gnus-visual} is @code{nil}.
2763 @item gnus-summary-update-hook
2764 @vindex gnus-summary-update-hook
2765 This hook is called when a summary line is changed. It is not run if
2766 @code{gnus-visual} is @code{nil}.
2768 @item gnus-summary-selected-face
2769 @vindex gnus-summary-selected-face
2770 This is the face (or @dfn{font} as some people call it) that is used to
2771 highlight the current article in the summary buffer.
2773 @item gnus-summary-highlight
2774 @vindex gnus-summary-highlight
2775 Summary lines are highlighted according to this variable, which is a
2776 list where the elements are on the format @code{(FORM . FACE)}. If you
2777 would, for instance, like ticked articles to be italic and high-scored
2778 articles to be bold, you could set this variable to something like
2780 (((eq mark gnus-ticked-mark) . italic)
2781 ((> score default) . bold))
2783 As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
2784 @var{FACE} will be applied to the line.
2788 @node Summary Maneuvering
2789 @section Summary Maneuvering
2790 @cindex summary movement
2792 All the straight movement commands understand the numeric prefix and
2793 behave pretty much as you'd expect.
2795 None of these commands select articles.
2800 @kindex M-n (Summary)
2801 @kindex G M-n (Summary)
2802 @findex gnus-summary-next-unread-subject
2803 Go to the next summary line of an unread article
2804 (@code{gnus-summary-next-unread-subject}).
2808 @kindex M-p (Summary)
2809 @kindex G M-p (Summary)
2810 @findex gnus-summary-prev-unread-subject
2811 Go to the previous summary line of an unread article
2812 (@code{gnus-summary-prev-unread-subject}).
2817 @kindex G j (Summary)
2818 @findex gnus-summary-goto-article
2819 Ask for an article number and then go that article
2820 (@code{gnus-summary-goto-article}).
2823 @kindex G g (Summary)
2824 @findex gnus-summary-goto-subject
2825 Ask for an article number and then go the summary line of that article
2826 (@code{gnus-summary-goto-subject}).
2829 If Gnus asks you to press a key to confirm going to the next group, you
2830 can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
2831 buffer, searching for the next group to read without actually returning
2832 to the group buffer.
2834 Variables related to summary movement:
2838 @vindex gnus-auto-select-next
2839 @item gnus-auto-select-next
2840 If you are at the end of the group and issue one of the movement
2841 commands, Gnus will offer to go to the next group. If this variable is
2842 @code{t} and the next group is empty, Gnus will exit summary mode and
2843 return to the group buffer. If this variable is neither @code{t} nor
2844 @code{nil}, Gnus will select the next group, no matter whether it has
2845 any unread articles or not. As a special case, if this variable is
2846 @code{quietly}, Gnus will select the next group without asking for
2847 confirmation. If this variable is @code{almost-quietly}, the same will
2848 happen only if you are located on the last article in the group.
2849 Finally, if this variable is @code{slightly-quietly}, the @kbd{Z n}
2850 command will go to the next group without confirmation. Also
2851 @pxref{Group Levels}.
2853 @item gnus-auto-select-same
2854 @vindex gnus-auto-select-same
2855 If non-@code{nil}, all the movement commands will try to go to the next
2856 article with the same subject as the current. This variable is not
2857 particularly useful if you use a threaded display.
2859 @item gnus-summary-check-current
2860 @vindex gnus-summary-check-current
2861 If non-@code{nil}, all the ``unread'' movement commands will not proceed
2862 to the next (or previous) article if the current article is unread.
2863 Instead, they will choose the current article.
2865 @item gnus-auto-center-summary
2866 @vindex gnus-auto-center-summary
2867 If non-@code{nil}, Gnus will keep the point in the summary buffer
2868 centered at all times. This makes things quite tidy, but if you have a
2869 slow network connection, or simply do not like this un-Emacsism, you can
2870 set this variable to @code{nil} to get the normal Emacs scrolling
2871 action. This will also inhibit horizontal re-centering of the summary
2872 buffer, which might make it more inconvenient to read extremely long
2878 @node Choosing Articles
2879 @section Choosing Articles
2880 @cindex selecting articles
2882 None of the following movement commands understand the numeric prefix,
2883 and they all select and display an article.
2887 @kindex SPACE (Summary)
2888 @findex gnus-summary-next-page
2889 Select the current article, or, if that one's read already, the next
2890 unread article (@code{gnus-summary-next-page}).
2895 @kindex G n (Summary)
2896 @findex gnus-summary-next-unread-article
2897 Go to next unread article (@code{gnus-summary-next-unread-article}).
2902 @findex gnus-summary-prev-unread-article
2903 Go to previous unread article (@code{gnus-summary-prev-unread-article}).
2908 @kindex G N (Summary)
2909 @findex gnus-summary-next-article
2910 Go to the next article (@code{gnus-summary-next-article}).
2915 @kindex G P (Summary)
2916 @findex gnus-summary-prev-article
2917 Go to the previous article (@code{gnus-summary-prev-article}).
2920 @kindex G C-n (Summary)
2921 @findex gnus-summary-next-same-subject
2922 Go to the next article with the same subject
2923 (@code{gnus-summary-next-same-subject}).
2926 @kindex G C-p (Summary)
2927 @findex gnus-summary-prev-same-subject
2928 Go to the previous article with the same subject
2929 (@code{gnus-summary-prev-same-subject}).
2933 @kindex G f (Summary)
2935 @findex gnus-summary-first-unread-article
2936 Go to the first unread article
2937 (@code{gnus-summary-first-unread-article}).
2941 @kindex G b (Summary)
2943 @findex gnus-summary-best-unread-article
2944 Go to the article with the highest score
2945 (@code{gnus-summary-best-unread-article}).
2950 @kindex G l (Summary)
2951 @findex gnus-summary-goto-last-article
2952 Go to the previous article read (@code{gnus-summary-goto-last-article}).
2955 @kindex G p (Summary)
2956 @findex gnus-summary-pop-article
2957 Pop an article off the summary history and go to this article
2958 (@code{gnus-summary-pop-article}). This command differs from the
2959 command above in that you can pop as many previous articles off the
2960 history as you like.
2963 Some variables that are relevant for moving and selecting articles:
2966 @item gnus-auto-extend-newsgroup
2967 @vindex gnus-auto-extend-newsgroup
2968 All the movement commands will try to go to the previous (or next)
2969 article, even if that article isn't displayed in the Summary buffer if
2970 this variable is non-@code{nil}. Gnus will then fetch the article from
2971 the server and display it in the article buffer.
2973 @item gnus-select-article-hook
2974 @vindex gnus-select-article-hook
2975 This hook is called whenever an article is selected. By default it
2976 exposes any threads hidden under the selected article.
2978 @item gnus-mark-article-hook
2979 @vindex gnus-mark-article-hook
2980 @findex gnus-summary-mark-unread-as-read
2981 @findex gnus-summary-mark-read-and-unread-as-read
2982 @findex gnus-unread-mark
2983 This hook is called whenever an article is selected. It is intended to
2984 be used for marking articles as read. The default value is
2985 @code{gnus-summary-mark-unread-and-read-as-read}, and will change the
2986 mark of almost any article you read to @code{gnus-unread-mark}. The
2987 only articles not affected by this function are ticked, dormant, and
2988 expirable articles. If you'd instead like to just have unread articles
2989 marked as read, you can use @code{gnus-summary-mark-unread-as-read}
2990 instead. It will leave marks like @code{gnus-low-score-mark},
2991 @code{gnus-del-mark} (and so on) alone.
2996 @node Paging the Article
2997 @section Scrolling the Article
2998 @cindex article scrolling
3003 @kindex SPACE (Summary)
3004 @findex gnus-summary-next-page
3005 Pressing @kbd{SPACE} will scroll the current article forward one page,
3006 or, if you have come to the end of the current article, will choose the
3007 next article (@code{gnus-summary-next-page}).
3010 @kindex DEL (Summary)
3011 @findex gnus-summary-prev-page
3012 Scroll the current article back one page (@code{gnus-summary-prev-page}).
3015 @kindex RET (Summary)
3016 @findex gnus-summary-scroll-up
3017 Scroll the current article one line forward
3018 (@code{gnus-summary-scroll-up}).
3023 @kindex A < (Summary)
3024 @findex gnus-summary-beginning-of-article
3025 Scroll to the beginning of the article
3026 (@code{gnus-summary-beginning-of-article}).
3031 @kindex A > (Summary)
3032 @findex gnus-summary-end-of-article
3033 Scroll to the end of the article (@code{gnus-summary-end-of-article}).
3036 @kindex A s (Summary)
3037 @findex gnus-summary-isearch-article
3038 Perform an isearch in the article buffer
3039 (@code{gnus-summary-isearch-article}).
3044 @node Reply Followup and Post
3045 @section Reply, Followup and Post
3048 * Summary Mail Commands:: Sending mail.
3049 * Summary Post Commands:: Sending news.
3050 * Summary Mail and Post Commands:: Sending both news and mail.
3054 @node Summary Mail Commands
3055 @subsection Summary Mail Commands
3057 @cindex composing mail
3059 Commands for composing a mail message:
3065 @kindex S r (Summary)
3067 @findex gnus-summary-reply
3068 Mail a reply to the author of the current article
3069 (@code{gnus-summary-reply}).
3074 @kindex S R (Summary)
3075 @findex gnus-summary-reply-with-original
3076 Mail a reply to the author of the current article and include the
3077 original message (@code{gnus-summary-reply-with-original}). This
3078 command uses the process/prefix convention.
3081 @kindex S o m (Summary)
3082 @findex gnus-summary-mail-forward
3083 Forward the current article to some other person
3084 (@code{gnus-summary-mail-forward}).
3087 @kindex S o p (Summary)
3088 @findex gnus-summary-post-forward
3089 Forward the current article to a newsgroup
3090 (@code{gnus-summary-post-forward}).
3095 @kindex S m (Summary)
3096 @findex gnus-summary-mail-other-window
3097 Send a mail to some other person
3098 (@code{gnus-summary-mail-other-window}).
3101 @kindex S D b (Summary)
3102 @findex gnus-summary-resend-bounced-mail
3103 @vindex gnus-bounced-headers-junk
3104 @cindex bouncing mail
3105 If you have sent a mail, but the mail was bounced back to you for some
3106 reason (wrong address, transient failure), you can use this command to
3107 resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
3108 will be popped into a mail buffer where you can edit the headers before
3109 sending the mail off again. The headers that match the regexp
3110 @code{gnus-bounced-headers-junk} (default @samp{^Received:}) are
3111 automatically deleted first. If you give a prefix to this command, and
3112 the bounced mail is a reply to some other mail, Gnus will try to fetch
3113 that mail and display it for easy perusal of its headers. This might
3114 very well fail, though.
3117 @kindex S D r (Summary)
3118 @findex gnus-summary-resend-message
3119 @vindex gnus-ignored-resent-headers
3120 Not to be confused with the previous command,
3121 @code{gnus-summary-resend-message} will prompt you for an address to
3122 send the current message off to, and then send it to that place. The
3123 headers of the message won't be altered---but lots of headers that say
3124 @code{Resent-To}, @code{Resent-From} and so on will be added. This
3125 means that you actually send a mail to someone that has a @code{To}
3126 header that (probably) points to yourself. This will confuse people.
3127 So, natcherly you'll only do that if you're really eVIl. All old
3128 headers that match the regular expression
3129 @code{gnus-ignored-resent-headers} will be deleted before resending the
3130 message. The default is @samp{"^Return-receipt"}.
3132 This command is mainly used if you have several accounts and want to
3133 ship a mail to a different account of yours. (If you're both
3134 @code{root} and @code{postmaster} and get a mail for @code{postmaster}
3135 to the @code{root} account, you may want to resend it to
3136 @code{postmaster}. Ordnung muss sein!
3139 @kindex S O m (Summary)
3140 @findex gnus-uu-digest-mail-forward
3141 Digest the current series and forward the result using mail
3142 (@code{gnus-uu-digest-mail-forward}). This command uses the
3143 process/prefix convention (@pxref{Process/Prefix}).
3146 @kindex S O p (Summary)
3147 @findex gnus-uu-digest-post-forward
3148 Digest the current series and forward the result to a newsgroup
3149 (@code{gnus-uu-digest-mail-forward}).
3153 @node Summary Post Commands
3154 @subsection Summary Post Commands
3156 @cindex composing news
3158 Commands for posting an article:
3164 @kindex S p (Summary)
3165 @findex gnus-summary-post-news
3166 Post an article to the current group
3167 (@code{gnus-summary-post-news}).
3172 @kindex S f (Summary)
3173 @findex gnus-summary-followup
3174 Post a followup to the current article (@code{gnus-summary-followup}).
3178 @kindex S F (Summary)
3180 @findex gnus-summary-followup-with-original
3181 Post a followup to the current article and include the original message
3182 (@code{gnus-summary-followup-with-original}). This command uses the
3183 process/prefix convention.
3186 @kindex S u (Summary)
3187 @findex gnus-uu-post-news
3188 Uuencode a file, split it into parts, and post it as a series
3189 (@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}).
3193 @node Summary Mail and Post Commands
3194 @subsection Summary Mail and Post Commands
3195 @cindex mail and post
3196 @cindex post and mail
3198 Commands for sending mail and post at the same time:
3202 @kindex S b (Summary)
3203 @findex gnus-summary-followup-and-reply
3204 Post a followup and send a reply to the current article
3205 (@code{gnus-summary-followup-and-reply}).
3208 @kindex S B (Summary)
3209 @findex gnus-summary-followup-and-reply-with-original
3210 Post a followup and send a reply to the current article and include the
3211 original message (@code{gnus-summary-followup-and-reply-with-original}).
3212 This command uses the process/prefix convention.
3216 @node Canceling and Superseding
3217 @section Canceling Articles
3218 @cindex canceling articles
3219 @cindex superseding articles
3221 Have you ever written something, and then decided that you really,
3222 really, really wish you hadn't posted that?
3224 Well, you can't cancel mail, but you can cancel posts.
3226 @findex gnus-summary-cancel-article
3228 Find the article you wish to cancel (you can only cancel your own
3229 articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
3230 c} (@code{gnus-summary-cancel-article}). Your article will be
3231 canceled---machines all over the world will be deleting your article.
3233 Be aware, however, that not all sites honor cancels, so your article may
3234 live on here and there, while most sites will delete the article in
3237 If you discover that you have made some mistakes and want to do some
3238 corrections, you can post a @dfn{superseding} article that will replace
3239 your original article.
3241 @findex gnus-summary-supersede-article
3243 Go to the original article and press @kbd{S s}
3244 (@code{gnus-summary-supersede-article}). You will be put in a buffer
3245 where you can edit the article all you want before sending it off the
3248 @vindex gnus-delete-supersedes-headers
3249 You probably want to delete some of the old headers before sending the
3250 superseding article---@code{Path} and @code{Date} are probably
3251 incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
3252 match the lines you want removed. The default is
3253 @samp{^Path:\\|^Date}.
3255 The same goes for superseding as for canceling, only more so: Some
3256 sites do not honor superseding. On those sites, it will appear that you
3257 have posted almost the same article twice.
3259 If you have just posted the article, and change your mind right away,
3260 there is a trick you can use to cancel/supersede the article without
3261 waiting for the article to appear on your site first. You simply return
3262 to the post buffer (which is called @code{*post-buf*}). There you will
3263 find the article you just posted, with all the headers intact. Change
3264 the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes}
3265 header by substituting one of those words for @code{Message-ID}. Then
3266 just press @kbd{C-c C-c} to send the article as you would do normally.
3267 The previous article will be canceled/superseded.
3269 Just remember, kids: There is no 'c' in 'supersede'.
3272 @node Marking Articles
3273 @section Marking Articles
3274 @cindex article marking
3275 @cindex article ticking
3278 There are several marks you can set on an article.
3280 You have marks that decide the @dfn{readedness} (whoo, neato-keano
3281 neologism ohoy!) of the article. Alphabetic marks generally mean
3282 @dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
3284 In addition, you also have marks that do not affect readedness.
3287 * Unread Articles:: Marks for unread articles.
3288 * Read Articles:: Marks for read articles.
3289 * Other Marks:: Marks that do not affect readedness.
3293 There's a plethora of commands for manipulating these marks:
3297 * Setting Marks:: How to set and remove marks.
3298 * Setting Process Marks:: How to mark articles for later processing.
3302 @node Unread Articles
3303 @subsection Unread Articles
3305 The following marks mark articles as unread, in one form or other.
3307 @vindex gnus-dormant-mark
3308 @vindex gnus-ticked-mark
3311 @dfn{Ticked articles} are articles that will remain visible always. If
3312 you see an article that you find interesting, or you want to put off
3313 reading it, or replying to it, until sometime later, you'd typically
3314 tick it. However, articles can be expired, so if you want to keep an
3315 article forever, you'll have to save it. Ticked articles have a
3316 @samp{!} (@code{gnus-ticked-mark}) in the first column.
3319 @vindex gnus-dormant-mark
3320 A @dfn{dormant} article is marked with a @samp{?}
3321 (@code{gnus-dormant-mark}), and will only appear in the summary buffer
3322 if there are followups to it.
3325 @vindex gnus-unread-mark
3326 An @dfn{unread} article is marked with a @samp{SPACE}
3327 (@code{gnus-unread-mark}). These are articles that haven't been read at
3333 @subsection Read Articles
3334 @cindex expirable mark
3336 All the following marks mark articles as read.
3341 @vindex gnus-del-mark
3342 Articles that are marked as read. They have a @samp{r}
3343 (@code{gnus-del-mark}) in the first column. These are articles that the
3344 user has marked as read more or less manually.
3347 @vindex gnus-read-mark
3348 Articles that are actually read are marked with @samp{R}
3349 (@code{gnus-read-mark}).
3352 @vindex gnus-ancient-mark
3353 Articles that were marked as read in previous sessions are now
3354 @dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
3357 @vindex gnus-killed-mark
3358 Marked as killed (@code{gnus-killed-mark}).
3361 @vindex gnus-kill-file-mark
3362 Marked as killed by kill files (@code{gnus-kill-file-mark}).
3365 @vindex gnus-low-score-mark
3366 Marked as read by having a too low score (@code{gnus-low-score-mark}).
3369 @vindex gnus-catchup-mark
3370 Marked as read by a catchup (@code{gnus-catchup-mark}).
3373 @vindex gnus-canceled-mark
3374 Canceled article (@code{gnus-canceled-mark})
3377 @vindex gnus-souped-mark
3378 @sc{SOUP}ed article (@code{gnus-souped-mark}).
3381 @vindex gnus-sparse-mark
3382 Sparsely reffed article (@code{gnus-sparse-mark}).
3385 All these marks just mean that the article is marked as read, really.
3386 They are interpreted differently by the adaptive scoring scheme,
3389 One more special mark, though:
3393 @vindex gnus-expirable-mark
3394 You can also mark articles as @dfn{expirable} (or have them marked as
3395 such automatically). That doesn't make much sense in normal groups,
3396 because a user does not control the expiring of news articles, but in
3397 mail groups, for instance, articles that are marked as @dfn{expirable}
3398 can be deleted by Gnus at any time. Expirable articles are marked with
3399 @samp{E} (@code{gnus-expirable-mark}).
3404 @subsection Other Marks
3405 @cindex process mark
3408 There are some marks that have nothing to do with whether the article is
3414 You can set a bookmark in the current article. Say you are reading a
3415 long thesis on cats' urinary tracts, and have to go home for dinner
3416 before you've finished reading the thesis. You can then set a bookmark
3417 in the article, and Gnus will jump to this bookmark the next time it
3418 encounters the article.
3421 @vindex gnus-replied-mark
3422 All articles that you have replied to or made a followup to (i.e., have
3423 answered) will be marked with an @samp{A} in the second column
3424 (@code{gnus-replied-mark}).
3427 @vindex gnus-cached-mark
3428 Articles that are stored in the article cache will be marked with an
3429 @samp{*} in the second column (@code{gnus-cached-mark}).
3432 @vindex gnus-saved-mark
3433 Articles that are ``saved'' (in some manner or other; not necessarily
3434 religiously) are marked with an @samp{S} in the second column
3435 (@code{gnus-saved-mark}.
3438 @vindex gnus-not-empty-thread-mark
3439 @vindex gnus-empty-thread-mark
3440 It the @samp{%e} spec is used, the presence of threads or not will be
3441 marked with @code{gnus-not-empty-thread-mark} and
3442 @code{gnus-empty-thread-mark} in the third column, respectively.
3445 @vindex gnus-process-mark
3446 Finally we have the @dfn{process mark} (@code{gnus-process-mark}. A
3447 variety of commands react to the presence of the process mark. For
3448 instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
3449 all articles that have been marked with the process mark. Articles
3450 marked with the process mark have a @samp{#} in the second column.
3454 You might have noticed that most of these ``non-readedness'' marks
3455 appear in the second column by default. So if you have a cached, saved,
3456 replied article that you have process-marked, what will that look like?
3458 Nothing much. The precedence rules go as follows: process -> cache ->
3459 replied -> saved. So if the article is in the cache and is replied,
3460 you'll only see the cache mark and not the replied mark.
3464 @subsection Setting Marks
3465 @cindex setting marks
3467 All the marking commands understand the numeric prefix.
3473 @kindex M t (Summary)
3474 @findex gnus-summary-tick-article-forward
3475 Tick the current article (@code{gnus-summary-tick-article-forward}).
3480 @kindex M ? (Summary)
3481 @findex gnus-summary-mark-as-dormant
3482 Mark the current article as dormant
3483 (@code{gnus-summary-mark-as-dormant}).
3487 @kindex M d (Summary)
3489 @findex gnus-summary-mark-as-read-forward
3490 Mark the current article as read
3491 (@code{gnus-summary-mark-as-read-forward}).
3496 @kindex M k (Summary)
3497 @findex gnus-summary-kill-same-subject-and-select
3498 Mark all articles that have the same subject as the current one as read,
3499 and then select the next unread article
3500 (@code{gnus-summary-kill-same-subject-and-select}).
3504 @kindex M K (Summary)
3505 @kindex C-k (Summary)
3506 @findex gnus-summary-kill-same-subject
3507 Mark all articles that have the same subject as the current one as read
3508 (@code{gnus-summary-kill-same-subject}).
3511 @kindex M C (Summary)
3512 @findex gnus-summary-catchup
3513 Mark all unread articles in the group as read
3514 (@code{gnus-summary-catchup}).
3517 @kindex M C-c (Summary)
3518 @findex gnus-summary-catchup-all
3519 Mark all articles in the group as read---even the ticked and dormant
3520 articles (@code{gnus-summary-catchup-all}).
3523 @kindex M H (Summary)
3524 @findex gnus-summary-catchup-to-here
3525 Catchup the current group to point
3526 (@code{gnus-summary-catchup-to-here}).
3529 @kindex C-w (Summary)
3530 @findex gnus-summary-mark-region-as-read
3531 Mark all articles between point and mark as read
3532 (@code{gnus-summary-mark-region-as-read}).
3535 @kindex M V k (Summary)
3536 @findex gnus-summary-kill-below
3537 Kill all articles with scores below the default score (or below the
3538 numeric prefix) (@code{gnus-summary-kill-below}).
3542 @kindex M c (Summary)
3543 @kindex M-u (Summary)
3544 @findex gnus-summary-clear-mark-forward
3545 Clear all readedness-marks from the current article
3546 (@code{gnus-summary-clear-mark-forward}).
3550 @kindex M e (Summary)
3552 @findex gnus-summary-mark-as-expirable
3553 Mark the current article as expirable
3554 (@code{gnus-summary-mark-as-expirable}).
3557 @kindex M b (Summary)
3558 @findex gnus-summary-set-bookmark
3559 Set a bookmark in the current article
3560 (@code{gnus-summary-set-bookmark}).
3563 @kindex M B (Summary)
3564 @findex gnus-summary-remove-bookmark
3565 Remove the bookmark from the current article
3566 (@code{gnus-summary-remove-bookmark}).
3569 @kindex M V c (Summary)
3570 @findex gnus-summary-clear-above
3571 Clear all marks from articles with scores over the default score (or
3572 over the numeric prefix) (@code{gnus-summary-clear-above}).
3575 @kindex M V u (Summary)
3576 @findex gnus-summary-tick-above
3577 Tick all articles with scores over the default score (or over the
3578 numeric prefix) (@code{gnus-summary-tick-above}).
3581 @kindex M V m (Summary)
3582 @findex gnus-summary-mark-above
3583 Prompt for a mark, and mark all articles with scores over the default
3584 score (or over the numeric prefix) with this mark
3585 (@code{gnus-summary-clear-above}).
3588 @vindex gnus-summary-goto-unread
3589 The @code{gnus-summary-goto-unread} variable controls what action should
3590 be taken after setting a mark. If non-@code{nil}, point will move to
3591 the next/previous unread article. If @code{nil}, point will just move
3592 one line up or down. As a special case, if this variable is
3593 @code{never}, all the marking commands as well as other commands (like
3594 @kbd{SPACE}) will move to the next article, whether it is unread or not.
3595 The default is @code{t}.
3598 @node Setting Process Marks
3599 @subsection Setting Process Marks
3600 @cindex setting process marks
3607 @kindex M P p (Summary)
3608 @findex gnus-summary-mark-as-processable
3609 Mark the current article with the process mark
3610 (@code{gnus-summary-mark-as-processable}).
3611 @findex gnus-summary-unmark-as-processable
3615 @kindex M P u (Summary)
3616 @kindex M-# (Summary)
3617 Remove the process mark, if any, from the current article
3618 (@code{gnus-summary-unmark-as-processable}).
3621 @kindex M P U (Summary)
3622 @findex gnus-summary-unmark-all-processable
3623 Remove the process mark from all articles
3624 (@code{gnus-summary-unmark-all-processable}).
3627 @kindex M P R (Summary)
3628 @findex gnus-uu-mark-by-regexp
3629 Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
3632 @kindex M P r (Summary)
3633 @findex gnus-uu-mark-region
3634 Mark articles in region (@code{gnus-uu-mark-region}).
3637 @kindex M P t (Summary)
3638 @findex gnus-uu-mark-thread
3639 Mark all articles in the current (sub)thread
3640 (@code{gnus-uu-mark-thread}).
3643 @kindex M P T (Summary)
3644 @findex gnus-uu-unmark-thread
3645 Unmark all articles in the current (sub)thread
3646 (@code{gnus-uu-unmark-thread}).
3649 @kindex M P v (Summary)
3650 @findex gnus-uu-mark-over
3651 Mark all articles that have a score above the prefix argument
3652 (@code{gnus-uu-mark-over}).
3655 @kindex M P s (Summary)
3656 @findex gnus-uu-mark-series
3657 Mark all articles in the current series (@code{gnus-uu-mark-series}).
3660 @kindex M P S (Summary)
3661 @findex gnus-uu-mark-sparse
3662 Mark all series that have already had some articles marked
3663 (@code{gnus-uu-mark-sparse}).
3666 @kindex M P a (Summary)
3667 @findex gnus-uu-mark-all
3668 Mark all articles in series order (@code{gnus-uu-mark-series}).
3671 @kindex M P b (Summary)
3672 @findex gnus-uu-mark-buffer
3673 Mark all articles in the buffer in the order they appear
3674 (@code{gnus-uu-mark-buffer}).
3682 It can be convenient to limit the summary buffer to just show some
3683 subset of the articles currently in the group. The effect most limit
3684 commands have is to remove a few (or many) articles from the summary
3691 @kindex / / (Summary)
3692 @findex gnus-summary-limit-to-subject
3693 Limit the summary buffer to articles that match some subject
3694 (@code{gnus-summary-limit-to-subject}).
3697 @kindex / a (Summary)
3698 @findex gnus-summary-limit-to-author
3699 Limit the summary buffer to articles that match some author
3700 (@code{gnus-summary-limit-to-author}).
3704 @kindex / u (Summary)
3706 @findex gnus-summary-limit-to-unread
3707 Limit the summary buffer to articles that are not marked as read
3708 (@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
3709 buffer to articles that are strictly unread. This means that ticked and
3710 dormant articles will also be excluded.
3713 @kindex / m (Summary)
3714 @findex gnus-summary-limit-to-marks
3715 Ask for a mark and then limit to all articles that have not been marked
3716 with that mark (@code{gnus-summary-limit-to-marks}).
3719 @kindex / n (Summary)
3720 @findex gnus-summary-limit-to-articles
3721 Limit the summary buffer to the current article
3722 (@code{gnus-summary-limit-to-articles}). Uses the process/prefix
3723 convention (@pxref{Process/Prefix}).
3726 @kindex / w (Summary)
3727 @findex gnus-summary-pop-limit
3728 Pop the previous limit off the stack and restore it
3729 (@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
3733 @kindex / v (Summary)
3734 @findex gnus-summary-limit-to-score
3735 Limit the summary buffer to articles that have a score at or above some
3736 score (@code{gnus-summary-limit-to-score}).
3740 @kindex M S (Summary)
3741 @kindex / E (Summary)
3742 @findex gnus-summary-limit-include-expunged
3743 Display all expunged articles
3744 (@code{gnus-summary-limit-include-expunged}).
3747 @kindex / D (Summary)
3748 @findex gnus-summary-limit-include-dormant
3749 Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
3752 @kindex / d (Summary)
3753 @findex gnus-summary-limit-exclude-dormant
3754 Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
3757 @kindex / c (Summary)
3758 @findex gnus-summary-limit-exclude-childless-dormant
3759 Hide all dormant articles that have no children
3760 (@code{gnus-summary-limit-exclude-childless-dormant}).
3763 @kindex / C (Summary)
3764 @findex gnus-summary-limit-mark-excluded-as-read
3765 Mark all excluded unread articles as read
3766 (@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix,
3767 also mark excluded ticked and dormant articles as read.
3775 @cindex article threading
3777 Gnus threads articles by default. @dfn{To thread} is to put replies to
3778 articles directly after the articles they reply to---in a hierarchical
3782 * Customizing Threading:: Variables you can change to affect the threading.
3783 * Thread Commands:: Thread based commands in the summary buffer.
3787 @node Customizing Threading
3788 @subsection Customizing Threading
3789 @cindex customizing threading
3795 @item gnus-show-threads
3796 @vindex gnus-show-threads
3797 If this variable is @code{nil}, no threading will be done, and all of
3798 the rest of the variables here will have no effect. Turning threading
3799 off will speed group selection up a bit, but it is sure to make reading
3800 slower and more awkward.
3802 @item gnus-fetch-old-headers
3803 @vindex gnus-fetch-old-headers
3804 If non-@code{nil}, Gnus will attempt to build old threads by fetching
3805 more old headers---headers to articles that are marked as read. If you
3806 would like to display as few summary lines as possible, but still
3807 connect as many loose threads as possible, you should set this variable
3808 to @code{some} or a number. If you set it to a number, no more than
3809 that number of extra old headers will be fetched. In either case,
3810 fetching old headers only works if the backend you are using carries
3811 overview files---this would normally be @code{nntp}, @code{nnspool} and
3812 @code{nnml}. Also remember that if the root of the thread has been
3813 expired by the server, there's not much Gnus can do about that.
3815 @item gnus-build-sparse-threads
3816 @vindex gnus-build-sparse-threads
3817 Fetching old headers can be slow. A low-rent similar effect can be
3818 gotten by setting this variable to @code{some}. Gnus will then look at
3819 the complete @code{References} headers of all articles and try to string
3820 articles that belong in the same thread together. This will leave
3821 @dfn{gaps} in the threading display where Gnus guesses that an article
3822 is missing from the thread. (These gaps appear like normal summary
3823 lines. If you select a gap, Gnus will try to fetch the article in
3824 question.) If this variable is @code{t}, Gnus will display all these
3825 ``gaps'' without regard for whether they are useful for completing the
3826 thread or not. Finally, if this variable is @code{more}, Gnus won't cut
3827 off sparse leaf nodes that don't lead anywhere. This variable is
3828 @code{nil} by default.
3830 @item gnus-summary-gather-subject-limit
3831 @vindex gnus-summary-gather-subject-limit
3832 Loose threads are gathered by comparing subjects of articles. If this
3833 variable is @code{nil}, Gnus requires an exact match between the
3834 subjects of the loose threads before gathering them into one big
3835 super-thread. This might be too strict a requirement, what with the
3836 presence of stupid newsreaders that chop off long subjects lines. If
3837 you think so, set this variable to, say, 20 to require that only the
3838 first 20 characters of the subjects have to match. If you set this
3839 variable to a really low number, you'll find that Gnus will gather
3840 everything in sight into one thread, which isn't very helpful.
3842 @cindex fuzzy article gathering
3843 If you set this variable to the special value @code{fuzzy}, Gnus will
3844 use a fuzzy string comparison algorithm on the subjects.
3846 @item gnus-simplify-subject-fuzzy-regexp
3847 @vindex gnus-simplify-subject-fuzzy-regexp
3848 This can either be a regular expression or list of regular expressions
3849 that match strings that will be removed from subjects if fuzzy subject
3850 simplification is used.
3852 @item gnus-simplify-ignored-prefixes
3853 @vindex gnus-simplify-ignored-prefixes
3854 If you set @code{gnus-summary-gather-subject-limit} to something as low
3855 as 10, you might consider setting this variable to something sensible:
3857 @c Written by Michael Ernst <mernst@cs.rice.edu>
3859 (setq gnus-simplify-ignored-prefixes
3862 (mapconcat 'identity
3864 "wanted" "followup" "summary\\( of\\)?"
3865 "help" "query" "problem" "question"
3866 "answer" "reference" "announce"
3867 "How can I" "How to" "Comparison of"
3872 (mapconcat 'identity
3873 '("for" "for reference" "with" "about")
3875 "\\)?\\]?:?[ \t]*"))
3878 All words that match this regexp will be removed before comparing two
3881 @item gnus-summary-gather-exclude-subject
3882 @vindex gnus-summary-gather-exclude-subject
3883 Since loose thread gathering is done on subjects only, that might lead
3884 to many false hits, especially with certain common subjects like
3885 @samp{} and @samp{(none)}. To make the situation slightly better,
3886 you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
3887 what subjects should be excluded from the gathering process. The
3888 default is @samp{^ *$\\|^(none)$}.
3890 @item gnus-summary-thread-gathering-function
3891 @vindex gnus-summary-thread-gathering-function
3892 Gnus gathers threads by looking at @code{Subject} headers. This means
3893 that totally unrelated articles may end up in the same ``thread'', which
3894 is confusing. An alternate approach is to look at all the
3895 @code{Message-ID}s in all the @code{References} headers to find matches.
3896 This will ensure that no gathered threads ever includes unrelated
3897 articles, but it's also means that people who have posted with broken
3898 newsreaders won't be gathered properly. The choice is yours---plague or
3902 @item gnus-gather-threads-by-subject
3903 @findex gnus-gather-threads-by-subject
3904 This function is the default gathering function and looks at
3905 @code{Subject}s exclusively.
3907 @item gnus-gather-threads-by-references
3908 @findex gnus-gather-threads-by-references
3909 This function looks at @code{References} headers exclusively.
3912 If you want to test gathering by @code{References}, you could say
3916 (setq gnus-summary-thread-gathering-function
3917 'gnus-gather-threads-by-references)
3920 @item gnus-summary-make-false-root
3921 @vindex gnus-summary-make-false-root
3922 If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
3923 and create a dummy root at the top. (Wait a minute. Root at the top?
3924 Yup.) Loose subtrees occur when the real root has expired, or you've
3925 read or killed the root in a previous session.
3927 When there is no real root of a thread, Gnus will have to fudge
3928 something. This variable says what fudging method Gnus should use.
3929 There are four possible values:
3931 @cindex adopting articles
3936 Gnus will make the first of the orphaned articles the parent. This
3937 parent will adopt all the other articles. The adopted articles will be
3938 marked as such by pointy brackets (@samp{<>}) instead of the standard
3939 square brackets (@samp{[]}). This is the default method.
3942 @vindex gnus-summary-dummy-line-format
3943 Gnus will create a dummy summary line that will pretend to be the
3944 parent. This dummy line does not correspond to any real article, so
3945 selecting it will just select the first real article after the dummy
3946 article. @code{gnus-summary-dummy-line-format} is used to specify the
3947 format of the dummy roots. It accepts only one format spec: @samp{S},
3948 which is the subject of the article. @xref{Formatting Variables}.
3951 Gnus won't actually make any article the parent, but simply leave the
3952 subject field of all orphans except the first empty. (Actually, it will
3953 use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
3957 Don't make any article parent at all. Just gather the threads and
3958 display them after one another.
3961 Don't gather loose threads.
3964 @item gnus-thread-hide-subtree
3965 @vindex gnus-thread-hide-subtree
3966 If non-@code{nil}, all threads will be hidden when the summary buffer is
3969 @item gnus-thread-hide-killed
3970 @vindex gnus-thread-hide-killed
3971 if you kill a thread and this variable is non-@code{nil}, the subtree
3974 @item gnus-thread-ignore-subject
3975 @vindex gnus-thread-ignore-subject
3976 Sometimes somebody changes the subject in the middle of a thread. If
3977 this variable is non-@code{nil}, the subject change is ignored. If it
3978 is @code{nil}, which is the default, a change in the subject will result
3981 @item gnus-thread-indent-level
3982 @vindex gnus-thread-indent-level
3983 This is a number that says how much each sub-thread should be indented.
3984 The default is @code{4}.
3988 @node Thread Commands
3989 @subsection Thread Commands
3990 @cindex thread commands
3996 @kindex T k (Summary)
3997 @kindex M-C-k (Summary)
3998 @findex gnus-summary-kill-thread
3999 Mark all articles in the current sub-thread as read
4000 (@code{gnus-summary-kill-thread}). If the prefix argument is positive,
4001 remove all marks instead. If the prefix argument is negative, tick
4006 @kindex T l (Summary)
4007 @kindex M-C-l (Summary)
4008 @findex gnus-summary-lower-thread
4009 Lower the score of the current thread
4010 (@code{gnus-summary-lower-thread}).
4013 @kindex T i (Summary)
4014 @findex gnus-summary-raise-thread
4015 Increase the score of the current thread
4016 (@code{gnus-summary-raise-thread}).
4019 @kindex T # (Summary)
4020 @findex gnus-uu-mark-thread
4021 Set the process mark on the current thread
4022 (@code{gnus-uu-mark-thread}).
4025 @kindex T M-# (Summary)
4026 @findex gnus-uu-unmark-thread
4027 Remove the process mark from the current thread
4028 (@code{gnus-uu-unmark-thread}).
4031 @kindex T T (Summary)
4032 @findex gnus-summary-toggle-threads
4033 Toggle threading (@code{gnus-summary-toggle-threads}).
4036 @kindex T s (Summary)
4037 @findex gnus-summary-show-thread
4038 Expose the thread hidden under the current article, if any
4039 (@code{gnus-summary-show-thread}).
4042 @kindex T h (Summary)
4043 @findex gnus-summary-hide-thread
4044 Hide the current (sub)thread (@code{gnus-summary-hide-thread}).
4047 @kindex T S (Summary)
4048 @findex gnus-summary-show-all-threads
4049 Expose all hidden threads (@code{gnus-summary-show-all-threads}).
4052 @kindex T H (Summary)
4053 @findex gnus-summary-hide-all-threads
4054 Hide all threads (@code{gnus-summary-hide-all-threads}).
4057 @kindex T t (Summary)
4058 @findex gnus-summary-rethread-current
4059 Re-thread the thread the current article is part of
4060 (@code{gnus-summary-rethread-current}). This works even when the
4061 summary buffer is otherwise unthreaded.
4064 @kindex T ^ (Summary)
4065 @findex gnus-summary-reparent-thread
4066 Make the current article the child of the marked (or previous) article
4067 (@code{gnus-summary-reparent-thread}.
4071 The following commands are thread movement commands. They all
4072 understand the numeric prefix.
4077 @kindex T n (Summary)
4078 @findex gnus-summary-next-thread
4079 Go to the next thread (@code{gnus-summary-next-thread}).
4082 @kindex T p (Summary)
4083 @findex gnus-summary-prev-thread
4084 Go to the previous thread (@code{gnus-summary-prev-thread}).
4087 @kindex T d (Summary)
4088 @findex gnus-summary-down-thread
4089 Descend the thread (@code{gnus-summary-down-thread}).
4092 @kindex T u (Summary)
4093 @findex gnus-summary-up-thread
4094 Ascend the thread (@code{gnus-summary-up-thread}).
4097 @kindex T o (Summary)
4098 @findex gnus-summary-top-thread
4099 Go to the top of the thread (@code{gnus-summary-top-thread}).
4102 @vindex gnus-thread-operation-ignore-subject
4103 If you ignore subject while threading, you'll naturally end up with
4104 threads that have several different subjects in them. If you then issue
4105 a command like `T k' (@code{gnus-summary-kill-thread}) you might not
4106 wish to kill the entire thread, but just those parts of the thread that
4107 have the same subject as the current article. If you like this idea,
4108 you can fiddle with @code{gnus-thread-operation-ignore-subject}. If is
4109 is non-@code{nil} (which it is by default), subjects will be ignored
4110 when doing thread commands. If this variable is @code{nil}, articles in
4111 the same thread with different subjects will not be included in the
4112 operation in question. If this variable is @code{fuzzy}, only articles
4113 that have subjects that are fuzzily equal will be included.
4116 @node Asynchronous Fetching
4117 @section Asynchronous Article Fetching
4118 @cindex asynchronous article fetching
4120 If you read your news from an @sc{nntp} server that's far away, the
4121 network latencies may make reading articles a chore. You have to wait
4122 for a while after pressing @kbd{n} to go to the next article before the
4123 article appears. Why can't Gnus just go ahead and fetch the article
4124 while you are reading the previous one? Why not, indeed.
4126 First, some caveats. There are some pitfalls to using asynchronous
4127 article fetching, especially the way Gnus does it.
4129 Let's say you are reading article 1, which is short, and article 2 is
4130 quite long, and you are not interested in reading that. Gnus does not
4131 know this, so it goes ahead and fetches article 2. You decide to read
4132 article 3, but since Gnus is in the process of fetching article 2, the
4133 connection is blocked.
4135 To avoid these situations, Gnus will open two (count 'em two)
4136 connections to the server. Some people may think this isn't a very nice
4137 thing to do, but I don't see any real alternatives. Setting up that
4138 extra connection takes some time, so Gnus startup will be slower.
4140 Gnus will fetch more articles than you will read. This will mean that
4141 the link between your machine and the @sc{nntp} server will become more
4142 loaded than if you didn't use article pre-fetch. The server itself will
4143 also become more loaded---both with the extra article requests, and the
4146 Ok, so now you know that you shouldn't really use this thing... unless
4149 @vindex gnus-asynchronous
4150 Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
4151 happen automatically.
4153 @vindex nntp-async-number
4154 You can control how many articles that are to be pre-fetched by setting
4155 @code{nntp-async-number}. This is five by default, which means that when
4156 you read an article in the group, @code{nntp} will pre-fetch the next
4157 five articles. If this variable is @code{t}, @code{nntp} will pre-fetch
4158 all the articles that it can without bound. If it is @code{nil}, no
4159 pre-fetching will be made.
4161 @vindex gnus-asynchronous-article-function
4162 You may wish to create some sort of scheme for choosing which articles
4163 that @code{nntp} should consider as candidates for pre-fetching. For
4164 instance, you may wish to pre-fetch all articles with high scores, and
4165 not pre-fetch low-scored articles. You can do that by setting the
4166 @code{gnus-asynchronous-article-function}, which will be called with an
4167 alist where the keys are the article numbers. Your function should
4168 return an alist where the articles you are not interested in have been
4169 removed. You could also do sorting on article score and the like.
4172 @node Article Caching
4173 @section Article Caching
4174 @cindex article caching
4177 If you have an @emph{extremely} slow @sc{nntp} connection, you may
4178 consider turning article caching on. Each article will then be stored
4179 locally under your home directory. As you may surmise, this could
4180 potentially use @emph{huge} amounts of disk space, as well as eat up all
4181 your inodes so fast it will make your head swim. In vodka.
4183 Used carefully, though, it could be just an easier way to save articles.
4185 @vindex gnus-use-long-file-name
4186 @vindex gnus-cache-directory
4187 @vindex gnus-use-cache
4188 To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
4189 all articles that are ticked or marked as dormant will then be copied
4190 over to your local cache (@code{gnus-cache-directory}). Whether this
4191 cache is flat or hierarchal is controlled by the
4192 @code{gnus-use-long-file-name} variable, as usual.
4194 When re-select a ticked or dormant article, it will be fetched from the
4195 cache instead of from the server. As articles in your cache will never
4196 expire, this might serve as a method of saving articles while still
4197 keeping them where they belong. Just mark all articles you want to save
4198 as dormant, and don't worry.
4200 When an article is marked as read, is it removed from the cache.
4202 @vindex gnus-cache-remove-articles
4203 @vindex gnus-cache-enter-articles
4204 The entering/removal of articles from the cache is controlled by the
4205 @code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
4206 variables. Both are lists of symbols. The first is @code{(ticked
4207 dormant)} by default, meaning that ticked and dormant articles will be
4208 put in the cache. The latter is @code{(read)} by default, meaning that
4209 articles that are marked as read are removed from the cache. Possibly
4210 symbols in these two lists are @code{ticked}, @code{dormant},
4211 @code{unread} and @code{read}.
4213 @findex gnus-jog-cache
4214 So where does the massive article-fetching and storing come into the
4215 picture? The @code{gnus-jog-cache} command will go through all
4216 subscribed newsgroups, request all unread articles, and store them in
4217 the cache. You should only ever, ever ever ever, use this command if 1)
4218 your connection to the @sc{nntp} server is really, really, really slow
4219 and 2) you have a really, really, really huge disk. Seriously.
4221 @vindex gnus-uncacheable-groups
4222 It is likely that you do not want caching on some groups. For instance,
4223 if your @code{nnml} mail is located under your home directory, it makes no
4224 sense to cache it somewhere else under your home directory. Unless you
4225 feel that it's neat to use twice as much space. To limit the caching,
4226 you could set the @code{gnus-uncacheable-groups} regexp to
4227 @samp{^nnml}, for instance. This variable is @code{nil} by
4230 @findex gnus-cache-generate-nov-databases
4231 @findex gnus-cache-generate-active
4232 @vindex gnus-cache-active-file
4233 The cache stores information on what articles it contains in its active
4234 file (@code{gnus-cache-active-file}). If this file (or any other parts
4235 of the cache) becomes all messed up for some reason or other, Gnus
4236 offers two functions that will try to set things right. @kbd{M-x
4237 gnus-cache-generate-nov-databases} will (re)build all the @sc{nov}
4238 files, and @kbd{gnus-cache-generate-active} will (re)generate the active
4242 @node Persistent Articles
4243 @section Persistent Articles
4244 @cindex persistent articles
4246 Closely related to article caching, we have @dfn{persistent articles}.
4247 In fact, it's just a different way of looking at caching, and much more
4248 useful in my opinion.
4250 Say you're reading a newsgroup, and you happen on to some valuable gem
4251 that you want to keep and treasure forever. You'd normally just save it
4252 (using one of the many saving commands) in some file. The problem with
4253 that is that it's just, well, yucky. Ideally you'd prefer just having
4254 the article remain in the group where you found it forever; untouched by
4255 the expiry going on at the news server.
4257 This is what a @dfn{persistent article} is---an article that just won't
4258 be deleted. It's implemented using the normal cache functions, but
4259 you use two explicit commands for managing persistent articles:
4265 @findex gnus-cache-enter-article
4266 Make the current article persistent (@code{gnus-cache-enter-article}).
4269 @kindex M-* (Summary)
4270 @findex gnus-cache-remove-article
4271 Remove the current article from the persistent articles
4272 (@code{gnus-cache-remove-article}). This will normally delete the
4276 Both these commands understand the process/prefix convention.
4278 To avoid having all ticked articles (and stuff) entered into the cache,
4279 you should set @code{gnus-use-cache} to @code{passive} if you're just
4280 interested in persistent articles:
4283 (setq gnus-use-cache 'passive)
4287 @node Article Backlog
4288 @section Article Backlog
4290 @cindex article backlog
4292 If you have a slow connection, but the idea of using caching seems
4293 unappealing to you (and it is, really), you can help the situation some
4294 by switching on the @dfn{backlog}. This is where Gnus will buffer
4295 already read articles so that it doesn't have to re-fetch articles
4296 you've already read. This only helps if you are in the habit of
4297 re-selecting articles you've recently read, of course. If you never do
4298 that, turning the backlog on will slow Gnus down a little bit, and
4299 increase memory usage some.
4301 @vindex gnus-keep-backlog
4302 If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store
4303 at most @var{n} old articles in a buffer for later re-fetching. If this
4304 variable is non-@code{nil} and is not a number, Gnus will store
4305 @emph{all} read articles, which means that your Emacs will grow without
4306 bound before exploding and taking your machine down with you. I put
4307 that in there just to keep y'all on your toes.
4309 This variable is @code{nil} by default.
4312 @node Saving Articles
4313 @section Saving Articles
4314 @cindex saving articles
4316 Gnus can save articles in a number of ways. Below is the documentation
4317 for saving articles in a fairly straight-forward fashion (i.e., little
4318 processing of the article is done before it is saved). For a different
4319 approach (uudecoding, unsharing) you should use @code{gnus-uu}
4320 (@pxref{Decoding Articles}).
4322 @vindex gnus-save-all-headers
4323 If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
4324 unwanted headers before saving the article.
4326 @vindex gnus-saved-headers
4327 If the preceding variable is @code{nil}, all headers that match the
4328 @code{gnus-saved-headers} regexp will be kept, while the rest will be
4329 deleted before saving.
4335 @kindex O o (Summary)
4337 @findex gnus-summary-save-article
4338 Save the current article using the default article saver
4339 (@code{gnus-summary-save-article}).
4342 @kindex O m (Summary)
4343 @findex gnus-summary-save-article-mail
4344 Save the current article in mail format
4345 (@code{gnus-summary-save-article-mail}).
4348 @kindex O r (Summary)
4349 @findex gnus-summary-save-article-rmail
4350 Save the current article in rmail format
4351 (@code{gnus-summary-save-article-rmail}).
4354 @kindex O f (Summary)
4355 @findex gnus-summary-save-article-file
4356 Save the current article in plain file format
4357 (@code{gnus-summary-save-article-file}).
4360 @kindex O b (Summary)
4361 @findex gnus-summary-save-article-body-file
4362 Save the current article body in plain file format
4363 (@code{gnus-summary-save-article-body-file}).
4366 @kindex O h (Summary)
4367 @findex gnus-summary-save-article-folder
4368 Save the current article in mh folder format
4369 (@code{gnus-summary-save-article-folder}).
4372 @kindex O v (Summary)
4373 @findex gnus-summary-save-article-vm
4374 Save the current article in a VM folder
4375 (@code{gnus-summary-save-article-vm}).
4378 @kindex O p (Summary)
4379 @findex gnus-summary-pipe-output
4380 Save the current article in a pipe. Uhm, like, what I mean is---Pipe
4381 the current article to a process (@code{gnus-summary-pipe-output}).
4384 @vindex gnus-prompt-before-saving
4385 All these commands use the process/prefix convention
4386 (@pxref{Process/Prefix}). If you save bunches of articles using these
4387 functions, you might get tired of being prompted for files to save each
4388 and every article in. The prompting action is controlled by
4389 the @code{gnus-prompt-before-saving} variable, which is @code{always} by
4390 default, giving you that excessive prompting action you know and
4391 loathe. If you set this variable to @code{t} instead, you'll be prompted
4392 just once for each series of articles you save. If you like to really
4393 have Gnus do all your thinking for you, you can even set this variable
4394 to @code{nil}, which means that you will never be prompted for files to
4395 save articles in. Gnus will simply save all the articles in the default
4399 @vindex gnus-default-article-saver
4400 You can customize the @code{gnus-default-article-saver} variable to make
4401 Gnus do what you want it to. You can use any of the four ready-made
4402 functions below, or you can create your own.
4406 @item gnus-summary-save-in-rmail
4407 @findex gnus-summary-save-in-rmail
4408 @vindex gnus-rmail-save-name
4409 @findex gnus-plain-save-name
4410 This is the default format, @dfn{babyl}. Uses the function in the
4411 @code{gnus-rmail-save-name} variable to get a file name to save the
4412 article in. The default is @code{gnus-plain-save-name}.
4414 @item gnus-summary-save-in-mail
4415 @findex gnus-summary-save-in-mail
4416 @vindex gnus-mail-save-name
4417 Save in a Unix mail (mbox) file. Uses the function in the
4418 @code{gnus-mail-save-name} variable to get a file name to save the
4419 article in. The default is @code{gnus-plain-save-name}.
4421 @item gnus-summary-save-in-file
4422 @findex gnus-summary-save-in-file
4423 @vindex gnus-file-save-name
4424 @findex gnus-numeric-save-name
4425 Append the article straight to an ordinary file. Uses the function in
4426 the @code{gnus-file-save-name} variable to get a file name to save the
4427 article in. The default is @code{gnus-numeric-save-name}.
4429 @item gnus-summary-save-body-in-file
4430 @findex gnus-summary-save-body-in-file
4431 Append the article body to an ordinary file. Uses the function in the
4432 @code{gnus-file-save-name} variable to get a file name to save the
4433 article in. The default is @code{gnus-numeric-save-name}.
4435 @item gnus-summary-save-in-folder
4436 @findex gnus-summary-save-in-folder
4437 @findex gnus-folder-save-name
4438 @findex gnus-Folder-save-name
4439 @vindex gnus-folder-save-name
4442 Save the article to an MH folder using @code{rcvstore} from the MH
4443 library. Uses the function in the @code{gnus-folder-save-name} variable
4444 to get a file name to save the article in. The default is
4445 @code{gnus-folder-save-name}, but you can also use
4446 @code{gnus-Folder-save-name}. The former creates capitalized names, and
4447 the latter does not.
4449 @item gnus-summary-save-in-vm
4450 @findex gnus-summary-save-in-vm
4451 Save the article in a VM folder. You have to have the VM mail
4452 reader to use this setting.
4455 @vindex gnus-article-save-directory
4456 All of these functions, except for the last one, will save the article
4457 in the @code{gnus-article-save-directory}, which is initialized from the
4458 @code{SAVEDIR} environment variable. This is @file{~/News/} by
4461 As you can see above, the functions use different functions to find a
4462 suitable name of a file to save the article in. Below is a list of
4463 available functions that generate names:
4467 @item gnus-Numeric-save-name
4468 @findex gnus-Numeric-save-name
4469 Generates file names that look like @file{~/News/Alt.andrea-dworkin/45}.
4471 @item gnus-numeric-save-name
4472 @findex gnus-numeric-save-name
4473 Generates file names that look like @file{~/News/alt.andrea-dworkin/45}.
4475 @item gnus-Plain-save-name
4476 @findex gnus-Plain-save-name
4477 Generates file names that look like @file{~/News/Alt.andrea-dworkin}.
4479 @item gnus-plain-save-name
4480 @findex gnus-plain-save-name
4481 Generates file names that look like @file{~/News/alt.andrea-dworkin}.
4484 @vindex gnus-split-methods
4485 You can have Gnus suggest where to save articles by plonking a regexp into
4486 the @code{gnus-split-methods} alist. For instance, if you would like to
4487 save articles related to Gnus in the file @file{gnus-stuff}, and articles
4488 related to VM in @code{vm-stuff}, you could set this variable to something
4492 (("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
4493 ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff")
4494 (my-choosing-function "../other-dir/my-stuff")
4495 ((equal gnus-newsgroup-name "mail.misc") "mail-stuff"))
4498 We see that this is a list where each element is a list that has two
4499 elements---the @dfn{match} and the @dfn{file}. The match can either be
4500 a string (in which case it is used as a regexp to match on the article
4501 head); it can be a symbol (which will be called as a function); or it
4502 can be a list (which will be @code{eval}ed). If any of these actions
4503 have a non-@code{nil} result, the @dfn{file} will be used as a default
4504 prompt. In addition, the result of the operation itself will be used if
4505 the function or form called returns a string or a list of strings.
4507 You basically end up with a list of file names that might be used when
4508 saving the current article. (All ``matches'' will be used.) You will
4509 then be prompted for what you really want to use as a name, with file
4510 name completion over the results from applying this variable.
4512 This variable is @code{((gnus-article-archive-name))} by default, which
4513 means that Gnus will look at the articles it saves for an
4514 @code{Archive-name} line and use that as a suggestion for the file
4517 @vindex gnus-use-long-file-name
4518 Finally, you have the @code{gnus-use-long-file-name} variable. If it is
4519 @code{nil}, all the preceding functions will replace all periods
4520 (@samp{.}) in the group names with slashes (@samp{/})---which means that
4521 the functions will generate hierarchies of directories instead of having
4522 all the files in the toplevel directory
4523 (@file{~/News/alt/andrea-dworkin} instead of
4524 @file{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default
4525 on most systems. However, for historical reasons, this is @code{nil} on
4526 Xenix and usg-unix-v machines by default.
4528 This function also affects kill and score file names. If this variable
4529 is a list, and the list contains the element @code{not-score}, long file
4530 names will not be used for score files, if it contains the element
4531 @code{not-save}, long file names will not be used for saving, and if it
4532 contains the element @code{not-kill}, long file names will not be used
4535 If you'd like to save articles in a hierarchy that looks something like
4539 (setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
4540 (setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
4543 Then just save with @kbd{o}. You'd then read this hierarchy with
4544 ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
4545 the toplevel directory as the argument (@file{~/News/}). Then just walk
4546 around to the groups/directories with @code{nneething}.
4549 @node Decoding Articles
4550 @section Decoding Articles
4551 @cindex decoding articles
4553 Sometime users post articles (or series of articles) that have been
4554 encoded in some way or other. Gnus can decode them for you.
4557 * Uuencoded Articles:: Uudecode articles.
4558 * Shared Articles:: Unshar articles.
4559 * PostScript Files:: Split PostScript.
4560 * Decoding Variables:: Variables for a happy decoding.
4561 * Viewing Files:: You want to look at the result of the decoding?
4564 All these functions use the process/prefix convention
4565 (@pxref{Process/Prefix}) for finding out what articles to work on, with
4566 the extension that a ``single article'' means ``a single series''. Gnus
4567 can find out by itself what articles belong to a series, decode all the
4568 articles and unpack/view/save the resulting file(s).
4570 Gnus guesses what articles are in the series according to the following
4571 simplish rule: The subjects must be (nearly) identical, except for the
4572 last two numbers of the line. (Spaces are largely ignored, however.)
4574 For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus
4575 will find all the articles that match the regexp @samp{^cat.gif
4576 ([0-9]+/[0-9]+).*$}.
4578 Subjects that are nonstandard, like @samp{cat.gif (2/3) Part 6 of a
4579 series}, will not be properly recognized by any of the automatic viewing
4580 commands, and you have to mark the articles manually with @kbd{#}.
4583 @node Uuencoded Articles
4584 @subsection Uuencoded Articles
4586 @cindex uuencoded articles
4591 @kindex X u (Summary)
4592 @findex gnus-uu-decode-uu
4593 Uudecodes the current series (@code{gnus-uu-decode-uu}).
4596 @kindex X U (Summary)
4597 @findex gnus-uu-decode-uu-and-save
4598 Uudecodes and saves the current series
4599 (@code{gnus-uu-decode-uu-and-save}).
4602 @kindex X v u (Summary)
4603 @findex gnus-uu-decode-uu-view
4604 Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
4607 @kindex X v U (Summary)
4608 @findex gnus-uu-decode-uu-and-save-view
4609 Uudecodes, views and saves the current series
4610 (@code{gnus-uu-decode-uu-and-save-view}).
4613 Remember that these all react to the presence of articles marked with
4614 the process mark. If, for instance, you'd like to decode and save an
4615 entire newsgroup, you'd typically do @kbd{M P a}
4616 (@code{gnus-uu-mark-all}) and then @kbd{X U}
4617 (@code{gnus-uu-decode-uu-and-save}).
4619 All this is very much different from how @code{gnus-uu} worked with
4620 @sc{gnus 4.1}, where you had explicit keystrokes for everything under
4621 the sun. This version of @code{gnus-uu} generally assumes that you mark
4622 articles in some way (@pxref{Setting Process Marks}) and then press
4625 @vindex gnus-uu-notify-files
4626 Note: When trying to decode articles that have names matching
4627 @code{gnus-uu-notify-files}, which is hard-coded to
4628 @samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
4629 automatically post an article on @samp{comp.unix.wizards} saying that
4630 you have just viewed the file in question. This feature can't be turned
4634 @node Shared Articles
4635 @subsection Shared Articles
4637 @cindex shared articles
4642 @kindex X s (Summary)
4643 @findex gnus-uu-decode-unshar
4644 Unshars the current series (@code{gnus-uu-decode-unshar}).
4647 @kindex X S (Summary)
4648 @findex gnus-uu-decode-unshar-and-save
4649 Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
4652 @kindex X v s (Summary)
4653 @findex gnus-uu-decode-unshar-view
4654 Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
4657 @kindex X v S (Summary)
4658 @findex gnus-uu-decode-unshar-and-save-view
4659 Unshars, views and saves the current series
4660 (@code{gnus-uu-decode-unshar-and-save-view}).
4664 @node PostScript Files
4665 @subsection PostScript Files
4671 @kindex X p (Summary)
4672 @findex gnus-uu-decode-postscript
4673 Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
4676 @kindex X P (Summary)
4677 @findex gnus-uu-decode-postscript-and-save
4678 Unpack and save the current PostScript series
4679 (@code{gnus-uu-decode-postscript-and-save}).
4682 @kindex X v p (Summary)
4683 @findex gnus-uu-decode-postscript-view
4684 View the current PostScript series
4685 (@code{gnus-uu-decode-postscript-view}).
4688 @kindex X v P (Summary)
4689 @findex gnus-uu-decode-postscript-and-save-view
4690 View and save the current PostScript series
4691 (@code{gnus-uu-decode-postscript-and-save-view}).
4695 @node Decoding Variables
4696 @subsection Decoding Variables
4698 Adjective, not verb.
4701 * Rule Variables:: Variables that say how a file is to be viewed.
4702 * Other Decode Variables:: Other decode variables.
4703 * Uuencoding and Posting:: Variables for customizing uuencoding.
4707 @node Rule Variables
4708 @subsubsection Rule Variables
4709 @cindex rule variables
4711 Gnus uses @dfn{rule variables} to decide how to view a file. All these
4712 variables are on the form
4715 (list '(regexp1 command2)
4722 @item gnus-uu-user-view-rules
4723 @vindex gnus-uu-user-view-rules
4725 This variable is consulted first when viewing files. If you wish to use,
4726 for instance, @code{sox} to convert an @samp{.au} sound file, you could
4729 (setq gnus-uu-user-view-rules
4730 (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
4733 @item gnus-uu-user-view-rules-end
4734 @vindex gnus-uu-user-view-rules-end
4735 This variable is consulted if Gnus couldn't make any matches from the
4736 user and default view rules.
4738 @item gnus-uu-user-archive-rules
4739 @vindex gnus-uu-user-archive-rules
4740 This variable can be used to say what commands should be used to unpack
4745 @node Other Decode Variables
4746 @subsubsection Other Decode Variables
4749 @vindex gnus-uu-grabbed-file-functions
4751 @item gnus-uu-grabbed-file-functions
4752 All functions in this list will be called right each file has been
4753 successfully decoded---so that you can move or view files right away,
4754 and don't have to wait for all files to be decoded before you can do
4755 anything. Ready-made functions you can put in this list are:
4759 @item gnus-uu-grab-view
4760 @findex gnus-uu-grab-view
4763 @item gnus-uu-grab-move
4764 @findex gnus-uu-grab-move
4765 Move the file (if you're using a saving function.)
4768 @item gnus-uu-ignore-files-by-name
4769 @vindex gnus-uu-ignore-files-by-name
4770 Files with name matching this regular expression won't be viewed.
4772 @item gnus-uu-ignore-files-by-type
4773 @vindex gnus-uu-ignore-files-by-type
4774 Files with a @sc{mime} type matching this variable won't be viewed.
4775 Note that Gnus tries to guess what type the file is based on the name.
4776 @code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
4779 @item gnus-uu-tmp-dir
4780 @vindex gnus-uu-tmp-dir
4781 Where @code{gnus-uu} does its work.
4783 @item gnus-uu-do-not-unpack-archives
4784 @vindex gnus-uu-do-not-unpack-archives
4785 Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
4786 looking for files to display.
4788 @item gnus-uu-view-and-save
4789 @vindex gnus-uu-view-and-save
4790 Non-@code{nil} means that the user will always be asked to save a file
4793 @item gnus-uu-ignore-default-view-rules
4794 @vindex gnus-uu-ignore-default-view-rules
4795 Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
4798 @item gnus-uu-ignore-default-archive-rules
4799 @vindex gnus-uu-ignore-default-archive-rules
4800 Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
4803 @item gnus-uu-kill-carriage-return
4804 @vindex gnus-uu-kill-carriage-return
4805 Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
4808 @item gnus-uu-unmark-articles-not-decoded
4809 @vindex gnus-uu-unmark-articles-not-decoded
4810 Non-@code{nil} means that @code{gnus-uu} will mark articles that were
4811 unsuccessfully decoded as unread.
4813 @item gnus-uu-correct-stripped-uucode
4814 @vindex gnus-uu-correct-stripped-uucode
4815 Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
4816 uuencoded files that have had trailing spaces deleted.
4818 @item gnus-uu-view-with-metamail
4819 @vindex gnus-uu-view-with-metamail
4821 Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
4822 commands defined by the rule variables and just fudge a @sc{mime}
4823 content type based on the file name. The result will be fed to
4824 @code{metamail} for viewing.
4826 @item gnus-uu-save-in-digest
4827 @vindex gnus-uu-save-in-digest
4828 Non-@code{nil} means that @code{gnus-uu}, when asked to save without
4829 decoding, will save in digests. If this variable is @code{nil},
4830 @code{gnus-uu} will just save everything in a file without any
4831 embellishments. The digesting almost conforms to RFC1153---no easy way
4832 to specify any meaningful volume and issue numbers were found, so I
4833 simply dropped them.
4838 @node Uuencoding and Posting
4839 @subsubsection Uuencoding and Posting
4843 @item gnus-uu-post-include-before-composing
4844 @vindex gnus-uu-post-include-before-composing
4845 Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
4846 before you compose the article. If this variable is @code{t}, you can
4847 either include an encoded file with @kbd{C-c C-i} or have one included
4848 for you when you post the article.
4850 @item gnus-uu-post-length
4851 @vindex gnus-uu-post-length
4852 Maximum length of an article. The encoded file will be split into how
4853 many articles it takes to post the entire file.
4855 @item gnus-uu-post-threaded
4856 @vindex gnus-uu-post-threaded
4857 Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
4858 thread. This may not be smart, as no other decoder I have seen are able
4859 to follow threads when collecting uuencoded articles. (Well, I have
4860 seen one package that does that---@code{gnus-uu}, but somehow, I don't
4861 think that counts...) Default is @code{nil}.
4863 @item gnus-uu-post-separate-description
4864 @vindex gnus-uu-post-separate-description
4865 Non-@code{nil} means that the description will be posted in a separate
4866 article. The first article will typically be numbered (0/x). If this
4867 variable is @code{nil}, the description the user enters will be included
4868 at the beginning of the first article, which will be numbered (1/x).
4869 Default is @code{t}.
4875 @subsection Viewing Files
4876 @cindex viewing files
4877 @cindex pseudo-articles
4879 After decoding, if the file is some sort of archive, Gnus will attempt
4880 to unpack the archive and see if any of the files in the archive can be
4881 viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
4882 containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
4883 uncompress and de-tar the main file, and then view the two pictures.
4884 This unpacking process is recursive, so if the archive contains archives
4885 of archives, it'll all be unpacked.
4887 Finally, Gnus will normally insert a @dfn{pseudo-article} for each
4888 extracted file into the summary buffer. If you go to these
4889 ``articles'', you will be prompted for a command to run (usually Gnus
4890 will make a suggestion), and then the command will be run.
4892 @vindex gnus-view-pseudo-asynchronously
4893 If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
4894 until the viewing is done before proceeding.
4896 @vindex gnus-view-pseudos
4897 If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
4898 the pseudo-articles into the summary buffer, but view them
4899 immediately. If this variable is @code{not-confirm}, the user won't even
4900 be asked for a confirmation before viewing is done.
4902 @vindex gnus-view-pseudos-separately
4903 If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
4904 pseudo-article will be created for each file to be viewed. If
4905 @code{nil}, all files that use the same viewing command will be given as
4906 a list of parameters to that command.
4908 @vindex gnus-insert-pseudo-articles
4909 If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert
4910 pseudo-articles when decoding. It is @code{t} by default.
4912 So; there you are, reading your @emph{pseudo-articles} in your
4913 @emph{virtual newsgroup} from the @emph{virtual server}; and you think:
4914 Why isn't anything real anymore? How did we get here?
4917 @node Article Treatment
4918 @section Article Treatment
4920 Reading through this huge manual, you may have quite forgotten that the
4921 object of newsreaders are to actually, like, read what people have
4922 written. Reading articles. Unfortunately, people are quite bad at
4923 writing, so there are tons of functions and variables to make reading
4924 these articles easier.
4927 * Article Highlighting:: You want to make the article look like fruit salad.
4928 * Article Hiding:: You also want to make certain info go away.
4929 * Article Washing:: Lots of way-neat functions to make life better.
4930 * Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
4931 * Article Date:: Grumble, UT!
4935 @node Article Highlighting
4936 @subsection Article Highlighting
4939 Not only do you want your article buffer to look like fruit salad, but
4940 you want it to look like technicolor fruit salad.
4945 @kindex W H a (Summary)
4946 @findex gnus-article-highlight
4947 Highlight the current article (@code{gnus-article-highlight}).
4950 @kindex W H h (Summary)
4951 @findex gnus-article-highlight-headers
4952 @vindex gnus-header-face-alist
4953 Highlight the headers (@code{gnus-article-highlight-headers}). The
4954 highlighting will be done according to the @code{gnus-header-face-alist}
4955 variable, which is a list where each element has the form @var{(regexp
4956 name content)}. @var{regexp} is a regular expression for matching the
4957 header, @var{name} is the face used for highlighting the header name and
4958 @var{content} is the face for highlighting the header value. The first
4959 match made will be used. Note that @var{regexp} shouldn't have @samp{^}
4960 prepended---Gnus will add one.
4963 @kindex W H c (Summary)
4964 @findex gnus-article-highlight-citation
4965 Highlight cited text (@code{gnus-article-highlight-citation}).
4967 Some variables to customize the citation highlights:
4970 @vindex gnus-cite-parse-max-size
4972 @item gnus-cite-parse-max-size
4973 If the article size if bigger than this variable (which is 25000 by
4974 default), no citation highlighting will be performed.
4976 @item gnus-cite-prefix-regexp
4977 @vindex gnus-cite-prefix-regexp
4978 Regexp matching the longest possible citation prefix on a line.
4980 @item gnus-cite-max-prefix
4981 @vindex gnus-cite-max-prefix
4982 Maximum possible length for a citation prefix (default 20).
4984 @item gnus-cite-face-list
4985 @vindex gnus-cite-face-list
4986 List of faces used for highlighting citations. When there are citations
4987 from multiple articles in the same message, Gnus will try to give each
4988 citation from each article its own face. This should make it easier to
4991 @item gnus-supercite-regexp
4992 @vindex gnus-supercite-regexp
4993 Regexp matching normal SuperCite attribution lines.
4995 @item gnus-supercite-secondary-regexp
4996 @vindex gnus-supercite-secondary-regexp
4997 Regexp matching mangled SuperCite attribution lines.
4999 @item gnus-cite-minimum-match-count
5000 @vindex gnus-cite-minimum-match-count
5001 Minimum number of identical prefixes we have to see before we believe
5002 that it's a citation.
5004 @item gnus-cite-attribution-prefix
5005 @vindex gnus-cite-attribution-prefix
5006 Regexp matching the beginning of an attribution line.
5008 @item gnus-cite-attribution-suffix
5009 @vindex gnus-cite-attribution-suffix
5010 Regexp matching the end of an attribution line.
5012 @item gnus-cite-attribution-face
5013 @vindex gnus-cite-attribution-face
5014 Face used for attribution lines. It is merged with the face for the
5015 cited text belonging to the attribution.
5021 @kindex W H s (Summary)
5022 @vindex gnus-signature-separator
5023 @vindex gnus-signature-face
5024 @findex gnus-article-highlight-signature
5025 Highlight the signature (@code{gnus-article-highlight-signature}).
5026 Everything after @code{gnus-signature-separator} in an article will be
5027 considered a signature and will be highlighted with
5028 @code{gnus-signature-face}, which is @code{italic} by default.
5033 @node Article Hiding
5034 @subsection Article Hiding
5035 @cindex article hiding
5037 Or rather, hiding certain things in each article. There usually is much
5038 too much cruft in most articles.
5043 @kindex W W a (Summary)
5044 @findex gnus-article-hide
5045 Do maximum hiding on the summary buffer (@kbd{gnus-article-hide}).
5048 @kindex W W h (Summary)
5049 @findex gnus-article-hide-headers
5050 Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
5054 @kindex W W b (Summary)
5055 @findex gnus-article-hide-boring-headers
5056 Hide headers that aren't particularly interesting
5057 (@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}.
5060 @kindex W W s (Summary)
5061 @findex gnus-article-hide-signature
5062 Hide signature (@code{gnus-article-hide-signature}).
5065 @kindex W W p (Summary)
5066 @findex gnus-article-hide-pgp
5067 Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}).
5070 @kindex W W c (Summary)
5071 @findex gnus-article-hide-citation
5072 Hide citation (@code{gnus-article-hide-citation}). Some variables for
5073 customizing the hiding:
5077 @item gnus-cite-hide-percentage
5078 @vindex gnus-cite-hide-percentage
5079 If the cited text is of a bigger percentage than this variable (default
5080 50), hide the cited text.
5082 @item gnus-cite-hide-absolute
5083 @vindex gnus-cite-hide-absolute
5084 The cited text must be have at least this length (default 10) before it
5087 @item gnus-cited-text-button-line-format
5088 @vindex gnus-cited-text-button-line-format
5089 Gnus adds buttons show where the cited text has been hidden, and to
5090 allow toggle hiding the text. The format of the variable is specified
5091 by this format-like variable. These specs are legal:
5095 Start point of the hidden text.
5097 End point of the hidden text.
5099 Length of the hidden text.
5102 @item gnus-cited-lines-visible
5103 @vindex gnus-cited-lines-visible
5104 The number of lines at the beginning of the cited text to leave shown.
5109 @kindex W W C (Summary)
5110 @findex gnus-article-hide-citation-in-followups
5111 Hide cited text in articles that aren't roots
5112 (@code{gnus-article-hide-citation-in-followups}). This isn't very
5113 useful as an interactive command, but might be a handy function to stick
5114 in @code{gnus-article-display-hook} (@pxref{Customizing Articles}).
5118 All these ``hiding'' commands are toggles, but if you give a negative
5119 prefix to these commands, they will show what they have previously
5120 hidden. If you give a positive prefix, they will always hide.
5122 Also @pxref{Article Highlighting} for further variables for
5123 citation customization.
5125 @vindex gnus-signature-limit
5126 @code{gnus-signature-limit} provides a limit to what is considered a
5127 signature. If it is a number, no signature may not be longer (in
5128 characters) than that number. If it is a function, the function will be
5129 called without any parameters, and if it returns @code{nil}, there is no
5130 signature in the buffer. If it is a string, it will be used as a
5131 regexp. If it matches, the text in question is not a signature.
5134 @node Article Washing
5135 @subsection Article Washing
5137 @cindex article washing
5139 We call this ``article washing'' for a really good reason. Namely, the
5140 @kbd{A} key was taken, so we had to use the @kbd{W} key instead.
5142 @dfn{Washing} is defined by us as ``changing something from something to
5143 something else'', but normally results in something looking better.
5149 @kindex W l (Summary)
5150 @findex gnus-summary-stop-page-breaking
5151 Remove page breaks from the current article
5152 (@code{gnus-summary-stop-page-breaking}).
5155 @kindex W r (Summary)
5156 @findex gnus-summary-caesar-message
5157 Do a Caesar rotate (rot13) on the article buffer
5158 (@code{gnus-summary-caesar-message}).
5161 @kindex A g (Summary)
5162 @findex gnus-summary-show-article
5163 (Re)fetch the current article (@code{gnus-summary-show-article}). If
5164 given a prefix, fetch the current article, but don't run any of the
5165 article treatment functions. This will give you a ``raw'' article, just
5166 the way it came from the server.
5169 @kindex W t (Summary)
5170 @findex gnus-summary-toggle-header
5171 Toggle whether to display all headers in the article buffer
5172 (@code{gnus-summary-toggle-header}).
5175 @kindex W v (Summary)
5176 @findex gnus-summary-verbose-header
5177 Toggle whether to display all headers in the article buffer permanently
5178 (@code{gnus-summary-verbose-header}).
5181 @kindex W m (Summary)
5182 @findex gnus-summary-toggle-mime
5183 Toggle whether to run the article through @sc{mime} before displaying
5184 (@code{gnus-summary-toggle-mime}).
5187 @kindex W o (Summary)
5188 @findex gnus-article-treat-overstrike
5189 Treat overstrike (@code{gnus-article-treat-overstrike}).
5192 @kindex W w (Summary)
5193 @findex gnus-article-fill-cited-article
5194 Do word wrap (@code{gnus-article-fill-cited-article}).
5197 @kindex W c (Summary)
5198 @findex gnus-article-remove-cr
5199 Remove CR (@code{gnus-article-remove-cr}).
5202 @kindex W L (Summary)
5203 @findex gnus-article-remove-trailing-blank-lines
5204 Remove all blank lines at the end of the article
5205 (@code{gnus-article-remove-trailing-blank-lines}).
5208 @kindex W q (Summary)
5209 @findex gnus-article-de-quoted-unreadable
5210 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
5213 @kindex W f (Summary)
5215 @findex gnus-article-display-x-face
5216 @findex gnus-article-x-face-command
5217 @vindex gnus-article-x-face-command
5218 @vindex gnus-article-x-face-too-ugly
5219 Look for and display any X-Face headers
5220 (@code{gnus-article-display-x-face}). The command executed by this
5221 function is given by the @code{gnus-article-x-face-command} variable. If
5222 this variable is a string, this string will be executed in a sub-shell.
5223 If it is a function, this function will be called with the face as the
5224 argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
5225 matches the @code{From} header, the face will not be shown.
5228 @kindex W b (Summary)
5229 @findex gnus-article-add-buttons
5230 Add clickable buttons to the article (@code{gnus-article-add-buttons}).
5233 @kindex W B (Summary)
5234 @findex gnus-article-add-buttons-to-head
5235 Add clickable buttons to the article headers
5236 (@code{gnus-article-add-buttons-to-head}).
5241 @node Article Buttons
5242 @subsection Article Buttons
5245 People often include references to other stuff in articles, and it would
5246 be nice if Gnus could just fetch whatever it is that people talk about
5247 with the minimum of fuzz.
5249 Gnus adds @dfn{buttons} to certain standard references by default:
5250 Well-formed URLs, mail addresses and Message-IDs. This is controlled by
5251 two variables, one that handles article bodies and one that handles
5256 @item gnus-button-alist
5257 @vindex gnus-button-alist
5258 This is an alist where each entry has this form:
5261 (REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
5267 All text that match this regular expression will be considered an
5268 external reference. Here's a typical regexp that match embedded URLs:
5269 @samp{<URL:\\([^\n\r>]*\\)>}.
5272 Gnus has to know which parts of the match is to be highlighted. This is
5273 a number that says what sub-expression of the regexp that is to be
5274 highlighted. If you want it all highlighted, you use @code{0} here.
5277 This form will be @code{eval}ed, and if the result is non-@code{nil},
5278 this is considered a match. This is useful if you want extra sifting to
5279 avoid false matches.
5282 This function will be called when you click on this button.
5285 As with @var{button-par}, this is a sub-expression number, but this one
5286 says which part of the match is to be sent as data to @var{function}.
5290 So the full entry for buttonizing URLs is then
5293 ("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
5296 @item gnus-header-button-alist
5297 @vindex gnus-header-button-alist
5298 This is just like the other alist, except that it is applied to the
5299 article head only, and that each entry has an additional element that is
5300 used to say what headers to apply the buttonize coding to:
5303 (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
5306 @var{header} is a regular expression.
5308 @item gnus-button-url-regexp
5309 @vindex gnus-button-url-regexp
5310 A regular expression that matches embedded URLs. It is used in the
5311 default values of the variables above.
5313 @item gnus-article-button-face
5314 @vindex gnus-article-button-face
5315 Face used on bottons.
5317 @item gnus-article-mouse-face
5318 @vindex gnus-article-mouse-face
5319 Face is used when the mouse cursor is over a button.
5325 @subsection Article Date
5327 The date is most likely generated in some obscure timezone you've never
5328 heard of, so it's quite nice to be able to find out what the time was
5329 when the article was sent.
5334 @kindex W T u (Summary)
5335 @findex gnus-article-date-ut
5336 Display the date in UT (aka. GMT, aka ZULU)
5337 (@code{gnus-article-date-ut}).
5340 @kindex W T l (Summary)
5341 @findex gnus-article-date-local
5342 Display the date in the local timezone (@code{gnus-article-date-local}).
5345 @kindex W T e (Summary)
5346 @findex gnus-article-date-lapsed
5347 Say how much time has (e)lapsed between the article was posted and now
5348 (@code{gnus-article-date-lapsed}).
5351 @kindex W T o (Summary)
5352 @findex gnus-article-date-original
5353 Display the original date (@code{gnus-article-date-original}). This can
5354 be useful if you normally use some other conversion function and is
5355 worried that it might be doing something totally wrong. Say, claiming
5356 that the article was posted in 1854. Although something like that is
5357 @emph{totally} impossible. Don't you trust me? *titter*
5362 @node Summary Sorting
5363 @section Summary Sorting
5364 @cindex summary sorting
5366 You can have the summary buffer sorted in various ways, even though I
5367 can't really see why you'd want that.
5372 @kindex C-c C-s C-n (Summary)
5373 @findex gnus-summary-sort-by-number
5374 Sort by article number (@code{gnus-summary-sort-by-number}).
5377 @kindex C-c C-s C-a (Summary)
5378 @findex gnus-summary-sort-by-author
5379 Sort by author (@code{gnus-summary-sort-by-author}).
5382 @kindex C-c C-s C-s (Summary)
5383 @findex gnus-summary-sort-by-subject
5384 Sort by subject (@code{gnus-summary-sort-by-subject}).
5387 @kindex C-c C-s C-d (Summary)
5388 @findex gnus-summary-sort-by-date
5389 Sort by date (@code{gnus-summary-sort-by-date}).
5392 @kindex C-c C-s C-i (Summary)
5393 @findex gnus-summary-sort-by-score
5394 Sort by score (@code{gnus-summary-sort-by-score}).
5397 These functions will work both when you use threading and when you don't
5398 use threading. In the latter case, all summary lines will be sorted,
5399 line by line. In the former case, sorting will be done on a
5400 root-by-root basis, which might not be what you were looking for. To
5401 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
5405 @node Finding the Parent
5406 @section Finding the Parent
5407 @cindex parent articles
5408 @cindex referring articles
5410 @findex gnus-summary-refer-parent-article
5412 If you'd like to read the parent of the current article, and it is not
5413 displayed in the article buffer, you might still be able to. That is,
5414 if the current group is fetched by @sc{nntp}, the parent hasn't expired
5415 and the @code{References} in the current article are not mangled, you
5416 can just press @kbd{^} or @kbd{A r}
5417 (@code{gnus-summary-refer-parent-article}). If everything goes well,
5418 you'll get the parent. If the parent is already displayed in the
5419 summary buffer, point will just move to this article.
5421 @findex gnus-summary-refer-references
5422 @kindex A R (Summary)
5423 You can have Gnus fetch all articles mentioned in the @code{References}
5424 header of the article by pushing @kbd{A R}
5425 (@code{gnus-summary-refer-references}).
5427 @findex gnus-summary-refer-article
5428 @kindex M-^ (Summary)
5429 You can also ask the @sc{nntp} server for an arbitrary article, no
5430 matter what group it belongs to. @kbd{M-^}
5431 (@code{gnus-summary-refer-article}) will ask you for a
5432 @code{Message-ID}, which is one of those long thingies that look
5433 something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
5434 it all exactly right. No fuzzy searches, I'm afraid.
5436 @vindex gnus-refer-article-method
5437 If the group you are reading is located on a backend that does not
5438 support fetching by @code{Message-ID} very well (like @code{nnspool}),
5439 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
5440 would, perhaps, be best if the @sc{nntp} server you consult is the same
5441 as the one that keeps the spool you are reading from updated, but that's
5442 not really necessary.
5444 Most of the mail backends support fetching by @code{Message-ID}, but do
5445 not do a particularly excellent job of it. That is, @code{nnmbox} and
5446 @code{nnbabyl} are able to locate articles from any groups, while
5447 @code{nnml} and @code{nnfolder} are only able to locate articles that
5448 have been posted to the current group. (Anything else would be too time
5449 consuming.) @code{nnmh} does not support this at all.
5452 @node Alternative Approaches
5453 @section Alternative Approaches
5455 Different people like to read news using different methods. This being
5456 Gnus, we offer a small selection of minor modes for the summary buffers.
5459 * Pick and Read:: First mark articles and then read them.
5460 * Binary Groups:: Auto-decode all articles.
5465 @subsection Pick and Read
5466 @cindex pick and read
5468 Some newsreaders (like @code{nn} and, uhm, @code{nn}) use a two-phased
5469 reading interface. The user first marks the articles she wants to read
5470 from a summary buffer. Then she starts reading the articles with just
5471 an article buffer displayed.
5473 @findex gnus-pick-mode
5474 @kindex M-x gnus-pick-mode
5475 Gnus provides a summary buffer minor mode that allows
5476 this---@code{gnus-pick-mode}. This basically means that a few process
5477 mark commands become one-keystroke commands to allow easy marking, and
5478 it makes one additional command for switching to the summary buffer
5481 Here are the available keystrokes when using pick mode:
5485 @kindex SPACE (Pick)
5486 @findex gnus-summary-mark-as-processable
5487 Pick the article (@code{gnus-summary-mark-as-processable}).
5491 @findex gnus-summary-unmark-as-processable
5492 Unpick the article (@code{gnus-summary-unmark-as-processable}).
5496 @findex gnus-summary-unmark-all-processable
5497 Unpick all articles (@code{gnus-summary-unmark-all-processable}).
5501 @findex gnus-uu-mark-thread
5502 Pick the thread (@code{gnus-uu-mark-thread}).
5506 @findex gnus-uu-unmark-thread
5507 Unpick the thread (@code{gnus-uu-unmark-thread}).
5511 @findex gnus-uu-mark-region
5512 Pick the region (@code{gnus-uu-mark-region}).
5516 @findex gnus-uu-unmark-region
5517 Unpick the region (@code{gnus-uu-unmark-region}).
5521 @findex gnus-uu-unmark-regexp
5522 Pick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
5526 @findex gnus-uu-unmark-regexp
5527 Unpick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
5531 @findex gnus-uu-mark-buffer
5532 Pick the buffer (@code{gnus-uu-mark-buffer}).
5536 @findex gnus-uu-unmark-buffer
5537 Unpick the buffer (@code{gnus-uu-unmark-buffer}).
5541 @findex gnus-pick-start-reading
5542 @vindex gnus-pick-display-summary
5543 Start reading the picked articles (@code{gnus-pick-start-reading}). If
5544 given a prefix, mark all unpicked articles as read first. If
5545 @code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer
5546 will still be visible when you are reading.
5550 If this sounds like a good idea to you, you could say:
5553 (add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)
5556 @vindex gnus-pick-mode-hook
5557 @code{gnus-pick-mode-hook} is run in pick minor mode buffers.
5561 @subsection Binary Groups
5562 @cindex binary groups
5564 @findex gnus-binary-mode
5565 @kindex M-x gnus-binary-mode
5566 If you spend much time in binary groups, you may grow tired of hitting
5567 @kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode}
5568 is a minor mode for summary buffers that makes all ordinary Gnus article
5569 selection functions uudecode series of articles and display the result
5570 instead of just displaying the articles the normal way.
5573 @findex gnus-binary-show-article
5574 In fact, the only way to see the actual articles if you have turned this
5575 mode on is the @kbd{g} command (@code{gnus-binary-show-article}).
5577 @vindex gnus-binary-mode-hook
5578 @code{gnus-binary-mode-hook} is called in binary minor mode buffers.
5582 @section Tree Display
5585 @vindex gnus-use-trees
5586 If you don't like the normal Gnus summary display, you might try setting
5587 @code{gnus-use-trees} to @code{t}. This will create (by default) an
5588 additional @dfn{tree buffer}. You can execute all summary mode commands
5591 There are a few variables to customize the tree display, of course:
5594 @item gnus-tree-mode-hook
5595 @vindex gnus-tree-mode-hook
5596 A hook called in all tree mode buffers.
5598 @item gnus-tree-mode-line-format
5599 @vindex gnus-tree-mode-line-format
5600 A format string for the mode bar in the tree mode buffers. The default
5601 is @samp{Gnus: %%b [%A] %Z}. For a list of legal specs, @pxref{Summary
5604 @item gnus-selected-tree-face
5605 @vindex gnus-selected-tree-face
5606 Face used for highlighting the selected article in the tree buffer. The
5607 default is @code{modeline}.
5609 @item gnus-tree-line-format
5610 @vindex gnus-tree-line-format
5611 A format string for the tree nodes. The name is a bit of a misnomer,
5612 though---it doesn't define a line, but just the node. The default value
5613 is @samp{%(%[%3,3n%]%)}, which displays the first three characters of
5614 the name of the poster. It is vital that all nodes are of the same
5615 length, so you @emph{must} use @samp{%4,4n}-like specifiers.
5621 The name of the poster.
5623 The @code{From} header.
5625 The number of the article.
5627 The opening bracket.
5629 The closing bracket.
5634 @xref{Formatting Variables}.
5636 Variables related to the display are:
5639 @item gnus-tree-brackets
5640 @vindex gnus-tree-brackets
5641 This is used for differentiating between ``real'' articles and
5642 ``sparse'' articles. The format is @var{((real-open . real-close)
5643 (sparse-open . sparse-close) (dummy-open . dummy-close))}, and the
5644 default is @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}))}.
5646 @item gnus-tree-parent-child-edges
5647 @vindex gnus-tree-parent-child-edges
5648 This is a list that contains the characters used for connecting parent
5649 nodes to their children. The default is @code{(?- ?\\ ?|)}.
5653 @item gnus-tree-minimize-window
5654 @vindex gnus-tree-minimize-window
5655 If this variable is non-@code{nil}, Gnus will try to keep the tree
5656 buffer as small as possible to allow more room for the other Gnus
5657 windows. If this variable is a number, the tree buffer will never be
5658 higher than that number. The default is @code{t}.
5660 @item gnus-generate-tree-function
5661 @vindex gnus-generate-tree-function
5662 @findex gnus-generate-horizontal-tree
5663 @findex gnus-generate-vertical-tree
5664 The function that actually generates the thread tree. Two predefined
5665 functions are available: @code{gnus-generate-horizontal-tree} and
5666 @code{gnus-generate-vertical-tree} (which is the default).
5670 Here's and example from a horizontal tree buffer:
5673 @{***@}-(***)-[odd]-[Gun]
5683 Here's the same thread displayed in a vertical tree buffer:
5687 |--------------------------\-----\-----\
5688 (***) [Bjo] [Gun] [Gun]
5690 [odd] [Jan] [odd] (***) [Jor]
5692 [Gun] [Eri] [Eri] [odd]
5698 @node Mail Group Commands
5699 @section Mail Group Commands
5700 @cindex mail group commands
5702 Some commands only make sense in mail groups. If these commands are
5703 illegal in the current group, they will raise a hell and let you know.
5705 All these commands (except the expiry and edit commands) use the
5706 process/prefix convention (@pxref{Process/Prefix}).
5711 @kindex B e (Summary)
5712 @findex gnus-summary-expire-articles
5713 Expire all expirable articles in the group
5714 (@code{gnus-summary-expire-articles}).
5717 @kindex B M-C-e (Summary)
5718 @findex gnus-summary-expire-articles-now
5719 Expunge all the expirable articles in the group
5720 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
5721 articles that are eligible for expiry in the current group will
5722 disappear forever into that big @file{/dev/null} in the sky.
5725 @kindex B DEL (Summary)
5726 @findex gnus-summary-delete-articles
5727 Delete the mail article. This is ``delete'' as in ``delete it from your
5728 disk forever and ever, never to return again.'' Use with caution.
5729 (@code{gnus-summary-delete-article}).
5732 @kindex B m (Summary)
5734 @findex gnus-summary-move-article
5735 Move the article from one mail group to another
5736 (@code{gnus-summary-move-article}).
5739 @kindex B c (Summary)
5741 @findex gnus-summary-copy-article
5742 Copy the article from one group (mail group or not) to a mail group
5743 (@code{gnus-summary-copy-article}).
5746 @kindex B C (Summary)
5747 @cindex crosspost mail
5748 @findex gnus-summary-crosspost-article
5749 Crosspost the current article to some other group
5750 (@code{gnus-summary-crosspost-article}). This will create a new copy of
5751 the article in the other group, and the Xref headers of the article will
5752 be properly updated.
5755 @kindex B i (Summary)
5756 @findex gnus-summary-import-article
5757 Import an arbitrary file into the current mail newsgroup
5758 (@code{gnus-summary-import-article}). You will be prompted for a file
5759 name, a @code{From} header and a @code{Subject} header.
5761 Something similar can be done by just starting to compose a mail
5762 message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
5763 @kbd{C-c M-C-p} instead. This will put the message you have just created
5764 into the current mail group.
5767 @kindex B r (Summary)
5768 @findex gnus-summary-respool-article
5769 Respool the mail article (@code{gnus-summary-move-article}).
5773 @kindex B w (Summary)
5775 @findex gnus-summary-edit-article
5776 @kindex C-c C-c (Article)
5777 Edit the current article (@code{gnus-summary-edit-article}). To finish
5778 editing and make the changes permanent, type @kbd{C-c C-c}
5779 (@kbd{gnus-summary-edit-article-done}).
5782 @kindex B q (Summary)
5783 @findex gnus-summary-respool-query
5784 If you want to re-spool an article, you might be curious as to what group
5785 the article will end up in before you do the re-spooling. This command
5786 will tell you (@code{gnus-summary-respool-query}).
5789 @vindex gnus-move-split-methods
5790 @cindex moving articles
5791 If you move (or copy) articles regularly, you might wish to have Gnus
5792 suggest where to put the articles. @code{gnus-move-split-methods} is a
5793 variable that uses the same syntax as @code{gnus-split-methods}
5794 (@pxref{Saving Articles}). You may customize that variable to create
5795 suggestions you find reasonable.
5798 @node Various Summary Stuff
5799 @section Various Summary Stuff
5802 * Summary Group Information:: Information oriented commands.
5803 * Searching for Articles:: Multiple article commands.
5804 * Really Various Summary Commands:: Those pesky non-conformant commands.
5808 @vindex gnus-summary-mode-hook
5809 @item gnus-summary-mode-hook
5810 This hook is called when creating a summary mode buffer.
5812 @vindex gnus-summary-generate-hook
5813 @item gnus-summary-generate-hook
5814 This is called as the last thing before doing the threading and the
5815 generation of the summary buffer. It's quite convenient for customizing
5816 the threading variables based on what data the newsgroup has. This hook
5817 is called from the summary buffer after most summary buffer variables
5820 @vindex gnus-summary-prepare-hook
5821 @item gnus-summary-prepare-hook
5822 Is is called after the summary buffer has been generated. You might use
5823 it to, for instance, highlight lines or modify the look of the buffer in
5824 some other ungodly manner. I don't care.
5829 @node Summary Group Information
5830 @subsection Summary Group Information
5835 @kindex H f (Summary)
5836 @findex gnus-summary-fetch-faq
5837 @vindex gnus-group-faq-directory
5838 Try to fetch the FAQ (list of frequently asked questions) for the
5839 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
5840 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
5841 on a remote machine. This variable can also be a list of directories.
5842 In that case, giving a prefix to this command will allow you to choose
5843 between the various sites. @code{ange-ftp} probably will be used for
5847 @kindex H d (Summary)
5848 @findex gnus-summary-describe-group
5849 Give a brief description of the current group
5850 (@code{gnus-summary-describe-group}). If given a prefix, force
5851 rereading the description from the server.
5854 @kindex H h (Summary)
5855 @findex gnus-summary-describe-briefly
5856 Give a very brief description of the most important summary keystrokes
5857 (@code{gnus-summary-describe-briefly}).
5860 @kindex H i (Summary)
5861 @findex gnus-info-find-node
5862 Go to the Gnus info node (@code{gnus-info-find-node}).
5866 @node Searching for Articles
5867 @subsection Searching for Articles
5872 @kindex M-s (Summary)
5873 @findex gnus-summary-search-article-forward
5874 Search through all subsequent articles for a regexp
5875 (@code{gnus-summary-search-article-forward}).
5878 @kindex M-r (Summary)
5879 @findex gnus-summary-search-article-backward
5880 Search through all previous articles for a regexp
5881 (@code{gnus-summary-search-article-backward}).
5885 @findex gnus-summary-execute-command
5886 This command will prompt you for a header field, a regular expression to
5887 match on this field, and a command to be executed if the match is made
5888 (@code{gnus-summary-execute-command}).
5891 @kindex M-& (Summary)
5892 @findex gnus-summary-universal-argument
5893 Perform any operation on all articles that have been marked with
5894 the process mark (@code{gnus-summary-universal-argument}).
5898 @node Really Various Summary Commands
5899 @subsection Really Various Summary Commands
5904 @kindex A D (Summary)
5905 @findex gnus-summary-enter-digest-group
5906 If the current article is a collection of other articles (for instance,
5907 a digest), you might use this command to enter a group based on the that
5908 article (@code{gnus-summary-enter-digest-group}). Gnus will try to
5909 guess what article type is currently displayed unless you give a prefix
5910 to this command, which forces a ``digest'' interpretation. Basically,
5911 whenever you see a message that is a collection of other messages on
5912 some format, you @kbd{A D} and read these messages in a more convenient
5916 @kindex C-t (Summary)
5917 @findex gnus-summary-toggle-truncation
5918 Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
5922 @findex gnus-summary-expand-window
5923 Expand the summary buffer window (@code{gnus-summary-expand-window}).
5924 If given a prefix, force an @code{article} window configuration.
5928 @node Exiting the Summary Buffer
5929 @section Exiting the Summary Buffer
5930 @cindex summary exit
5931 @cindex exiting groups
5933 Exiting from the summary buffer will normally update all info on the
5934 group and return you to the group buffer.
5940 @kindex Z Z (Summary)
5942 @findex gnus-summary-exit
5943 @vindex gnus-summary-exit-hook
5944 @vindex gnus-summary-prepare-exit-hook
5945 Exit the current group and update all information on the group
5946 (@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
5947 called before doing much of the exiting, and calls
5948 @code{gnus-summary-expire-articles} by default.
5949 @code{gnus-summary-exit-hook} is called after finishing the exiting
5954 @kindex Z E (Summary)
5956 @findex gnus-summary-exit-no-update
5957 Exit the current group without updating any information on the group
5958 (@code{gnus-summary-exit-no-update}).
5962 @kindex Z c (Summary)
5964 @findex gnus-summary-catchup-and-exit
5965 Mark all unticked articles in the group as read and then exit
5966 (@code{gnus-summary-catchup-and-exit}).
5969 @kindex Z C (Summary)
5970 @findex gnus-summary-catchup-all-and-exit
5971 Mark all articles, even the ticked ones, as read and then exit
5972 (@code{gnus-summary-catchup-all-and-exit}).
5975 @kindex Z n (Summary)
5976 @findex gnus-summary-catchup-and-goto-next-group
5977 Mark all articles as read and go to the next group
5978 (@code{gnus-summary-catchup-and-goto-next-group}).
5981 @kindex Z R (Summary)
5982 @findex gnus-summary-reselect-current-group
5983 Exit this group, and then enter it again
5984 (@code{gnus-summary-reselect-current-group}). If given a prefix, select
5985 all articles, both read and unread.
5989 @kindex Z G (Summary)
5990 @kindex M-g (Summary)
5991 @findex gnus-summary-rescan-group
5992 Exit the group, check for new articles in the group, and select the
5993 group (@code{gnus-summary-rescan-group}). If given a prefix, select all
5994 articles, both read and unread.
5997 @kindex Z N (Summary)
5998 @findex gnus-summary-next-group
5999 Exit the group and go to the next group
6000 (@code{gnus-summary-next-group}).
6003 @kindex Z P (Summary)
6004 @findex gnus-summary-prev-group
6005 Exit the group and go to the previous group
6006 (@code{gnus-summary-prev-group}).
6009 @vindex gnus-exit-group-hook
6010 @code{gnus-exit-group-hook} is called when you exit the current
6013 @findex gnus-summary-wake-up-the-dead
6014 @findex gnus-dead-summary-mode
6015 @vindex gnus-kill-summary-on-exit
6016 If you're in the habit of exiting groups, and then changing your mind
6017 about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}.
6018 If you do that, Gnus won't kill the summary buffer when you exit it.
6019 (Quelle surprise!) Instead it will change the name of the buffer to
6020 something like @samp{*Dead Summary ... *} and install a minor mode
6021 called @code{gnus-dead-summary-mode}. Now, if you switch back to this
6022 buffer, you'll find that all keys are mapped to a function called
6023 @code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead
6024 summary buffer will result in a live, normal summary buffer.
6026 There will never be more than one dead summary buffer at any one time.
6028 @vindex gnus-use-cross-reference
6029 The data on the current group will be updated (which articles you have
6030 read, which articles you have replied to, etc.) when you exit the
6031 summary buffer. If the @code{gnus-use-cross-reference} variable is
6032 @code{t} (which is the default), articles that are cross-referenced to
6033 this group and are marked as read, will also be marked as read in the
6034 other subscribed groups they were cross-posted to. If this variable is
6035 neither @code{nil} nor @code{t}, the article will be marked as read in
6036 both subscribed and unsubscribed groups.
6040 Marking cross-posted articles as read ensures that you'll never have to
6041 read the same article more than once. Unless, of course, somebody has
6042 posted it to several groups separately. Posting the same article to
6043 several groups (not cross-posting) is called @dfn{spamming}, and you are
6044 by law required to send nasty-grams to anyone who perpetrates such a
6047 Remember: Cross-posting is kinda ok, but posting the same article
6048 separately to several groups is not.
6050 @cindex cross-posting
6053 One thing that may cause Gnus to not do the cross-posting thing
6054 correctly is if you use an @sc{nntp} server that supports @sc{xover}
6055 (which is very nice, because it speeds things up considerably) which
6056 does not include the @code{Xref} header in its @sc{nov} lines. This is
6057 Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
6058 even with @sc{xover} by registering the @code{Xref} lines of all
6059 articles you actually read, but if you kill the articles, or just mark
6060 them as read without reading them, Gnus will not get a chance to snoop
6061 the @code{Xref} lines out of these articles, and will be unable to use
6062 the cross reference mechanism.
6064 @cindex LIST overview.fmt
6065 @cindex overview.fmt
6066 To check whether your @sc{nntp} server includes the @code{Xref} header
6067 in its overview files, try @samp{telnet your.nntp.server nntp} and then
6068 say @samp{LIST overview.fmt}. This may not work, but if it does, and
6069 the last line you get does not read @samp{Xref:full}, then you should
6070 shout and whine at your news admin until she includes the @code{Xref}
6071 header in the overview files.
6073 @vindex gnus-nov-is-evil
6074 If you want Gnus to get the @code{Xref}s right all the time, you have to
6075 set @code{gnus-nov-is-evil} to @code{t}, which slows things down
6081 @node The Article Buffer
6082 @chapter The Article Buffer
6083 @cindex article buffer
6085 The articles are displayed in the article buffer, of which there is only
6086 one. All the summary buffers share the same article buffer unless you
6087 tell Gnus otherwise.
6090 * Hiding Headers:: Deciding what headers should be displayed.
6091 * Using MIME:: Pushing articles through @sc{mime} before reading them.
6092 * Customizing Articles:: Tailoring the look of the articles.
6093 * Article Keymap:: Keystrokes available in the article buffer
6094 * Misc Article:: Other stuff.
6098 @node Hiding Headers
6099 @section Hiding Headers
6100 @cindex hiding headers
6101 @cindex deleting headers
6103 The top section of each article is the @dfn{head}. (The rest is the
6104 @dfn{body}, but you may have guessed that already.)
6106 @vindex gnus-show-all-headers
6107 There is a lot of useful information in the head: the name of the person
6108 who wrote the article, the date it was written and the subject of the
6109 article. That's well and nice, but there's also lots of information
6110 most people do not want to see---what systems the article has passed
6111 through before reaching you, the @code{Message-ID}, the
6112 @code{References}, etc. ad nauseum---and you'll probably want to get rid
6113 of some of those lines. If you want to keep all those lines in the
6114 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
6116 Gnus provides you with two variables for sifting headers:
6120 @item gnus-visible-headers
6121 @vindex gnus-visible-headers
6122 If this variable is non-@code{nil}, it should be a regular expression
6123 that says what headers you wish to keep in the article buffer. All
6124 headers that do not match this variable will be hidden.
6126 For instance, if you only want to see the name of the person who wrote
6127 the article and the subject, you'd say:
6130 (setq gnus-visible-headers "^From:\\|^Subject:")
6133 This variable can also be a list of regexps to match headers that are to
6136 @item gnus-ignored-headers
6137 @vindex gnus-ignored-headers
6138 This variable is the reverse of @code{gnus-visible-headers}. If this
6139 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
6140 should be a regular expression that matches all lines that you want to
6141 hide. All lines that do not match this variable will remain visible.
6143 For instance, if you just want to get rid of the @code{References} line
6144 and the @code{Xref} line, you might say:
6147 (setq gnus-ignored-headers "^References:\\|^Xref:")
6150 This variable can also be a list of regexps to match headers that are to
6153 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
6154 variable will have no effect.
6158 @vindex gnus-sorted-header-list
6159 Gnus can also sort the headers for you. (It does this by default.) You
6160 can control the sorting by setting the @code{gnus-sorted-header-list}
6161 variable. It is a list of regular expressions that says in what order
6162 the headers are to be displayed.
6164 For instance, if you want the name of the author of the article first,
6165 and then the subject, you might say something like:
6168 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
6171 Any headers that are to remain visible, but are not listed in this
6172 variable, will be displayed in random order after all the headers that
6173 are listed in this variable.
6175 @findex gnus-article-hide-boring-headers
6176 @vindex gnus-article-display-hook
6177 @vindex gnus-boring-article-headers
6178 You can hide further boring headers by entering
6179 @code{gnus-article-hide-boring-headers} into
6180 @code{gnus-article-display-hook}. What this function does depends on
6181 the @code{gnus-boring-article-headers} variable. It's a list, but this
6182 list doesn't actually contain header names. Instead is lists various
6183 @dfn{boring conditions} that Gnus can check and remove from sight.
6185 These conditions are:
6188 Remove all empty headers.
6190 Remove the @code{Newsgroups} header if it only contains the current group
6193 Remove the @code{Followup-To} header if it is identical to the
6194 @code{Newsgroups} header.
6196 Remove the @code{Reply-To} header if it lists the same address as the
6199 Remove the @code{Date} header if the article is less than three days
6203 To include the four first elements, you could say something like;
6206 (setq gnus-boring-article-headers
6207 '(empty newsgroups followup-to reply-to))
6210 This is also the default value for this variable.
6214 @section Using @sc{mime}
6217 Mime is a standard for waving your hands through the air, aimlessly,
6218 while people stand around yawning.
6220 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
6221 while all newsreaders die of fear.
6223 @sc{mime} may specify what character set the article uses, the encoding
6224 of the characters, and it also makes it possible to embed pictures and
6225 other naughty stuff in innocent-looking articles.
6227 @vindex gnus-show-mime
6228 @vindex gnus-show-mime-method
6229 @vindex gnus-strict-mime
6230 @findex metamail-buffer
6231 Gnus handles @sc{mime} by shoving the articles through
6232 @code{gnus-show-mime-method}, which is @code{metamail-buffer} by
6233 default. Set @code{gnus-show-mime} to @code{t} if you want to use
6234 @sc{mime} all the time. However, if @code{gnus-strict-mime} is
6235 non-@code{nil}, the @sc{mime} method will only be used if there are
6236 @sc{mime} headers in the article.
6238 It might be best to just use the toggling functions from the summary
6239 buffer to avoid getting nasty surprises. (For instance, you enter the
6240 group @samp{alt.sing-a-long} and, before you know it, @sc{mime} has
6241 decoded the sound file in the article and some horrible sing-a-long song
6242 comes streaming out out your speakers, and you can't find the volume
6243 button, because there isn't one, and people are starting to look at you,
6244 and you try to stop the program, but you can't, and you can't find the
6245 program to control the volume, and everybody else in the room suddenly
6246 decides to look at you disdainfully, and you'll feel rather stupid.)
6248 Any similarity to real events and people is purely coincidental. Ahem.
6251 @node Customizing Articles
6252 @section Customizing Articles
6253 @cindex article customization
6255 @vindex gnus-article-display-hook
6256 The @code{gnus-article-display-hook} is called after the article has
6257 been inserted into the article buffer. It is meant to handle all
6258 treatment of the article before it is displayed.
6260 @findex gnus-article-maybe-highlight
6261 By default it contains @code{gnus-article-hide-headers},
6262 @code{gnus-article-treat-overstrike}, and
6263 @code{gnus-article-maybe-highlight}, but there are thousands, nay
6264 millions, of functions you can put in this hook. For an overview of
6265 functions @pxref{Article Highlighting}, @pxref{Article Hiding},
6266 @pxref{Article Washing}, @pxref{Article Buttons} and @pxref{Article
6269 You can, of course, write your own functions. The functions are called
6270 from the article buffer, and you can do anything you like, pretty much.
6271 There is no information that you have to keep in the buffer---you can
6272 change everything. However, you shouldn't delete any headers. Instead
6273 make them invisible if you want to make them go away.
6276 @node Article Keymap
6277 @section Article Keymap
6279 Most of the keystrokes in the summary buffer can also be used in the
6280 article buffer. They should behave as if you typed them in the summary
6281 buffer, which means that you don't actually have to have a summary
6282 buffer displayed while reading. You can do it all from the article
6285 A few additional keystrokes are available:
6290 @kindex SPACE (Article)
6291 @findex gnus-article-next-page
6292 Scroll forwards one page (@code{gnus-article-next-page}).
6295 @kindex DEL (Article)
6296 @findex gnus-article-prev-page
6297 Scroll backwards one page (@code{gnus-article-prev-page}).
6300 @kindex C-c ^ (Article)
6301 @findex gnus-article-refer-article
6302 If point is in the neighborhood of a @code{Message-ID} and you press
6303 @kbd{r}, Gnus will try to get that article from the server
6304 (@code{gnus-article-refer-article}).
6307 @kindex C-c C-m (Article)
6308 @findex gnus-article-mail
6309 Send a reply to the address near point (@code{gnus-article-mail}). If
6310 given a prefix, include the mail.
6314 @findex gnus-article-show-summary
6315 Reconfigure the buffers so that the summary buffer becomes visible
6316 (@code{gnus-article-show-summary}).
6320 @findex gnus-article-describe-briefly
6321 Give a very brief description of the available keystrokes
6322 (@code{gnus-article-describe-briefly}).
6325 @kindex TAB (Article)
6326 @findex gnus-article-next-button
6327 Go to the next button, if any (@code{gnus-article-next-button}. This
6328 only makes sense if you have buttonizing turned on.
6331 @kindex M-TAB (Article)
6332 @findex gnus-article-prev-button
6333 Go to the previous button, if any (@code{gnus-article-prev-button}.
6339 @section Misc Article
6343 @item gnus-single-article-buffer
6344 @vindex gnus-single-article-buffer
6345 If non-@code{nil}, use the same article buffer for all the groups.
6346 (This is the default.) If @code{nil}, each group will have its own
6349 @vindex gnus-article-prepare-hook
6350 @item gnus-article-prepare-hook
6351 This hook is called right after the article has been inserted into the
6352 article buffer. It is mainly intended for functions that do something
6353 depending on the contents; it should probably not be used for changing
6354 the contents of the article buffer.
6356 @vindex gnus-article-display-hook
6357 @item gnus-article-display-hook
6358 This hook is called as the last thing when displaying an article, and is
6359 intended for modifying the contents of the buffer, doing highlights,
6360 hiding headers, and the like.
6362 @item gnus-article-mode-hook
6363 @vindex gnus-article-mode-hook
6364 Hook called in article mode buffers.
6366 @vindex gnus-article-mode-line-format
6367 @item gnus-article-mode-line-format
6368 This variable is a format string along the same lines as
6369 @code{gnus-summary-mode-line-format}. It accepts exactly the same
6370 format specifications as that variable.
6371 @vindex gnus-break-pages
6373 @item gnus-break-pages
6374 Controls whether @dfn{page breaking} is to take place. If this variable
6375 is non-@code{nil}, the articles will be divided into pages whenever a
6376 page delimiter appears in the article. If this variable is @code{nil},
6377 paging will not be done.
6379 @item gnus-page-delimiter
6380 @vindex gnus-page-delimiter
6381 This is the delimiter mentioned above. By default, it is @samp{^L}
6392 All message composition (both mail and news) takes place in
6393 @code{message} mode buffers.
6396 * Message Interface:: Setting up message buffers.
6397 * Message Commands:: Commands you can execute in message mode buffers.
6398 * Message Variables:: Customizing the message buffers.
6402 @node Message Interface
6403 @section Message Interface
6405 When a program (or a person) wants to respond to a message -- reply,
6406 follow up, forward, cancel -- the program (or person) should just put
6407 point in the buffer where the message is and call the required command.
6408 @code{Message} will then pop up a new @code{message} mode buffer with
6409 appropriate headers filled out, and the user can edit the message before
6413 * New Mail Message::
6414 * New News Message::
6426 @node New Mail Message
6427 @subsection New Mail Message
6429 @findex message-mail
6430 The @code{message-mail} command pops up a new message buffer.
6432 Two optional parameters are accepted: The first will be used as the
6433 @code{To} header and the second as the @code{Subject} header. If these
6434 aren't present, those two headers will be empty.
6437 @node New News Message
6438 @subsection New News Message
6440 @findex message-news
6441 The @code{message-news} command pops up a new message buffer.
6443 This function accepts two optional parameters. The first will be used
6444 as the @code{Newsgroups} header and the second as the @code{Subject}
6445 header. If these aren't present, those two headers will be empty.
6451 @findex message-reply
6452 The @code{message-reply} function pops up a message buffer that's a
6453 reply to the message in the current buffer.
6455 @vindex message-reply-to-function
6456 Message uses the normal methods to determine where replies are to go,
6457 but you can change the behavior to suit your needs by fiddling with the
6458 @code{message-reply-to-function} variable.
6460 If you want the replies to go to the @code{Sender} instead of the
6461 @code{From}, you could do something like this:
6464 (setq message-reply-to-function
6466 (cond ((equal (mail-fetch-field "from") "somebody")
6467 (mail-fetch-field "sender"))
6472 This function will be called narrowed to the head of the article that is
6475 As you can see, this function should return a string if it has an
6476 opinion as to what the To header should be. If it does not, it should
6477 just return @code{nil}, and the normal methods for determining the To
6478 header will be used.
6480 This function can also return a list. In that case, each list element
6481 should be a cons, where the car should be the name of an header
6482 (eg. @code{Cc}) and the cdr should be the header value
6483 (eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into
6484 the head of the outgoing mail.
6488 @subsection Wide Reply
6490 @findex message-wide-reply
6491 The @code{message-wide-reply} pops up a message buffer that's a wide
6492 reply to the message in the current buffer.
6494 @vindex message-wide-reply-to-function
6495 Message uses the normal methods to determine where wide replies are to go,
6496 but you can change the behavior to suit your needs by fiddling with the
6497 @code{message-wide-reply-to-function}. It is used in the same way as
6498 @code{message-reply-to-function} (@pxref{Reply}).
6502 @subsection Followup
6504 @findex message-followup
6505 The @code{message-followup} command pops up a message buffer that's a
6506 followup to the message in the current buffer.
6508 @vindex message-followup-to-function
6509 Message uses the normal methods to determine where followups are to go,
6510 but you can change the behavior to suit your needs by fiddling with the
6511 @code{message-followup-to-function}. It is used in the same way as
6512 @code{message-reply-to-function} (@pxref{Reply}).
6514 @vindex message-use-followup-to
6515 The @code{message-use-followup-to} variable says what to do about
6516 @code{Followup-To} headers. If it is @code{use}, always use the value.
6517 If it is @code{ask} (which is the default), ask whether to use the
6518 value. If it is @code{t}, use the value unless it is @samp{poster}. If
6519 it is @code{nil}, don't use the value.
6522 @node Canceling News
6523 @subsection Canceling News
6525 @findex message-cancel-news
6526 The @code{message-cancel-news} command cancels the article in the
6531 @subsection Superseding
6533 @findex message-supersede
6534 The @code{message-supersede} command pops up a message buffer that will
6535 supersede the message in the current buffer.
6537 @vindex message-ignored-supersedes-headers
6538 Headers matching the @code{message-ignored-supersedes-headers} are
6539 removed before popping up the new message buffer. The default is
6540 @samp{^Path:\\|^Date\\|^NNTP-Posting-Host:\\|^Xref:\\|^Lines:\\|^Received:\\|^X-From-Line:\\|Return-Path:}.
6545 @subsection Forwarding
6547 @findex message-forward
6548 The @code{message-forward} command pops up a message buffer to forward
6549 the message in the current buffer. If given a prefix, forward using
6553 @item message-forward-start-separator
6554 @vindex message-forward-start-separator
6555 Delimiter inserted before forwarded messages. The default is
6556 @samp{------- Start of forwarded message -------\n}.
6558 @vindex message-forward-end-separator
6559 @item message-forward-end-separator
6560 @vindex message-forward-end-separator
6561 Delimiter inserted after forwarded messages. The default is
6562 @samp{------- End of forwarded message -------\n}.
6564 @item message-signature-before-forwarded-message
6565 @vindex message-signature-before-forwarded-message
6566 If this variable is @code{t}, which it is by default, your personal
6567 signature will be inserted before the forwarded message. If not, the
6568 forwarded message will be inserted first in the new mail.
6570 @item message-forward-included-headers
6571 @vindex message-forward-included-headers
6572 Regexp matching header lines to be included in forwarded messages.
6578 @subsection Resending
6580 @findex message-resend
6581 The @code{message-resend} command will prompt the user for an address
6582 and resend the message in the current buffer to that address.
6584 @vindex message-ignored-resent-headers
6585 Headers the match the @code{message-ignored-resent-headers} regexp will
6586 be removed before sending the message. The default is
6587 @samp{^Return-receipt}.
6591 @subsection Bouncing
6593 @findex message-bounce
6594 The @code{message-bounce} command will, if the current buffer contains a
6595 bounced mail message, pop up a message buffer stripped of the bounce
6598 @vindex message-ignored-bounced-headers
6599 Headers that match the @code{message-ignored-bounced-headers} regexp
6600 will be removed before popping up the buffer. The default is
6604 @node Message Commands
6605 @section Message Commands
6608 * Message Header Commands:: Commands for moving to headers.
6609 * Message Movement:: Moving around in message buffers.
6610 * Message Insertion:: Inserting things into message buffers.
6611 * Various Message:: Various things.
6612 * Sending Messages:: Actually sending the message.
6616 @node Message Header Commands
6617 @subsection Message Header Commands
6619 All these commands move to the header in question. If it doesn't exist,
6620 it will be inserted.
6625 @kindex C-c ? (Message)
6626 @findex message-goto-to
6627 Describe the message mode.
6630 @kindex C-c C-f C-t (Message)
6631 @findex message-goto-to
6632 Go to the @code{To} header (@code{message-goto-to}).
6635 @kindex C-c C-f C-b (Message)
6636 @findex message-goto-bcc
6637 Go to the @code{Bcc} header (@code{message-goto-bcc}).
6640 @kindex C-c C-f C-f (Message)
6641 @findex message-goto-fcc
6642 Go to the @code{Fcc} header (@code{message-goto-fcc}).
6645 @kindex C-c C-f C-c (Message)
6646 @findex message-goto-cc
6647 Go to the @code{Cc} header (@code{message-goto-cc}).
6650 @kindex C-c C-f C-s (Message)
6651 @findex message-goto-subject
6652 Go to the @code{Subject} header (@code{message-goto-subject}).
6655 @kindex C-c C-f C-r (Message)
6656 @findex message-goto-reply-to
6657 Go to the @code{Reply-To} header (@code{message-goto-reply-to}).
6660 @kindex C-c C-f C-n (Message)
6661 @findex message-goto-newsgroups
6662 Go to the @code{Newsgroups} header (@code{message-goto-newsgroups}).
6665 @kindex C-c C-f C-d (Message)
6666 @findex message-goto-distribution
6667 Go to the @code{Distribution} header (@code{message-goto-distribution}).
6670 @kindex C-c C-f C-o (Message)
6671 @findex message-goto-followup-to
6672 Go to the @code{Followup-To} header (@code{message-goto-followup-to}).
6675 @kindex C-c C-f C-k (Message)
6676 @findex message-goto-keywords
6677 Go to the @code{Keywords} header (@code{message-goto-keywords}).
6680 @kindex C-c C-f C-u (Message)
6681 @findex message-goto-summary
6682 Go to the @code{Summary} header (@code{message-goto-summary}).
6687 @node Message Movement
6688 @subsection Message Movement
6692 @kindex C-c C-b (Message)
6693 @findex message-goto-body
6694 Move to the beginning of the body of the message
6695 (@code{message-goto-body}).
6698 @kindex C-c C-i (Message)
6699 @findex message-goto-signature
6700 Move to the signature of the message (@code{message-goto-signature}).
6705 @node Message Insertion
6706 @subsection Message Insertion
6711 @kindex C-c C-y (Message)
6712 @findex message-yank-original
6713 Yank the message that's being replied to into the message buffer
6714 (@code{message-yank-original}).
6717 @kindex C-c C-q (Message)
6718 @findex message-fill-yanked-message
6719 Fill the yanked message (@code{message-fill-yanked-message}).
6722 @kindex C-c C-w (Message)
6723 @findex message-insert-signature
6724 Insert a signature at the end of the buffer
6725 (@code{message-insert-signature}).
6730 @item message-ignored-cited-headers
6731 @vindex message-ignored-cited-headers
6732 All headers that match this regexp will be removed from yanked
6733 messages. The default is @samp{.}, which means that all headers will be
6736 @item message-citation-line-function
6737 @vindex message-citation-line-function
6738 Function called to insert the citation line. The default is
6739 @code{message-insert-citation-line}.
6741 @item message-yank-prefix
6742 @vindex message-yank-prefix
6745 When you are replying to or following up an article, you normally want
6746 to quote the person you are answering. Inserting quoted text is done by
6747 @dfn{yanking}, and each quoted line you yank will have
6748 @code{message-yank-prefix} prepended to it. The default is @samp{> }.
6749 If it is @code{nil}, just indent the message.
6751 @item message-indentation-spaces
6752 @vindex message-indentation-spaces
6753 Number of spaces to indent yanked messages.
6755 @item message-cite-function
6756 @vindex message-cite-function
6757 Function for citing an original message. The default is
6758 @code{message-cite-original}.
6760 @item message-indent-citation-function
6761 @vindex message-indent-citation-function
6762 Function for modifying a citation just inserted in the mail buffer.
6763 This can also be a list of functions. Each function can find the
6764 citation between @code{(point)} and @code{(mark t)}. And each function
6765 should leave point and mark around the citation text as modified.
6767 @item message-signature
6768 @vindex message-signature
6769 String to be inserted at the end of the message buffer. If @code{t}
6770 (which is the default), the @code{message-signature-file} file will be
6771 inserted instead. If a function, the result from the function will be
6772 used instead. If a form, the result from the form will be used instead.
6773 If this variable is @code{nil}, no signature will be inserted at all.
6775 @item message-signature-file
6776 @vindex message-signature-file
6777 File containing the signature to be inserted at the end of the buffer.
6778 The default is @samp{~/.signature}.
6782 Note that RFC1036 says that a signature should be preceded by the three
6783 characters @samp{-- } on a line by themselves. This is to make it
6784 easier for the recipient to automatically recognize and process the
6785 signature. So don't remove those characters, even though you might feel
6786 that they ruin you beautiful design, like, totally.
6788 Also note that no signature should be more than four lines long.
6789 Including ASCII graphics is an efficient way to get everybody to believe
6790 that you are silly and have nothing important to say.
6794 @node Various Message
6795 @subsection Various Message
6800 @kindex C-c C-r (Message)
6801 @findex message-caesar-buffer-body
6802 Caesar rotate (aka. rot13) the current message
6803 (@code{message-caesar-buffer-body}). If narrowing is in effect, just
6804 rotate the visible portion of the buffer. A numerical prefix says how
6805 many places to rotate the text. The default is 13.
6808 @kindex C-c C-t (Message)
6809 @findex message-insert-to
6810 Insert a @code{To} header that contains the @code{Reply-To} or
6811 @code{From} header of the message you're following up
6812 (@code{message-insert-to}).
6815 @kindex C-c C-n (Message)
6816 @findex message-insert-newsgroups
6817 Insert a @code{Newsgroups} header that reflects the @code{Followup-To}
6818 or @code{Newsgroups} header of the article you're replying to
6819 (@code{message-insert-newsgroups}).
6824 @node Sending Messages
6825 @subsection Sending Messages
6829 @kindex C-c C-c (Message)
6830 @findex message-send-and-exit
6831 Send the message and bury the current buffer
6832 (@code{message-send-and-exit}).
6835 @kindex C-c C-s (Message)
6836 @findex message-send
6837 Send the message (@code{message-send}).
6842 @node Message Variables
6843 @section Message Variables
6851 * Various Message Variables::
6852 * Sending Variables::
6856 @node Message Headers
6857 @subsection Message Headers
6859 Message is a quite aggressive on the message generation front. It has
6860 to be -- it's a combined news and mail agent. To be able to send
6861 combined messages, it has to generate all headers itself to ensure that
6862 mail and news copies of messages look sufficiently similar.
6866 @item message-generate-headers-first
6867 @vindex message-generate-headers-first
6868 If non-@code{nil}, generate all headers before starting to compose the
6871 @item message-from-style
6872 @vindex message-from-style
6873 Specifies how @code{From} headers should look. There are four legal
6878 Just the address -- @samp{king@@grassland.com}.
6881 @samp{king@@grassland.com (Elvis Parsley)}.
6884 @samp{Elvis Parsley <king@@grassland.com>}.
6887 Look like @code{angles} if that doesn't require quoting, and
6888 @code{parens} if it does. If even @code{parens} requires quoting, use
6889 @code{angles} anyway.
6893 @item message-deletable-headers
6894 @vindex message-deletable-headers
6895 Headers in this list that were previously generated by Gnus will be
6896 deleted before posting. Let's say you post an article. Then you decide
6897 to post it again to some other group, you naughty boy, so you jump back
6898 to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
6899 ship it off again. By default, this variable makes sure that the old
6900 generated @code{Message-ID} is deleted, and a new one generated. If
6901 this isn't done, the entire empire would probably crumble, anarchy would
6902 prevail, and cats would start walking on two legs and rule the world.
6905 @item message-default-headers
6906 @vindex message-default-headers
6907 This string is inserted at the end of the headers in all message
6914 @subsection Mail Headers
6917 @item message-required-mail-headers
6918 @vindex message-required-mail-headers
6919 See @pxref{News Headers} for the syntax of this variable. It is
6920 @code{(From Date Subject (optional . In-Reply-To) Message-ID Lines
6921 (optional . X-Mailer))} by default.
6923 @item message-ignored-mail-headers
6924 @vindex message-ignored-mail-headers
6925 Regexp of headers to be removed before mailing. The default is
6926 @samp{^Gcc:\\|^Fcc:}.
6928 @item message-default-mail-headers
6929 @vindex message-default-mail-headers
6930 This string is inserted at the end of the headers in all message
6931 buffers that are initialized as mail.
6936 @node Mail Variables
6937 @subsection Mail Variables
6940 @item message-send-mail-function
6941 @vindex message-send-mail-function
6942 Function used to send the current buffer as mail. The default is
6943 @code{message-send-mail}.
6949 @subsection News Headers
6951 @vindex message-required-news-headers
6952 @code{message-required-news-headers} a list of header symbols. These
6953 headers will either be automatically generated, or, if that's
6954 impossible, they will be prompted for. The following symbols are legal:
6960 This required header will be filled out with the result of the
6961 @code{message-make-from} function, which depends on the
6962 @code{message-from-style}, @code{user-full-name},
6963 @code{user-mail-address} variables.
6967 This required header will be prompted for if not present already.
6971 This required header says which newsgroups the article is to be posted
6972 to. If it isn't present already, it will be prompted for.
6975 @cindex organization
6976 This optional header will be filled out depending on the
6977 @code{message-user-organization} variable.
6978 @code{message-user-organization-file} will be used if that variable is
6983 This optional header will be computed by Gnus.
6987 This required header will be generated by Gnus. A unique ID will be
6988 created based on date, time, user name and system name.
6991 @cindex X-Newsreader
6992 This optional header will be filled out according to the
6993 @code{message-newsreader} local variable.
6996 This optional header will be filled out according to the
6997 @code{message-mailer} local variable, unless there already is an
6998 @code{X-Newsreader} header present.
7001 This optional header is filled out using the @code{Date} and @code{From}
7002 header of the article being replied.
7006 This extremely optional header will be inserted according to the
7007 @code{message-expires} variable. It is highly deprecated and shouldn't
7008 be used unless you know what you're doing.
7011 @cindex Distribution
7012 This optional header is filled out according to the
7013 @code{message-distribution-function} variable. It is a deprecated and
7014 much misunderstood header.
7018 This extremely optional header should probably not ever be used.
7019 However, some @emph{very} old servers require that this header is
7020 present. @code{message-user-path} further controls how this
7021 @code{Path} header is to look. If is is @code{nil}, the the server name
7022 as the leaf node. If is is a string, use the string. If it is neither
7023 a string nor @code{nil}, use the user name only. However, it is highly
7024 unlikely that you should need to fiddle with this variable at all.
7028 @cindex Mime-Version
7029 In addition, you can enter conses into this list. The car of this cons
7030 should be a symbol. This symbol's name is the name of the header, and
7031 the cdr can either be a string to be entered verbatim as the value of
7032 this header, or it can be a function to be called. This function should
7033 return a string to be inserted. For instance, if you want to insert
7034 @code{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
7035 into the list. If you want to insert a funny quote, you could enter
7036 something like @code{(X-Yow . yow)} into the list. The function
7037 @code{yow} will then be called without any arguments.
7039 If the list contains a cons where the car of the cons is
7040 @code{optional}, the cdr of this cons will only be inserted if it is
7043 Other variables for customizing outgoing news articles:
7047 @item message-syntax-checks
7048 @vindex message-syntax-checks
7049 If non-@code{nil}, message will attempt to check the legality of the
7050 headers, as well as some other stuff, before posting. You can control
7051 the granularity of the check by adding or removing elements from this
7052 list. Legal elements are:
7056 Check the subject for commands.
7059 Insert a new @code{Sender} header if the @code{From} header looks odd.
7060 @item multiple-headers
7061 Check for the existence of multiple equal headers.
7064 Check for the existence of version and sendsys commands.
7066 Check whether the @code{Message-ID} looks ok.
7068 Check whether the @code{From} header seems nice.
7071 Check for too long lines.
7073 Check for illegal characters.
7075 Check for excessive size.
7077 Check whether there is any new text in the messages.
7079 Check the length of the signature.
7082 Check whether the article has an @code{Approved} header, which is
7083 something only moderators should include.
7085 Check whether the article is empty.
7087 Check whether any of the headers are empty.
7090 All these conditions are checked by default.
7092 @item message-ignored-news-headers
7093 @vindex message-ignored-news-headers
7094 Regexp of headers to be removed before posting. The default is
7095 @samp{^NNTP-Posting-Host:\\|^Xref:\\|^Bcc:\\|^Gcc:\\|^Fcc:}.
7097 @item message-default-news-headers
7098 @vindex message-default-news-headers
7099 This string is inserted at the end of the headers in all message
7100 buffers that are initialized as news.
7105 @node News Variables
7106 @subsection News Variables
7109 @item message-send-news-function
7110 @vindex message-send-news-function
7111 Function used to send the current buffer as news. The default is
7112 @code{message-send-news}.
7114 @item message-post-method
7115 @vindex message-post-method
7116 Method used for posting a prepared news message.
7121 @node Various Message Variables
7122 @subsection Various Message Variables
7125 @item message-signature-separator
7126 @vindex message-signature-separator
7127 Regexp matching the signature separator. It is @samp{^-- *$} by
7130 @item mail-header-separator
7131 @vindex mail-header-separator
7132 String used to separate the headers from the body. It is @samp{--text
7133 follows this line--} by default.
7135 @item message-autosave-directory
7136 @vindex message-autosave-directory
7137 Directory where message buffers will be autosaved to.
7139 @item message-setup-hook
7140 @vindex message-setup-hook
7141 Hook run when the message buffer has been initialized.
7143 @item message-header-setup-hook
7144 @vindex message-header-setup-hook
7145 Hook called narrowed to the headers after initializing the headers.
7147 @item message-send-hook
7148 @vindex message-send-hook
7149 Hook run before sending messages.
7151 @item message-sent-hook
7152 @vindex message-sent-hook
7153 Hook run after sending messages.
7155 @item message-mode-syntax-table
7156 @vindex message-mode-syntax-table
7157 Syntax table used in message mode buffers.
7163 @node Sending Variables
7164 @subsection Sending Variables
7168 @item message-fcc-handler-function
7169 @vindex message-fcc-handler-function
7170 A function called to save outgoing articles. This function will be
7171 called with the name of the file to store the article in. The default
7172 function is @code{rmail-output} which saves in Unix mailbox format.
7174 @item message-courtesy-message
7175 @vindex message-courtesy-message
7176 When sending combined messages, this string is inserted at the start of
7177 the mailed copy. If this variable is @code{nil}, no such courtesy
7178 message will be added.
7186 @node Composing Messages
7187 @chapter Composing Messages
7192 @kindex C-c C-c (Post)
7193 All commands for posting and mailing will put you in a message buffer
7194 where you can edit the article all you like, before you send the article
7195 by pressing @kbd{C-c C-c}. If you are in a foreign news group, and you
7196 wish to post the article using the foreign server, you can give a prefix
7197 to @kbd{C-c C-c} to make Gnus try to post using the foreign server.
7200 * Mail:: Mailing and replying.
7201 * Post:: Posting and following up.
7202 * Posting Server:: What server should you post via?
7203 * Mail and Post:: Mailing and posting at the same time.
7204 * Archived Messages:: Where Gnus stores the messages you've sent.
7205 * Posting Styles:: An easier way to configure some key elements.
7206 * Drafts:: Postponing messages and rejected messages.
7207 * Rejected Articles:: What happens if the server doesn't like your article?
7210 Also see @pxref{Canceling and Superseding} for information on how to
7211 remove articles you shouldn't have posted.
7217 Variables for customizing outgoing mail:
7220 @item gnus-uu-digest-headers
7221 @vindex gnus-uu-digest-headers
7222 List of regexps to match headers included in digested messages. The
7223 headers will be included in the sequence they are matched.
7231 Variables for composing news articles:
7234 @item gnus-sent-message-ids-file
7235 @vindex gnus-sent-message-ids-file
7236 Gnus will keep a @code{Message-ID} history file of all the mails it has
7237 sent. If it discovers that it has already sent a mail, it will ask the
7238 user whether to re-send the mail. (This is primarily useful when
7239 dealing with @sc{soup} packets and the like where one is apt to sent the
7240 same packet multiple times.) This variable says what the name of this
7241 history file is. It is @file{~/News/Sent-Message-IDs} by default. Set
7242 this variable to @code{nil} if you don't want Gnus to keep a history
7245 @item gnus-sent-message-ids-length
7246 @vindex gnus-sent-message-ids-length
7247 This variable says how many @code{Message-ID}s to keep in the history
7248 file. It is 1000 by default.
7253 @node Posting Server
7254 @section Posting Server
7256 When you press those magical @kbd{C-c C-c} keys to ship off your latest
7257 (extremely intelligent, of course) article, where does it go?
7259 Thank you for asking. I hate you.
7261 @vindex gnus-post-method
7263 It can be quite complicated. Normally, Gnus will use the same native
7264 server. However. If your native server doesn't allow posting, just
7265 reading, you probably want to use some other server to post your
7266 (extremely intelligent and fabulously interesting) articles. You can
7267 then set the @code{gnus-post-method} to some other method:
7270 (setq gnus-post-method '(nnspool ""))
7273 Now, if you've done this, and then this server rejects your article, or
7274 this server is down, what do you do then? To override this variable you
7275 can use a non-zero prefix to the @kbd{C-c C-c} command to force using
7276 the ``current'' server for posting.
7278 If you give a zero prefix (i. e., @kbd{C-u 0 C-c C-c}) to that command,
7279 Gnus will prompt you for what method to use for posting.
7281 You can also set @code{gnus-post-method} to a list of select methods.
7282 If that's the case, Gnus will always prompt you for what method to use
7287 @section Mail and Post
7289 Here's a list of variables that are relevant to both mailing and
7293 @item gnus-mailing-list-groups
7294 @findex gnus-mailing-list-groups
7295 @cindex mailing lists
7297 If your news server offers groups that are really mailing lists that are
7298 gatewayed to the @sc{nntp} server, you can read those groups without
7299 problems, but you can't post/followup to them without some difficulty.
7300 One solution is to add a @code{to-address} to the group parameters
7301 (@pxref{Group Parameters}). An easier thing to do is set the
7302 @code{gnus-mailing-list-groups} to a regexp that match the groups that
7303 really are mailing lists. Then, at least, followups to the mailing
7304 lists will work most of the time. Posting to these groups (@kbd{a}) is
7305 still a pain, though.
7309 You may want to do spell-checking on messages that you send out. Or, if
7310 you don't want to spell-check by hand, you could add automatic
7311 spell-checking via the @code{ispell} package:
7313 @vindex news-inews-hook
7315 @findex ispell-message
7317 (add-hook 'message-send-hook 'ispell-message)
7321 @node Archived Messages
7322 @section Archived Messages
7323 @cindex archived messages
7324 @cindex sent messages
7326 Gnus provides a few different methods for storing the mail you send.
7327 The default method is to use the @dfn{archive virtual server} to store
7328 the mail. If you want to disable this completely, you should set
7329 @code{gnus-message-archive-group} to @code{nil}.
7331 @vindex gnus-message-archive-method
7332 @code{gnus-message-archive-method} says what virtual server Gnus is to
7333 use to store sent messages. It is @code{(nnfolder "archive"
7334 (nnfolder-directory "~/Mail/archive/"))} by default, but you can use any
7335 mail select method (@code{nnml}, @code{nnmbox}, etc.). However,
7336 @code{nnfolder} is a quite likeable select method for doing this sort of
7337 thing. If you don't like the default directory chosen, you could say
7341 (setq gnus-message-archive-method
7342 '(nnfolder "archive"
7343 (nnfolder-inhibit-expiry t)
7344 (nnfolder-active-file "~/Mail/sent-mail/active")
7345 (nnfolder-directory "~/News/sent-mail/")))
7348 @vindex gnus-message-archive-group
7350 Gnus will insert @code{Gcc} headers in all outgoing messages that point
7351 to one or more group(s) on that server. Which group to use is
7352 determined by the @code{gnus-message-archive-group} variable.
7354 This variable can be:
7358 Messages will be saved in that group.
7359 @item a list of strings
7360 Messages will be saved in all those groups.
7361 @item an alist of regexps, functions and forms
7362 When a key ``matches'', the result is used.
7367 Just saving to a single group called @samp{MisK}:
7369 (setq gnus-message-archive-group "MisK")
7372 Saving to two groups, @samp{MisK} and @samp{safe}:
7374 (setq gnus-message-archive-group '("MisK" "safe"))
7377 Save to different groups based on what group you are in:
7379 (setq gnus-message-archive-group
7380 '(("^alt" "sent-to-alt")
7381 ("mail" "sent-to-mail")
7382 (".*" "sent-to-misc")))
7387 (setq gnus-message-archive-group
7388 '((if (message-news-p)
7393 This is the default.
7395 How about storing all news messages in one file, but storing all mail
7396 messages in one file per month:
7399 (setq gnus-message-archive-group
7400 '((if (message-news-p)
7402 (concat "mail." (format-time-string
7403 "%Y-%m" (current-time))))))
7406 Now, when you send a message off, it will be stored in the appropriate
7407 group. (If you want to disable storing for just one particular message,
7408 you can just remove the @code{Gcc} header that has been inserted.) The
7409 archive group will appear in the group buffer the next time you start
7410 Gnus, or the next time you press @kbd{F} in the group buffer. You can
7411 enter it and read the articles in it just like you'd read any other
7412 group. If the group gets really big and annoying, you can simply rename
7413 if (using @kbd{G r} in the group buffer) to something nice --
7414 @samp{misc-mail-september-1995}, or whatever. New messages will
7415 continue to be stored in the old (now empty) group.
7417 That's the default method of archiving sent mail. Gnus also offers two
7418 other variables for the people who don't like the default method. In
7419 that case you should set @code{gnus-message-archive-group} to
7420 @code{nil}; this will disable archiving.
7423 @item gnus-author-copy
7424 @vindex gnus-author-copy
7426 This is a file name, and all outgoing articles will be saved in that
7427 file. Initialized from the @code{AUTHORCOPY} environment variable.
7429 If this variable begins with the character @samp{|}, outgoing articles
7430 will be piped to the named program. It is possible to save an article in
7431 an MH folder as follows:
7434 (setq gnus-author-copy
7435 "|/usr/local/lib/mh/rcvstore +Article")
7438 If the first character is not a pipe, articles are saved using the
7439 function specified by the @code{gnus-author-copy-saver} variable.
7441 @item gnus-author-copy-saver
7442 @vindex gnus-author-copy-saver
7443 @findex rmail-output
7444 A function called to save outgoing articles. This function will be
7445 called with the same of the file to store the article in. The default
7446 function is @code{rmail-output} which saves in the Unix mailbox format.
7448 @item gnus-outgoing-message-group
7449 @vindex gnus-outgoing-message-group
7450 All outgoing messages will be put in this group. If you want to store
7451 all your outgoing mail and articles in the group @samp{nnml:archive},
7452 you set this variable to that value. This variable can also be a list of
7455 If you want to have greater control over what group to put each
7456 message in, you can set this variable to a function that checks the
7457 current newsgroup name and then returns a suitable group name (or list
7462 @node Posting Styles
7463 @section Posting Styles
7464 @cindex posting styles
7467 All them variables, they make my head swim.
7469 So what if you want a different @code{Organization} and signature based
7470 on what groups you post to? And you post both from your home machine
7471 and your work machine, and you want different @code{From} lines, and so
7474 @vindex gnus-posting-styles
7475 One way to do stuff like that is to write clever hooks that change the
7476 variables you need to have changed. That's a bit boring, so somebody
7477 came up with the bright idea of letting the user specify these things in
7478 a handy alist. Here's an example of a @code{gnus-posting-styles}
7483 (signature . "Peace and happiness")
7484 (organization . "What me?"))
7486 (signature . "Death to everybody"))
7487 ("comp.emacs.i-love-it"
7488 (organization . "Emacs is it")))
7491 As you might surmise from this example, this alist consists of several
7492 @dfn{styles}. Each style will be applicable if the first element
7493 ``matches'', in some form or other. The entire alist will be iterated
7494 over, from the beginning towards the end, and each match will be
7495 applied, which means that attributes in later styles that match override
7496 the same attributes in earlier matching styles. So
7497 @samp{comp.programming.literate} will have the @samp{Death to everybody}
7498 signature and the @samp{What me?} @code{Organization} header.
7500 The first element in each style is called the @code{match}. If it's a
7501 string, then Gnus will try to regexp match it against the group name.
7502 If it's a function symbol, that function will be called with no
7503 arguments. If it's a variable symbol, then the variable will be
7504 referenced. If it's a list, then that list will be @code{eval}ed. In
7505 any case, if this returns a non-@code{nil} value, then the style is said
7508 Each style may contain a arbitrary amount of @dfn{attributes}. Each
7509 attribute consists of a @var{(name . value)} pair. The attribute name
7510 can be one of @code{signature}, @code{organization} or @code{from}. The
7511 attribute name can also be a string. In that case, this will be used as
7512 a header name, and the value will be inserted in the headers of the
7515 The attribute value can be a string (used verbatim), a function (the
7516 return value will be used), a variable (its value will be used) or a
7517 list (it will be @code{eval}ed and the return value will be used).
7519 So here's a new example:
7522 (setq gnus-posting-styles
7524 (signature . "~/.signature")
7525 (from . "user@@foo (user)")
7526 ("X-Home-Page" . (getenv "WWW_HOME"))
7527 (organization . "People's Front Against MWM"))
7529 (signature . my-funny-signature-randomizer))
7530 ((equal (system-name) "gnarly")
7531 (signature . my-quote-randomizer))
7532 (posting-from-work-p
7533 (signature . "~/.work-signature")
7534 (from . "user@@bar.foo (user)")
7535 (organization . "Important Work, Inc"))
7537 (signature . "~/.mail-signature"))))
7545 If you are writing a message (mail or news) and suddenly remember that
7546 you have a steak in the oven (or some pesto in the food processor, you
7547 craazy vegetarians), you'll probably wish there was a method to save the
7548 message you are writing so that you can continue editing it some other
7549 day, and send it when you feel its finished.
7551 Well, don't worry about it. Whenever you start composing a message of
7552 some sort using the Gnus mail and post commands, the buffer you get will
7553 automatically associate to an article in a special @dfn{draft} group.
7554 If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the
7555 article will be saved there. (Auto-save files also go to the draft
7559 @vindex gnus-draft-group-directory
7560 The draft group is a special group (which is implemented as an
7561 @code{nndraft} group, if you absolutely have to know) called
7562 @samp{nndraft:drafts}. The variable @code{gnus-draft-group-directory}
7563 controls both the name of the group and the location---the leaf element
7564 in the path will be used as the name of the group. What makes this
7565 group special is that you can't tick any articles in it or mark any
7566 articles as read---all articles in the group are permanently unread.
7568 If the group doesn't exist, it will be created and you'll be subscribed
7571 @findex gnus-dissociate-buffer-from-draft
7572 @kindex C-c M-d (Mail)
7573 @kindex C-c M-d (Post)
7574 @findex gnus-associate-buffer-with-draft
7575 @kindex C-c C-d (Mail)
7576 @kindex C-c C-d (Post)
7577 If you're writing some super-secret message that you later want to
7578 encode with PGP before sending, you may wish to turn the auto-saving
7579 (and association with the draft group) off. You never know who might be
7580 interested in reading all your extremely valuable and terribly horrible
7581 and interesting secrets. The @kbd{C-c M-d}
7582 (@code{gnus-dissociate-buffer-from-draft}) command does that for you.
7583 If you change your mind and want to turn the auto-saving back on again,
7584 @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that.
7586 @vindex gnus-use-draft
7587 To leave association with the draft group off by default, set
7588 @code{gnus-use-draft} to @code{nil}. It is @code{t} by default.
7590 @findex gnus-summary-send-draft
7591 @kindex S D c (Summary)
7592 When you want to continue editing the article, you simply enter the
7593 draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
7594 that. You will be placed in a buffer where you left off.
7596 Rejected articles will also be put in this draft group (@pxref{Rejected
7599 @findex gnus-summary-send-all-drafts
7600 If you have lots of rejected messages you want to post (or mail) without
7601 doing further editing, you can use the @kbd{S D a} command
7602 (@code{gnus-summary-send-all-drafts}). This command understands the
7603 process/prefix convention (@pxref{Process/Prefix}).
7606 @node Rejected Articles
7607 @section Rejected Articles
7608 @cindex rejected articles
7610 Sometimes a news server will reject an article. Perhaps the server
7611 doesn't like your face. Perhaps it just feels miserable. Perhaps
7612 @emph{there be demons}. Perhaps you have included too much cited text.
7613 Perhaps the disk is full. Perhaps the server is down.
7615 These situations are, of course, totally beyond the control of Gnus.
7616 (Gnus, of course, loves the way you look, always feels great, has angels
7617 fluttering around inside of it, doesn't care about how much cited text
7618 you include, never runs full and never goes down.) So Gnus saves these
7619 articles until some later time when the server feels better.
7621 The rejected articles will automatically be put in a special draft group
7622 (@pxref{Drafts}). When the server comes back up again, you'd then
7623 typically enter that group and send all the articles off.
7626 @node Select Methods
7627 @chapter Select Methods
7628 @cindex foreign groups
7629 @cindex select methods
7631 A @dfn{foreign group} is a group that is not read by the usual (or
7632 default) means. It could be, for instance, a group from a different
7633 @sc{nntp} server, it could be a virtual group, or it could be your own
7634 personal mail group.
7636 A foreign group (or any group, really) is specified by a @dfn{name} and
7637 a @dfn{select method}. To take the latter first, a select method is a
7638 list where the first element says what backend to use (eg. @code{nntp},
7639 @code{nnspool}, @code{nnml}) and the second element is the @dfn{server
7640 name}. There may be additional elements in the select method, where the
7641 value may have special meaning for the backend in question.
7643 One could say that a select method defines a @dfn{virtual server}---so
7644 we do just that (@pxref{The Server Buffer}).
7646 The @dfn{name} of the group is the name the backend will recognize the
7649 For instance, the group @samp{soc.motss} on the @sc{nntp} server
7650 @samp{some.where.edu} will have the name @samp{soc.motss} and select
7651 method @code{(nntp "some.where.edu")}. Gnus will call this group, in
7652 all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
7653 @code{nntp} backend just knows this group as @samp{soc.motss}.
7655 The different methods all have their peculiarities, of course.
7658 * The Server Buffer:: Making and editing virtual servers.
7659 * Getting News:: Reading USENET news with Gnus.
7660 * Getting Mail:: Reading your personal mail with Gnus.
7661 * Other Sources:: Reading directories, files, SOUP packets.
7662 * Combined Groups:: Combining groups into one group.
7666 @node The Server Buffer
7667 @section The Server Buffer
7669 Traditionally, a @dfn{server} is a machine or a piece of software that
7670 one connects to, and then requests information from. Gnus does not
7671 connect directly to any real servers, but does all transactions through
7672 one backend or other. But that's just putting one layer more between
7673 the actual media and Gnus, so we might just as well say that each
7674 backend represents a virtual server.
7676 For instance, the @code{nntp} backend may be used to connect to several
7677 different actual @sc{nntp} servers, or, perhaps, to many different ports
7678 on the same actual @sc{nntp} server. You tell Gnus which backend to
7679 use, and what parameters to set by specifying a @dfn{select method}.
7681 These select methods specifications can sometimes become quite
7682 complicated---say, for instance, that you want to read from the
7683 @sc{nntp} server @samp{news.funet.fi} on port number @code{13}, which
7684 hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
7685 Anyways, if you had to specify that for each group that used this
7686 server, that would be too much work, so Gnus offers a way of naming
7687 select methods, which is what you do in the server buffer.
7689 To enter the server buffer, user the @kbd{^}
7690 (@code{gnus-group-enter-server-mode}) command in the group buffer.
7693 * Server Buffer Format:: You can customize the look of this buffer.
7694 * Server Commands:: Commands to manipulate servers.
7695 * Example Methods:: Examples server specifications.
7696 * Creating a Virtual Server:: An example session.
7697 * Servers and Methods:: You can use server names as select methods.
7698 * Unavailable Servers:: Some servers you try to contact may be down.
7701 @vindex gnus-server-mode-hook
7702 @code{gnus-server-mode-hook} is run when creating the server buffer.
7705 @node Server Buffer Format
7706 @subsection Server Buffer Format
7707 @cindex server buffer format
7709 @vindex gnus-server-line-format
7710 You can change the look of the server buffer lines by changing the
7711 @code{gnus-server-line-format} variable. This is a @code{format}-like
7712 variable, with some simple extensions:
7717 How the news is fetched---the backend name.
7720 The name of this server.
7723 Where the news is to be fetched from---the address.
7726 The opened/closed/denied status of the server.
7729 @vindex gnus-server-mode-line-format
7730 The mode line can also be customized by using the
7731 @code{gnus-server-mode-line-format} variable. The following specs are
7742 Also @pxref{Formatting Variables}.
7745 @node Server Commands
7746 @subsection Server Commands
7747 @cindex server commands
7753 @findex gnus-server-add-server
7754 Add a new server (@code{gnus-server-add-server}).
7758 @findex gnus-server-edit-server
7759 Edit a server (@code{gnus-server-edit-server}).
7762 @kindex SPACE (Server)
7763 @findex gnus-server-read-server
7764 Browse the current server (@code{gnus-server-read-server}).
7768 @findex gnus-server-exit
7769 Return to the group buffer (@code{gnus-server-exit}).
7773 @findex gnus-server-kill-server
7774 Kill the current server (@code{gnus-server-kill-server}).
7778 @findex gnus-server-yank-server
7779 Yank the previously killed server (@code{gnus-server-yank-server}).
7783 @findex gnus-server-copy-server
7784 Copy the current server (@code{gnus-server-copy-server}).
7788 @findex gnus-server-list-servers
7789 List all servers (@code{gnus-server-list-servers}).
7794 @node Example Methods
7795 @subsection Example Methods
7797 Most select methods are pretty simple and self-explanatory:
7800 (nntp "news.funet.fi")
7803 Reading directly from the spool is even simpler:
7809 As you can see, the first element in a select method is the name of the
7810 backend, and the second is the @dfn{address}, or @dfn{name}, if you
7813 After these two elements, there may be a arbitrary number of
7814 @var{(variable form)} pairs.
7816 To go back to the first example---imagine that you want to read from
7817 port @code{15} from that machine. This is what the select method should
7821 (nntp "news.funet.fi" (nntp-port-number 15))
7824 You should read the documentation to each backend to find out what
7825 variables are relevant, but here's an @code{nnmh} example.
7827 @code{nnmh} is a mail backend that reads a spool-like structure. Say
7828 you have two structures that you wish to access: One is your private
7829 mail spool, and the other is a public one. Here's the possible spec for
7833 (nnmh "private" (nnmh-directory "~/private/mail/"))
7836 (This server is then called @samp{private}, but you may have guessed
7839 Here's the method for a public spool:
7843 (nnmh-directory "/usr/information/spool/")
7844 (nnmh-get-new-mail nil))
7848 @node Creating a Virtual Server
7849 @subsection Creating a Virtual Server
7851 If you're saving lots of articles in the cache by using persistent
7852 articles, you may want to create a virtual server to read the cache.
7854 First you need to add a new server. The @kbd{a} command does that. It
7855 would probably be best to use @code{nnspool} to read the cache. You
7856 could also use @code{nnml} or @code{nnmh}, though.
7858 Type @kbd{a nnspool RET cache RET}.
7860 You should now have a brand new @code{nnspool} virtual server called
7861 @samp{cache}. You now need to edit it to have the right definitions.
7862 Type @kbd{e} to edit the server. You'll be entered into a buffer that
7863 will contain the following:
7873 (nnspool-spool-directory "~/News/cache/")
7874 (nnspool-nov-directory "~/News/cache/")
7875 (nnspool-active-file "~/News/cache/active"))
7878 Type @kbd{C-c C-c} to return to the server buffer. If you now press
7879 @kbd{RET} over this virtual server, you should be entered into a browse
7880 buffer, and you should be able to enter any of the groups displayed.
7883 @node Servers and Methods
7884 @subsection Servers and Methods
7886 Wherever you would normally use a select method
7887 (eg. @code{gnus-secondary-select-method}, in the group select method,
7888 when browsing a foreign server) you can use a virtual server name
7889 instead. This could potentially save lots of typing. And it's nice all
7893 @node Unavailable Servers
7894 @subsection Unavailable Servers
7896 If a server seems to be unreachable, Gnus will mark that server as
7897 @code{denied}. That means that any subsequent attempt to make contact
7898 with that server will just be ignored. ``It can't be opened,'' Gnus
7899 will tell you, without making the least effort to see whether that is
7900 actually the case or not.
7902 That might seem quite naughty, but it does make sense most of the time.
7903 Let's say you have 10 groups subscribed to the server
7904 @samp{nepholococcygia.com}. This server is located somewhere quite far
7905 away from you, the machine is quite, so it takes 1 minute just to find
7906 out that it refuses connection from you today. If Gnus were to attempt
7907 to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
7908 that. Once it has gotten a single ``connection refused'', it will
7909 regard that server as ``down''.
7911 So, what happens if the machine was only feeling unwell temporarily?
7912 How do you test to see whether the machine has come up again?
7914 You jump to the server buffer (@pxref{The Server Buffer}) and poke it
7915 with the following commands:
7921 @findex gnus-server-open-server
7922 Try to establish connection to the server on the current line
7923 (@code{gnus-server-open-server}).
7927 @findex gnus-server-close-server
7928 Close the connection (if any) to the server
7929 (@code{gnus-server-close-server}).
7933 @findex gnus-server-deny-server
7934 Mark the current server as unreachable
7935 (@code{gnus-server-deny-server}).
7939 @findex gnus-server-remove-denials
7940 Remove all marks to whether Gnus was denied connection from all servers
7941 (@code{gnus-server-remove-denials}).
7947 @section Getting News
7948 @cindex reading news
7949 @cindex news backends
7951 A newsreader is normally used for reading news. Gnus currently provides
7952 only two methods of getting news -- it can read from an @sc{nntp}
7953 server, or it can read from a local spool.
7956 * NNTP:: Reading news from an @sc{nntp} server.
7957 * News Spool:: Reading news from the local spool.
7962 @subsection @sc{nntp}
7965 Subscribing to a foreign group from an @sc{nntp} server is rather easy.
7966 You just specify @code{nntp} as method and the address of the @sc{nntp}
7967 server as the, uhm, address.
7969 If the @sc{nntp} server is located at a non-standard port, setting the
7970 third element of the select method to this port number should allow you
7971 to connect to the right port. You'll have to edit the group info for
7972 that (@pxref{Foreign Groups}).
7974 The name of the foreign group can be the same as a native group. In
7975 fact, you can subscribe to the same group from as many different servers
7976 you feel like. There will be no name collisions.
7978 The following variables can be used to create a virtual @code{nntp}
7983 @item nntp-server-opened-hook
7984 @vindex nntp-server-opened-hook
7985 @cindex @sc{mode reader}
7987 @cindex authentification
7988 @cindex nntp authentification
7989 @findex nntp-send-authinfo
7990 @findex nntp-send-mode-reader
7991 @code{nntp-server-opened-hook} is run after a connection has been made.
7992 It can be used to send commands to the @sc{nntp} server after it has
7993 been contacted. By default is sends the command @code{MODE READER} to
7994 the server with the @code{nntp-send-mode-reader} function. Another
7995 popular function is @code{nntp-send-authinfo}, which will prompt you for
7996 an @sc{nntp} password and stuff.
7998 @item nntp-server-action-alist
7999 @vindex nntp-server-action-alist
8000 This is an list of regexps to match on server types and actions to be
8001 taken when matches are made. For instance, if you want Gnus to beep
8002 every time you connect to innd, you could say something like:
8005 (setq nntp-server-action-alist
8009 You probably don't want to do that, though.
8011 The default value is
8014 '(("nntpd 1\\.5\\.11t"
8015 (remove-hook 'nntp-server-opened-hook nntp-send-mode-reader)))
8018 This ensures that Gnus doesn't send the @code{MODE READER} command to
8019 nntpd 1.5.11t, since that command chokes that server, I've been told.
8021 @item nntp-maximum-request
8022 @vindex nntp-maximum-request
8023 If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
8024 will collect headers by sending a series of @code{head} commands. To
8025 speed things up, the backend sends lots of these commands without
8026 waiting for reply, and then reads all the replies. This is controlled
8027 by the @code{nntp-maximum-request} variable, and is 400 by default. If
8028 your network is buggy, you should set this to 1.
8030 @item nntp-connection-timeout
8031 @vindex nntp-connection-timeout
8032 If you have lots of foreign @code{nntp} groups that you connect to
8033 regularly, you're sure to have problems with @sc{nntp} servers not
8034 responding properly, or being too loaded to reply within reasonable
8035 time. This is can lead to awkward problems, which can be helped
8036 somewhat by setting @code{nntp-connection-timeout}. This is an integer
8037 that says how many seconds the @code{nntp} backend should wait for a
8038 connection before giving up. If it is @code{nil}, which is the default,
8039 no timeouts are done.
8041 @item nntp-command-timeout
8042 @vindex nntp-command-timeout
8043 @cindex PPP connections
8044 @cindex dynamic IP addresses
8045 If you're running Gnus on a machine that has a dynamically assigned
8046 address, Gnus may become confused. If the address of your machine
8047 changes after connecting to the @sc{nntp} server, Gnus will simply sit
8048 waiting forever for replies from the server. To help with this
8049 unfortunate problem, you can set this command to a number. Gnus will
8050 then, if it sits waiting longer than that number of seconds for a reply
8051 from the server, shut down the connection, start a new one, and resend
8052 the command. This should hopefully be transparent to the user. A
8053 likely number is 30 seconds.
8055 @item nntp-retry-on-break
8056 @vindex nntp-retry-on-break
8057 If this variable is non-@code{nil}, you can also @kbd{C-g} if Gnus
8058 hangs. This will have much the same effect as the command timeout
8061 @item nntp-server-hook
8062 @vindex nntp-server-hook
8063 This hook is run as the last step when connecting to an @sc{nntp}
8066 @findex nntp-open-rlogin
8067 @findex nntp-open-network-stream
8068 @item nntp-open-server-function
8069 @vindex nntp-open-server-function
8070 This function is used to connect to the remote system. Two pre-made
8071 functions are @code{nntp-open-network-stream}, which is the default, and
8072 simply connects to some port or other on the remote system. The other
8073 is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
8074 and then does a telnet to the @sc{nntp} server available there.
8076 @item nntp-rlogin-parameters
8077 @vindex nntp-rlogin-parameters
8078 If you use @code{nntp-open-rlogin} as the
8079 @code{nntp-open-server-function}, this list will be used as the
8080 parameter list given to @code{rsh}.
8082 @item nntp-end-of-line
8083 @vindex nntp-end-of-line
8084 String to use as end-of-line markers when talking to the @sc{nntp}
8085 server. This is @samp{\r\n} by default, but should be @samp{\n} when
8086 using @code{rlogin} to talk to the server.
8088 @item nntp-rlogin-user-name
8089 @vindex nntp-rlogin-user-name
8090 User name on the remote system when using the @code{rlogin} connect
8094 @vindex nntp-address
8095 The address of the remote system running the @sc{nntp} server.
8097 @item nntp-port-number
8098 @vindex nntp-port-number
8099 Port number to connect to when using the @code{nntp-open-network-stream}
8102 @item nntp-buggy-select
8103 @vindex nntp-buggy-select
8104 Set this to non-@code{nil} if your select routine is buggy.
8106 @item nntp-nov-is-evil
8107 @vindex nntp-nov-is-evil
8108 If the @sc{nntp} server does not support @sc{nov}, you could set this
8109 variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
8110 can be used automatically.
8112 @item nntp-xover-commands
8113 @vindex nntp-xover-commands
8116 List of strings that are used as commands to fetch @sc{nov} lines from a
8117 server. The default value of this variable is @code{("XOVER"
8121 @vindex nntp-nov-gap
8122 @code{nntp} normally sends just one big request for @sc{nov} lines to
8123 the server. The server responds with one huge list of lines. However,
8124 if you have read articles 2-5000 in the group, and only want to read
8125 article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
8126 lines that you do not want, and will not use. This variable says how
8127 big a gap between two consecutive articles is allowed to be before the
8128 @code{XOVER} request is split into several request. Note that if your
8129 network is fast, setting this variable to a really small number means
8130 that fetching will probably be slower. If this variable is @code{nil},
8131 @code{nntp} will never split requests.
8133 @item nntp-prepare-server-hook
8134 @vindex nntp-prepare-server-hook
8135 A hook run before attempting to connect to an @sc{nntp} server.
8137 @item nntp-async-number
8138 @vindex nntp-async-number
8139 How many articles should be pre-fetched when in asynchronous mode. If
8140 this variable is @code{t}, @code{nntp} will pre-fetch all the articles
8141 that it can without bound. If it is @code{nil}, no pre-fetching will be
8144 @item nntp-warn-about-losing-connection
8145 @vindex nntp-warn-about-losing-connection
8146 If this variable is non-@code{nil}, some noise will be made when a
8147 server closes connection.
8153 @subsection News Spool
8157 Subscribing to a foreign group from the local spool is extremely easy,
8158 and might be useful, for instance, to speed up reading groups like
8159 @samp{alt.binaries.pictures.furniture}.
8161 Anyways, you just specify @code{nnspool} as the method and @samp{} (or
8162 anything else) as the address.
8164 If you have access to a local spool, you should probably use that as the
8165 native select method (@pxref{Finding the News}). It is normally faster
8166 than using an @code{nntp} select method, but might not be. It depends.
8167 You just have to try to find out what's best at your site.
8171 @item nnspool-inews-program
8172 @vindex nnspool-inews-program
8173 Program used to post an article.
8175 @item nnspool-inews-switches
8176 @vindex nnspool-inews-switches
8177 Parameters given to the inews program when posting an article.
8179 @item nnspool-spool-directory
8180 @vindex nnspool-spool-directory
8181 Where @code{nnspool} looks for the articles. This is normally
8182 @file{/usr/spool/news/}.
8184 @item nnspool-nov-directory
8185 @vindex nnspool-nov-directory
8186 Where @code{nnspool} will look for @sc{nov} files. This is normally
8187 @file{/usr/spool/news/over.view/}.
8189 @item nnspool-lib-dir
8190 @vindex nnspool-lib-dir
8191 Where the news lib dir is (@file{/usr/lib/news/} by default).
8193 @item nnspool-active-file
8194 @vindex nnspool-active-file
8195 The path of the active file.
8197 @item nnspool-newsgroups-file
8198 @vindex nnspool-newsgroups-file
8199 The path of the group descriptions file.
8201 @item nnspool-history-file
8202 @vindex nnspool-history-file
8203 The path of the news history file.
8205 @item nnspool-active-times-file
8206 @vindex nnspool-active-times-file
8207 The path of the active date file.
8209 @item nnspool-nov-is-evil
8210 @vindex nnspool-nov-is-evil
8211 If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
8214 @item nnspool-sift-nov-with-sed
8215 @vindex nnspool-sift-nov-with-sed
8217 If non-@code{nil}, which is the default, use @code{sed} to get the
8218 relevant portion from the overview file. If nil, @code{nnspool} will
8219 load the entire file into a buffer and process it there.
8225 @section Getting Mail
8226 @cindex reading mail
8229 Reading mail with a newsreader---isn't that just plain WeIrD? But of
8233 * Getting Started Reading Mail:: A simple cookbook example.
8234 * Splitting Mail:: How to create mail groups.
8235 * Mail Backend Variables:: Variables for customizing mail handling.
8236 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
8237 * Mail and Procmail:: Reading mail groups that procmail create.
8238 * Incorporating Old Mail:: What about the old mail you have?
8239 * Expiring Mail:: Getting rid of unwanted mail.
8240 * Duplicates:: Dealing with duplicated mail.
8241 * Not Reading Mail:: Using mail backends for reading other files.
8242 * Choosing a Mail Backend:: Gnus can read a variety of mail formats.
8246 @node Getting Started Reading Mail
8247 @subsection Getting Started Reading Mail
8249 It's quite easy to use Gnus to read your new mail. You just plonk the
8250 mail backend of your choice into @code{gnus-secondary-select-methods},
8251 and things will happen automatically.
8253 For instance, if you want to use @code{nnml} (which is a one file per
8254 mail backend), you could put the following in your @file{.gnus} file:
8257 (setq gnus-secondary-select-methods
8258 '((nnml "private")))
8261 Now, the next time you start Gnus, this backend will be queried for new
8262 articles, and it will move all the messages in your spool file to its
8263 directory, which is @code{~/Mail/} by default. The new group that will
8264 be created (@samp{mail.misc}) will be subscribed, and you can read it
8265 like any other group.
8267 You will probably want to split the mail into several groups, though:
8270 (setq nnmail-split-methods
8271 '(("junk" "^From:.*Lars Ingebrigtsen")
8272 ("crazy" "^Subject:.*die\\|^Organization:.*flabby")
8276 This will result in three new mail groups being created:
8277 @samp{nnml:junk}, @samp{nnml:crazy}, and @samp{nnml:other}. All the
8278 mail that doesn't fit into the first two groups will be placed in the
8281 This should be sufficient for reading mail with Gnus. You might want to
8282 give the other sections in this part of the manual a perusal, though,
8283 especially @pxref{Choosing a Mail Backend} and @pxref{Expiring Mail}.
8286 @node Splitting Mail
8287 @subsection Splitting Mail
8288 @cindex splitting mail
8289 @cindex mail splitting
8291 @vindex nnmail-split-methods
8292 The @code{nnmail-split-methods} variable says how the incoming mail is
8293 to be split into groups.
8296 (setq nnmail-split-methods
8297 '(("mail.junk" "^From:.*Lars Ingebrigtsen")
8298 ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
8302 This variable is a list of lists, where the first element of each of
8303 these lists is the name of the mail group (they do not have to be called
8304 something beginning with @samp{mail}, by the way), and the second
8305 element is a regular expression used on the header of each mail to
8306 determine if it belongs in this mail group.
8308 The second element can also be a function. In that case, it will be
8309 called narrowed to the headers with the first element of the rule as the
8310 argument. It should return a non-@code{nil} value if it thinks that the
8311 mail belongs in that group.
8313 The last of these groups should always be a general one, and the regular
8314 expression should @emph{always} be @samp{} so that it matches any
8315 mails that haven't been matched by any of the other regexps.
8317 If you like to tinker with this yourself, you can set this variable to a
8318 function of your choice. This function will be called without any
8319 arguments in a buffer narrowed to the headers of an incoming mail
8320 message. The function should return a list of groups names that it
8321 thinks should carry this mail message.
8323 Note that the mail backends are free to maul the poor, innocent
8324 incoming headers all they want to. They all add @code{Lines} headers;
8325 some add @code{X-Gnus-Group} headers; most rename the Unix mbox
8326 @code{From<SPACE>} line to something else.
8328 @vindex nnmail-crosspost
8329 The mail backends all support cross-posting. If several regexps match,
8330 the mail will be ``cross-posted'' to all those groups.
8331 @code{nnmail-crosspost} says whether to use this mechanism or not. Note
8332 that no articles are crossposted to the general (@samp{}) group.
8334 @vindex nnmail-crosspost-link-function
8337 @code{nnmh} and @code{nnml} makes crossposts by creating hard links to
8338 the crossposted articles. However, not all files systems support hard
8339 links. If that's the case for you, set
8340 @code{nnmail-crosspost-link-function} to @code{copy-file}. (This
8341 variable is @code{add-name-to-file} by default.)
8343 Gnus gives you all the opportunity you could possibly want for shooting
8344 yourself in the foot. Let's say you create a group that will contain
8345 all the mail you get from your boss. And then you accidentally
8346 unsubscribe from the group. Gnus will still put all the mail from your
8347 boss in the unsubscribed group, and so, when your boss mails you ``Have
8348 that report ready by Monday or you're fired!'', you'll never see it and,
8349 come Tuesday, you'll still believe that you're gainfully employed while
8350 you really should be out collecting empty bottles to save up for next
8354 @node Mail Backend Variables
8355 @subsection Mail Backend Variables
8357 These variables are (for the most part) pertinent to all the various
8361 @vindex nnmail-read-incoming-hook
8362 @item nnmail-read-incoming-hook
8363 The mail backends all call this hook after reading new mail. You can
8364 use this hook to notify any mail watch programs, if you want to.
8366 @vindex nnmail-spool-file
8367 @item nnmail-spool-file
8371 The backends will look for new mail in this file. If this variable is
8372 @code{nil}, the mail backends will never attempt to fetch mail by
8373 themselves. If you are using a POP mail server and your name is
8374 @samp{larsi}, you should set this variable to @samp{po:larsi}. If
8375 your name is not @samp{larsi}, you should probably modify that
8376 slightly, but you may have guessed that already, you smart & handsome
8377 devil! You can also set this variable to @code{pop}, and Gnus will try
8378 to figure out the POP mail string by itself. In any case, Gnus will
8379 call @code{movemail} which will contact the POP server named in the
8380 @code{MAILHOST} environment variable.
8382 When you use a mail backend, Gnus will slurp all your mail from your
8383 inbox and plonk it down in your home directory. Gnus doesn't move any
8384 mail if you're not using a mail backend---you have to do a lot of magic
8385 invocations first. At the time when you have finished drawing the
8386 pentagram, lightened the candles, and sacrificed the goat, you really
8387 shouldn't be too surprised when Gnus moves your mail.
8389 @vindex nnmail-use-procmail
8390 @vindex nnmail-procmail-suffix
8391 @item nnmail-use-procmail
8392 If non-@code{nil}, the mail backends will look in
8393 @code{nnmail-procmail-directory} for incoming mail. All the files in
8394 that directory that have names ending in @code{nnmail-procmail-suffix}
8395 will be considered incoming mailboxes, and will be searched for new
8398 @vindex nnmail-crash-box
8399 @item nnmail-crash-box
8400 When the mail backends read a spool file, it is first moved to this
8401 file, which is @file{~/.gnus-crash-box} by default. If this file
8402 already exists, it will always be read (and incorporated) before any
8405 @vindex nnmail-prepare-incoming-hook
8406 @item nnmail-prepare-incoming-hook
8407 This is run in a buffer that holds all the new incoming mail, and can be
8408 used for, well, anything, really.
8410 @vindex nnmail-pre-get-new-mail-hook
8411 @vindex nnmail-post-get-new-mail-hook
8412 @item nnmail-pre-get-new-mail-hook
8413 @itemx nnmail-post-get-new-mail-hook
8414 These are two useful hooks executed when treating new incoming
8415 mail---@code{nnmail-pre-get-new-mail-hook} (is called just before
8416 starting to handle the new mail) and
8417 @code{nnmail-post-get-new-mail-hook} (is called when the mail handling
8418 is done). Here's and example of using these two hooks to change the
8419 default file modes the new mail files get:
8422 (add-hook 'gnus-pre-get-new-mail-hook
8423 (lambda () (set-default-file-modes 511)))
8425 (add-hook 'gnus-post-get-new-mail-hook
8426 (lambda () (set-default-file-modes 551)))
8429 @item nnmail-tmp-directory
8430 @vindex nnmail-tmp-directory
8431 This variable says where to move the incoming mail to while processing
8432 it. This is usually done in the same directory that the mail backend
8433 inhabits (i.e., @file{~/Mail/}), but if this variable is non-@code{nil},
8434 it will be used instead.
8436 @item nnmail-movemail-program
8437 @vindex nnmail-movemail-program
8438 This program is executed to move mail from the user's inbox to her home
8439 directory. The default is @samp{movemail}.
8441 @item nnmail-delete-incoming
8442 @vindex nnmail-delete-incoming
8443 @cindex incoming mail files
8444 @cindex deleting incoming files
8445 If non-@code{nil}, the mail backends will delete the temporary incoming
8446 file after splitting mail into the proper groups. This is @code{nil} by
8447 default for reasons of security.
8449 @item nnmail-use-long-file-names
8450 @vindex nnmail-use-long-file-names
8451 If non-@code{nil}, the mail backends will use long file and directory
8452 names. Groups like @samp{mail.misc} will end up in directories like
8453 @file{mail.misc/}. If it is @code{nil}, the same group will end up in
8456 @item nnmail-delete-file-function
8457 @vindex nnmail-delete-file-function
8459 Function called to delete files. It is @code{delete-file} by default.
8464 @node Fancy Mail Splitting
8465 @subsection Fancy Mail Splitting
8466 @cindex mail splitting
8467 @cindex fancy mail splitting
8469 @vindex nnmail-split-fancy
8470 @findex nnmail-split-fancy
8471 If the rather simple, standard method for specifying how to split mail
8472 doesn't allow you to do what you want, you can set
8473 @code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
8474 play with the @code{nnmail-split-fancy} variable.
8476 Let's look at an example value of this variable first:
8479 ;; Messages from the mailer daemon are not crossposted to any of
8480 ;; the ordinary groups. Warnings are put in a separate group
8481 ;; from real errors.
8482 (| ("from" mail (| ("subject" "warn.*" "mail.warning")
8484 ;; Non-error messages are crossposted to all relevant
8485 ;; groups, but we don't crosspost between the group for the
8486 ;; (ding) list and the group for other (ding) related mail.
8487 (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
8488 ("subject" "ding" "ding.misc"))
8489 ;; Other mailing lists...
8490 (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
8491 (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
8493 (any "larsi@@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
8494 ;; Unmatched mail goes to the catch all group.
8498 This variable has the format of a @dfn{split}. A split is a (possibly)
8499 recursive structure where each split may contain other splits. Here are
8500 the four possible split syntaxes:
8505 If the split is a string, that will be taken as a group name.
8507 @item (FIELD VALUE SPLIT)
8508 If the split is a list, and the first element is a string, then that
8509 means that if header FIELD (a regexp) contains VALUE (also a regexp),
8510 then store the message as specified by SPLIT.
8513 If the split is a list, and the first element is @code{|} (vertical
8514 bar), then process each SPLIT until one of them matches. A SPLIT is
8515 said to match if it will cause the mail message to be stored in one or
8519 If the split is a list, and the first element is @code{&}, then process
8520 all SPLITs in the list.
8523 In these splits, FIELD must match a complete field name. VALUE must
8524 match a complete word according to the fundamental mode syntax table.
8525 You can use @code{.*} in the regexps to match partial field names or
8528 @vindex nnmail-split-abbrev-alist
8529 FIELD and VALUE can also be lisp symbols, in that case they are expanded
8530 as specified by the variable @code{nnmail-split-abbrev-alist}. This is
8531 an alist of cons cells, where the car of the cells contains the key, and
8532 the cdr contains a string.
8534 @vindex nnmail-split-fancy-syntax-table
8535 @code{nnmail-split-fancy-syntax-table} is the syntax table in effect
8536 when all this splitting is performed.
8539 @node Mail and Procmail
8540 @subsection Mail and Procmail
8545 Many people use @code{procmail} (or some other mail filter program or
8546 external delivery agent---@code{slocal}, @code{elm}, etc) to split
8547 incoming mail into groups. If you do that, you should set
8548 @code{nnmail-spool-file} to @code{procmail} to ensure that the mail
8549 backends never ever try to fetch mail by themselves.
8551 This also means that you probably don't want to set
8552 @code{nnmail-split-methods} either, which has some, perhaps, unexpected
8555 When a mail backend is queried for what groups it carries, it replies
8556 with the contents of that variable, along with any groups it has figured
8557 out that it carries by other means. None of the backends (except
8558 @code{nnmh}) actually go out to the disk and check what groups actually
8559 exist. (It's not trivial to distinguish between what the user thinks is
8560 a basis for a newsgroup and what is just a plain old file or directory.)
8562 This means that you have to tell Gnus (and the backends) what groups
8565 Let's take the @code{nnmh} backend as an example.
8567 The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
8568 There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
8570 Go to the group buffer and type @kbd{G m}. When prompted, answer
8571 @samp{foo} for the name and @samp{nnmh} for the method. Repeat
8572 twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
8573 to include all your mail groups.
8575 That's it. You are now set to read your mail. An active file for this
8576 method will be created automatically.
8578 @vindex nnmail-procmail-suffix
8579 @vindex nnmail-procmail-directory
8580 If you use @code{nnfolder} or any other backend that store more than a
8581 single article in each file, you should never have procmail add mails to
8582 the file that Gnus sees. Instead, procmail should put all incoming mail
8583 in @code{nnmail-procmail-directory}. To arrive at the file name to put
8584 the incoming mail in, append @code{nnmail-procmail-suffix} to the group
8585 name. The mail backends will read the mail from these files.
8587 @vindex nnmail-resplit-incoming
8588 When Gnus reads a file called @file{mail.misc.spool}, this mail will be
8589 put in the @code{mail.misc}, as one would expect. However, if you want
8590 Gnus to split the mail the normal way, you could set
8591 @code{nnmail-resplit-incoming} to @code{t}.
8593 @vindex nnmail-keep-last-article
8594 If you use @code{procmail} to split things directory into an @code{nnmh}
8595 directory (which you shouldn't do), you should set
8596 @code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
8597 ever expiring the final article in a mail newsgroup. This is quite,
8601 @node Incorporating Old Mail
8602 @subsection Incorporating Old Mail
8604 Most people have lots of old mail stored in various file formats. If
8605 you have set up Gnus to read mail using one of the spiffy Gnus mail
8606 backends, you'll probably wish to have that old mail incorporated into
8609 Doing so can be quite easy.
8611 To take an example: You're reading mail using @code{nnml}
8612 (@pxref{Mail Spool}), and have set @code{nnmail-split-methods} to a
8613 satisfactory value (@pxref{Splitting Mail}). You have an old Unix mbox
8614 file filled with important, but old, mail. You want to move it into
8615 your @code{nnml} groups.
8621 Go to the group buffer.
8624 Type `G f' and give the path of the mbox file when prompted to create an
8625 @code{nndoc} group from the mbox file (@pxref{Foreign Groups}).
8628 Type `SPACE' to enter the newly created group.
8631 Type `M P b' to process-mark all articles in this group (@pxref{Setting
8635 Type `B r' to respool all the process-marked articles, and answer
8636 @samp{nnml} when prompted (@pxref{Mail Group Commands}).
8639 All the mail messages in the mbox file will now also be spread out over
8640 all your @code{nnml} groups. Try entering them and check whether things
8641 have gone without a glitch. If things look ok, you may consider
8642 deleting the mbox file, but I wouldn't do that unless I was absolutely
8643 sure that all the mail has ended up where it should be.
8645 Respooling is also a handy thing to do if you're switching from one mail
8646 backend to another. Just respool all the mail in the old mail groups
8647 using the new mail backend.
8651 @subsection Expiring Mail
8652 @cindex article expiry
8654 Traditional mail readers have a tendency to remove mail articles when
8655 you mark them as read, in some way. Gnus takes a fundamentally
8656 different approach to mail reading.
8658 Gnus basically considers mail just to be news that has been received in
8659 a rather peculiar manner. It does not think that it has the power to
8660 actually change the mail, or delete any mail messages. If you enter a
8661 mail group, and mark articles as ``read'', or kill them in some other
8662 fashion, the mail articles will still exist on the system. I repeat:
8663 Gnus will not delete your old, read mail. Unless you ask it to, of
8666 To make Gnus get rid of your unwanted mail, you have to mark the
8667 articles as @dfn{expirable}. This does not mean that the articles will
8668 disappear right away, however. In general, a mail article will be
8669 deleted from your system if, 1) it is marked as expirable, AND 2) it is
8670 more than one week old. If you do not mark an article as expirable, it
8671 will remain on your system until hell freezes over. This bears
8672 repeating one more time, with some spurious capitalizations: IF you do
8673 NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
8675 @vindex gnus-auto-expirable-newsgroups
8676 You do not have to mark articles as expirable by hand. Groups that
8677 match the regular expression @code{gnus-auto-expirable-newsgroups} will
8678 have all articles that you read marked as expirable automatically. All
8679 articles that are marked as expirable have an @samp{E} in the first
8680 column in the summary buffer.
8682 Let's say you subscribe to a couple of mailing lists, and you want the
8683 articles you have read to disappear after a while:
8686 (setq gnus-auto-expirable-newsgroups
8687 "mail.nonsense-list\\|mail.nice-list")
8690 Another way to have auto-expiry happen is to have the element
8691 @code{auto-expire} in the group parameters of the group.
8693 @vindex nnmail-expiry-wait
8694 The @code{nnmail-expiry-wait} variable supplies the default time an
8695 expirable article has to live. The default is seven days.
8697 Gnus also supplies a function that lets you fine-tune how long articles
8698 are to live, based on what group they are in. Let's say you want to
8699 have one month expiry period in the @samp{mail.private} group, a one day
8700 expiry period in the @samp{mail.junk} group, and a six day expiry period
8703 @vindex nnmail-expiry-wait-function
8705 (setq nnmail-expiry-wait-function
8707 (cond ((string= group "mail.private")
8709 ((string= group "mail.junk")
8711 ((string= group "important")
8717 The group names that this function is fed are ``unadorned'' group
8718 names---no @samp{nnml:} prefixes and the like.
8720 The @code{nnmail-expiry-wait} variable and
8721 @code{nnmail-expiry-wait-function} function can be either a number (not
8722 necessarily an integer) or the symbols @code{immediate} or
8725 You can also use the @code{expiry-wait} group parameter to selectively
8726 change the expiry period (@pxref{Group Parameters}).
8728 @vindex nnmail-keep-last-article
8729 If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
8730 expire the final article in a mail newsgroup. This is to make life
8731 easier for procmail users.
8733 @vindex gnus-total-expirable-newsgroups
8734 By the way, that line up there about Gnus never expiring non-expirable
8735 articles is a lie. If you put @code{total-expire} in the group
8736 parameters, articles will not be marked as expirable, but all read
8737 articles will be put through the expiry process. Use with extreme
8738 caution. Even more dangerous is the
8739 @code{gnus-total-expirable-newsgroups} variable. All groups that match
8740 this regexp will have all read articles put through the expiry process,
8741 which means that @emph{all} old mail articles in the groups in question
8742 will be deleted after a while. Use with extreme caution, and don't come
8743 crying to me when you discover that the regexp you used matched the
8744 wrong group and all your important mail has disappeared. Be a
8745 @emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
8750 @subsection Duplicates
8752 @vindex nnmail-delete-duplicates
8753 @vindex nnmail-message-id-cache-length
8754 @vindex nnmail-message-id-cache-file
8755 @vindex nnmail-treat-duplicates
8756 @cindex duplicate mails
8757 If you are a member of a couple of mailing list, you will sometime
8758 receive two copies of the same mail. This can be quite annoying, so
8759 @code{nnmail} checks for and treats any duplicates it might find. To do
8760 this, it keeps a cache of old @code{Message-ID}s -
8761 @code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
8762 default. The approximate maximum number of @code{Message-ID}s stored
8763 there is controlled by the @code{nnmail-message-id-cache-length}
8764 variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
8765 stored.) If all this sounds scary to you, you can set
8766 @code{nnmail-delete-duplicates} to @code{warn} (which is what it is by
8767 default), and @code{nnmail} won't delete duplicate mails. Instead it
8768 will generate a brand new @code{Message-ID} for the mail and insert a
8769 warning into the head of the mail saying that it thinks that this is a
8770 duplicate of a different message.
8772 This variable can also be a function. If that's the case, the function
8773 will be called from a buffer narrowed to the message in question with
8774 the @code{Message-ID} as a parameter. The function must return either
8775 @code{nil}, @code{warn}, or @code{delete}.
8777 You can turn this feature off completely by setting the variable to
8780 If you want all the duplicate mails to be put into a special
8781 @dfn{duplicates} group, you could do that using the normal mail split
8785 (setq nnmail-split-fancy
8786 '(| ;; Messages duplicates go to a separate group.
8787 ("gnus-warning" "duplication of message" "duplicate")
8788 ;; Message from daemons, postmaster, and the like to another.
8789 (any mail "mail.misc")
8796 (setq nnmail-split-methods
8797 '(("duplicates" "^Gnus-Warning:")
8802 Here's a neat feature: If you know that the recipient reads her mail
8803 with Gnus, and that she has @code{nnmail-treat-duplicates} set to
8804 @code{delete}, you can send her as many insults as you like, just by
8805 using a @code{Message-ID} of a mail that you know that she's already
8806 received. Think of all the fun! She'll never see any of it! Whee!
8809 @node Not Reading Mail
8810 @subsection Not Reading Mail
8812 If you start using any of the mail backends, they have the annoying
8813 habit of assuming that you want to read mail with them. This might not
8814 be unreasonable, but it might not be what you want.
8816 If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
8817 will ever attempt to read incoming mail, which should help.
8819 @vindex nnbabyl-get-new-mail
8820 @vindex nnmbox-get-new-mail
8821 @vindex nnml-get-new-mail
8822 @vindex nnmh-get-new-mail
8823 @vindex nnfolder-get-new-mail
8824 This might be too much, if, for instance, you are reading mail quite
8825 happily with @code{nnml} and just want to peek at some old @sc{rmail}
8826 file you have stashed away with @code{nnbabyl}. All backends have
8827 variables called backend-@code{get-new-mail}. If you want to disable
8828 the @code{nnbabyl} mail reading, you edit the virtual server for the
8829 group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
8831 All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
8832 narrowed to the article to be saved before saving it when reading
8836 @node Choosing a Mail Backend
8837 @subsection Choosing a Mail Backend
8839 Gnus will read the mail spool when you activate a mail group. The mail
8840 file is first copied to your home directory. What happens after that
8841 depends on what format you want to store your mail in.
8844 * Unix Mail Box:: Using the (quite) standard Un*x mbox.
8845 * Rmail Babyl:: Emacs programs use the rmail babyl format.
8846 * Mail Spool:: Store your mail in a private spool?
8847 * MH Spool:: An mhspool-like backend.
8848 * Mail Folders:: Having one file for each group.
8853 @subsubsection Unix Mail Box
8855 @cindex unix mail box
8857 @vindex nnmbox-active-file
8858 @vindex nnmbox-mbox-file
8859 The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
8860 mail. @code{nnmbox} will add extra headers to each mail article to say
8861 which group it belongs in.
8863 Virtual server settings:
8866 @item nnmbox-mbox-file
8867 @vindex nnmbox-mbox-file
8868 The name of the mail box in the user's home directory.
8870 @item nnmbox-active-file
8871 @vindex nnmbox-active-file
8872 The name of the active file for the mail box.
8874 @item nnmbox-get-new-mail
8875 @vindex nnmbox-get-new-mail
8876 If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
8882 @subsubsection Rmail Babyl
8886 @vindex nnbabyl-active-file
8887 @vindex nnbabyl-mbox-file
8888 The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
8889 mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
8890 article to say which group it belongs in.
8892 Virtual server settings:
8895 @item nnbabyl-mbox-file
8896 @vindex nnbabyl-mbox-file
8897 The name of the rmail mbox file.
8899 @item nnbabyl-active-file
8900 @vindex nnbabyl-active-file
8901 The name of the active file for the rmail box.
8903 @item nnbabyl-get-new-mail
8904 @vindex nnbabyl-get-new-mail
8905 If non-@code{nil}, @code{nnbabyl} will read incoming mail.
8910 @subsubsection Mail Spool
8912 @cindex mail @sc{nov} spool
8914 The @dfn{nnml} spool mail format isn't compatible with any other known
8915 format. It should be used with some caution.
8917 @vindex nnml-directory
8918 If you use this backend, Gnus will split all incoming mail into files;
8919 one file for each mail, and put the articles into the correct
8920 directories under the directory specified by the @code{nnml-directory}
8921 variable. The default value is @file{~/Mail/}.
8923 You do not have to create any directories beforehand; Gnus will take
8926 If you have a strict limit as to how many files you are allowed to store
8927 in your account, you should not use this backend. As each mail gets its
8928 own file, you might very well occupy thousands of inodes within a few
8929 weeks. If this is no problem for you, and it isn't a problem for you
8930 having your friendly systems administrator walking around, madly,
8931 shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should
8932 know that this is probably the fastest format to use. You do not have
8933 to trudge through a big mbox file just to read your new mail.
8935 @code{nnml} is probably the slowest backend when it comes to article
8936 splitting. It has to create lots of files, and it also generates
8937 @sc{nov} databases for the incoming mails. This makes is the fastest
8938 backend when it comes to reading mail.
8940 Virtual server settings:
8943 @item nnml-directory
8944 @vindex nnml-directory
8945 All @code{nnml} directories will be placed under this directory.
8947 @item nnml-active-file
8948 @vindex nnml-active-file
8949 The active file for the @code{nnml} server.
8951 @item nnml-newsgroups-file
8952 @vindex nnml-newsgroups-file
8953 The @code{nnml} group descriptions file. @xref{Newsgroups File
8956 @item nnml-get-new-mail
8957 @vindex nnml-get-new-mail
8958 If non-@code{nil}, @code{nnml} will read incoming mail.
8960 @item nnml-nov-is-evil
8961 @vindex nnml-nov-is-evil
8962 If non-@code{nil}, this backend will ignore any @sc{nov} files.
8964 @item nnml-nov-file-name
8965 @vindex nnml-nov-file-name
8966 The name of the @sc{nov} files. The default is @file{.overview}.
8968 @item nnml-prepare-save-mail-hook
8969 @vindex nnml-prepare-save-mail-hook
8970 Hook run narrowed to an article before saving.
8974 @findex nnml-generate-nov-databases
8975 If your @code{nnml} groups and @sc{nov} files get totally out of whack,
8976 you can do a complete update by typing @kbd{M-x
8977 nnml-generate-nov-databases}. This command will trawl through the
8978 entire @code{nnml} hierarchy, looking at each and every article, so it
8979 might take a while to complete.
8983 @subsubsection MH Spool
8985 @cindex mh-e mail spool
8987 @code{nnmh} is just like @code{nnml}, except that is doesn't generate
8988 @sc{nov} databases and it doesn't keep an active file. This makes
8989 @code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
8990 makes it easier to write procmail scripts for.
8992 Virtual server settings:
8995 @item nnmh-directory
8996 @vindex nnmh-directory
8997 All @code{nnmh} directories will be located under this directory.
8999 @item nnmh-get-new-mail
9000 @vindex nnmh-get-new-mail
9001 If non-@code{nil}, @code{nnmh} will read incoming mail.
9004 @vindex nnmh-be-safe
9005 If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
9006 sure that the articles in the folder are actually what Gnus thinks they
9007 are. It will check date stamps and stat everything in sight, so
9008 setting this to @code{t} will mean a serious slow-down. If you never
9009 use anything but Gnus to read the @code{nnmh} articles, you do not have
9010 to set this variable to @code{t}.
9015 @subsubsection Mail Folders
9017 @cindex mbox folders
9018 @cindex mail folders
9020 @code{nnfolder} is a backend for storing each mail group in a separate
9021 file. Each file is in the standard Un*x mbox format. @code{nnfolder}
9022 will add extra headers to keep track of article numbers and arrival
9025 Virtual server settings:
9028 @item nnfolder-directory
9029 @vindex nnfolder-directory
9030 All the @code{nnfolder} mail boxes will be stored under this directory.
9032 @item nnfolder-active-file
9033 @vindex nnfolder-active-file
9034 The name of the active file.
9036 @item nnfolder-newsgroups-file
9037 @vindex nnfolder-newsgroups-file
9038 The name of the group descriptions file. @xref{Newsgroups File Format}.
9040 @item nnfolder-get-new-mail
9041 @vindex nnfolder-get-new-mail
9042 If non-@code{nil}, @code{nnfolder} will read incoming mail.
9045 @findex nnfolder-generate-active-file
9046 @kindex M-x nnfolder-generate-active-file
9047 If you have lots of @code{nnfolder}-like files you'd like to read with
9048 @code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file}
9049 command to make @code{nnfolder} aware of all likely files in
9050 @code{nnfolder-directory}.
9054 @section Other Sources
9056 Gnus can do more than just read news or mail. The methods described
9057 below allow Gnus to view directories and files as if they were
9061 * Directory Groups:: You can read a directory as if it was a newsgroup.
9062 * Anything Groups:: Dired? Who needs dired?
9063 * Document Groups:: Single files can be the basis of a group.
9064 * SOUP:: Reading @sc{SOUP} packets ``offline''.
9068 @node Directory Groups
9069 @subsection Directory Groups
9071 @cindex directory groups
9073 If you have a directory that has lots of articles in separate files in
9074 it, you might treat it as a newsgroup. The files have to have numerical
9077 This might be an opportune moment to mention @code{ange-ftp}, that most
9078 wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
9079 didn't think much about it---a backend to read directories. Big deal.
9081 @code{ange-ftp} changes that picture dramatically. For instance, if you
9082 enter @file{"/ftp.hpc.uh.edu:/pub/emacs/ding-list/"} as the the
9083 directory name, ange-ftp will actually allow you to read this directory
9084 over at @samp{sina} as a newsgroup. Distributed news ahoy!
9086 @code{nndir} will use @sc{nov} files if they are present.
9088 @code{nndir} is a ``read-only'' backend---you can't delete or expire
9089 articles with this method. You can use @code{nnmh} or @code{nnml} for
9090 whatever you use @code{nndir} for, so you could switch to any of those
9091 methods if you feel the need to have a non-read-only @code{nndir}.
9094 @node Anything Groups
9095 @subsection Anything Groups
9098 From the @code{nndir} backend (which reads a single spool-like
9099 directory), it's just a hop and a skip to @code{nneething}, which
9100 pretends that any arbitrary directory is a newsgroup. Strange, but
9103 When @code{nneething} is presented with a directory, it will scan this
9104 directory and assign article numbers to each file. When you enter such
9105 a group, @code{nneething} must create ``headers'' that Gnus can use.
9106 After all, Gnus is a newsreader, in case you're
9107 forgetting. @code{nneething} does this in a two-step process. First, it
9108 snoops each file in question. If the file looks like an article (i.e.,
9109 the first few lines look like headers), it will use this as the head.
9110 If this is just some arbitrary file without a head (eg. a C source
9111 file), @code{nneething} will cobble up a header out of thin air. It
9112 will use file ownership, name and date and do whatever it can with these
9115 All this should happen automatically for you, and you will be presented
9116 with something that looks very much like a newsgroup. Totally like a
9117 newsgroup, to be precise. If you select an article, it will be displayed
9118 in the article buffer, just as usual.
9120 If you select a line that represents a directory, Gnus will pop you into
9121 a new summary buffer for this @code{nneething} group. And so on. You can
9122 traverse the entire disk this way, if you feel like, but remember that
9123 Gnus is not dired, really, and does not intend to be, either.
9125 There are two overall modes to this action---ephemeral or solid. When
9126 doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
9127 will not store information on what files you have read, and what files
9128 are new, and so on. If you create a solid @code{nneething} group the
9129 normal way with @kbd{G m}, Gnus will store a mapping table between
9130 article numbers and file names, and you can treat this group like any
9131 other groups. When you activate a solid @code{nneething} group, you will
9132 be told how many unread articles it contains, etc., etc.
9137 @item nneething-map-file-directory
9138 @vindex nneething-map-file-directory
9139 All the mapping files for solid @code{nneething} groups will be stored
9140 in this directory, which defaults to @file{~/.nneething/}.
9142 @item nneething-exclude-files
9143 @vindex nneething-exclude-files
9144 All files that match this regexp will be ignored. Nice to use to exclude
9145 auto-save files and the like, which is what it does by default.
9147 @item nneething-map-file
9148 @vindex nneething-map-file
9149 Name of the map files.
9153 @node Document Groups
9154 @subsection Document Groups
9156 @cindex documentation group
9159 @code{nndoc} is a cute little thing that will let you read a single file
9160 as a newsgroup. Several files types are supported:
9167 The babyl (rmail) mail box.
9172 The standard Unix mbox file.
9174 @cindex MMDF mail box
9176 The MMDF mail box format.
9179 Several news articles appended into a file.
9182 @cindex rnews batch files
9183 The rnews batch transport format.
9184 @cindex forwarded messages
9193 @cindex RFC 1153 digest
9194 @cindex RFC 341 digest
9195 MIME (RFC 1341) digest format.
9197 @item standard-digest
9198 The standard (RFC 1153) digest format.
9201 Non-standard digest format---matches most things, but does it badly.
9204 You can also use the special ``file type'' @code{guess}, which means
9205 that @code{nndoc} will try to guess what file type it is looking at.
9206 @code{digest} means that @code{nndoc} should guess what digest type the
9209 @code{nndoc} will not try to change the file or insert any extra headers into
9210 it---it will simply, like, let you use the file as the basis for a
9211 group. And that's it.
9213 If you have some old archived articles that you want to insert into your
9214 new & spiffy Gnus mail backend, @code{nndoc} can probably help you with
9215 that. Say you have an old @file{RMAIL} file with mail that you now want
9216 to split into your new @code{nnml} groups. You look at that file using
9217 @code{nndoc}, set the process mark on all the articles in the buffer
9218 (@kbd{M P b}, for instance), and then re-spool (@kbd{B r}) using
9219 @code{nnml}. If all goes well, all the mail in the @file{RMAIL} file is
9220 now also stored in lots of @code{nnml} directories, and you can delete
9221 that pesky @file{RMAIL} file. If you have the guts!
9223 Virtual server variables:
9226 @item nndoc-article-type
9227 @vindex nndoc-article-type
9228 This should be one of @code{mbox}, @code{babyl}, @code{digest},
9229 @code{mmdf}, @code{forward}, @code{news}, @code{rnews},
9230 @code{mime-digest}, @code{clari-briefs}, or @code{guess}.
9232 @item nndoc-post-type
9233 @vindex nndoc-post-type
9234 This variable says whether Gnus is to consider the group a news group or
9235 a mail group. There are two legal values: @code{mail} (the default)
9245 In the PC world people often talk about ``offline'' newsreaders. These
9246 are thingies that are combined reader/news transport monstrosities.
9247 With built-in modem programs. Yecchh!
9249 Of course, us Unix Weenie types of human beans use things like
9250 @code{uucp} and, like, @code{nntpd} and set up proper news and mail
9251 transport things like Ghod intended. And then we just use normal
9254 However, it can sometimes be convenient to do something a that's a bit
9255 easier on the brain if you have a very slow modem, and you're not really
9256 that interested in doing things properly.
9258 A file format called @sc{soup} has been developed for transporting news
9259 and mail from servers to home machines and back again. It can be a bit
9265 You log in on the server and create a @sc{soup} packet. You can either
9266 use a dedicated @sc{soup} thingie, or you can use Gnus to create the
9267 packet with the @kbd{O s} command.
9270 You transfer the packet home. Rail, boat, car or modem will do fine.
9273 You put the packet in your home directory.
9276 You fire up Gnus using the @code{nnsoup} backend as the native server.
9279 You read articles and mail and answer and followup to the things you
9283 You do the @kbd{G s r} command to pack these replies into a @sc{soup}
9287 You transfer this packet to the server.
9290 You use Gnus to mail this packet out with the @kbd{G s s} command.
9293 You then repeat until you die.
9297 So you basically have a bipartite system---you use @code{nnsoup} for
9298 reading and Gnus for packing/sending these @sc{soup} packets.
9301 * SOUP Commands:: Commands for creating and sending @sc{soup} packets
9302 * SOUP Groups:: A backend for reading @sc{soup} packets.
9303 * SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
9308 @subsubsection SOUP Commands
9312 @kindex G s b (Group)
9313 @findex gnus-group-brew-soup
9314 Pack all unread articles in the current group
9315 (@code{gnus-group-brew-soup}). This command understands the
9316 process/prefix convention.
9319 @kindex G s w (Group)
9320 @findex gnus-soup-save-areas
9321 Save all data files (@code{gnus-soup-save-areas}).
9324 @kindex G s s (Group)
9325 @findex gnus-soup-send-replies
9326 Send all replies from the replies packet
9327 (@code{gnus-soup-send-replies}).
9330 @kindex G s p (Group)
9331 @findex gnus-soup-pack-packet
9332 Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
9335 @kindex G s r (Group)
9336 @findex nnsoup-pack-replies
9337 Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
9340 @kindex O s (Summary)
9341 @findex gnus-soup-add-article
9342 This summary-mode command adds the current article to a @sc{soup} packet
9343 (@code{gnus-soup-add-article}). It understands the process/prefix
9349 There are a few variables to customize where Gnus will put all these
9354 @item gnus-soup-directory
9355 @vindex gnus-soup-directory
9356 Directory where Gnus will save intermediate files while composing
9357 @sc{soup} packets. The default is @file{~/SoupBrew/}.
9359 @item gnus-soup-replies-directory
9360 @vindex gnus-soup-replies-directory
9361 This is what Gnus will use as a temporary directory while sending our
9362 reply packets. The default is @file{~/SoupBrew/SoupReplies/}.
9364 @item gnus-soup-prefix-file
9365 @vindex gnus-soup-prefix-file
9366 Name of the file where Gnus stores the last used prefix. The default is
9369 @item gnus-soup-packer
9370 @vindex gnus-soup-packer
9371 A format string command for packing a @sc{soup} packet. The default is
9372 @samp{tar cf - %s | gzip > $HOME/Soupout%d.tgz}.
9374 @item gnus-soup-unpacker
9375 @vindex gnus-soup-unpacker
9376 Format string command for unpacking a @sc{soup} packet. The default is
9377 @samp{gunzip -c %s | tar xvf -}.
9379 @item gnus-soup-packet-directory
9380 @vindex gnus-soup-packet-directory
9381 Where Gnus will look for reply packets. The default is @file{~/}.
9383 @item gnus-soup-packet-regexp
9384 @vindex gnus-soup-packet-regexp
9385 Regular expression matching @sc{soup} reply packets in
9386 @code{gnus-soup-packet-directory}.
9392 @subsubsection @sc{soup} Groups
9395 @code{nnsoup} is the backend for reading @sc{soup} packets. It will
9396 read incoming packets, unpack them, and put them in a directory where
9397 you can read them at leisure.
9399 These are the variables you can use to customize its behavior:
9403 @item nnsoup-tmp-directory
9404 @vindex nnsoup-tmp-directory
9405 When @code{nnsoup} unpacks a @sc{soup} packet, it does it in this
9406 directory. (@file{/tmp/} by default.)
9408 @item nnsoup-directory
9409 @vindex nnsoup-directory
9410 @code{nnsoup} then moves each message and index file to this directory.
9411 The default is @file{~/SOUP/}.
9413 @item nnsoup-replies-directory
9414 @vindex nnsoup-replies-directory
9415 All replies will stored in this directory before being packed into a
9416 reply packet. The default is @file{~/SOUP/replies/"}.
9418 @item nnsoup-replies-format-type
9419 @vindex nnsoup-replies-format-type
9420 The @sc{soup} format of the replies packets. The default is @samp{?n}
9421 (rnews), and I don't think you should touch that variable. I probably
9422 shouldn't even have documented it. Drats! Too late!
9424 @item nnsoup-replies-index-type
9425 @vindex nnsoup-replies-index-type
9426 The index type of the replies packet. The is @samp{?n}, which means
9427 ``none''. Don't fiddle with this one either!
9429 @item nnsoup-active-file
9430 @vindex nnsoup-active-file
9431 Where @code{nnsoup} stores lots of information. This is not an ``active
9432 file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
9433 this file or mess it up in any way, you're dead. The default is
9434 @file{~/SOUP/active}.
9437 @vindex nnsoup-packer
9438 Format string command for packing a reply @sc{soup} packet. The default
9439 is @samp{tar cf - %s | gzip > $HOME/Soupin%d.tgz}.
9441 @item nnsoup-unpacker
9442 @vindex nnsoup-unpacker
9443 Format string command for unpacking incoming @sc{soup} packets. The
9444 default is @samp{gunzip -c %s | tar xvf -}.
9446 @item nnsoup-packet-directory
9447 @vindex nnsoup-packet-directory
9448 Where @code{nnsoup} will look for incoming packets. The default is
9451 @item nnsoup-packet-regexp
9452 @vindex nnsoup-packet-regexp
9453 Regular expression matching incoming @sc{soup} packets. The default is
9460 @subsubsection SOUP Replies
9462 Just using @code{nnsoup} won't mean that your postings and mailings end
9463 up in @sc{soup} reply packets automagically. You have to work a bit
9464 more for that to happen.
9466 @findex nnsoup-set-variables
9467 The @code{nnsoup-set-variables} command will set the appropriate
9468 variables to ensure that all your followups and replies end up in the
9471 In specific, this is what it does:
9474 (setq gnus-inews-article-function 'nnsoup-request-post)
9475 (setq send-mail-function 'nnsoup-request-mail)
9478 And that's it, really. If you only want news to go into the @sc{soup}
9479 system you just use the first line. If you only want mail to be
9480 @sc{soup}ed you use the second.
9483 @node Combined Groups
9484 @section Combined Groups
9486 Gnus allows combining a mixture of all the other group types into bigger
9490 * Virtual Groups:: Combining articles from many groups.
9491 * Kibozed Groups:: Looking through parts of the newsfeed for articles.
9495 @node Virtual Groups
9496 @subsection Virtual Groups
9498 @cindex virtual groups
9500 An @dfn{nnvirtual group} is really nothing more than a collection of
9503 For instance, if you are tired of reading many small group, you can
9504 put them all in one big group, and then grow tired of reading one
9505 big, unwieldy group. The joys of computing!
9507 You specify @code{nnvirtual} as the method. The address should be a
9508 regexp to match component groups.
9510 All marks in the virtual group will stick to the articles in the
9511 component groups. So if you tick an article in a virtual group, the
9512 article will also be ticked in the component group from whence it came.
9513 (And vice versa---marks from the component groups will also be shown in
9516 Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
9517 newsgroups into one, big, happy newsgroup:
9520 (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
9523 The component groups can be native or foreign; everything should work
9524 smoothly, but if your computer explodes, it was probably my fault.
9526 Collecting the same group from several servers might actually be a good
9527 idea if users have set the Distribution header to limit distribution.
9528 If you would like to read @samp{soc.motss} both from a server in Japan
9529 and a server in Norway, you could use the following as the group regexp:
9532 "^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
9535 This should work kinda smoothly---all articles from both groups should
9536 end up in this one, and there should be no duplicates. Threading (and
9537 the rest) will still work as usual, but there might be problems with the
9538 sequence of articles. Sorting on date might be an option here
9539 (@pxref{Selecting a Group}.
9541 One limitation, however---all groups that are included in a virtual
9542 group has to be alive (i.e., subscribed or unsubscribed). Killed or
9543 zombie groups can't be component groups for @code{nnvirtual} groups.
9545 @vindex nnvirtual-always-rescan
9546 If the @code{nnvirtual-always-rescan} is non-@code{nil},
9547 @code{nnvirtual} will always scan groups for unread articles when
9548 entering a virtual group. If this variable is @code{nil} (which is the
9549 default) and you read articles in a component group after the virtual
9550 group has been activated, the read articles from the component group
9551 will show up when you enter the virtual group. You'll also see this
9552 effect if you have two virtual groups that contain the same component
9553 group. If that's the case, you should set this variable to @code{t}.
9554 Or you can just tap @code{M-g} on the virtual group every time before
9555 you enter it---it'll have much the same effect.
9558 @node Kibozed Groups
9559 @subsection Kibozed Groups
9563 @dfn{Kibozing} is defined by @sc{oed} as ``grepping through (parts of)
9564 the news feed''. @code{nnkiboze} is a backend that will do this for
9565 you. Oh joy! Now you can grind any @sc{nntp} server down to a halt
9566 with useless requests! Oh happiness!
9568 The address field of the @code{nnkiboze} method is, as with
9569 @code{nnvirtual}, a regexp to match groups to be ``included'' in the
9570 @code{nnkiboze} group. There most similarities between @code{nnkiboze}
9571 and @code{nnvirtual} ends.
9573 In addition to this regexp detailing component groups, an @code{nnkiboze} group
9574 must have a score file to say what articles that are to be included in
9575 the group (@pxref{Scoring}).
9577 @kindex M-x nnkiboze-generate-groups
9578 @findex nnkiboze-generate-groups
9579 You must run @kbd{M-x nnkiboze-generate-groups} after creating the
9580 @code{nnkiboze} groups you want to have. This command will take time. Lots of
9581 time. Oodles and oodles of time. Gnus has to fetch the headers from
9582 all the articles in all the components groups and run them through the
9583 scoring process to determine if there are any articles in the groups
9584 that are to be part of the @code{nnkiboze} groups.
9586 Please limit the number of component groups by using restrictive
9587 regexps. Otherwise your sysadmin may become annoyed with you, and the
9588 @sc{nntp} site may throw you off and never let you back in again.
9589 Stranger things have happened.
9591 @code{nnkiboze} component groups do not have to be alive---they can be dead,
9592 and they can be foreign. No restrictions.
9594 @vindex nnkiboze-directory
9595 The generation of an @code{nnkiboze} group means writing two files in
9596 @code{nnkiboze-directory}, which is @file{~/News/} by default. One
9597 contains the @sc{nov} header lines for all the articles in the group,
9598 and the other is an additional @file{.newsrc} file to store information
9599 on what groups that have been searched through to find component
9602 Articles that are marked as read in the @code{nnkiboze} group will have their
9603 @sc{nov} lines removed from the @sc{nov} file.
9610 Other people use @dfn{kill files}, but we here at Gnus Towers like
9611 scoring better than killing, so we'd rather switch than fight. They do
9612 something completely different as well, so sit up straight and pay
9615 @vindex gnus-summary-mark-below
9616 All articles have a default score (@code{gnus-summary-default-score}),
9617 which is 0 by default. This score may be raised or lowered either
9618 interactively or by score files. Articles that have a score lower than
9619 @code{gnus-summary-mark-below} are marked as read.
9621 Gnus will read any @dfn{score files} that apply to the current group
9622 before generating the summary buffer.
9624 There are several commands in the summary buffer that insert score
9625 entries based on the current article. You can, for instance, ask Gnus to
9626 lower or increase the score of all articles with a certain subject.
9628 There are two sorts of scoring entries: Permanent and temporary.
9629 Temporary score entries are self-expiring entries. Any entries that are
9630 temporary and have not been used for, say, a week, will be removed
9631 silently to help keep the sizes of the score files down.
9634 * Summary Score Commands:: Adding score entries for the current group.
9635 * Group Score Commands:: General score commands.
9636 * Score Variables:: Customize your scoring. (My, what terminology).
9637 * Score File Format:: What a score file may contain.
9638 * Score File Editing:: You can edit score files by hand as well.
9639 * Adaptive Scoring:: Big Sister Gnus *knows* what you read.
9640 * Followups To Yourself:: Having Gnus notice when people answer you.
9641 * Scoring Tips:: How to score effectively.
9642 * Reverse Scoring:: That problem child of old is not problem.
9643 * Global Score Files:: Earth-spanning, ear-splitting score files.
9644 * Kill Files:: They are still here, but they can be ignored.
9645 * GroupLens:: Getting predictions on what you like to read.
9649 @node Summary Score Commands
9650 @section Summary Score Commands
9651 @cindex score commands
9653 The score commands that alter score entries do not actually modify real
9654 score files. That would be too inefficient. Gnus maintains a cache of
9655 previously loaded score files, one of which is considered the
9656 @dfn{current score file alist}. The score commands simply insert
9657 entries into this list, and upon group exit, this list is saved.
9659 The current score file is by default the group's local score file, even
9660 if no such score file actually exists. To insert score commands into
9661 some other score file (eg. @file{all.SCORE}), you must first make this
9662 score file the current one.
9664 General score commands that don't actually change the score file:
9669 @kindex V s (Summary)
9670 @findex gnus-summary-set-score
9671 Set the score of the current article (@code{gnus-summary-set-score}).
9674 @kindex V S (Summary)
9675 @findex gnus-summary-current-score
9676 Display the score of the current article
9677 (@code{gnus-summary-current-score}).
9680 @kindex V t (Summary)
9681 @findex gnus-score-find-trace
9682 Display all score rules that have been used on the current article
9683 (@code{gnus-score-find-trace}).
9686 @cindex V R (Summary)
9687 @findex gnus-summary-rescore
9688 Run the current summary through the scoring process
9689 (@code{gnus-summary-rescore}). This might be useful if you're playing
9690 around with your score files behind Gnus' back and want to see the
9691 effect you're having.
9694 @kindex V a (Summary)
9695 @findex gnus-summary-score-entry
9696 Add a new score entry, and allow specifying all elements
9697 (@code{gnus-summary-score-entry}).
9700 @kindex V c (Summary)
9701 @findex gnus-score-change-score-file
9702 Make a different score file the current
9703 (@code{gnus-score-change-score-file}).
9706 @kindex V e (Summary)
9707 @findex gnus-score-edit-current-scores
9708 Edit the current score file (@code{gnus-score-edit-current-scores}).
9709 You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score
9713 @kindex V f (Summary)
9714 @findex gnus-score-edit-file
9715 Edit a score file and make this score file the current one
9716 (@code{gnus-score-edit-file}).
9719 @kindex V C (Summary)
9720 @findex gnus-score-customize
9721 Customize a score file in a visually pleasing manner
9722 (@code{gnus-score-customize}).
9725 @kindex I C-i (Summary)
9726 @findex gnus-summary-raise-score
9727 Increase the score of the current article
9728 (@code{gnus-summary-raise-score}).
9731 @kindex L C-l (Summary)
9732 @findex gnus-summary-lower-score
9733 Lower the score of the current article
9734 (@code{gnus-summary-lower-score}).
9737 The rest of these commands modify the local score file.
9742 @kindex V m (Summary)
9743 @findex gnus-score-set-mark-below
9744 Prompt for a score, and mark all articles with a score below this as
9745 read (@code{gnus-score-set-mark-below}).
9748 @kindex V E (Summary)
9749 @findex gnus-score-set-expunge-below
9750 Expunge all articles with a score below the default score (or the
9751 numeric prefix) (@code{gnus-score-set-expunge-below}).
9754 The keystrokes for actually making score entries follow a very regular
9755 pattern, so there's no need to list all the commands. (Hundreds of
9760 The first key is either @kbd{I} (upper case i) for increasing the score
9761 or @kbd{L} for lowering the score.
9763 The second key says what header you want to score on. The following
9768 Score on the author name.
9771 Score on the subject line.
9774 Score on the Xref line---i.e., the cross-posting line.
9777 Score on thread---the References line.
9783 Score on the number of lines.
9786 Score on the Message-ID.
9799 The third key is the match type. Which match types are legal depends on
9800 what headers you are scoring on.
9844 Greater than number.
9849 The fourth and final key says whether this is a temporary (i.e., expiring)
9850 score entry, or a permanent (i.e., non-expiring) score entry, or whether
9851 it is to be done immediately, without adding to the score file.
9855 Temporary score entry.
9858 Permanent score entry.
9861 Immediately scoring.
9866 So, let's say you want to increase the score on the current author with
9867 exact matching permanently: @kbd{I a e p}. If you want to lower the
9868 score based on the subject line, using substring matching, and make a
9869 temporary score entry: @kbd{L s s t}. Pretty easy.
9871 To make things a bit more complicated, there are shortcuts. If you use
9872 a capital letter on either the second or third keys, Gnus will use
9873 defaults for the remaining one or two keystrokes. The defaults are
9874 ``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s
9875 t}, and @kbd{I a R} is the same as @kbd{I a r t}.
9877 @vindex gnus-score-mimic-keymap
9878 The @code{gnus-score-mimic-keymap} says whether these commands will
9879 pretend they are keymaps or not.
9882 @node Group Score Commands
9883 @section Group Score Commands
9884 @cindex group score commands
9886 There aren't many of these as yet, I'm afraid.
9892 @findex gnus-score-flush-cache
9893 Gnus maintains a cache of score alists to avoid having to reload them
9894 all the time. This command will flush the cache
9895 (@code{gnus-score-flush-cache}).
9900 @node Score Variables
9901 @section Score Variables
9902 @cindex score variables
9906 @item gnus-use-scoring
9907 @vindex gnus-use-scoring
9908 If @code{nil}, Gnus will not check for score files, and will not, in
9909 general, do any score-related work. This is @code{t} by default.
9911 @item gnus-kill-killed
9912 @vindex gnus-kill-killed
9913 If this variable is @code{nil}, Gnus will never apply score files to
9914 articles that have already been through the kill process. While this
9915 may save you lots of time, it also means that if you apply a kill file
9916 to a group, and then change the kill file and want to run it over you
9917 group again to kill more articles, it won't work. You have to set this
9918 variable to @code{t} to do that. (It is @code{t} by default.)
9920 @item gnus-kill-files-directory
9921 @vindex gnus-kill-files-directory
9922 All kill and score files will be stored in this directory, which is
9923 initialized from the @code{SAVEDIR} environment variable by default.
9924 This is @file{~/News/} by default.
9926 @item gnus-score-file-suffix
9927 @vindex gnus-score-file-suffix
9928 Suffix to add to the group name to arrive at the score file name
9929 (@samp{SCORE} by default.)
9931 @item gnus-score-uncacheable-files
9932 @vindex gnus-score-uncacheable-files
9934 All score files are normally cached to avoid excessive re-loading of
9935 score files. However, if this might make you Emacs grow big and
9936 bloated, so this regexp can be used to weed out score files that are
9937 unlikely to be needed again. It would be a bad idea to deny caching of
9938 @file{all.SCORE}, while it might be a good idea to not cache
9939 @file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
9940 variable is @samp{ADAPT$} by default, so no adaptive score files will
9943 @item gnus-save-score
9944 @vindex gnus-save-score
9945 If you have really complicated score files, and do lots of batch
9946 scoring, then you might set this variable to @code{t}. This will make
9947 Gnus save the scores into the @file{.newsrc.eld} file.
9949 @item gnus-score-interactive-default-score
9950 @vindex gnus-score-interactive-default-score
9951 Score used by all the interactive raise/lower commands to raise/lower
9952 score with. Default is 1000, which may seem excessive, but this is to
9953 ensure that the adaptive scoring scheme gets enough room to play with.
9954 We don't want the small changes from the adaptive scoring to overwrite
9955 manually entered data.
9957 @item gnus-summary-default-score
9958 @vindex gnus-summary-default-score
9959 Default score of an article, which is 0 by default.
9961 @item gnus-score-over-mark
9962 @vindex gnus-score-over-mark
9963 Mark (in the third column) used for articles with a score over the
9964 default. Default is @samp{+}.
9966 @item gnus-score-below-mark
9967 @vindex gnus-score-below-mark
9968 Mark (in the third column) used for articles with a score below the
9969 default. Default is @samp{-}.
9971 @item gnus-score-find-score-files-function
9972 @vindex gnus-score-find-score-files-function
9973 Function used to find score files for the current group. This function
9974 is called with the name of the group as the argument.
9976 Predefined functions available are:
9979 @item gnus-score-find-single
9980 @findex gnus-score-find-single
9981 Only apply the group's own score file.
9983 @item gnus-score-find-bnews
9984 @findex gnus-score-find-bnews
9985 Apply all score files that match, using bnews syntax. This is the
9986 default. For instance, if the current group is @samp{gnu.emacs.gnus},
9987 @file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and
9988 @file{gnu.all.SCORE} would all apply. In short, the instances of
9989 @samp{all} in the score file names are translated into @samp{.*}, and
9990 then a regexp match is done.
9992 This means that if you have some score entries that you want to apply to
9993 all groups, then you put those entries in the @file{all.SCORE} file.
9995 @item gnus-score-find-hierarchical
9996 @findex gnus-score-find-hierarchical
9997 Apply all score files from all the parent groups. This means that you
9998 can't have score files like @file{all.SCORE} or @file{all.emacs.SCORE},
9999 but you can have @file{SCORE}, @file{comp.SCORE} and
10000 @file{comp.emacs.SCORE}.
10003 This variable can also be a list of functions. In that case, all these
10004 functions will be called, and all the returned lists of score files will
10005 be applied. These functions can also return lists of score alists
10006 directly. In that case, the functions that return these non-file score
10007 alists should probably be placed before the ``real'' score file
10008 functions, to ensure that the last score file returned is the local
10011 @item gnus-score-expiry-days
10012 @vindex gnus-score-expiry-days
10013 This variable says how many days should pass before an unused score file
10014 entry is expired. If this variable is @code{nil}, no score file entries
10015 are expired. It's 7 by default.
10017 @item gnus-update-score-entry-dates
10018 @vindex gnus-update-score-entry-dates
10019 If this variable is non-@code{nil}, matching score entries will have
10020 their dates updated. (This is how Gnus controls expiry---all
10021 non-matching entries will become too old while matching entries will
10022 stay fresh and young.) However, if you set this variable to @code{nil},
10023 even matching entries will grow old and will have to face that oh-so
10026 @item gnus-score-after-write-file-function
10027 @vindex gnus-score-after-write-file-function
10028 Function called with the name of the score file just written.
10033 @node Score File Format
10034 @section Score File Format
10035 @cindex score file format
10037 A score file is an @code{emacs-lisp} file that normally contains just a
10038 single form. Casual users are not expected to edit these files;
10039 everything can be changed from the summary buffer.
10041 Anyway, if you'd like to dig into it yourself, here's an example:
10045 ("Lars Ingebrigtsen" -10000)
10047 ("larsi\\|lmi" -50000 nil R))
10049 ("Ding is Badd" nil 728373))
10051 ("alt.politics" -1000 728372 s))
10056 (mark-and-expunge -10)
10060 (files "/hom/larsi/News/gnu.SCORE")
10061 (exclude-files "all.SCORE")
10062 (local (gnus-newsgroup-auto-expire t)
10063 (gnus-summary-make-false-root 'empty))
10067 This example demonstrates absolutely everything about a score file.
10069 Even though this looks much like lisp code, nothing here is actually
10070 @code{eval}ed. The lisp reader is used to read this form, though, so it
10071 has to be legal syntactically, if not semantically.
10073 Six keys are supported by this alist:
10078 If the key is a string, it is the name of the header to perform the
10079 match on. Scoring can only be performed on these eight headers:
10080 @code{From}, @code{Subject}, @code{References}, @code{Message-ID},
10081 @code{Xref}, @code{Lines}, @code{Chars} and @code{Date}. In addition to
10082 these headers, there are three strings to tell Gnus to fetch the entire
10083 article and do the match on larger parts of the article: @code{Body}
10084 will perform the match on the body of the article, @code{Head} will
10085 perform the match on the head of the article, and @code{All} will
10086 perform the match on the entire article. Note that using any of these
10087 last three keys will slow down group entry @emph{considerably}. The
10088 final ``header'' you can score on is @code{Followup}. These score
10089 entries will result in new score entries being added for all follow-ups
10090 to articles that matches these score entries.
10092 Following this key is a arbitrary number of score entries, where each
10093 score entry has one to four elements.
10097 The first element is the @dfn{match element}. On most headers this will
10098 be a string, but on the Lines and Chars headers, this must be an
10102 If the second element is present, it should be a number---the @dfn{score
10103 element}. This number should be an integer in the neginf to posinf
10104 interval. This number is added to the score of the article if the match
10105 is successful. If this element is not present, the
10106 @code{gnus-score-interactive-default-score} number will be used
10107 instead. This is 1000 by default.
10110 If the third element is present, it should be a number---the @dfn{date
10111 element}. This date says when the last time this score entry matched,
10112 which provides a mechanism for expiring the score entries. It this
10113 element is not present, the score entry is permanent. The date is
10114 represented by the number of days since December 31, 1 ce.
10117 If the fourth element is present, it should be a symbol---the @dfn{type
10118 element}. This element specifies what function should be used to see
10119 whether this score entry matches the article. What match types that can
10120 be used depends on what header you wish to perform the match on.
10123 @item From, Subject, References, Xref, Message-ID
10124 For most header types, there are the @code{r} and @code{R} (regexp) as
10125 well as @code{s} and @code{S} (substring) types and @code{e} and
10126 @code{E} (exact match) types. If this element is not present, Gnus will
10127 assume that substring matching should be used. @code{R} and @code{S}
10128 differ from the other two in that the matches will be done in a
10129 case-sensitive manner. All these one-letter types are really just
10130 abbreviations for the @code{regexp}, @code{string} and @code{exact}
10131 types, which you can use instead, if you feel like.
10134 These two headers use different match types: @code{<}, @code{>},
10135 @code{=}, @code{>=} and @code{<=}.
10138 For the Date header we have three match types: @code{before}, @code{at}
10139 and @code{after}. I can't really imagine this ever being useful, but,
10140 like, it would feel kinda silly not to provide this function. Just in
10141 case. You never know. Better safe than sorry. Once burnt, twice shy.
10142 Don't judge a book by its cover. Never not have sex on a first date.
10144 @item Head, Body, All
10145 These three match keys use the same match types as the @code{From} (etc)
10149 This match key will add a score entry on all articles that followup to
10150 some author. Uses the same match types as the @code{From} header uses.
10153 This match key will add a score entry on all articles that are part of
10154 a thread. Uses the same match types as the @code{References} header
10160 The value of this entry should be a number. Any articles with a score
10161 lower than this number will be marked as read.
10164 The value of this entry should be a number. Any articles with a score
10165 lower than this number will be removed from the summary buffer.
10167 @item mark-and-expunge
10168 The value of this entry should be a number. Any articles with a score
10169 lower than this number will be marked as read and removed from the
10172 @item thread-mark-and-expunge
10173 The value of this entry should be a number. All articles that belong to
10174 a thread that has a total score below this number will be marked as read
10175 and removed from the summary buffer. @code{gnus-thread-score-function}
10176 says how to compute the total score for a thread.
10179 The value of this entry should be any number of file names. These files
10180 are assumed to be score files as well, and will be loaded the same way
10183 @item exclude-files
10184 The clue of this entry should be any number of files. This files will
10185 not be loaded, even though they would normally be so, for some reason or
10189 The value of this entry will be @code{eval}el. This element will be
10190 ignored when handling global score files.
10193 Read-only score files will not be updated or saved. Global score files
10194 should feature this atom (@pxref{Global Score Files}).
10197 The value of this entry should be a number. Articles that do not have
10198 parents will get this number added to their scores. Imagine you follow
10199 some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you
10200 will only follow a few of the threads, also want to see any new threads.
10202 You can do this with the following two score file entries:
10206 (mark-and-expunge -100)
10209 When you enter the group the first time, you will only see the new
10210 threads. You then raise the score of the threads that you find
10211 interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{C y}) the
10212 rest. Next time you enter the group, you will see new articles in the
10213 interesting threads, plus any new threads.
10215 I.e. -- the orphan score atom is for high-volume groups where there
10216 exist a few interesting threads which can't be found automatically by
10217 ordinary scoring rules.
10220 This entry controls the adaptive scoring. If it is @code{t}, the
10221 default adaptive scoring rules will be used. If it is @code{ignore}, no
10222 adaptive scoring will be performed on this group. If it is a list, this
10223 list will be used as the adaptive scoring rules. If it isn't present,
10224 or is something other than @code{t} or @code{ignore}, the default
10225 adaptive scoring rules will be used. If you want to use adaptive
10226 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
10227 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
10228 not want adaptive scoring. If you only want adaptive scoring in a few
10229 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
10230 insert @code{(adapt t)} in the score files of the groups where you want
10234 All adaptive score entries will go to the file named by this entry. It
10235 will also be applied when entering the group. This atom might be handy
10236 if you want to adapt on several groups at once, using the same adaptive
10237 file for a number of groups.
10240 @cindex local variables
10241 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
10242 Each @var{var} will be made buffer-local to the current summary buffer,
10243 and set to the value specified. This is a convenient, if somewhat
10244 strange, way of setting variables in some groups if you don't like hooks
10249 @node Score File Editing
10250 @section Score File Editing
10252 You normally enter all scoring commands from the summary buffer, but you
10253 might feel the urge to edit them by hand as well, so we've supplied you
10254 with a mode for that.
10256 It's simply a slightly customized @code{emacs-lisp} mode, with these
10257 additional commands:
10262 @kindex C-c C-c (Score)
10263 @findex gnus-score-edit-done
10264 Save the changes you have made and return to the summary buffer
10265 (@code{gnus-score-edit-done}).
10268 @kindex C-c C-d (Score)
10269 @findex gnus-score-edit-insert-date
10270 Insert the current date in numerical format
10271 (@code{gnus-score-edit-insert-date}). This is really the day number, if
10272 you were wondering.
10275 @kindex C-c C-p (Score)
10276 @findex gnus-score-pretty-print
10277 The adaptive score files are saved in an unformatted fashion. If you
10278 intend to read one of these files, you want to @dfn{pretty print} it
10279 first. This command (@code{gnus-score-pretty-print}) does that for
10284 Type @kbd{M-x gnus-score-mode} to use this mode.
10286 @vindex gnus-score-mode-hook
10287 @code{gnus-score-menu-hook} is run in score mode buffers.
10289 In the summary buffer you can use commands like @kbd{V f} and @kbd{V
10290 e} to begin editing score files.
10293 @node Adaptive Scoring
10294 @section Adaptive Scoring
10295 @cindex adaptive scoring
10297 If all this scoring is getting you down, Gnus has a way of making it all
10298 happen automatically---as if by magic. Or rather, as if by artificial
10299 stupidity, to be precise.
10301 @vindex gnus-use-adaptive-scoring
10302 When you read an article, or mark an article as read, or kill an
10303 article, you leave marks behind. On exit from the group, Gnus can sniff
10304 these marks and add score elements depending on what marks it finds.
10305 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
10308 @vindex gnus-default-adaptive-score-alist
10309 To give you complete control over the scoring process, you can customize
10310 the @code{gnus-default-adaptive-score-alist} variable. For instance, it
10311 might look something like this:
10314 (defvar gnus-default-adaptive-score-alist
10315 '((gnus-unread-mark)
10316 (gnus-ticked-mark (from 4))
10317 (gnus-dormant-mark (from 5))
10318 (gnus-del-mark (from -4) (subject -1))
10319 (gnus-read-mark (from 4) (subject 2))
10320 (gnus-expirable-mark (from -1) (subject -1))
10321 (gnus-killed-mark (from -1) (subject -3))
10322 (gnus-kill-file-mark)
10323 (gnus-ancient-mark)
10324 (gnus-low-score-mark)
10325 (gnus-catchup-mark (from -1) (subject -1))))
10328 As you see, each element in this alist has a mark as a key (either a
10329 variable name or a ``real'' mark---a character). Following this key is
10330 a arbitrary number of header/score pairs. If there are no header/score
10331 pairs following the key, no adaptive scoring will be done on articles
10332 that have that key as the article mark. For instance, articles with
10333 @code{gnus-unread-mark} in the example above will not get adaptive score
10336 Each article can have only one mark, so just a single of these rules
10337 will be applied to each article.
10339 To take @code{gnus-del-mark} as an example---this alist says that all
10340 articles that have that mark (i.e., are marked with @samp{D}) will have a
10341 score entry added to lower based on the @code{From} header by -4, and
10342 lowered by @code{Subject} by -1. Change this to fit your prejudices.
10344 If you have marked 10 articles with the same subject with
10345 @code{gnus-del-mark}, the rule for that mark will be applied ten times.
10346 That means that that subject will get a score of ten times -1, which
10347 should be, unless I'm much mistaken, -10.
10349 The headers you can score on are @code{from}, @code{subject},
10350 @code{message-id}, @code{references}, @code{xref}, @code{lines},
10351 @code{chars} and @code{date}. In addition, you can score on
10352 @code{followup}, which will create an adaptive score entry that matches
10353 on the @code{References} header using the @code{Message-ID} of the
10354 current article, thereby matching the following thread.
10356 You can also score on @code{thread}, which will try to score all
10357 articles that appear in a thread. @code{thread} matches uses a
10358 @code{Message-ID} to match on the @code{References} header of the
10359 article. If the match is made, the @code{Message-ID} of the article is
10360 added to the @code{thread} rule. (Think about it. I'd recommend two
10361 aspirins afterwards.)
10363 If you use this scheme, you should set the score file atom @code{mark}
10364 to something small---like -300, perhaps, to avoid having small random
10365 changes result in articles getting marked as read.
10367 After using adaptive scoring for a week or so, Gnus should start to
10368 become properly trained and enhance the authors you like best, and kill
10369 the authors you like least, without you having to say so explicitly.
10371 You can control what groups the adaptive scoring is to be performed on
10372 by using the score files (@pxref{Score File Format}). This will also
10373 let you use different rules in different groups.
10375 @vindex gnus-adaptive-file-suffix
10376 The adaptive score entries will be put into a file where the name is the
10377 group name with @code{gnus-adaptive-file-suffix} appended. The default
10380 @vindex gnus-score-exact-adapt-limit
10381 When doing adaptive scoring, substring or fuzzy matching would probably
10382 give you the best results in most cases. However, if the header one
10383 matches is short, the possibility for false positives is great, so if
10384 the length of the match is less than
10385 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
10386 this variable is @code{nil}, exact matching will always be used to avoid
10390 @node Followups To Yourself
10391 @section Followups To Yourself
10393 Gnus offers two commands for picking out the @code{Message-ID} header in
10394 the current buffer. Gnus will then add a score rule that scores using
10395 this @code{Message-ID} on the @code{References} header of other
10396 articles. This will, in effect, increase the score of all articles that
10397 respond to the article in the current buffer. Quite useful if you want
10398 to easily note when people answer what you've said.
10402 @item gnus-score-followup-article
10403 @findex gnus-score-followup-article
10404 This will add a score to articles that directly follow up your own
10407 @item gnus-score-followup-thread
10408 @findex gnus-score-followup-thread
10409 This will add a score to all articles that appear in a thread ``below''
10413 @vindex gnus-inews-article-hook
10414 These two functions are both primarily meant to be used in hooks like
10415 @code{gnus-inews-article-hook}.
10419 @section Scoring Tips
10420 @cindex scoring tips
10426 @cindex scoring crossposts
10427 If you want to lower the score of crossposts, the line to match on is
10428 the @code{Xref} header.
10430 ("xref" (" talk.politics.misc:" -1000))
10433 @item Multiple crossposts
10434 If you want to lower the score of articles that have been crossposted to
10435 more than, say, 3 groups:
10437 ("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
10440 @item Matching on the body
10441 This is generally not a very good idea---it takes a very long time.
10442 Gnus actually has to fetch each individual article from the server. But
10443 you might want to anyway, I guess. Even though there are three match
10444 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
10445 and stick with it in each score file. If you use any two, each article
10446 will be fetched @emph{twice}. If you want to match a bit on the
10447 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
10450 @item Marking as read
10451 You will probably want to mark articles that has a score below a certain
10452 number as read. This is most easily achieved by putting the following
10453 in your @file{all.SCORE} file:
10457 You may also consider doing something similar with @code{expunge}.
10459 @item Negated character classes
10460 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
10461 That will match newlines, which might lead to, well, The Unknown. Say
10462 @code{[^abcd\n]*} instead.
10466 @node Reverse Scoring
10467 @section Reverse Scoring
10468 @cindex reverse scoring
10470 If you want to keep just articles that have @samp{Sex with Emacs} in the
10471 subject header, and expunge all other articles, you could put something
10472 like this in your score file:
10476 ("Sex with Emacs" 2))
10481 So, you raise all articles that match @samp{Sex with Emacs} and mark the
10482 rest as read, and expunge them to boot.
10485 @node Global Score Files
10486 @section Global Score Files
10487 @cindex global score files
10489 Sure, other newsreaders have ``global kill files''. These are usually
10490 nothing more than a single kill file that applies to all groups, stored
10491 in the user's home directory. Bah! Puny, weak newsreaders!
10493 What I'm talking about here are Global Score Files. Score files from
10494 all over the world, from users everywhere, uniting all nations in one
10495 big, happy score file union! Ange-score! New and untested!
10497 @vindex gnus-global-score-files
10498 All you have to do to use other people's score files is to set the
10499 @code{gnus-global-score-files} variable. One entry for each score file,
10500 or each score file directory. Gnus will decide by itself what score
10501 files are applicable to which group.
10503 Say you want to use all score files in the
10504 @file{/ftp@@ftp.some-where:/pub/score} directory and the single score
10505 file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
10508 (setq gnus-global-score-files
10509 '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
10510 "/ftp@@ftp.some-where:/pub/score/"))
10513 @findex gnus-score-search-global-directories
10514 Simple, eh? Directory names must end with a @samp{/}. These
10515 directories are typically scanned only once during each Gnus session.
10516 If you feel the need to manually re-scan the remote directories, you can
10517 use the @code{gnus-score-search-global-directories} command.
10519 Note that, at present, using this option will slow down group entry
10520 somewhat. (That is---a lot.)
10522 If you want to start maintaining score files for other people to use,
10523 just put your score file up for anonymous ftp and announce it to the
10524 world. Become a retro-moderator! Participate in the retro-moderator
10525 wars sure to ensue, where retro-moderators battle it out for the
10526 sympathy of the people, luring them to use their score files on false
10527 premises! Yay! The net is saved!
10529 Here are some tips for the would-be retro-moderator, off the top of my
10535 Articles that are heavily crossposted are probably junk.
10537 To lower a single inappropriate article, lower by @code{Message-ID}.
10539 Particularly brilliant authors can be raised on a permanent basis.
10541 Authors that repeatedly post off-charter for the group can safely be
10542 lowered out of existence.
10544 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
10545 articles completely.
10548 Use expiring score entries to keep the size of the file down. You
10549 should probably have a long expiry period, though, as some sites keep
10550 old articles for a long time.
10553 ... I wonder whether other newsreaders will support global score files
10554 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
10555 Wave, xrn and 1stReader are bound to implement scoring. Should we start
10556 holding our breath yet?
10560 @section Kill Files
10563 Gnus still supports those pesky old kill files. In fact, the kill file
10564 entries can now be expiring, which is something I wrote before Daniel
10565 Quinlan thought of doing score files, so I've left the code in there.
10567 In short, kill processing is a lot slower (and I do mean @emph{a lot})
10568 than score processing, so it might be a good idea to rewrite your kill
10569 files into score files.
10571 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
10572 forms into this file, which means that you can use kill files as some
10573 sort of primitive hook function to be run on group entry, even though
10574 that isn't a very good idea.
10576 XCNormal kill files look like this:
10579 (gnus-kill "From" "Lars Ingebrigtsen")
10580 (gnus-kill "Subject" "ding")
10584 This will mark every article written by me as read, and remove them from
10585 the summary buffer. Very useful, you'll agree.
10587 Other programs use a totally different kill file syntax. If Gnus
10588 encounters what looks like a @code{rn} kill file, it will take a stab at
10591 Two summary functions for editing a GNUS kill file:
10596 @kindex M-k (Summary)
10597 @findex gnus-summary-edit-local-kill
10598 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
10601 @kindex M-K (Summary)
10602 @findex gnus-summary-edit-global-kill
10603 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
10606 Two group mode functions for editing the kill files:
10611 @kindex M-k (Group)
10612 @findex gnus-group-edit-local-kill
10613 Edit this group's kill file (@code{gnus-group-edit-local-kill}).
10616 @kindex M-K (Group)
10617 @findex gnus-group-edit-global-kill
10618 Edit the general kill file (@code{gnus-group-edit-global-kill}).
10621 Kill file variables:
10624 @item gnus-kill-file-name
10625 @vindex gnus-kill-file-name
10626 A kill file for the group @samp{soc.motss} is normally called
10627 @file{soc.motss.KILL}. The suffix appended to the group name to get
10628 this file name is detailed by the @code{gnus-kill-file-name} variable.
10629 The ``global'' kill file (not in the score file sense of ``global'', of
10630 course) is called just @file{KILL}.
10632 @vindex gnus-kill-save-kill-file
10633 @item gnus-kill-save-kill-file
10634 If this variable is non-@code{nil}, Gnus will save the
10635 kill file after processing, which is necessary if you use expiring
10638 @item gnus-apply-kill-hook
10639 @vindex gnus-apply-kill-hook
10640 @findex gnus-apply-kill-file-unless-scored
10641 @findex gnus-apply-kill-file
10642 A hook called to apply kill files to a group. It is
10643 @code{(gnus-apply-kill-file)} by default. If you want to ignore the
10644 kill file if you have a score file for the same group, you can set this
10645 hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want
10646 kill files to be processed, you should set this variable to @code{nil}.
10648 @item gnus-kill-file-mode-hook
10649 @vindex gnus-kill-file-mode-hook
10650 A hook called in kill-file mode buffers.
10659 GroupLens is a collaborative filtering system that helps you work
10660 together with other people to find the quality news articles out of the
10661 huge volume of news articles generated every day.
10663 To accomplish this the GroupLens system combines your opinions about
10664 articles you have already read with the opinions of others who have done
10665 likewise and gives you a personalized prediction for each unread news
10666 article. Think of GroupLens as a matchmaker. GroupLens watches how you
10667 rate articles, and finds other people that rate articles the same way.
10668 Once it has found for you some people you agree with it tells you, in
10669 the form of a prediction, what they thought of the article. You can use
10670 this prediction to help you decide whether or not you want to read the
10674 * Using GroupLens:: How to make Gnus use GroupLens.
10675 * Rating Articles:: Letting GroupLens know how you rate articles.
10676 * Displaying Predictions:: Displaying predictions given by GroupLens.
10677 * GroupLens Variables:: Customizing GroupLens.
10681 @node Using GroupLens
10682 @subsection Using GroupLens
10684 To use GroupLens you must register a pseudonym with your local Better
10685 Bit Bureau (BBB). At the moment the only better bit in town is at
10686 @samp{http://www.cs.umn.edu/Research/GroupLens/bbb.html}.
10688 Once you have registered you'll need to set a couple of variables.
10692 @item gnus-use-grouplens
10693 @vindex gnus-use-grouplens
10694 Setting this variable to a non-@code{nil} value will make Gnus hook into
10695 all the relevant GroupLens functions.
10697 @item grouplens-pseudonym
10698 @vindex grouplens-pseudonym
10699 This variable should be set to the pseudonum you got when registering
10700 with the Better Bit Bureau.
10702 @item grouplens-newsgroups
10703 @vindex grouplens-newsgroups
10704 A list of groups that you want to get GroupLens predictions for.
10708 Thats the minimum of what you need to get up and running with GroupLens.
10709 Once you've registered, GroupLens will start giving you scores for
10710 articles based on the average of what other people think. But, to get
10711 the real benefit of GroupLens you need to start rating articles
10712 yourself. Then the scores GroupLens gives you will be personalized for
10713 you, based on how the people you usually agree with have already rated.
10716 @node Rating Articles
10717 @subsection Rating Articles
10719 In GroupLens, an article is rated on a scale from 1 to 5, inclusive.
10720 Where 1 means something like this article is a waste of bandwidth and 5
10721 means that the article was really good. The basic question to ask
10722 yourself is, "on a scale from 1 to 5 would I like to see more articles
10725 There are four ways to enter a rating for an article in GroupLens.
10730 @kindex r (GroupLens)
10731 @findex bbb-summary-rate-article
10732 This function will prompt you for a rating on a scale of one to five.
10735 @kindex k (GroupLens)
10736 @findex grouplens-score-thread
10737 This function will prompt you for a rating, and rate all the articles in
10738 the thread. This is really useful for some of those long running giant
10739 threads in rec.humor.
10743 The next two commands, @kbd{n} and @kbd{,} take a numerical prefix to be
10744 the score of the article you're reading.
10749 @kindex n (GroupLens)
10750 @findex grouplens-next-unread-article
10751 Rate the article and go to the next unread article.
10754 @kindex , (GroupLens)
10755 @findex grouplens-best-unread-article
10756 Rate the article and go to the next unread article with the highest score.
10760 If you want to give the current article a score of 4 and then go to the
10761 next article, just type @kbd{4 n}.
10764 @node Displaying Predictions
10765 @subsection Displaying Predictions
10767 GroupLens makes a prediction for you about how much you will like a
10768 news article. The predictions from GroupLens are on a scale from 1 to
10769 5, where 1 is the worst and 5 is the best. You can use the predictions
10770 from GroupLens in one of three ways controlled by the variable
10771 @code{gnus-grouplens-override-scoring}.
10773 @vindex gnus-grouplens-override-scoring
10774 There are three ways to display predictions in grouplens. You may
10775 choose to have the GroupLens scores contribute to, or override the
10776 regular gnus scoring mechanism. override is the default; however, some
10777 people prefer to see the Gnus scores plus the grouplens scores. To get
10778 the separate scoring behavior you need to set
10779 @code{gnus-grouplens-override-scoring} to @code{'separate}. To have the
10780 GroupLens predictions combined with the grouplens scores set it to
10781 @code{'override} and to combine the scores set
10782 @code{gnus-grouplens-override-scoring} to @code{'combine}. When you use
10783 the combine option you will also want to set the values for
10784 @code{grouplens-prediction-offset} and
10785 @code{grouplens-score-scale-factor}.
10787 @vindex grouplens-prediction-display
10788 In either case, GroupLens gives you a few choices for how you would like
10789 to see your predictions displayed. The display of predictions is
10790 controlled by the @code{grouplens-prediction-display} variable.
10792 The following are legal values for that variable.
10795 @item prediction-spot
10796 The higher the prediction, the further to the right an @samp{*} is
10799 @item confidence-interval
10800 A numeric confidence interval.
10802 @item prediction-bar
10803 The higher the prediction, the longer the bar.
10805 @item confidence-bar
10806 Numerical confidence.
10808 @item confidence-spot
10809 The spot gets bigger with more confidence.
10811 @item prediction-num
10812 Plain-old numeric value.
10814 @item confidence-plus-minus
10815 Prediction +/i confidence.
10820 @node GroupLens Variables
10821 @subsection GroupLens Variables
10825 @item gnus-summary-grouplens-line-format
10826 The summary line format used in summary buffers that are GroupLens
10827 enhanced. It accepts the same specs as the normal summary line format
10828 (@pxref{ Summary Buffer Lines}). The default is
10829 @samp{%U%R%z%l%I%(%[%4L: %-20,20n%]%) %s\n}.
10831 @item grouplens-bbb-host
10832 Host running the bbbd server. The default is
10833 @samp{grouplens.cs.umn.edu}.
10835 @item grouplens-bbb-port
10836 Port of the host running the bbbd server. The default is 9000.
10838 @item grouplens-score-offset
10839 Offset the prediction by this value. In other words, subtract the
10840 prediction value by this number to arrive at the effective score. The
10843 @item grouplens-score-scale-factor
10844 This variable allows the user to magnify the effect of GroupLens scores.
10845 The scale factor is applied after the offset. The default is 1.
10855 * Process/Prefix:: A convention used by many treatment commands.
10856 * Interactive:: Making Gnus ask you many questions.
10857 * Formatting Variables:: You can specify what buffers should look like.
10858 * Windows Configuration:: Configuring the Gnus buffer windows.
10859 * Compilation:: How to speed Gnus up.
10860 * Mode Lines:: Displaying information in the mode lines.
10861 * Highlighting and Menus:: Making buffers look all nice and cozy.
10862 * Buttons:: Get tendonitis in ten easy steps!
10863 * Daemons:: Gnus can do things behind your back.
10864 * NoCeM:: How to avoid spam and other fatty foods.
10865 * Picons:: How to display pictures of what your reading.
10866 * Various Various:: Things that are really various.
10870 @node Process/Prefix
10871 @section Process/Prefix
10872 @cindex process/prefix convention
10874 Many functions, among them functions for moving, decoding and saving
10875 articles, use what is known as the @dfn{Process/Prefix convention}.
10877 This is a method for figuring out what articles that the user wants the
10878 command to be performed on.
10882 If the numeric prefix is N, perform the operation on the next N
10883 articles, starting with the current one. If the numeric prefix is
10884 negative, perform the operation on the previous N articles, starting
10885 with the current one.
10887 @vindex transient-mark-mode
10888 If @code{transient-mark-mode} in non-@code{nil} and the region is
10889 active, all articles in the region will be worked upon.
10891 If there is no numeric prefix, but some articles are marked with the
10892 process mark, perform the operation on the articles that are marked with
10895 If there is neither a numeric prefix nor any articles marked with the
10896 process mark, just perform the operation on the current article.
10898 Quite simple, really, but it needs to be made clear so that surprises
10901 @vindex gnus-summary-goto-unread
10902 One thing that seems to shock & horrify lots of people is that, for
10903 instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}.
10904 Since each @kbd{d} (which marks the current article as read) by default
10905 goes to the next unread article after marking, this means that @kbd{3 d}
10906 will mark the next three unread articles as read, no matter what the
10907 summary buffer looks like. Set @code{gnus-summary-goto-unread} to
10908 @code{nil} for a more straightforward action.
10912 @section Interactive
10913 @cindex interaction
10917 @item gnus-novice-user
10918 @vindex gnus-novice-user
10919 If this variable is non-@code{nil}, you are either a newcomer to the
10920 World of Usenet, or you are very cautious, which is a nice thing to be,
10921 really. You will be given questions of the type ``Are you sure you want
10922 to do this?'' before doing anything dangerous. This is @code{t} by
10925 @item gnus-expert-user
10926 @vindex gnus-expert-user
10927 If this variable is non-@code{nil}, you will never ever be asked any
10928 questions by Gnus. It will simply assume you know what you're doing, no
10929 matter how strange.
10931 @item gnus-interactive-catchup
10932 @vindex gnus-interactive-catchup
10933 Require confirmation before catching up a group if non-@code{nil}. It
10934 is @code{t} by default.
10936 @item gnus-interactive-post
10937 @vindex gnus-interactive-post
10938 If non-@code{nil}, the user will be prompted for a group name when
10939 posting an article. It is @code{t} by default.
10941 @item gnus-interactive-exit
10942 @vindex gnus-interactive-exit
10943 Require confirmation before exiting Gnus. This variable is @code{t} by
10948 @node Formatting Variables
10949 @section Formatting Variables
10950 @cindex formatting variables
10952 Throughout this manual you've probably noticed lots of variables that
10953 are called things like @code{gnus-group-line-format} and
10954 @code{gnus-summary-mode-line-format}. These control how Gnus is to
10955 output lines in the various buffers. There's quite a lot of them.
10956 Fortunately, they all use the same syntax, so there's not that much to
10959 Here's an example format spec (from the group buffer): @samp{%M%S%5y:
10960 %(%g%)\n}. We see that it is indeed extremely ugly, and that there are
10961 lots of percentages everywhere.
10963 Each @samp{%} element will be replaced by some string or other when the
10964 buffer in question is generated. @samp{%5y} means ``insert the @samp{y}
10965 spec, and pad with spaces to get a 5-character field''. Just like a
10966 normal format spec, almost.
10968 You can also say @samp{%6,4y}, which means that the field will never be
10969 more than 6 characters wide and never less than 4 characters wide.
10971 There are also specs for highlighting, and these are shared by all the
10972 format variables. Text inside the @samp{%(} and @samp{%)} specifiers
10973 will get the special @code{mouse-face} property set, which means that it
10974 will be highlighted (with @code{gnus-mouse-face}) when you put the mouse
10977 Text inside the @samp{%[} and @samp{%]} specifiers will have their
10978 normal faces set using @code{gnus-face-0}, which is @code{bold} by
10979 default. If you say @samp{%1[} instead, you'll get @code{gnus-face-1}
10980 instead, and so on. Create as many faces as you wish. The same goes
10981 for the @code{mouse-face} specs---you can say @samp{%3(hello%)} to have
10982 @samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
10984 Here's an alternative recipe for the group buffer:
10987 ;; Create three face types.
10988 (setq gnus-face-1 'bold)
10989 (setq gnus-face-3 'italic)
10991 ;; We want the article count to be in
10992 ;; a bold and green face. So we create
10993 ;; a new face called `my-green-bold'.
10994 (copy-face 'bold 'my-green-bold)
10996 (set-face-foreground 'my-green-bold "ForestGreen")
10997 (setq gnus-face-2 'my-green-bold)
10999 ;; Set the new & fancy format.
11000 (setq gnus-group-line-format
11001 "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
11004 I'm sure you'll be able to use this scheme to create totally unreadable
11005 and extremely vulgar displays. Have fun!
11007 Currently Gnus uses the following formatting variables:
11008 @code{gnus-group-line-format}, @code{gnus-summary-line-format},
11009 @code{gnus-server-line-format}, @code{gnus-topic-line-format},
11010 @code{gnus-group-mode-line-format},
11011 @code{gnus-summary-mode-line-format},
11012 @code{gnus-article-mode-line-format},
11013 @code{gnus-server-mode-line-format}.
11015 Note that the @samp{%(} specs (and friends) do not make any sense on the
11016 mode-line variables.
11018 All these format variables can also be arbitrary elisp forms. In that
11019 case, they will be @code{eval}ed to insert the required lines.
11021 @kindex M-x gnus-update-format
11022 @findex gnus-update-format
11023 Gnus includes a command to help you while creating your own format
11024 specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
11025 update the spec in question and pop you to a buffer where you can
11026 examine the resulting lisp code to be run to generate the line.
11029 @node Windows Configuration
11030 @section Windows Configuration
11031 @cindex windows configuration
11033 No, there's nothing here about X, so be quiet.
11035 @vindex gnus-use-full-window
11036 If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all
11037 other windows and occupy the entire Emacs screen by itself. It is
11038 @code{t} by default.
11040 @vindex gnus-buffer-configuration
11041 @code{gnus-buffer-configuration} describes how much space each Gnus
11042 buffer should be given. Here's an excerpt of this variable:
11045 ((group (vertical 1.0 (group 1.0 point)
11046 (if gnus-carpal (group-carpal 4))))
11047 (article (vertical 1.0 (summary 0.25 point)
11051 This is an alist. The @dfn{key} is a symbol that names some action or
11052 other. For instance, when displaying the group buffer, the window
11053 configuration function will use @code{group} as the key. A full list of
11054 possible names is listed below.
11056 The @dfn{value} (i. e., the @dfn{split}) says how much space each buffer
11057 should occupy. To take the @code{article} split as an example -
11060 (article (vertical 1.0 (summary 0.25 point)
11064 This @dfn{split} says that the summary buffer should occupy 25% of upper
11065 half of the screen, and that it is placed over the article buffer. As
11066 you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all
11067 reaching for that calculator there). However, the special number
11068 @code{1.0} is used to signal that this buffer should soak up all the
11069 rest of the space available after the rest of the buffers have taken
11070 whatever they need. There should be only one buffer with the @code{1.0}
11071 size spec per split.
11073 Point will be put in the buffer that has the optional third element
11076 Here's a more complicated example:
11079 (article (vertical 1.0 (group 4)
11080 (summary 0.25 point)
11081 (if gnus-carpal (summary-carpal 4))
11085 If the size spec is an integer instead of a floating point number,
11086 then that number will be used to say how many lines a buffer should
11087 occupy, not a percentage.
11089 If the @dfn{split} looks like something that can be @code{eval}ed (to be
11090 precise---if the @code{car} of the split is a function or a subr), this
11091 split will be @code{eval}ed. If the result is non-@code{nil}, it will
11092 be used as a split. This means that there will be three buffers if
11093 @code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal}
11096 Not complicated enough for you? Well, try this on for size:
11099 (article (horizontal 1.0
11104 (summary 0.25 point)
11109 Whoops. Two buffers with the mystery 100% tag. And what's that
11110 @code{horizontal} thingie?
11112 If the first element in one of the split is @code{horizontal}, Gnus will
11113 split the window horizontally, giving you two windows side-by-side.
11114 Inside each of these strips you may carry on all you like in the normal
11115 fashion. The number following @code{horizontal} says what percentage of
11116 the screen is to be given to this strip.
11118 For each split, there @emph{must} be one element that has the 100% tag.
11119 The splitting is never accurate, and this buffer will eat any leftover
11120 lines from the splits.
11122 To be slightly more formal, here's a definition of what a legal split
11126 split = frame | horizontal | vertical | buffer | form
11127 frame = "(frame " size *split ")"
11128 horizontal = "(horizontal " size *split ")"
11129 vertical = "(vertical " size *split ")"
11130 buffer = "(" buffer-name " " size *[ "point" ] ")"
11131 size = number | frame-params
11132 buffer-name = group | article | summary ...
11135 The limitations are that the @code{frame} split can only appear as the
11136 top-level split. @var{form} should be an Emacs Lisp form that should
11137 return a valid split. We see that each split is fully recursive, and
11138 may contain any number of @code{vertical} and @code{horizontal} splits.
11140 @vindex gnus-window-min-width
11141 @vindex gnus-window-min-height
11142 @cindex window height
11143 @cindex window width
11144 Finding the right sizes can be a bit complicated. No window may be less
11145 than @code{gnus-window-min-height} (default 2) characters high, and all
11146 windows must be at least @code{gnus-window-min-width} (default 1)
11147 characters wide. Gnus will try to enforce this before applying the
11148 splits. If you want to use the normal Emacs window width/height limit,
11149 you can just set these two variables to @code{nil}.
11151 If you're not familiar with Emacs terminology, @code{horizontal} and
11152 @code{vertical} splits may work the opposite way of what you'd expect.
11153 Windows inside a @code{horizontal} split are shown side-by-side, and
11154 windows within a @code{vertical} split are shown above each other.
11156 @findex gnus-configure-frame
11157 If you want to experiment with window placement, a good tip is to call
11158 @code{gnus-configure-frame} directly with a split. This is the function
11159 that does all the real work when splitting buffers. Below is a pretty
11160 nonsensical configuration with 5 windows; two for the group buffer and
11161 three for the article buffer. (I said it was nonsensical.) If you
11162 @code{eval} the statement below, you can get an idea of how that would
11163 look straight away, without going through the normal Gnus channels.
11164 Play with it until you're satisfied, and then use
11165 @code{gnus-add-configuration} to add your new creation to the buffer
11166 configuration list.
11169 (gnus-configure-frame
11173 (article 0.3 point))
11181 You might want to have several frames as well. No prob---just use the
11182 @code{frame} split:
11185 (gnus-configure-frame
11188 (summary 0.25 point)
11190 (vertical ((height . 5) (width . 15)
11191 (user-position . t)
11192 (left . -1) (top . 1))
11197 This split will result in the familiar summary/article window
11198 configuration in the first (or ``main'') frame, while a small additional
11199 frame will be created where picons will be shown. As you can see,
11200 instead of the normal @code{1.0} top-level spec, each additional split
11201 should have a frame parameter alist as the size spec.
11202 @xref{(elisp)Frame Parameters}.
11204 Here's a list of all possible keys for
11205 @code{gnus-buffer-configuration}:
11207 @code{group}, @code{summary}, @code{article}, @code{server},
11208 @code{browse}, @code{group-mail}, @code{summary-mail},
11209 @code{summary-reply}, @code{info}, @code{summary-faq},
11210 @code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
11211 @code{followup}, @code{followup-yank}, @code{edit-score}.
11213 @findex gnus-add-configuration
11214 Since the @code{gnus-buffer-configuration} variable is so long and
11215 complicated, there's a function you can use to ease changing the config
11216 of a single setting: @code{gnus-add-configuration}. If, for instance,
11217 you want to change the @code{article} setting, you could say:
11220 (gnus-add-configuration
11221 '(article (vertical 1.0
11223 (summary .25 point)
11227 You'd typically stick these @code{gnus-add-configuration} calls in your
11228 @file{.gnus} file or in some startup hook -- they should be run after
11229 Gnus has been loaded.
11233 @section Compilation
11234 @cindex compilation
11235 @cindex byte-compilation
11237 @findex gnus-compile
11239 Remember all those line format specification variables?
11240 @code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
11241 on. Now, Gnus will of course heed whatever these variables are, but,
11242 unfortunately, changing them will mean a quite significant slow-down.
11243 (The default values of these variables have byte-compiled functions
11244 associated with them, while the user-generated versions do not, of
11247 To help with this, you can run @kbd{M-x gnus-compile} after you've
11248 fiddled around with the variables and feel that you're (kind of)
11249 satisfied. This will result in the new specs being byte-compiled, and
11250 you'll get top speed again.
11254 @section Mode Lines
11257 @vindex gnus-updated-mode-lines
11258 @code{gnus-updated-mode-lines} says what buffers should keep their mode
11259 lines updated. It is a list of symbols. Supported symbols include
11260 @code{group}, @code{article}, @code{summary}, @code{server},
11261 @code{browse}, and @code{tree}. If the corresponding symbol is present,
11262 Gnus will keep that mode line updated with information that may be
11263 pertinent. If this variable is @code{nil}, screen refresh may be
11266 @cindex display-time
11268 @vindex gnus-mode-non-string-length
11269 By default, Gnus displays information on the current article in the mode
11270 lines of the summary and article buffers. The information Gnus wishes
11271 to display (eg. the subject of the article) is often longer than the
11272 mode lines, and therefore have to be cut off at some point. The
11273 @code{gnus-mode-non-string-length} variable says how long the other
11274 elements on the line is (i.e., the non-info part). If you put
11275 additional elements on the mode line (eg. a clock), you should modify
11278 @c Hook written by Francesco Potorti` <pot@cnuce.cnr.it>
11280 (add-hook 'display-time-hook
11281 (lambda () (setq gnus-mode-non-string-length
11283 (if line-number-mode 5 0)
11284 (if column-number-mode 4 0)
11285 (length display-time-string)))))
11288 If this variable is @code{nil} (which is the default), the mode line
11289 strings won't be chopped off, and they won't be padded either.
11292 @node Highlighting and Menus
11293 @section Highlighting and Menus
11295 @cindex highlighting
11298 @vindex gnus-visual
11299 The @code{gnus-visual} variable controls most of the prettifying Gnus
11300 aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy
11301 colors or fonts. This will also inhibit loading the @file{gnus-vis.el}
11304 This variable can be a list of visual properties that are enabled. The
11305 following elements are legal, and are all included by default:
11308 @item group-highlight
11309 Do highlights in the group buffer.
11310 @item summary-highlight
11311 Do highlights in the summary buffer.
11312 @item article-highlight
11313 Do highlights in the article buffer.
11315 Turn on highlighting in all buffers.
11317 Create menus in the group buffer.
11319 Create menus in the summary buffers.
11321 Create menus in the article buffer.
11323 Create menus in the browse buffer.
11325 Create menus in the server buffer.
11327 Create menus in the score buffers.
11329 Create menus in all buffers.
11332 So if you only want highlighting in the article buffer and menus in all
11333 buffers, you could say something like:
11336 (setq gnus-visual '(article-highlight menu))
11339 If you want only highlighting and no menus whatsoever, you'd say:
11342 (setq gnus-visual '(highlight))
11345 If @code{gnus-visual} is @code{t}, highlighting and menus will be used
11346 in all Gnus buffers.
11348 Other general variables that influence the look of all buffers include:
11351 @item gnus-mouse-face
11352 @vindex gnus-mouse-face
11353 This is the face (i.e., font) used for mouse highlighting in Gnus. No
11354 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
11356 @item gnus-display-type
11357 @vindex gnus-display-type
11358 This variable is symbol indicating the display type Emacs is running
11359 under. The symbol should be one of @code{color}, @code{grayscale} or
11360 @code{mono}. If Gnus guesses this display attribute wrongly, either set
11361 this variable in your @file{~/.emacs} or set the resource
11362 @code{Emacs.displayType} in your @file{~/.Xdefaults}.
11364 @item gnus-background-mode
11365 @vindex gnus-background-mode
11366 This is a symbol indicating the Emacs background brightness. The symbol
11367 should be one of @code{light} or @code{dark}. If Gnus guesses this
11368 frame attribute wrongly, either set this variable in your @file{~/.emacs} or
11369 set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
11370 `gnus-display-type'.
11373 There are hooks associated with the creation of all the different menus:
11377 @item gnus-article-menu-hook
11378 @vindex gnus-article-menu-hook
11379 Hook called after creating the article mode menu.
11381 @item gnus-group-menu-hook
11382 @vindex gnus-group-menu-hook
11383 Hook called after creating the group mode menu.
11385 @item gnus-summary-menu-hook
11386 @vindex gnus-summary-menu-hook
11387 Hook called after creating the summary mode menu.
11389 @item gnus-server-menu-hook
11390 @vindex gnus-server-menu-hook
11391 Hook called after creating the server mode menu.
11393 @item gnus-browse-menu-hook
11394 @vindex gnus-browse-menu-hook
11395 Hook called after creating the browse mode menu.
11397 @item gnus-score-menu-hook
11398 @vindex gnus-score-menu-hook
11399 Hook called after creating the score mode menu.
11410 Those new-fangled @dfn{mouse} contraptions is very popular with the
11411 young, hep kids who don't want to learn the proper way to do things
11412 these days. Why, I remember way back in the summer of '89, when I was
11413 using Emacs on a Tops 20 system. Three hundred users on one single
11414 machine, and every user was running Simula compilers. Bah!
11418 @vindex gnus-carpal
11419 Well, you can make Gnus display bufferfuls of buttons you can click to
11420 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
11421 really. Tell the chiropractor I sent you.
11426 @item gnus-carpal-mode-hook
11427 @vindex gnus-carpal-mode-hook
11428 Hook run in all carpal mode buffers.
11430 @item gnus-carpal-button-face
11431 @vindex gnus-carpal-button-face
11432 Face used on buttons.
11434 @item gnus-carpal-header-face
11435 @vindex gnus-carpal-header-face
11436 Face used on carpal buffer headers.
11438 @item gnus-carpal-group-buffer-buttons
11439 @vindex gnus-carpal-group-buffer-buttons
11440 Buttons in the group buffer.
11442 @item gnus-carpal-summary-buffer-buttons
11443 @vindex gnus-carpal-summary-buffer-buttons
11444 Buttons in the summary buffer.
11446 @item gnus-carpal-server-buffer-buttons
11447 @vindex gnus-carpal-server-buffer-buttons
11448 Buttons in the server buffer.
11450 @item gnus-carpal-browse-buffer-buttons
11451 @vindex gnus-carpal-browse-buffer-buttons
11452 Buttons in the browse buffer.
11455 All the @code{buttons} variables are lists. The elements in these list
11456 is either a cons cell where the car contains a text to be displayed and
11457 the cdr contains a function symbol, or a simple string.
11465 Gnus, being larger than any program ever written (allegedly), does lots
11466 of strange stuff that you may wish to have done while you're not
11467 present. For instance, you may want it to check for new mail once in a
11468 while. Or you may want it to close down all connections to all servers
11469 when you leave Emacs idle. And stuff like that.
11471 Gnus will let you do stuff like that by defining various
11472 @dfn{handlers}. Each handler consists of three elements: A
11473 @var{function}, a @var{time}, and an @var{idle} parameter.
11475 Here's an example of a handler that closes connections when Emacs has
11476 been idle for thirty minutes:
11479 (gnus-demon-close-connections nil 30)
11482 Here's a handler that scans for PGP headers every hour when Emacs is
11486 (gnus-demon-scan-pgp 60 t)
11489 This @var{time} parameter and than @var{idle} parameter works together
11490 in a strange, but wonderful fashion. Basically, if @var{idle} is
11491 @code{nil}, then the function will be called every @var{time} minutes.
11493 If @var{idle} is @code{t}, then the function will be called after
11494 @var{time} minutes only if Emacs is idle. So if Emacs is never idle,
11495 the function will never be called. But once Emacs goes idle, the
11496 function will be called every @var{time} minutes.
11498 If @var{idle} is a number and @var{time} is a number, the function will
11499 be called every @var{time} minutes only when Emacs has been idle for
11500 @var{idle} minutes.
11502 If @var{idle} is a number and @var{time} is @code{nil}, the function
11503 will be called once every time Emacs has been idle for @var{idle}
11506 And if @var{time} is a string, it should look like @samp{07:31}, and
11507 the function will then be called once every day somewhere near that
11508 time. Modified by the @var{idle} parameter, of course.
11510 @vindex gnus-demon-timestep
11511 (When I say ``minute'' here, I really mean @code{gnus-demon-timestep}
11512 seconds. This is @code{60} by default. If you change that variable,
11513 all the timings in the handlers will be affected.)
11515 @vindex gnus-use-demon
11516 To set the whole thing in motion, though, you have to set
11517 @code{gnus-use-demon} to @code{t}.
11519 So, if you want to add a handler, you could put something like this in
11520 your @file{.gnus} file:
11522 @findex gnus-demon-add-handler
11524 (gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
11527 @findex gnus-demon-add-nocem
11528 @findex gnus-demon-add-scanmail
11529 @findex gnus-demon-add-disconnection
11530 Some ready-made functions to do this has been created:
11531 @code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, and
11532 @code{gnus-demon-add-scanmail}. Just put those functions in your
11533 @file{.gnus} if you want those abilities.
11535 @findex gnus-demon-init
11536 @findex gnus-demon-cancel
11537 @vindex gnus-demon-handlers
11538 If you add handlers to @code{gnus-demon-handlers} directly, you should
11539 run @code{gnus-demon-init} to make the changes take hold. To cancel all
11540 daemons, you can use the @code{gnus-demon-cancel} function.
11542 Note that adding daemons can be pretty naughty if you overdo it. Adding
11543 functions that scan all news and mail from all servers every two seconds
11544 is a sure-fire way of getting booted off any respectable system. So
11553 @dfn{Spamming} is posting the same article lots and lots of times.
11554 Spamming is bad. Spamming is evil.
11556 Spamming is usually canceled within a day or so by various anti-spamming
11557 agencies. These agencies usually also send out @dfn{NoCeM} messages.
11558 NoCeM is pronounced ``no see-'em'', and means what the name
11559 implies---these are messages that make the offending articles, like, go
11562 What use are these NoCeM messages if the articles are canceled anyway?
11563 Some sites do not honor cancel messages and some sites just honor cancels
11564 from a select few people. Then you may wish to make use of the NoCeM
11565 messages, which are distributed in the @samp{alt.nocem.misc} newsgroup.
11567 Gnus can read and parse the messages in this group automatically, and
11568 this will make spam disappear.
11570 There are some variables to customize, of course:
11573 @item gnus-use-nocem
11574 @vindex gnus-use-nocem
11575 Set this variable to @code{t} to set the ball rolling. It is @code{nil}
11578 @item gnus-nocem-groups
11579 @vindex gnus-nocem-groups
11580 Gnus will look for NoCeM messages in the groups in this list. The
11581 default is @code{("alt.nocem.misc" "news.admin.net-abuse.announce")}.
11583 @item gnus-nocem-issuers
11584 @vindex gnus-nocem-issuers
11585 There are many people issuing NoCeM messages. This list says what
11586 people you want to listen to. The default is @code{("Automoose-1"
11587 "clewis@@ferret.ocunix.on.ca;" "jem@@xpat.com;" "red@@redpoll.mrfs.oh.us
11588 (Richard E. Depew)")}; fine, upstanding citizens all of them.
11590 Known despammers that you can put in this list include:
11593 @item clewis@@ferret.ocunix.on.ca;
11594 @cindex Chris Lewis
11595 Chris Lewis---Major Canadian despammer who has probably canceled more
11596 usenet abuse than anybody else.
11599 @cindex CancelMoose[tm]
11600 The CancelMoose[tm] on autopilot. The CancelMoose[tm] is reputed to be
11601 Norwegian, and was the person(s) who invented NoCeM.
11603 @item jem@@xpat.com;
11605 Jem---Korean despammer who is getting very busy these days.
11607 @item red@@redpoll.mrfs.oh.us (Richard E. Depew)
11608 Richard E. Depew---lone American despammer. He mostly cancels binary
11609 postings to non-binary groups and removes spews (regurgitated articles).
11612 You do not have to heed NoCeM messages from all these people---just the
11613 ones you want to listen to.
11615 @item gnus-nocem-directory
11616 @vindex gnus-nocem-directory
11617 This is where Gnus will store its NoCeM cache files. The default is
11618 @file{~/News/NoCeM/}.
11620 @item gnus-nocem-expiry-wait
11621 @vindex gnus-nocem-expiry-wait
11622 The number of days before removing old NoCeM entries from the cache.
11623 The default is 15. If you make it shorter Gnus will be faster, but you
11624 might then see old spam.
11632 So... You want to slow down your news reader even more! This is a
11633 good way to do so. Its also a great way to impress people staring
11634 over your shoulder as you read news.
11637 * Picon Basics:: What are picons and How do I get them.
11638 * Picon Requirements:: Don't go further if you aren't using XEmacs.
11639 * Easy Picons:: Displaying Picons -- the easy way.
11640 * Hard Picons:: The way you should do it. You'll learn something.
11641 * Picon Configuration:: Other variables you can trash/tweak/munge/play with.
11646 @subsection Picon Basics
11648 What are Picons? To quote directly from the Picons Web site
11649 (@samp{http://www.cs.indiana.edu/picons/ftp/index.html}):
11652 @dfn{Picons} is short for ``personal icons''. They're small,
11653 constrained images used to represent users and domains on the net,
11654 organized into databases so that the appropriate image for a given
11655 e-mail address can be found. Besides users and domains, there are picon
11656 databases for Usenet newsgroups and weather forecasts. The picons are
11657 in either monochrome @code{XBM} format or color @code{XPM} and
11658 @code{GIF} formats.
11661 Please see the above mentioned web site for instructions on obtaining
11662 and installing the picons databases, or the following ftp site:
11663 @samp{http://www.cs.indiana.edu/picons/ftp/index.html}.
11665 @vindex gnus-picons-database
11666 Gnus expects picons to be installed into a location pointed to by
11667 @code{gnus-picons-database}.
11670 @node Picon Requirements
11671 @subsection Picon Requirements
11673 To use have Gnus display Picons for you, you must be running XEmacs
11674 19.13 or greater since all other versions of Emacs aren't yet able to
11677 Additionally, you must have @code{xpm} support compiled into XEmacs.
11679 @vindex gnus-picons-convert-x-face
11680 If you want to display faces from @code{X-Face} headers, you must have
11681 the @code{netpbm} utilities installed, or munge the
11682 @code{gnus-picons-convert-x-face} variable to use something else.
11686 @subsection Easy Picons
11688 To enable displaying picons, simply put the following line in your
11689 @file{~/.gnus} file and start Gnus.
11692 (setq gnus-use-picons t)
11693 (add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
11694 (add-hook 'gnus-summary-prepare-hook 'gnus-group-display-picons t)
11695 (add-hook 'gnus-article-display-hook 'gnus-picons-article-display-x-face)
11700 @subsection Hard Picons
11702 Gnus can display picons for you as you enter and leave groups and
11703 articles. It knows how to interact with three sections of the picons
11704 database. Namely, it can display the picons newsgroup pictures,
11705 author's face picture(s), and the authors domain. To enable this
11706 feature, you need to first decide where to display them.
11710 @item gnus-picons-display-where
11711 @vindex gnus-picons-display-where
11712 Where the picon images should be displayed. It is @code{picons} by
11713 default (which by default maps to the buffer @samp{*Picons*}). Other
11714 valid places could be @code{article}, @code{summary}, or
11715 @samp{"*scratch*"} for all I care. Just make sure that you've made the
11716 buffer visible using the standard Gnus window configuration routines --
11717 @xref{Windows Configuration}.
11721 Note: If you set @code{gnus-use-picons} to @code{t}, it will set up your
11722 window configuration for you to include the @code{picons} buffer.
11724 Now that you've made that decision, you need to add the following
11725 functions to the appropriate hooks so these pictures will get
11726 displayed at the right time.
11728 @vindex gnus-article-display-hook
11729 @vindex gnus-picons-display-where
11731 @item gnus-article-display-picons
11732 @findex gnus-article-display-picons
11733 Looks up and display the picons for the author and the author's domain
11734 in the @code{gnus-picons-display-where} buffer. Should be added to
11735 the @code{gnus-article-display-hook}.
11737 @item gnus-group-display-picons
11738 @findex gnus-article-display-picons
11739 Displays picons representing the current group. This function should
11740 be added to the @code{gnus-summary-prepare-hook} or to the
11741 @code{gnus-article-display-hook} if @code{gnus-picons-display-where}
11742 is set to @code{article}.
11744 @item gnus-picons-article-display-x-face
11745 @findex gnus-article-display-picons
11746 Decodes and displays the X-Face header if present. This function
11747 should be added to @code{gnus-article-display-hook}.
11751 Note: You must append them to the hook, so make sure to specify 't'
11752 to the append flag of @code{add-hook}:
11755 (add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
11759 @node Picon Configuration
11760 @subsection Picon Configuration
11762 The following variables offer further control over how things are
11763 done, where things are located, and other useless stuff you really
11764 don't need to worry about.
11767 @item gnus-picons-database
11768 @vindex gnus-picons-database
11769 The location of the picons database. Should point to a directory
11770 containing the @file{news}, @file{domains}, @file{users} (and so on)
11771 subdirectories. Defaults to @file{/usr/local/faces}.
11773 @item gnus-picons-news-directory
11774 @vindex gnus-picons-news-directory
11775 Sub-directory of the faces database containing the icons for
11778 @item gnus-picons-user-directories
11779 @vindex gnus-picons-user-directories
11780 List of subdirectories to search in @code{gnus-picons-database} for user
11781 faces. Defaults to @code{("local" "users" "usenix" "misc/MISC")}.
11783 @item gnus-picons-domain-directories
11784 @vindex gnus-picons-domain-directories
11785 List of subdirectories to search in @code{gnus-picons-database} for
11786 domain name faces. Defaults to @code{("domains")}. Some people may
11787 want to add @samp{unknown} to this list.
11789 @item gnus-picons-convert-x-face
11790 @vindex gnus-picons-convert-x-face
11791 The command to use to convert the @code{X-Face} header to an X bitmap
11792 (@code{xbm}). Defaults to @code{(format "@{ echo '/* Width=48,
11793 Height=48 */'; uncompface; @} | icontopbm | pbmtoxbm > %s"
11794 gnus-picons-x-face-file-name)}
11796 @item gnus-picons-x-face-file-name
11797 @vindex gnus-picons-x-face-file-name
11798 Names a temporary file to store the @code{X-Face} bitmap in. Defaults
11799 to @code{(format "/tmp/picon-xface.%s.xbm" (user-login-name))}.
11801 @item gnus-picons-buffer
11802 @vindex gnus-picons-buffer
11803 The name of the buffer that @code{picons} points to. Defaults to
11804 @samp{*Icon Buffer*}.
11809 @node Various Various
11810 @section Various Various
11817 @vindex gnus-verbose
11818 This variable is an integer between zero and ten. The higher the value,
11819 the more messages will be displayed. If this variable is zero, Gnus
11820 will never flash any messages, if it is seven (which is the default),
11821 most important messages will be shown, and if it is ten, Gnus won't ever
11822 shut up, but will flash so many messages it will make your head swim.
11824 @item gnus-verbose-backends
11825 @vindex gnus-verbose-backends
11826 This variable works the same way as @code{gnus-verbose}, but it applies
11827 to the Gnus backends instead of Gnus proper.
11829 @item nnheader-max-head-length
11830 @vindex nnheader-max-head-length
11831 When the backends read straight heads of articles, they all try to read
11832 as little as possible. This variable (default @code{4096}) specifies
11833 the absolute max length the backends will try to read before giving up
11834 on finding a separator line between the head and the body. If this
11835 variable is @code{nil}, there is no upper read bound. If it is
11836 @code{t}, the backends won't try to read the articles piece by piece,
11837 but read the entire articles. This makes sense with some versions of
11840 @item nnheader-file-name-translation-alist
11841 @vindex nnheader-file-name-translation-alist
11843 @cindex illegal characters in file names
11844 @cindex characters in file names
11845 This is an alist that says how to translate characters in file names.
11846 For instance, if @samp{:} is illegal as a file character in file names
11847 on your system (you OS/2 user you), you could say something like:
11850 (setq nnheader-file-name-translation-alist
11854 In fact, this is the default value for this variable on OS/2 and MS
11855 Windows (phooey) systems.
11857 @item gnus-hidden-properties
11858 @vindex gnus-hidden-properties
11859 This is a list of properties to use to hide ``invisible'' text. It is
11860 @code{(invisible t intangible t)} by default on most systems, which
11861 makes invisible text invisible and intangible.
11863 @item gnus-parse-header-hook
11864 @vindex gnus-parse-header-hook
11865 A hook called before parsing headers. It can be used, for instance, to
11866 gather statistics on the headers fetched, or perhaps you'd like to prune
11867 some headers. I don't see why you'd want that, though.
11875 Well, that's the manual---you can get on with your life now. Keep in
11876 touch. Say hello to your cats from me.
11878 My @strong{ghod}---I just can't stand goodbyes. Sniffle.
11880 Ol' Charles Reznikoff said it pretty well, so I leave the floor to him:
11885 Not because of victories @*
11888 but for the common sunshine,@*
11890 the largess of the spring.
11893 but for the day's work done@*
11894 as well as I was able;@*
11895 not for a seat upon the dais@*
11896 but at the common table.@*
11901 @chapter Appendices
11904 * History:: How Gnus got where it is today.
11905 * Terminology:: We use really difficult, like, words here.
11906 * Customization:: Tailoring Gnus to your needs.
11907 * Troubleshooting:: What you might try if things do not work.
11908 * A Programmers Guide to Gnus:: Rilly, rilly technical stuff.
11909 * Emacs for Heathens:: A short introduction to Emacsian terms.
11910 * Frequently Asked Questions:: A question-and-answer session.
11918 @sc{gnus} was written by Masanobu @sc{Umeda}. When autumn crept up in
11919 '94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
11921 If you want to investigate the person responsible for this outrage, you
11922 can point your (feh!) web browser to
11923 @file{http://www.ifi.uio.no/~larsi/}. This is also the primary
11924 distribution point for the new and spiffy versions of Gnus, and is known
11925 as The Site That Destroys Newsrcs And Drives People Mad.
11927 During the first extended alpha period of development, the new Gnus was
11928 called ``(ding) Gnus''. @dfn{(ding)}, is, of course, short for
11929 @dfn{ding is not Gnus}, which is a total and utter lie, but who cares?
11930 (Besides, the ``Gnus'' in this abbreviation should probably be
11931 pronounced ``news'' as @sc{Umeda} intended, which makes it a more
11932 appropriate name, don't you think?)
11934 In any case, after spending all that energy on coming up with a new and
11935 spunky name, we decided that the name was @emph{too} spunky, so we
11936 renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs.
11937 ``@sc{gnus}''. New vs. old.
11939 The first ``proper'' release of Gnus 5 was done in November 1995 when it
11940 was included in the Emacs 19.30 distribution.
11942 Incidentally, the next Gnus generation will be called ``September
11943 Gnus'', and won't be released until April 1996. Confused? You will be.
11946 * Why?:: What's the point of Gnus?
11947 * Compatibility:: Just how compatible is Gnus with @sc{gnus}?
11948 * Conformity:: Gnus tries to conform to all standards.
11949 * Emacsen:: Gnus can be run on a few modern Emacsen.
11950 * Contributors:: Oodles of people.
11951 * New Features:: Pointers to some of the new stuff in Gnus.
11952 * Newest Features:: Features so new that they haven't been written yet.
11953 * Censorship:: This manual has been censored.
11960 What's the point of Gnus?
11962 I want to provide a ``rad'', ``happening'', ``way cool'' and ``hep''
11963 newsreader, that lets you do anything you can think of. That was my
11964 original motivation, but while working on Gnus, it has become clear to
11965 me that this generation of newsreaders really belong in the stone age.
11966 Newsreaders haven't developed much since the infancy of the net. If the
11967 volume continues to rise with the current rate of increase, all current
11968 newsreaders will be pretty much useless. How do you deal with
11969 newsgroups that have thousands of new articles each day? How do you
11970 keep track of millions of people who post?
11972 Gnus offers no real solutions to these questions, but I would very much
11973 like to see Gnus being used as a testing ground for new methods of
11974 reading and fetching news. Expanding on @sc{Umeda}-san's wise decision
11975 to separate the newsreader from the backends, Gnus now offers a simple
11976 interface for anybody who wants to write new backends for fetching mail
11977 and news from different sources. I have added hooks for customizations
11978 everywhere I could imagine useful. By doing so, I'm inviting every one
11979 of you to explore and invent.
11981 May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
11984 @node Compatibility
11985 @subsection Compatibility
11987 @cindex compatibility
11988 Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
11989 bindings have been kept. More key bindings have been added, of course,
11990 but only in one or two obscure cases have old bindings been changed.
11995 @center In a cloud bones of steel.
11999 All commands have kept their names. Some internal functions have changed
12002 The @code{gnus-uu} package has changed drastically. @pxref{Decoding
12005 One major compatibility question is the presence of several summary
12006 buffers. All variables that are relevant while reading a group are
12007 buffer-local to the summary buffer they belong in. Although many
12008 important variables have their values copied into their global
12009 counterparts whenever a command is executed in the summary buffer, this
12010 change might lead to incorrect values being used unless you are careful.
12012 All code that relies on knowledge of @sc{gnus} internals will probably
12013 fail. To take two examples: Sorting @code{gnus-newsrc-alist} (or
12014 changing it in any way, as a matter of fact) is strictly verboten. Gnus
12015 maintains a hash table that points to the entries in this alist (which
12016 speeds up many functions), and changing the alist directly will lead to
12020 @cindex highlighting
12021 Old hilit19 code does not work at all. In fact, you should probably
12022 remove all hilit code from all Gnus hooks
12023 (@code{gnus-group-prepare-hook} and @code{gnus-summary-prepare-hook}).
12024 Gnus provides various integrated functions for highlighting. These are
12025 faster and more accurate. To make life easier for everybody, Gnus will
12026 by default remove all hilit calls from all hilit hooks. Uncleanliness!
12029 Packages like @code{expire-kill} will no longer work. As a matter of
12030 fact, you should probably remove all old @sc{gnus} packages (and other
12031 code) when you start using Gnus. More likely than not, Gnus already
12032 does what you have written code to make @sc{gnus} do. (Snicker.)
12034 Even though old methods of doing things are still supported, only the
12035 new methods are documented in this manual. If you detect a new method of
12036 doing something while reading this manual, that does not mean you have
12037 to stop doing it the old way.
12039 Gnus understands all @sc{gnus} startup files.
12041 @kindex M-x gnus-bug
12043 @cindex reporting bugs
12045 Overall, a casual user who hasn't written much code that depends on
12046 @sc{gnus} internals should suffer no problems. If problems occur,
12047 please let me know by issuing that magic command @kbd{M-x gnus-bug}.
12051 @subsection Conformity
12053 No rebels without a clue here, ma'am. We conform to all standards known
12054 to (wo)man. Except for those standards and/or conventions we disagree
12061 There are no known breaches of this standard.
12065 There are no known breaches of this standard, either.
12067 @item Usenet Seal of Approval
12068 @cindex Usenet Seal of Approval
12069 Gnus hasn't been formally through the Seal process, but I have read
12070 through the Seal text and I think Gnus would pass.
12072 @item Son-of-RFC 1036
12073 @cindex Son-of-RFC 1036
12074 We do have some breaches to this one.
12079 Gnus does no MIME handling, and this standard-to-be seems to think that
12080 MIME is the bees' knees, so we have major breakage here.
12083 This is considered to be a ``vanity header'', while I consider it to be
12084 consumer information. After seeing so many badly formatted articles
12085 coming from @code{tin} and @code{Netscape} I know not to use either of
12086 those for posting articles. I would not have known that if it wasn't
12087 for the @code{X-Newsreader} header.
12090 Gnus does line breaking on this header. I infer from RFC1036 that being
12091 conservative in what you output is not creating 5000-character lines, so
12092 it seems like a good idea to me. However, this standard-to-be says that
12093 whitespace in the @code{References} header is to be preserved, so... It
12094 doesn't matter one way or the other to Gnus, so if somebody tells me
12095 what The Way is, I'll change it. Or not.
12100 If you ever notice Gnus acting non-compliantly with regards to the texts
12101 mentioned above, don't hesitate to drop a note to Gnus Towers and let us
12106 @subsection Emacsen
12112 Gnus should work on :
12117 Emacs 19.30 and up.
12120 XEmacs 19.13 and up.
12123 Mule versions based on Emacs 19.30 and up.
12127 Gnus will absolutely not work on any Emacsen older than that. Not
12128 reliably, at least.
12130 There are some vague differences between Gnus on the various platforms:
12135 The mouse-face on Gnus lines under Emacs and Mule is delimited to
12136 certain parts of the lines while they cover the entire line under
12140 The same with current-article marking---XEmacs puts an underline under
12141 the entire summary line while Emacs and Mule are nicer and kinder.
12144 XEmacs features more graphics---a logo and a toolbar.
12147 Citation highlighting us better under Emacs and Mule than under XEmacs.
12150 Emacs 19.26-19.28 have tangible hidden headers, which can be a bit
12157 @subsection Contributors
12158 @cindex contributors
12160 The new Gnus version couldn't have been done without the help of all the
12161 people on the (ding) mailing list. Every day for over a year I have
12162 gotten billions of nice bug reports from them, filling me with joy,
12163 every single one of them. Smooches. The people on the list have been
12164 tried beyond endurance, what with my ``oh, that's a neat idea <type
12165 type>, yup, I'll release it right away <ship off> no wait, that doesn't
12166 work at all <type type>, yup, I'll ship that one off right away <ship
12167 off> no, wait, that absolutely does not work'' policy for releases.
12168 Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that
12169 ``worser''? ``much worser''? ``worsest''?)
12171 I would like to take this opportunity to thank the Academy for... oops,
12176 @item Masanobu @sc{Umeda}
12177 The writer of the original @sc{gnus}.
12179 @item Per Abrahamsen
12180 Custom, scoring, highlighting and @sc{soup} code (as well as numerous
12183 @item Luis Fernandes
12184 Design and graphics.
12187 @file{gnus-picon.el} and the manual section on @dfn{picons}
12191 @file{gnus-gl.el} and the GroupLens manual section (@pxref{GroupLens}).
12193 @item Sudish Joseph
12194 Innumerable bug fixes.
12197 @file{gnus-topic.el}.
12199 @item Steven L. Baur
12200 Lots and lots of bugs detections and fixes.
12202 @item Vladimir Alexiev
12203 The refcard and reference booklets.
12205 @item Felix Lee & JWZ
12206 I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
12209 @file{nnfolder.el} enhancements & rewrite.
12211 @item Peter Mutsaers
12212 Orphan article scoring code.
12217 @item Hallvard B Furuseth
12218 Various bits and pieces, especially dealing with .newsrc files.
12220 @item Brian Edmonds
12221 @file{gnus-bbdb.el}.
12223 @item Ricardo Nassif and Mark Borges
12226 @item Kevin Davidson
12227 Came up with the name @dfn{ding}, so blame him.
12231 Peter Arius, Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel
12232 Quinlan, Frank D. Cringle, Geoffrey T. Dairiki, Fabrice Popineau and
12233 Andrew Eskilsson have all contributed code and suggestions.
12237 @subsection New Features
12238 @cindex new features
12243 The look of all buffers can be changed by setting format-like variables
12244 (@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
12247 Local spool and several @sc{nntp} servers can be used at once
12248 (@pxref{Select Methods}).
12251 You can combine groups into virtual groups (@pxref{Virtual Groups}).
12254 You can read a number of different mail formats (@pxref{Getting Mail}).
12255 All the mail backends implement a convenient mail expiry scheme
12256 (@pxref{Expiring Mail}).
12259 Gnus can use various strategies for gathering threads that have lost
12260 their roots (thereby gathering loose sub-threads into one thread) or it
12261 can go back and retrieve enough headers to build a complete thread
12262 (@pxref{Customizing Threading}).
12265 Killed groups can be displayed in the group buffer, and you can read
12266 them as well (@pxref{Listing Groups}).
12269 Gnus can do partial group updates---you do not have to retrieve the
12270 entire active file just to check for new articles in a few groups
12271 (@pxref{The Active File}).
12274 Gnus implements a sliding scale of subscribedness to groups
12275 (@pxref{Group Levels}).
12278 You can score articles according to any number of criteria
12279 (@pxref{Scoring}). You can even get Gnus to find out how to score
12280 articles for you (@pxref{Adaptive Scoring}).
12283 Gnus maintains a dribble buffer that is auto-saved the normal Emacs
12284 manner, so it should be difficult to lose much data on what you have
12285 read if your machine should go down (@pxref{Auto Save}).
12288 Gnus now has its own startup file (@file{.gnus}) to avoid cluttering up
12289 the @file{.emacs} file.
12292 You can set the process mark on both groups and articles and perform
12293 operations on all the marked items (@pxref{Process/Prefix}).
12296 You can grep through a subset of groups and create a group from the
12297 results (@pxref{Kibozed Groups}).
12300 You can list subsets of groups according to, well, anything
12301 (@pxref{Listing Groups}).
12304 You can browse foreign servers and subscribe to groups from those
12305 servers (@pxref{Browse Foreign Server}).
12308 Gnus can fetch articles asynchronously on a second connection to the
12309 server (@pxref{Asynchronous Fetching}).
12312 You can cache articles locally (@pxref{Article Caching}).
12315 The uudecode functions have been expanded and generalized
12316 (@pxref{Decoding Articles}).
12319 You can still post uuencoded articles, which was a little-known feature
12320 of @sc{gnus}' past (@pxref{Uuencoding and Posting}).
12323 Fetching parents (and other articles) now actually works without
12324 glitches (@pxref{Finding the Parent}).
12327 Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
12330 Digests (and other files) can be used as the basis for groups
12331 (@pxref{Document Groups}).
12334 Articles can be highlighted and customized (@pxref{Customizing
12338 URLs and other external references can be buttonized (@pxref{Article
12342 You can do lots of strange stuff with the Gnus window & frame
12343 configuration (@pxref{Windows Configuration}).
12346 You can click on buttons instead of using the keyboard
12350 Gnus can use NoCeM files to weed out spam (@pxref{NoCeM}).
12354 This is, of course, just a @emph{short} overview of the @emph{most}
12355 important new features. No, really. There are tons more. Yes, we have
12356 feeping creaturism in full effect, but nothing too gratuitous, I would
12360 @node Newest Features
12361 @subsection Newest Features
12364 Also known as the @dfn{todo list}. Sure to be implemented before the
12367 Be afraid. Be very afraid.
12371 Native @sc{mime} support is something that should be done.
12373 A better and simpler method for specifying mail composing methods.
12375 Allow posting through mail-to-news gateways.
12377 Really do unbinhexing.
12380 And much, much, much more. There is more to come than has already been
12381 implemented. (But that's always true, isn't it?)
12383 @code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>} is where the actual
12384 up-to-the-second todo list is located, so if you're really curious, you
12385 could point your Web browser over that-a-way.
12389 @subsection Censorship
12392 This version of the Gnus manual (as well as Gnus itself) has been
12393 censored in accord with the Communications Decency Act. This law was
12394 described by its proponents as a ban on pornography---which was a
12395 deception, since it prohibits far more than that. This manual did not
12396 contain pornography, but part of it was prohibited nonetheless.
12398 For information on US government censorship of the Internet, and
12399 what you can do to bring back freedom of the press, see the web
12400 site @samp{http://www.vtw.org/}.
12404 @section Terminology
12406 @cindex terminology
12411 This is what you are supposed to use this thing for---reading news.
12412 News is generally fetched from a nearby @sc{nntp} server, and is
12413 generally publicly available to everybody. If you post news, the entire
12414 world is likely to read just what you have written, and they'll all
12415 snigger mischievously. Behind your back.
12419 Everything that's delivered to you personally is mail. Some news/mail
12420 readers (like Gnus) blur the distinction between mail and news, but
12421 there is a difference. Mail is private. News is public. Mailing is
12422 not posting, and replying is not following up.
12426 Send a mail to the person who has written what you are reading.
12430 Post an article to the current newsgroup responding to the article you
12435 Gnus gets fed articles from a number of backends, both news and mail
12436 backends. Gnus does not handle the underlying media, so to speak---this
12437 is all done by the backends.
12441 Gnus will always use one method (and backend) as the @dfn{native}, or
12442 default, way of getting news.
12446 You can also have any number of foreign groups active at the same time.
12447 These are groups that use different backends for getting news.
12451 Secondary backends are somewhere half-way between being native and being
12452 foreign, but they mostly act like they are native.
12456 A nessage that has been posted as news.
12459 @cindex mail message
12460 A message that has been mailed.
12464 A mail message or news article
12468 The top part of a message, where administrative information (etc.) is
12473 The rest of an article. Everything that is not in the head is in the
12478 A line from the head of an article.
12482 A collection of such lines, or a collection of heads. Or even a
12483 collection of @sc{nov} lines.
12487 When Gnus enters a group, it asks the backend for the headers of all
12488 unread articles in the group. Most servers support the News OverView
12489 format, which is more compact and much faster to read and parse than the
12490 normal @sc{head} format.
12494 Each group is subscribed at some @dfn{level} or other (1-9). The ones
12495 that have a lower level are ``more'' subscribed than the groups with a
12496 higher level. In fact, groups on levels 1-5 are considered
12497 @dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
12498 are @dfn{killed}. Commands for listing groups and scanning for new
12499 articles will all use the numeric prefix as @dfn{working level}.
12501 @item killed groups
12502 @cindex killed groups
12503 No information on killed groups is stored or updated, which makes killed
12504 groups much easier to handle than subscribed groups.
12506 @item zombie groups
12507 @cindex zombie groups
12508 Just like killed groups, only slightly less dead.
12511 @cindex active file
12512 The news server has to keep track of what articles it carries, and what
12513 groups exist. All this information in stored in the active file, which
12514 is rather large, as you might surmise.
12517 @cindex bogus groups
12518 A group that exists in the @file{.newsrc} file, but isn't known to the
12519 server (i. e., it isn't in the active file), is a @emph{bogus group}.
12520 This means that the group probably doesn't exist (any more).
12524 A machine than one can connect to and get news (or mail) from.
12526 @item select method
12527 @cindex select method
12528 A structure that specifies the backend, the server and the virtual
12531 @item virtual server
12532 @cindex virtual server
12533 A named select method. Since a select methods defines all there is to
12534 know about connecting to a (physical) server, taking the who things as a
12535 whole is a virtual server.
12540 @node Customization
12541 @section Customization
12542 @cindex general customization
12544 All variables are properly documented elsewhere in this manual. This
12545 section is designed to give general pointers on how to customize Gnus
12546 for some quite common situations.
12549 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
12550 * Slow Terminal Connection:: You run a remote Emacs.
12551 * Little Disk Space:: You feel that having large setup files is icky.
12552 * Slow Machine:: You feel like buying a faster machine.
12556 @node Slow/Expensive Connection
12557 @subsection Slow/Expensive @sc{nntp} Connection
12559 If you run Emacs on a machine locally, and get your news from a machine
12560 over some very thin strings, you want to cut down on the amount of data
12561 Gnus has to get from the @sc{nntp} server.
12565 @item gnus-read-active-file
12566 Set this to @code{nil}, which will inhibit Gnus from requesting the
12567 entire active file from the server. This file is often v. large. You
12568 also have to set @code{gnus-check-new-news} and
12569 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
12570 doesn't suddenly decide to fetch the active file anyway.
12572 @item gnus-nov-is-evil
12573 This one has to be @code{nil}. If not, grabbing article headers from
12574 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
12575 support @sc{xover}; Gnus will detect this by itself.
12579 @node Slow Terminal Connection
12580 @subsection Slow Terminal Connection
12582 Let's say you use your home computer for dialing up the system that
12583 runs Emacs and Gnus. If your modem is slow, you want to reduce the
12584 amount of data that is sent over the wires as much as possible.
12588 @item gnus-auto-center-summary
12589 Set this to @code{nil} to inhibit Gnus from re-centering the summary
12590 buffer all the time. If it is @code{vertical}, do only vertical
12591 re-centering. If it is neither @code{nil} nor @code{vertical}, do both
12592 horizontal and vertical recentering.
12594 @item gnus-visible-headers
12595 Cut down on the headers that are included in the articles to the
12596 minimum. You can, in fact, make do without them altogether---most of the
12597 useful data is in the summary buffer, anyway. Set this variable to
12598 @samp{^NEVVVVER} or @samp{From:}, or whatever you feel you need.
12600 @item gnus-article-display-hook
12601 Set this hook to all the available hiding commands:
12603 (setq gnus-article-display-hook
12604 '(gnus-article-hide-headers gnus-article-hide-signature
12605 gnus-article-hide-citation))
12608 @item gnus-use-full-window
12609 By setting this to @code{nil}, you can make all the windows smaller.
12610 While this doesn't really cut down much generally, it means that you
12611 have to see smaller portions of articles before deciding that you didn't
12612 want to read them anyway.
12614 @item gnus-thread-hide-subtree
12615 If this is non-@code{nil}, all threads in the summary buffer will be
12618 @item gnus-updated-mode-lines
12619 If this is @code{nil}, Gnus will not put information in the buffer mode
12620 lines, which might save some time.
12624 @node Little Disk Space
12625 @subsection Little Disk Space
12628 The startup files can get rather large, so you may want to cut their
12629 sizes a bit if you are running out of space.
12633 @item gnus-save-newsrc-file
12634 If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
12635 only save @file{.newsrc.eld}. This means that you will not be able to
12636 use any other newsreaders than Gnus. This variable is @code{t} by
12639 @item gnus-save-killed-list
12640 If this is @code{nil}, Gnus will not save the list of dead groups. You
12641 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
12642 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
12643 variable to @code{nil}. This variable is @code{t} by default.
12649 @subsection Slow Machine
12650 @cindex slow machine
12652 If you have a slow machine, or are just really impatient, there are a
12653 few things you can do to make Gnus run faster.
12655 Set@code{gnus-check-new-newsgroups} and
12656 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
12658 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
12659 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
12660 summary buffer faster.
12662 Set @code{gnus-article-display-hook} to @code{nil} to make article
12663 processing a bit faster.
12666 @node Troubleshooting
12667 @section Troubleshooting
12668 @cindex troubleshooting
12670 Gnus works @emph{so} well straight out of the box---I can't imagine any
12678 Make sure your computer is switched on.
12681 Make sure that you really load the current Gnus version. If you have
12682 been running @sc{gnus}, you need to exit Emacs and start it up again before
12686 Try doing an @kbd{M-x gnus-version}. If you get something that looks
12687 like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
12688 on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
12689 flee}, you have some old @file{.el} files lying around. Delete these.
12692 Read the help group (@kbd{G h} in the group buffer) for a FAQ and a
12696 If all else fails, report the problem as a bug.
12699 @cindex reporting bugs
12701 @kindex M-x gnus-bug
12703 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
12704 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
12705 me the backtrace. I will fix bugs, but I can only fix them if you send
12706 me a precise description as to how to reproduce the bug.
12708 You really can never be too detailed in a bug report. Always use the
12709 @kbd{M-x gnus-bug} command when you make bug reports, even if it creates
12710 a 10Kb mail each time you use it, and even if you have sent me your
12711 environment 500 times before. I don't care. I want the full info each
12714 It is also important to remember that I have no memory whatsoever. If
12715 you send a bug report, and I send you a reply, and then you send back
12716 just ``No, it's not! Moron!'', I will have no idea what you are
12717 insulting me about. Always over-explain everything. It's much easier
12718 for all of us---if I don't have all the information I need, I will just
12719 mail you and ask for more info, and everything takes more time.
12721 If you just need help, you are better off asking on
12722 @samp{gnu.emacs.gnus}. I'm not very helpful.
12724 @cindex gnu.emacs.gnus
12725 @cindex ding mailing list
12726 You can also ask on the ding mailing list---@samp{ding@@ifi.uio.no}.
12727 Write to @samp{ding-request@@ifi.uio.no} to subscribe.
12730 @node A Programmers Guide to Gnus
12731 @section A Programmer's Guide to Gnus
12733 It is my hope that other people will figure out smart stuff that Gnus
12734 can do, and that other people will write those smart things as well. To
12735 facilitate that I thought it would be a good idea to describe the inner
12736 workings of Gnus. And some of the not-so-inner workings, while I'm at
12739 You can never expect the internals of a program not to change, but I
12740 will be defining (in some details) the interface between Gnus and its
12741 backends (this is written in stone), the format of the score files
12742 (ditto), data structures (some are less likely to change than others)
12743 and general method of operations.
12746 * Backend Interface:: How Gnus communicates with the servers.
12747 * Score File Syntax:: A BNF definition of the score file standard.
12748 * Headers:: How Gnus stores headers internally.
12749 * Ranges:: A handy format for storing mucho numbers.
12750 * Group Info:: The group info format.
12751 * Various File Formats:: Formats of files that Gnus use.
12755 @node Backend Interface
12756 @subsection Backend Interface
12758 Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
12759 groups. It only knows how to talk to @dfn{virtual servers}. A virtual
12760 server is a @dfn{backend} and some @dfn{backend variables}. As examples
12761 of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
12762 examples of the latter we have @code{nntp-port-number} and
12763 @code{nnmbox-directory}.
12765 When Gnus asks for information from a backend---say @code{nntp}---on
12766 something, it will normally include a virtual server name in the
12767 function parameters. (If not, the backend should use the ``current''
12768 virtual server.) For instance, @code{nntp-request-list} takes a virtual
12769 server as its only (optional) parameter. If this virtual server hasn't
12770 been opened, the function should fail.
12772 Note that a virtual server name has no relation to some physical server
12773 name. Take this example:
12777 (nntp-address "ifi.uio.no")
12778 (nntp-port-number 4324))
12781 Here the virtual server name is @samp{odd-one} while the name of
12782 the physical server is @samp{ifi.uio.no}.
12784 The backends should be able to switch between several virtual servers.
12785 The standard backends implement this by keeping an alist of virtual
12786 server environments that it pulls down/pushes up when needed.
12788 There are two groups of interface functions: @dfn{required functions},
12789 which must be present, and @dfn{optional functions}, which Gnus will
12790 always check whether are present before attempting to call.
12792 All these functions are expected to return data in the buffer
12793 @code{nntp-server-buffer} (@samp{ *nntpd*}), which is somewhat
12794 unfortunately named, but we'll have to live with it. When I talk about
12795 ``resulting data'', I always refer to the data in that buffer. When I
12796 talk about ``return value'', I talk about the function value returned by
12799 Some backends could be said to be @dfn{server-forming} backends, and
12800 some might be said to not be. The latter are backends that generally
12801 only operate on one group at a time, and have no concept of ``server''
12802 -- they have a group, and they deliver info on that group and nothing
12805 In the examples and definitions I will refer to the imaginary backend
12808 @cindex @code{nnchoke}
12811 * Required Backend Functions:: Functions that must be implemented.
12812 * Optional Backend Functions:: Functions that need not be implemented.
12813 * Writing New Backends:: Extending old backends.
12817 @node Required Backend Functions
12818 @subsubsection Required Backend Functions
12822 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
12824 @var{articles} is either a range of article numbers or a list of
12825 @code{Message-ID}s. Current backends do not fully support either---only
12826 sequences (lists) of article numbers, and most backends do not support
12827 retrieval of @code{Message-ID}s. But they should try for both.
12829 The result data should either be HEADs or NOV lines, and the result
12830 value should either be @code{headers} or @code{nov} to reflect this.
12831 This might later be expanded to @code{various}, which will be a mixture
12832 of HEADs and NOV lines, but this is currently not supported by Gnus.
12834 If @var{fetch-old} is non-@code{nil} it says to try to fetch "extra
12835 headers, in some meaning of the word. This is generally done by
12836 fetching (at most) @var{fetch-old} extra headers less than the smallest
12837 article number in @code{articles}, and fill in the gaps as well. The
12838 presence of this parameter can be ignored if the backend finds it
12839 cumbersome to follow the request. If this is non-@code{nil} and not a
12840 number, do maximum fetches.
12842 Here's an example HEAD:
12845 221 1056 Article retrieved.
12846 Path: ifi.uio.no!sturles
12847 From: sturles@@ifi.uio.no (Sturle Sunde)
12848 Newsgroups: ifi.discussion
12849 Subject: Re: Something very droll
12850 Date: 27 Oct 1994 14:02:57 +0100
12851 Organization: Dept. of Informatics, University of Oslo, Norway
12853 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
12854 References: <38jdmq$4qu@@visbur.ifi.uio.no>
12855 NNTP-Posting-Host: holmenkollen.ifi.uio.no
12859 So a @code{headers} return value would imply that there's a number of
12860 these in the data buffer.
12862 Here's a BNF definition of such a buffer:
12866 head = error / valid-head
12867 error-message = [ "4" / "5" ] 2number " " <error message> eol
12868 valid-head = valid-message *header "." eol
12869 valid-message = "221 " <number> " Article retrieved." eol
12870 header = <text> eol
12873 If the return value is @code{nov}, the data buffer should contain
12874 @dfn{network overview database} lines. These are basically fields
12878 nov-buffer = *nov-line
12879 nov-line = 8*9 [ field <TAB> ] eol
12880 field = <text except TAB>
12883 For a closer explanation what should be in those fields,
12887 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
12889 @var{server} is here the virtual server name. @var{definitions} is a
12890 list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
12892 If the server can't be opened, no error should be signaled. The backend
12893 may then choose to refuse further attempts at connecting to this
12894 server. In fact, it should do so.
12896 If the server is opened already, this function should return a
12897 non-@code{nil} value. There should be no data returned.
12900 @item (nnchoke-close-server &optional SERVER)
12902 Close connection to @var{server} and free all resources connected
12903 to it. Return @code{nil} if the server couldn't be closed for some
12906 There should be no data returned.
12909 @item (nnchoke-request-close)
12911 Close connection to all servers and free all resources that the backend
12912 have reserved. All buffers that have been created by that backend
12913 should be killed. (Not the @code{nntp-server-buffer}, though.) This
12914 function is generally only called when Gnus is shutting down.
12916 There should be no data returned.
12919 @item (nnchoke-server-opened &optional SERVER)
12921 If @var{server} is the current virtual server, and the connection to the
12922 physical server is alive, then this function should return a
12923 non-@code{nil} vlue. This function should under no circumstances
12924 attempt to reconnect to a server that is has lost connection to.
12926 There should be no data returned.
12929 @item (nnchoke-status-message &optional SERVER)
12931 This function should return the last error message from @var{server}.
12933 There should be no data returned.
12936 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
12938 The result data from this function should be the article specified by
12939 @var{article}. This might either be a @code{Message-ID} or a number.
12940 It is optional whether to implement retrieval by @code{Message-ID}, but
12941 it would be nice if that were possible.
12943 If @var{to-buffer} is non-@code{nil}, the result data should be returned
12944 in this buffer instead of the normal data buffer. This is to make it
12945 possible to avoid copying large amounts of data from one buffer to
12946 another, and Gnus mainly request articles to be inserted directly into
12947 its article buffer.
12949 If it is at all possible, this function should return a cons cell where
12950 the car is the group name the article was fetched from, and the cdr is
12951 the article number. This will enable Gnus to find out what the real
12952 group and article numbers are when fetching articles by
12953 @code{Message-ID}. If this isn't possible, @code{t} should be returned
12954 on successful article retrievement.
12957 @item (nnchoke-open-group GROUP &optional SERVER)
12959 Make @var{group} the current group.
12961 There should be no data returned by this function.
12964 @item (nnchoke-request-group GROUP &optional SERVER)
12966 Get data on @var{group}. This function also has the side effect of
12967 making @var{group} the current group.
12969 Here's an example of some result data and a definition of the same:
12972 211 56 1000 1059 ifi.discussion
12975 The first number is the status, which should be @code{211}. Next is the
12976 total number of articles in the group, the lowest article number, the
12977 highest article number, and finally the group name. Note that the total
12978 number of articles may be less than one might think while just
12979 considering the highest and lowest article numbers, but some articles
12980 may have been canceled. Gnus just discards the total-number, so
12981 whether one should take the bother to generate it properly (if that is a
12982 problem) is left as an exercise to the reader.
12985 group-status = [ error / info ] eol
12986 error = [ "4" / "5" ] 2<number> " " <Error message>
12987 info = "211 " 3* [ <number> " " ] <string>
12991 @item (nnchoke-close-group GROUP &optional SERVER)
12993 Close @var{group} and free any resources connected to it. This will be
12994 a no-op on most backends.
12996 There should be no data returned.
12999 @item (nnchoke-request-list &optional SERVER)
13001 Return a list of all groups available on @var{server}. And that means
13004 Here's an example from a server that only carries two groups:
13007 ifi.test 0000002200 0000002000 y
13008 ifi.discussion 3324 3300 n
13011 On each line we have a group name, then the highest article number in
13012 that group, the lowest article number, and finally a flag.
13015 active-file = *active-line
13016 active-line = name " " <number> " " <number> " " flags eol
13018 flags = "n" / "y" / "m" / "x" / "j" / "=" name
13021 The flag says whether the group is read-only (@samp{n}), is moderated
13022 (@samp{m}), is dead (@samp{x}), is aliased to some other group
13023 (@samp{=other-group} or none of the above (@samp{y}).
13026 @item (nnchoke-request-post &optional SERVER)
13028 This function should post the current buffer. It might return whether
13029 the posting was successful or not, but that's not required. If, for
13030 instance, the posting is done asynchronously, it has generally not been
13031 completed by the time this function concludes. In that case, this
13032 function should set up some kind of sentinel to beep the user loud and
13033 clear if the posting could not be completed.
13035 There should be no result data from this function.
13040 @node Optional Backend Functions
13041 @subsubsection Optional Backend Functions
13045 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
13047 @var{groups} is a list of groups, and this function should request data
13048 on all those groups. How it does it is of no concern to Gnus, but it
13049 should attempt to do this in a speedy fashion.
13051 The return value of this function can be either @code{active} or
13052 @code{group}, which says what the format of the result data is. The
13053 former is in the same format as the data from
13054 @code{nnchoke-request-list}, while the latter is a buffer full of lines
13055 in the same format as @code{nnchoke-request-group} gives.
13058 group-buffer = *active-line / *group-status
13062 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
13064 A Gnus group info (@pxref{Group Info}) is handed to the backend for
13065 alterations. This comes in handy if the backend really carries all the
13066 information (as is the case with virtual an imap groups). This function
13067 may alter the info in any manner it sees fit, and should return the
13068 (altered) group info. This function may alter the group info
13069 destructively, so no copying is needed before boogeying.
13071 There should be no result data from this function.
13074 @item (nnchoke-request-type GROUP &optional ARTICLE)
13076 When the user issues commands for ``sending news'' (@kbd{F} in the
13077 summary buffer, for instance), Gnus has to know whether the article the
13078 user is following up is news or mail. This function should return
13079 @code{news} if @var{article} in @var{group} is news, @code{mail} if it
13080 is mail and @code{unknown} if the type can't be decided. (The
13081 @var{article} parameter is necessary in @code{nnvirtual} groups which
13082 might very well combine mail groups and news groups.)
13084 There should be no result data from this function.
13087 @item (nnchoke-request-update-mark GROUP ARTICLE MARK)
13089 If the user tries to set a mark that the backend doesn't like, this
13090 function may change the mark. Gnus will use whatever this function
13091 returns as the mark for @var{article} instead of the original
13092 @var{mark}. If the backend doesn't care, it must return the original
13093 @var{mark}, and not @code{nil} or any other type of garbage.
13095 The only use for this that I can see is what @code{nnvirtual} does with
13096 it---if a component group is auto-expirable, marking an article as read
13097 in the virtual group should result in the article being marked as
13100 There should be no result data from this function.
13103 @item (nnchoke-request-scan &optional GROUP SERVER)
13105 This function may be called at any time (by Gnus or anything else) to
13106 request that the backend check for incoming articles, in one way or
13107 another. A mail backend will typically read the spool file or query the
13108 POP server when this function is invoked. The @var{group} doesn't have
13109 to be heeded---if the backend decides that it is too much work just
13110 scanning for a single group, it may do a total scan of all groups. It
13111 would be nice, however, to keep things local if that's practical.
13113 There should be no result data from this function.
13116 @item (nnchoke-request-asynchronous GROUP &optional SERVER ARTICLES)
13118 This is a request to fetch articles asynchronously later.
13119 @var{articles} is an alist of @var{(article-number line-number)}. One
13120 would generally expect that if one later fetches article number 4, for
13121 instance, some sort of asynchronous fetching of the articles after 4
13122 (which might be 5, 6, 7 or 11, 3, 909 depending on the order in that
13123 alist) would be fetched asynchronously, but that is left up to the
13124 backend. Gnus doesn't care.
13126 There should be no result data from this function.
13129 @item (nnchoke-request-group-description GROUP &optional SERVER)
13131 The result data from this function should be a description of
13135 description-line = name <TAB> description eol
13137 description = <text>
13140 @item (nnchoke-request-list-newsgroups &optional SERVER)
13142 The result data from this function should be the description of all
13143 groups available on the server.
13146 description-buffer = *description-line
13150 @item (nnchoke-request-newgroups DATE &optional SERVER)
13152 The result data from this function should be all groups that were
13153 created after @samp{date}, which is in normal human-readable date
13154 format. The data should be in the active buffer format.
13157 @item (nnchoke-request-create-group GROUP &optional SERVER)
13159 This function should create an empty group with name @var{group}.
13161 There should be no return data.
13164 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
13166 This function should run the expiry process on all articles in the
13167 @var{articles} range (which is currently a simple list of article
13168 numbers.) It is left up to the backend to decide how old articles
13169 should be before they are removed by this function. If @var{force} is
13170 non-@code{nil}, all @var{articles} should be deleted, no matter how new
13173 This function should return a list of articles that it did not/was not
13176 There should be no result data returned.
13179 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
13182 This function should move @var{article} (which is a number) from
13183 @var{group} by calling @var{accept-form}.
13185 This function should ready the article in question for moving by
13186 removing any header lines it has added to the article, and generally
13187 should ``tidy up'' the article. Then it should @code{eval}
13188 @var{accept-form} in the buffer where the ``tidy'' article is. This
13189 will do the actual copying. If this @code{eval} returns a
13190 non-@code{nil} value, the article should be removed.
13192 If @var{last} is @code{nil}, that means that there is a high likelihood
13193 that there will be more requests issued shortly, so that allows some
13196 The function should return a cons where the car is the group name and
13197 the cdr is the article number that the article was entered as.
13199 There should be no data returned.
13202 @item (nnchoke-request-accept-article GROUP &optional SERVER LAST)
13204 This function takes the current buffer and inserts it into @var{group}.
13205 If @var{last} in @code{nil}, that means that there will be more calls to
13206 this function in short order.
13208 The function should return a cons where the car is the group name and
13209 the cdr is the article number that the article was entered as.
13211 There should be no data returned.
13214 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
13216 This function should remove @var{article} (which is a number) from
13217 @var{group} and insert @var{buffer} there instead.
13219 There should be no data returned.
13222 @item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
13224 This function should delete @var{group}. If @var{force}, it should
13225 really delete all the articles in the group, and then delete the group
13226 itself. (If there is such a thing as ``the group itself''.)
13228 There should be no data returned.
13231 @item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
13233 This function should rename @var{group} into @var{new-name}. All
13234 articles that are in @var{group} should move to @var{new-name}.
13236 There should be no data returned.
13241 @node Writing New Backends
13242 @subsubsection Writing New Backends
13244 The various backends share many similarities. @code{nnml} is just like
13245 @code{nnspool}, but it allows you to edit the articles on the server.
13246 @code{nnmh} is just like @code{nnml}, but it doesn't use an active file,
13247 and it doesn't maintain overview databases. @code{nndir} is just like
13248 @code{nnml}, but it has no concept of ``groups'', and it doesn't allow
13251 It would make sense if it were possible to ``inherit'' functions from
13252 backends when writing new backends. And, indeed, you can do that if you
13253 want to. (You don't have to if you don't want to, of course.)
13255 All the backends declare their public variables and functions by using a
13256 package called @code{nnoo}.
13258 To inherit functions from other backends (and allow other backends to
13259 inherit functions from the current backend), you should use the
13266 This macro declares the first parameter to be a child of the subsequent
13267 parameters. For instance:
13270 (nnoo-declare nndir
13274 @code{nndir} has here declared that it intends to inherit functions from
13275 both @code{nnml} and @code{nnmh}.
13278 This macro is equivalent to @code{defvar}, but registers the variable as
13279 a public server variable. Most state-oriented variables should be
13280 declared with @code{defvoo} instead of @code{defvar}.
13282 In addition to the normal @code{defvar} parameters, it takes a list of
13283 variables in the parent backends to map the variable to when executing
13284 a function in those backends.
13287 (defvoo nndir-directory nil
13288 "Where nndir will look for groups."
13289 nnml-current-directory nnmh-current-directory)
13292 This means that @code{nnml-current-directory} will be set to
13293 @code{nndir-directory} when an @code{nnml} function is called on behalf
13294 of @code{nndir}. (The same with @code{nnmh}.)
13296 @item nnoo-define-basics
13297 This macro defines some common functions that almost all backends should
13301 (nnoo-define-basics nndir)
13305 This macro is just like @code{defun} and takes the same parameters. In
13306 addition to doing the normal @code{defun} things, it registers the
13307 function as being public so that other backends can inherit it.
13309 @item nnoo-map-functions
13310 This macro allows mapping of functions from the current backend to
13311 functions from the parent backends.
13314 (nnoo-map-functions nndir
13315 (nnml-retrieve-headers 0 nndir-current-group 0 0)
13316 (nnmh-request-article 0 nndir-current-group 0 0))
13319 This means that when @code{nndir-retrieve-headers} is called, the first,
13320 third, and fourth parameters will be passed on to
13321 @code{nnml-retrieve-headers}, while the second parameter is set to the
13322 value of @code{nndir-current-group}.
13325 This macro allows importing functions from backends. It should be the
13326 last thing in the source file, since it will only define functions that
13327 haven't already been defined.
13333 nnmh-request-newgroups)
13337 This means that calls to @code{nndir-request-list} should just be passed
13338 on to @code{nnmh-request-list}, while all public functions from
13339 @code{nnml} that haven't been defined in @code{nndir} yet should be
13344 Below is a slightly shortened version of the @code{nndir} backend.
13347 ;;; nndir.el --- single directory newsgroup access for Gnus
13348 ;; Copyright (C) 1995,96 Free Software Foundation, Inc.
13352 (require 'nnheader)
13356 (eval-when-compile (require 'cl))
13358 (nnoo-declare nndir
13361 (defvoo nndir-directory nil
13362 "Where nndir will look for groups."
13363 nnml-current-directory nnmh-current-directory)
13365 (defvoo nndir-nov-is-evil nil
13366 "*Non-nil means that nndir will never retrieve NOV headers."
13371 (defvoo nndir-current-group "" nil nnml-current-group nnmh-current-group)
13372 (defvoo nndir-top-directory nil nil nnml-directory nnmh-directory)
13373 (defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail)
13375 (defvoo nndir-status-string "" nil nnmh-status-string)
13376 (defconst nndir-version "nndir 1.0")
13380 ;;; Interface functions.
13382 (nnoo-define-basics nndir)
13384 (deffoo nndir-open-server (server &optional defs)
13385 (setq nndir-directory
13386 (or (cadr (assq 'nndir-directory defs))
13388 (unless (assq 'nndir-directory defs)
13389 (push `(nndir-directory ,server) defs))
13390 (push `(nndir-current-group
13391 ,(file-name-nondirectory (directory-file-name nndir-directory)))
13393 (push `(nndir-top-directory
13394 ,(file-name-directory (directory-file-name nndir-directory)))
13396 (nnoo-change-server 'nndir server defs))
13398 (nnoo-map-functions nndir
13399 (nnml-retrieve-headers 0 nndir-current-group 0 0)
13400 (nnmh-request-article 0 nndir-current-group 0 0)
13401 (nnmh-request-group nndir-current-group 0 0)
13402 (nnmh-close-group nndir-current-group 0))
13406 nnmh-status-message
13408 nnmh-request-newgroups))
13415 @node Score File Syntax
13416 @subsection Score File Syntax
13418 Score files are meant to be easily parsable, but yet extremely
13419 mallable. It was decided that something that had the same read syntax
13420 as an Emacs Lisp list would fit that spec.
13422 Here's a typical score file:
13426 ("win95" -10000 nil s)
13433 BNF definition of a score file:
13436 score-file = "" / "(" *element ")"
13437 element = rule / atom
13438 rule = string-rule / number-rule / date-rule
13439 string-rule = "(" quote string-header quote space *string-match ")"
13440 number-rule = "(" quote number-header quote space *number-match ")"
13441 date-rule = "(" quote date-header quote space *date-match ")"
13443 string-header = "subject" / "from" / "references" / "message-id" /
13444 "xref" / "body" / "head" / "all" / "followup"
13445 number-header = "lines" / "chars"
13446 date-header = "date"
13447 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
13448 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
13449 score = "nil" / <integer>
13450 date = "nil" / <natural number>
13451 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
13452 "r" / "regex" / "R" / "Regex" /
13453 "e" / "exact" / "E" / "Exact" /
13454 "f" / "fuzzy" / "F" / "Fuzzy"
13455 number-match = "(" <integer> [ "" / [ space score [ "" /
13456 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
13457 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
13458 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
13459 space date [ "" / [ space date-match-t ] ] ] ] ")"
13460 date-match-t = "nil" / "at" / "before" / "after"
13461 atom = "(" [ required-atom / optional-atom ] ")"
13462 required-atom = mark / expunge / mark-and-expunge / files /
13463 exclude-files / read-only / touched
13464 optional-atom = adapt / local / eval
13465 mark = "mark" space nil-or-number
13466 nil-or-number = "nil" / <integer>
13467 expunge = "expunge" space nil-or-number
13468 mark-and-expunge = "mark-and-expunge" space nil-or-number
13469 files = "files" *[ space <string> ]
13470 exclude-files = "exclude-files" *[ space <string> ]
13471 read-only = "read-only" [ space "nil" / space "t" ]
13472 adapt = "adapt" [ space "nil" / space "t" / space adapt-rule ]
13473 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
13474 local = "local" *[ space "(" <string> space <form> ")" ]
13475 eval = "eval" space <form>
13476 space = *[ " " / <TAB> / <NEWLINE> ]
13479 Any unrecognized elements in a score file should be ignored, but not
13482 As you can see, white space is needed, but the type and amount of white
13483 space is irrelevant. This means that formatting of the score file is
13484 left up to the programmer---if it's simpler to just spew it all out on
13485 one looong line, then that's ok.
13487 The meaning of the various atoms are explained elsewhere in this
13492 @subsection Headers
13494 Gnus uses internally a format for storing article headers that
13495 corresponds to the @sc{nov} format in a mysterious fashion. One could
13496 almost suspect that the author looked at the @sc{nov} specification and
13497 just shamelessly @emph{stole} the entire thing, and one would be right.
13499 @dfn{Header} is a severely overloaded term. ``Header'' is used in
13500 RFC1036 to talk about lines in the head of an article (eg.,
13501 @code{From}). It is used by many people as a synonym for
13502 ``head''---``the header and the body''. (That should be avoided, in my
13503 opinion.) And Gnus uses a format internally that it calls ``header'',
13504 which is what I'm talking about here. This is a 9-element vector,
13505 basically, with each header (ouch) having one slot.
13507 These slots are, in order: @code{number}, @code{subject}, @code{from},
13508 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
13509 @code{xref}. There are macros for accessing and setting these slots --
13510 they all have predictable names beginning with @code{mail-header-} and
13511 @code{mail-header-set-}, respectively.
13513 The @code{xref} slot is really a @code{misc} slot. Any extra info will
13520 @sc{gnus} introduced a concept that I found so useful that I've started
13521 using it a lot and have elaborated on it greatly.
13523 The question is simple: If you have a large amount of objects that are
13524 identified by numbers (say, articles, to take a @emph{wild} example)
13525 that you want to callify as being ``included'', a normal sequence isn't
13526 very useful. (A 200,000 length sequence is a bit long-winded.)
13528 The solution is as simple as the question: You just collapse the
13532 (1 2 3 4 5 6 10 11 12)
13535 is transformed into
13538 ((1 . 6) (10 . 12))
13541 To avoid having those nasty @samp{(13 . 13)} elements to denote a
13542 lonesome object, a @samp{13} is a valid element:
13545 ((1 . 6) 7 (10 . 12))
13548 This means that comparing two ranges to find out whether they are equal
13549 is slightly tricky:
13552 ((1 . 5) 7 8 (10 . 12))
13558 ((1 . 5) (7 . 8) (10 . 12))
13561 are equal. In fact, any non-descending list is a range:
13567 is a perfectly valid range, although a pretty long-winded one. This is
13574 and is equal to the previous range.
13576 Here's a BNF definition of ranges. Of course, one must remember the
13577 semantic requirement that the numbers are non-descending. (Any number
13578 of repetition of the same number is allowed, but apt to disappear in
13582 range = simple-range / normal-range
13583 simple-range = "(" number " . " number ")"
13584 normal-range = "(" start-contents ")"
13585 contents = "" / simple-range *[ " " contents ] /
13586 number *[ " " contents ]
13589 Gnus currently uses ranges to keep track of read articles and article
13590 marks. I plan on implementing a number of range operators in C if The
13591 Powers That Be are willing to let me. (I haven't asked yet, because I
13592 need to do some more thinking on what operators I need to make life
13593 totally range-based without ever having to convert back to normal
13598 @subsection Group Info
13600 Gnus stores all permanent info on groups in a @dfn{group info} list.
13601 This list is from three to six elements (or more) long and exhaustively
13602 describes the group.
13604 Here are two example group infos; one is a very simple group while the
13605 second is a more complex one:
13608 ("no.group" 5 (1 . 54324))
13610 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
13611 ((tick (15 . 19)) (replied 3 6 (19 . 3)))
13613 (auto-expire (to-address "ding@@ifi.uio.no")))
13616 The first element is the group name as Gnus knows the group; the second
13617 is the group level; the third is the read articles in range format; the
13618 fourth is a list of article marks lists; the fifth is the select method;
13619 and the sixth contains the group parameters.
13621 Here's a BNF definition of the group info format:
13624 info = "(" group space level space read
13625 [ "" / [ space marks-list [ "" / [ space method [ "" /
13626 space parameters ] ] ] ] ] ")"
13627 group = quote <string> quote
13628 level = <integer in the range of 1 to inf>
13630 marks-lists = nil / "(" *marks ")"
13631 marks = "(" <string> range ")"
13632 method = "(" <string> *elisp-forms ")"
13633 parameters = "(" *elisp-forms ")"
13636 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
13637 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
13641 @node Various File Formats
13642 @subsection Various File Formats
13645 * Active File Format:: Information on articles and groups available.
13646 * Newsgroups File Format:: Group descriptions.
13650 @node Active File Format
13651 @subsubsection Active File Format
13653 The active file lists all groups that are available on the server in
13654 question. It also lists the highest and lowest current article numbers
13657 Here's an excerpt from a typical active file:
13660 soc.motss 296030 293865 y
13661 alt.binaries.pictures.fractals 3922 3913 n
13662 comp.sources.unix 1605 1593 m
13663 comp.binaries.ibm.pc 5097 5089 y
13664 no.general 1000 900 y
13667 Here's a pseudo-BNF definition of this file:
13670 active = *group-line
13671 group-line = group space high-number space low-number space flag <NEWLINE>
13672 group = <non-white-space string>
13674 high-number = <non-negative integer>
13675 low-number = <positive integer>
13676 flag = "y" / "n" / "m" / "j" / "x" / "=" group
13680 @node Newsgroups File Format
13681 @subsubsection Newsgroups File Format
13683 The newsgroups file lists groups along with their descriptions. Not all
13684 groups on the server have to be listed, and not all groups in the file
13685 have to exist on the server. The file is meant purely as information to
13688 The format is quite simple; a group name, a tab, and the description.
13689 Here's the definition:
13693 line = group tab description <NEWLINE>
13694 group = <non-white-space string>
13696 description = <string>
13700 @node Emacs for Heathens
13701 @section Emacs for Heathens
13703 Believe it or not, but some people who use Gnus haven't really used
13704 Emacs much before they embarked on their journey on the Gnus Love Boat.
13705 If you are one of those unfortunates whom ``@kbd{M-C-a}'', ``kill the
13706 region'', and ``set @code{gnus-flargblossen} to an alist where the key
13707 is a regexp that is used for matching on the group name'' are magical
13708 phrases with little or no meaning, then this appendix is for you. If
13709 you are already familiar with Emacs, just ignore this and go fondle your
13713 * Keystrokes:: Entering text and executing commands.
13714 * Emacs Lisp:: The built-in Emacs programming language.
13719 @subsection Keystrokes
13723 Q: What is an experienced Emacs user?
13726 A: A person who wishes that the terminal had pedals.
13729 Yes, when you use Emacs, you are apt to use the control key, the shift
13730 key and the meta key a lot. This is very annoying to some people
13731 (notably @code{vi}le users), and the rest of us just love the hell out
13732 of it. Just give up and submit. Emacs really does stand for
13733 ``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you
13734 may have heard from other disreputable sources (like the Emacs author).
13736 The shift key is normally located near your pinky fingers, and are
13737 normally used to get capital letters and stuff. You probably use it all
13738 the time. The control key is normally marked ``CTRL'' or something like
13739 that. The meta key is, funnily enough, never marked as such on any
13740 keyboards. The one I'm currently at has a key that's marked ``Alt'',
13741 which is the meta key on this keyboard. It's usually located somewhere
13742 to the left hand side of the keyboard, usually on the bottom row.
13744 Now, us Emacs people doesn't say ``press the meta-control-m key'',
13745 because that's just too inconvenient. We say ``press the @kbd{M-C-m}
13746 key''. @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the
13747 prefix that means ``control''. So ``press @kbd{C-k}'' means ``press
13748 down the control key, and hold it down while you press @kbd{k}''.
13749 ``Press @kbd{M-C-k}'' means ``press down and hold down the meta key and
13750 the control key and then press @kbd{k}''. Simple, ay?
13752 This is somewhat complicated by the fact that not all keyboards have a
13753 meta key. In that case you can use the ``escape'' key. Then @kbd{M-k}
13754 means ``press escape, release escape, press @kbd{k}''. That's much more
13755 work than if you have a meta key, so if that's the case, I respectfully
13756 suggest you get a real keyboard with a meta key. You can't live without
13762 @subsection Emacs Lisp
13764 Emacs is the King of Editors because it's really a Lisp interpreter.
13765 Each and every key you tap runs some Emacs Lisp code snippet, and since
13766 Emacs Lisp is an interpreted language, that means that you can configure
13767 any key to run any arbitrary code. You just, like, do it.
13769 Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
13770 functions. (These are byte-compiled for speed, but it's still
13771 interpreted.) If you decide that you don't like the way Gnus does
13772 certain things, it's trivial to have it do something a different way.
13773 (Well, at least if you know how to write Lisp code.) However, that's
13774 beyond the scope of this manual, so we are simply going to talk about
13775 some common constructs that you normally use in your @file{.emacs} file
13778 If you want to set the variable @code{gnus-florgbnize} to four (4), you
13779 write the following:
13782 (setq gnus-florgbnize 4)
13785 This function (really ``special form'') @code{setq} is the one that can
13786 set a variable to some value. This is really all you need to know. Now
13787 you can go and fill your @code{.emacs} file with lots of these to change
13790 If you have put that thing in your @code{.emacs} file, it will be read
13791 and @code{eval}ed (which is lisp-ese for ``run'') the next time you
13792 start Emacs. If you want to change the variable right away, simply say
13793 @kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
13794 previous ``form'', which here is a simple @code{setq} statement.
13796 Go ahead---just try it, if you're located at your Emacs. After you
13797 @kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
13798 is the return value of the form you @code{eval}ed.
13802 If the manual says ``set @code{gnus-read-active-file} to @code{some}'',
13806 (setq gnus-read-active-file 'some)
13809 On the other hand, if the manual says ``set @code{gnus-nntp-server} to
13810 @samp{nntp.ifi.uio.no}'', that means:
13813 (setq gnus-nntp-server "nntp.ifi.uio.no")
13816 So be careful not to mix up strings (the latter) with symbols (the
13817 former). The manual is unambiguous, but it can be confusing.
13820 @include gnus-faq.texi