1 \input texinfo @c -*-texinfo-*-
2 @comment %**start of header (This is for running Texinfo on a region.)
4 @settitle September Gnus Manual
11 @setchapternewpage odd
13 @comment %**end of header (This is for running Texinfo on a region.)
16 %\global\baselineskip 30pt % For printing in double spaces
21 This file documents Gnus, the GNU Emacs newsreader.
23 Copyright (C) 1995 Free Software Foundation, Inc.
25 Permission is granted to make and distribute verbatim copies of
26 this manual provided the copyright notice and this permission notice
27 are preserved on all copies.
30 Permission is granted to process this file through Tex and print the
31 results, provided the printed document carries copying permission
32 notice identical to this one except for the removal of this paragraph
33 (this paragraph not being relevant to the printed manual).
36 Permission is granted to copy and distribute modified versions of this
37 manual under the conditions for verbatim copying, provided also that the
38 entire resulting derived work is distributed under the terms of a
39 permission notice identical to this one.
41 Permission is granted to copy and distribute translations of this manual
42 into another language, under the above conditions for modified versions.
48 @title September Gnus Manual
50 @author by Lars Magne Ingebrigtsen
52 @vskip 0pt plus 1filll
53 Copyright @copyright{} 1995 Free Software Foundation, Inc.
55 Permission is granted to make and distribute verbatim copies of
56 this manual provided the copyright notice and this permission notice
57 are preserved on all copies.
59 Permission is granted to copy and distribute modified versions of this
60 manual under the conditions for verbatim copying, provided that the
61 entire resulting derived work is distributed under the terms of a
62 permission notice identical to this one.
64 Permission is granted to copy and distribute translations of this manual
65 into another language, under the above conditions for modified versions.
67 Cover art by Etienne Suvasa.
74 @top The Gnus Newsreader
76 You can read news (and mail) from within Emacs by using Gnus. The news
77 can be gotten by any nefarious means you can think of---@sc{nntp}, local
78 spool or your mbox file. All at the same time, if you want to push your
82 * History:: How Gnus got where it is today.
83 * Terminology:: We use really difficult, like, words here.
84 * Starting Up:: Finding news can be a pain.
85 * The Group Buffer:: Selecting, subscribing and killing groups.
86 * The Summary Buffer:: Reading, saving and posting articles.
87 * The Article Buffer:: Displaying and handling articles.
88 * The Server Buffer:: Making and editing virtual servers.
89 * Scoring:: Assigning values to articles.
90 * Various:: General purpose settings.
91 * Customization:: Tailoring Gnus to your needs.
92 * Troubleshooting:: What you might try if things do not work.
93 * The End:: Farewell and goodbye.
94 * Appendices:: Technical stuff, Emacs intro, FAQ
95 * Index:: Variable, function and concept index.
96 * Key Index:: Key Index.
103 @sc{gnus} was written by Masanobu UMEDA. When autumn crept up in '94,
104 Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
106 If you want to investigate the person responsible for this outrage, you
107 can point your (feh!) web browser to
108 @file{http://www.ifi.uio.no/~larsi/}. This is also the primary
109 distribution point for the new and spiffy versions of Gnus, also know as
110 The Site That Destroys Newsrcs And Drives People Mad.
112 During the first extended alpha period of develpment, the new Gnus was
113 called "(ding) Gnus". @dfn{(ding)}, is, of course, short for @dfn{ding
114 is not Gnus}, which is a total and utter lie, but who cares? (Besides,
115 the "Gnus" in this abbreviation should probably be pronounced "news" as
116 UMEDA intended, which makes it a more appropriate name, don't you
119 In any case, after spending all that energy with coming up with a new
120 and spiffy name, we decided that the name was @emph{too} spiffy, so we
121 renamamed it back again to "Gnus". But in mixed case. "Gnus" vs.
122 "@sc{gnus}". New vs. old.
124 Incidentally, the next Gnus generation will be called "September Gnus",
125 and won't be released until February. Confused? You will be.
128 * Why?:: What's the point of Gnus?
129 * Compatibility:: Just how compatible is Gnus with @sc{gnus}?
130 * Conformity:: Gnus tries to conform to all standards.
131 * Emacsen:: Gnus can be run on a few modern Emacsen.
132 * Contributors:: Oodles of people.
133 * New Features:: Pointers to some of the new stuff in Gnus.
134 * Newest Features:: Features so new that they haven't been written yet.
140 What's the point of Gnus?
142 I want to provide a "rad", "happening", "way cool" and "hep" newsreader,
143 that lets you do anything you can think of. That was my original
144 motivation, but while working on Gnus, it has become clear to me that
145 this generation of newsreaders really belong in the stone age.
146 Newsreaders haven't developed much since the infancy of the net. If the
147 volume continues to rise with the current rate of increase, all current
148 newsreaders will be pretty much useless. How do you deal with
149 newsgroups that have hundreds (or thousands) of new articles each day?
151 Gnus offer no real solutions to these questions, but I would very much
152 like to see Gnus being used as a testing ground for new methods of
153 reading and fetching news. Expanding on Umeda-san's wise decision to
154 separate the newsreader from the backends, Gnus now offers a simple
155 interface for anybody who wants to write new backends for fetching mail
156 and news from different sources. I have added hooks for customizations
157 everywhere I can imagine useful. By doing so, I'm inviting every one of
158 you to explore and invent new ways of reading news.
160 May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
163 @section Compatibility
165 @cindex compatibility
166 Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
167 bindings have been kept. More key bindings have been added, of course,
168 but only in one or two obscure cases have old bindings been changed.
173 @center In a cloud bones of steel.
177 All commands have kept their names. Some internal functions have changed
180 The @code{gnus-uu} package has changed drastically. @xref{Decoding
183 One major compatibility question if the presence of several summary
184 buffers. All variables that are relevant while reading a group are
185 buffer-local to the summary buffer they belong in. Although most
186 important variables have their values copied into their global
187 counterparts whenever a command is executed in the summary buffer, this
188 change might lead to incorrect values being used unless you are careful.
190 All code that relies on knowledge of @sc{gnus} internals will probably
191 fail. To take two examples: Sorting @code{gnus-newsrc-assoc} (or
192 changing it in any way, as a matter of fact) is strictly verboten. Gnus
193 maintains a hash table that points to the entries in this assoc (which
194 speeds up many functions), and changing the assoc directly will lead to
199 Old hilit19 code does not work at all. In fact, you should probably
200 remove all hilit code from all Gnus hooks
201 (@code{gnus-group-prepare-hook}, @code{gnus-summary-prepare-hook} and
202 @code{gnus-summary-article-hook}). (Well, at the very least the first
203 two.) Gnus provides various integrated functions for highlighting.
204 These are faster and more accurate. To make life easier for everybody,
205 Gnus will by default remove all hilit calls from all hilit hooks.
208 Packages like @code{expire-kill} will no longer work. As a matter of
209 fact, you should probably remove all old @sc{gnus} packages (and other
210 code) when you start using Gnus. More likely than not, Gnus already
211 does what you have written code to make @sc{gnus} do. (Snicker.)
213 Even though old methods of doing things are still supported, only the
214 new methods are documented in this manual. If you detect a new method of
215 doing something while reading this manual, that does not mean you have
216 to stop doing it the old way.
218 Gnus understands all @sc{gnus} startup files.
221 Overall, a casual user who hasn't written much code that depends on
222 @sc{gnus} internals should suffer no problems. If problems occur,
223 please let me know (@kbd{M-x gnus-bug}).
229 No rebels without a clue here, ma'am. We conform to all standards known
230 to (wo)man. Except for those standards and/or conventions we disagree
236 There are no known breaches of this standard.
239 There are no known breaches of this standard, either.
241 @item Usenet Seal of Approval
242 Gnus hasn't been formally through the Seal process, but I have read
243 through the Seal text and I think Gnus would pass.
245 @item Son-of-RFC 1036
246 We do have some breaches to this one.
250 Gnus does no MIME handling, and this standard-to-be seems to think that
251 MIME is the bees' knees, so we have major breakage here.
253 This is considered to be a "vanity header", while I consider it to be
254 consumer information. After seeing so many badly formatted articles
255 coming from @code{tin} and @code{Netscape} I know not to use either of
256 those for posting articles. I would not have known that if it wasn't
257 for the @code{X-Newsreader} header.
259 Gnus breaks lines if this header is long. I infer from RFC1036 that
260 being conservative in what you output is not creating 5000-character
261 lines, so it seems like a good idea to me. However, this standard-to-be
262 says that whitespace in the @code{References} header is to be preserved,
263 so... It doesn't matter one way or the other to Gnus, so if somebody
264 tells me what The Way is, I'll change it. Or not.
269 If you ever see Gnus act noncompliantly to the texts mentioned above,
270 don't hesitate to drop a note to Gnus Towers and let us know.
280 Gnus should work on :
291 Mule versions based on Emacs 19.26 and up.
295 Gnus will absolutely not work on any Emacsen older than that. Not
298 There are some vague differences in what Gnus does, though:
303 The mouse-face on Gnus lines under Emacs and Mule is delimited to
304 certain parts of the lines while they cover the entire line under
308 The same with current-article marking---XEmacs puts an underline under
309 the entire summary line while Emacs and Mule are nicer and kinder.
312 XEmacs features more graphics---a logo and a toolbar.
315 Citation highlighting us better under Emacs and Mule than under XEmacs.
318 Emacs 19.26-19.28 have tangible hidden headers, which can be a bit
325 @section Contributors
328 The new Gnus version couldn't have been done without the help of all the
329 people on the (ding) mailing list. Every day for months I have gotten
330 tens of nice bug reports from them, filling me with joy, every single
331 one of them. Smooches. The people on the list have been tried beyond
332 endurance, what with my "oh, that's a neat idea <type type>, yup, I'll
333 release it right away <ship off> no wait, that doesn't work at all <type
334 type>, yup, I'll ship that one off right away <ship off> no, wait, that
335 absolutely does not work" policy for releases. Micro$oft---bah.
336 Amateurs. I'm @emph{much} worse. (Or is that "worser"? "much worser"?
339 I would like to take this opportunity to thank the Academy for... oops,
344 Of course, GNUS was written by Masanobu UMEDA.
346 Many excellent functions, especially dealing with scoring and
347 highlighting (as well as the soon-to-come @sc{soup} support) was written
350 Innumerable bug fixes were written by Sudish Joseph.
352 @code{gnus-topic} was written by Ilja Weis.
354 The refcard was written by Vladimir Alexiev.
356 I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
358 @code{nnfolder} has been much enhanced by Scott Byer.
360 The orphan scoring was written by Peter Mutsaers.
362 GNU XEmacs support has been added by Fabrice Popineau.
364 Various bits and pieces, especially dealing with .newsrc files, were
365 suggested and added by Hallvard B Furuseth.
367 Brian Edmonds has written @code{gnus-bbdb}.
369 Ricardo Nassif did the proof-reading.
371 Kevin Davidson came up with the name @dfn{ding}, so blame him.
373 Peter Arius, Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel
374 Quinlan, Frank D. Cringle, Geoffrey T. Dairiki and Andrew Eskilsson have
375 all contributed code and suggestions.
380 @section New Features
386 The look of all buffers can be changed by setting format-like variables
387 (@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
390 Local spool and several @sc{nntp} servers can be used at once
391 (@pxref{Foreign Groups}).
394 You can combine groups into virtual groups (@pxref{nnvirtual}).
397 You can read a number of different mail formats (@pxref{Reading Mail}).
398 All the mail backends implement a convenient mail expiry scheme
399 (@pxref{Expiring Old Mail Articles}).
402 Gnus can use various strategies for gathering threads that have lost
403 their roots (thereby gathering loose sub-threads into one thread) or it
404 can go back and retrieve enough headers to build a complete thread
405 (@pxref{Customizing Threading}).
408 Killed groups can be displayed in the group buffer, and you can read
412 Gnus can do partial group updates---you do not have to retrieve the
413 entire active file just to check for new articles in a few groups
414 (@pxref{The Active File}).
417 Gnus implements a sliding scale of subscribedness to groups
418 (@pxref{Group Levels}).
421 You can score articles according to any number of criteria
422 (@pxref{Scoring}). You can even get Gnus to find out how to score
423 articles for you (@pxref{Adaptive Scoring}).
426 Gnus maintains a dribble buffer that is auto-saved the normal Emacs
427 manner, so it should be difficult to lose much data on what you have
428 read if your machine should go down (@pxref{Auto Save}).
431 Gnus now has its own startup file to avoid cluttering up the
435 You can set the process mark on both groups and articles and perform
436 operations on all the marked items (@pxref{Process/Prefix}).
439 You can grep through a subset of groups and create a group from the
440 results (@pxref{nnkiboze}).
443 You can list subsets of groups according to, well, anything
444 (@pxref{Listing Groups}).
447 You can browse foreign servers and subscribe to groups from those
448 servers (@pxref{Browse Foreign Server}).
451 Gnus can fetch articles asynchronously on a second connection to the
452 server (@pxref{Asynchronous Fetching}).
455 You can cache articles locally (@pxref{Article Caching}).
458 The uudecode functions have been expanded and generalized
459 (@pxref{Decoding Articles}).
462 You can still post uuencoded articles, which was a little-known feature
463 of @sc{gnus} past (@pxref{Uuencoding & Posting}).
466 Fetching parents (and other articles) now actually works without
467 glitches (@pxref{Finding the Parent}).
470 Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
473 Digests (and other files) can be used as the basis for groups
477 Articles can be highlighted and customized (@pxref{Customizing
481 URLs and other external references can be buttonized (@pxref{Article
485 All Gnus buffers can be customized in a difficult fashion
486 (@pxref{Windows Configuration}).
489 You can click on buttons instead of using the keyboard
494 This is, of course, just a @emph{short} overview of the @emph{most}
495 important new features. No, really. There are tons more. Yes, we have
496 feeping creaturism in full effect, but nothing too gratuitous, I would
500 @node Newest Features
501 @section Newest Features
504 Also known as the @dfn{todo list}. Sure to be implemented before the
507 Be afraid. Be very afraid.
511 Native @sc{mime} support is something that should be done.
513 @code{trn}-like trees.
515 @code{nn}-like pick-and-read summary interface.
521 Floating point group levels and group bubbling.
523 Automatic re-scan of incoming mail.
525 Buttonize more stuff in the article buffer.
527 A better and simpler method for specifying mail composing methods.
529 Marks for saved, forwarded, etc articles.
531 Speed up caching and adaptive scoring.
533 Gather thread by filling in missing Message-IDs.
537 Allow posting through mail-to-news gateways.
539 Speed up massive group massacres.
541 @code{jka-compr} isn't fully supported.
543 Create better digests.
545 Do better word-wrap on cited text.
547 Better X-Face support with X-Face databases and stuff.
549 Support SELF-DISCIPLINE pins.
551 Really do unbinhexing.
553 Listing of all active groups.
557 Do the X-Receipt-To thing.
559 Don't kill summary buffers upon exit from the groups.
561 Allow adaption on secondary marks.
564 And much, much, much more. There is more to come than has already been
565 implemented. (But that's always true, isn't it?)
567 @code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>} is where the actual
568 up-to-the-second todo list is located, so if you're really curious, you
569 could point your Web browser over that-a-way.
578 This is what you are supposed to use this thing for---reading news.
579 News is generally fetched from a nearby @sc{nntp} server, and is
580 generally publicly available to everybody. If you post news, the entire
581 world is likely to read just what you have written, and they'll all
582 snigger mischievously. Behind your back.
585 Everything that's delivered to you personally is mail. Some news/mail
586 readers (like Gnus) blur the distinction between mail and news, but
587 there is a difference. Mail is private. News is public. Mailing is
588 not posting, and replying is not following up.
590 Send a mail to the person who has written what you are reading.
592 Post an article to the current newsgroup responding to the article you
595 Gnus gets fed articles from a number of backends, both news and mail
596 backends. Gnus does not handle the underlying media, so to speak---this
597 is all done by the backends.
599 Gnus will always use one method (and backend) as the @dfn{native}, or
600 default, way of getting news.
602 You can also have any number of foreign groups at the same time. These
603 are groups that use different backends for getting news.
606 The top part of an article, where administration information (etc.) is
610 The rest of an article. Everything that is not in the head is in the
614 A line from the head of an article.
617 A collection of such lines, or a collection of heads. Or even a
618 collection of @sc{nov} lines.
621 When Gnus enters a group, it asks the backend for the headers for all
622 the unread articles in the group. Most servers support the News OverView
623 format, which is much smaller and much faster to read than the normal
627 Each group is subscribed at some @dfn{level} or other (1-9). The ones
628 that have a lower level are "more" subscribed than the groups with a
629 higher level. In fact, groups on levels 1-5 are considered
630 @dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
631 are @dfn{killed}. Commands for listing groups and scanning for new
632 articles will all use the numeric prefix as @dfn{working level}.
634 @cindex killed groups
635 No information on killed groups is stored or updated, which makes killed
636 groups much easier to handle than subscribed groups.
638 @cindex zombie groups
639 Just like killed groups, only slightly less dead.
642 The news server has to keep track of what articles it carries, and what
643 groups exist. All this information in stored in the active file, which
644 is rather large, as you might surmise.
647 A group that exists in the @file{.newsrc} file, but isn't known to the
648 server (i. e., it isn't in the active file), is a @emph{bogus group}.
649 This means that the group probably doesn't exist (any more).
653 @chapter Starting Gnus
657 If your system administrator has set things up properly, starting Gnus
658 and reading news is extremely easy---you just type @kbd{M-x gnus}.
660 If things do not go smoothly at startup, you have to twiddle some
664 * Finding the News:: Choosing a method for getting news.
665 * The First Time:: What does Gnus do the first time you start it?
666 * The Server is Down:: How can I read my mail then?
667 * Slave Gnusii:: You can have more than one Gnus active at a time.
668 * Fetching a Group:: Starting Gnus just to read a group.
669 * New Groups:: What is Gnus supposed to do with new groups?
670 * Startup Files:: Those pesky startup files---@file{.newsrc}.
671 * Auto Save:: Recovering from a crash.
672 * The Active File:: Reading the active file over a slow line Takes Time.
673 * Startup Variables:: Other variables you might change.
676 @node Finding the News
677 @section Finding the News
679 @vindex gnus-select-method
680 The @code{gnus-select-method} variable controls how Gnus finds news.
681 This variable should be a list where the first element says @dfn{how}
682 and the second element says @dfn{where}. This method is is your native
683 method. All groups that are not fetched with this method are foreign
686 For instance, if you want to get your daily dosage of news from the
687 @samp{news.somewhere.edu} @sc{nntp} server, you'd say:
690 (setq gnus-select-method '(nntp "news.somewhere.edu"))
693 If you want to read directly from the local spool, say:
696 (setq gnus-select-method '(nnspool ""))
699 If you can use a local spool, you probably should, as it will almost
700 certainly be much faster.
702 @vindex gnus-nntpserver-file
704 @cindex @sc{nntp} server
705 If this variable is not set, Gnus will take a look at the
706 @code{NNTPSERVER} environment variable. If that variable isn't set,
707 Gnus will see whether @code{gnus-nntpserver-file} (default
708 @file{/etc/nntpserver}) has any opinions in the matter. It that fails
709 as well, Gnus will will try to use the machine that is running Emacs as
710 an @sc{nntp} server. That's a longshot, though.
712 @vindex gnus-nntp-server
713 If @code{gnus-nntp-server} is set, this variable will override
714 @code{gnus-select-method}. You should therefore set
715 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
717 @vindex gnus-secondary-servers
718 You can also make Gnus prompt you interactively for the name of an
719 @sc{nntp} server. If you give a non-numerical prefix to @code{gnus}
720 (i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
721 in the @code{gnus-secondary-servers} list (if any). You can also just
722 type in the name of any server you feel like visiting.
724 However, if you use one @sc{nntp} server regularly, and are just
725 interested in a couple of groups from a different server, you would be
726 better served by using the @code{gnus-group-browse-foreign-server}
727 command from the group buffer. It will let you have a look at what
728 groups are available, and you can subscribe to any of the groups you
729 want to. This also makes @file{.newsrc} maintenance much tidier.
730 @xref{Foreign Groups}.
732 @vindex gnus-secondary-select-methods
733 A slightly different approach to foreign groups is to set the
734 @code{gnus-secondary-select-methods} variable. The select methods
735 listed in this variable are in many ways just as native as the
736 @code{gnus-select-method} server. They will also be queried for active
737 files during startup (if that's required), and new newsgroups that
738 appear on these servers will be subscribed (or not) just as native
741 For instance, if you use the @code{nnmbox} backend to read you mail, you
742 would typically set this variable to
745 (setq gnus-secondary-select-methods '((nnmbox "")))
749 @section The First Time
750 @cindex first time usage
752 If no startup files exist, Gnus will try to determine what groups should
753 be subscribed by default.
755 @vindex gnus-default-subscribed-newsgroups
756 If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
757 will subscribe you to just those groups in that list, leaving the rest
758 killed. Your system administrator should have set this variable to
761 Since she hasn't, Gnus will just subscribe you to a few randomly picked
762 groups (i.e., @samp{*.newusers}). (@dfn{Random} is here defined as
763 "whatever Lars thinks you should read".)
765 You'll also be subscribed to the Gnus documentation group, which should
766 help you with most common problems.
768 If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
769 use the normal functions for handling new groups, and not do anything
772 @node The Server is Down
773 @section The Server is Down
774 @cindex server errors
776 If the default server is down, Gnus will understandably have some
777 problems starting. However, if you have some mail groups in addition to
778 the news groups, you may want to start Gnus anyway.
780 Gnus, being the trusting sort of program, will ask whether to proceed
781 without a native select method if that server can't be contacted. This
782 will happen whether the server doesn't actually exist (i.e., you have
783 given the wrong address) or the server has just momentarily taken ill
784 for some reason or other.
786 If Gnus says "nntp server on <your server> can't be opened. Continue?",
787 you do not want to continue unless you have some foreign groups that you
788 want to read. Even if you don't, Gnus will let you continue, but you'll
789 find it difficult to actually do anything in the group buffer. But,
790 hey, that's your problem. Blllrph!
792 @findex gnus-no-server
793 If you know that the server is definitely down, or you just want to read
794 your mail without bothering with the server at all, you can use the
795 @code{gnus-no-server} command to start Gnus. That might come in handy
796 if you're in a hurry as well.
800 @section Slave Gnusii
803 You might want to run more than one Emacs with more than one Gnus at the
804 same time. If you are using different @file{.newsrc} files (eg., if you
805 are using the two different Gnusii to read from two different servers),
806 that is no problem whatsoever. You just do it.
808 The problem appears when you want to run two Gnusii that use the same
811 To work around that problem some, we here at the Think-Tank at the Gnus
812 Towers have come up with a new concept: @dfn{Masters} and
813 @dfn{servants}. (We have applied for a patent on this concept, and have
814 taken out a copyright on those words. If you wish to use those words in
815 conjunction with each other, you have to send $1 per usage instance to
816 me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
817 Applications}) will be much more expensive, of course.)
819 Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
820 however you do it). Each subsequent slave Gnusii should be started with
821 @kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
822 files, but some slave files that contains information only on what
823 groups have been read in the slave session. When a master Gnus starts,
824 it will read (and delete) these slave files, incorporating all
825 information from all of them. (The slave files will be read in the
826 sequence they were created, so the latest changes will have precedence.)
828 Information from the slave files has, of course, presedence over the
829 information in the normal (i. e., master) @code{.newsrc} file.
832 @node Fetching a Group
833 @section Fetching a Group
835 @findex gnus-fetch-group
836 It it sometime convenient to be able to just say "I want to read this
837 group and I don't care whether Gnus has been started or not". This is
838 perhaps more useful for people who write code than for users, but the
839 command @code{gnus-fetch-group} provides this functionality in any
840 case. It takes the group name as a paramenter.
847 @vindex gnus-subscribe-newsgroup-method
848 What Gnus does when it encounters a new group is determined by the
849 @code{gnus-subscribe-newsgroup-method} variable.
851 This variable should contain a function. Some handy pre-fab values
855 @item gnus-subscribe-randomly
856 @vindex gnus-subscribe-randomly
857 Subscribe all new groups randomly.
858 @item gnus-subscribe-alphabetically
859 @vindex gnus-subscribe-alphabetically
860 Subscribe all new groups alphabetically.
861 @item gnus-subscribe-hierarchically
862 @vindex gnus-subscribe-hierarchically
863 Subscribe all new groups hierarchically.
864 @item gnus-subscribe-interactively
865 @vindex gnus-subscribe-interactively
866 Subscribe new groups interactively. This means that Gnus will ask
867 you about @strong{all} new groups.
868 @item gnus-subscribe-zombies
869 @vindex gnus-subscribe-zombies
870 Make all new groups zombies. You can browse the zombies later and
871 either kill them all off properly, or subscribe to them. This is the
875 @vindex gnus-subscribe-hierarchical-interactive
876 A closely related variable is
877 @code{gnus-subscribe-hierarchical-interactive}. (That's quite a
878 mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a
879 hierarchical fashion whether to subscribe to new groups or not. Gnus
880 will ask you for each sub-hierarchy whether you want to descend the
883 One common way to control which new newsgroups should be subscribed or
884 ignored is to put an @dfn{options} line at the start of the
885 @file{.newsrc} file. Here's an example:
888 options -n !alt.all !rec.all sci.all
891 @vindex gnus-subscribe-options-newsgroup-method
892 This line obviously belongs to a serious-minded intellectual scientific
893 person (or she may just be plain old boring), because it says that all
894 groups that have names beginning with @samp{alt} and @samp{rec} should
895 be ignored, and all groups with names beginning with @samp{sci} should
896 be subscribed. Gnus will not use the normal subscription method for
897 subscribing these groups.
898 @code{gnus-subscribe-options-newsgroup-method} is used instead. This
899 variable defaults to @code{gnus-subscribe-alphabetically}.
901 @vindex gnus-options-not-subscribe
902 @vindex gnus-options-subscribe
903 If you don't want to mess with your @file{.newsrc} file, you can just
904 set the two variables @code{gnus-options-subscribe} and
905 @code{gnus-options-not-subscribe}. These two variables do exactly the
906 same as the @file{.newsrc} options -n trick. Both are regexps, and if
907 the the new group matches the first, it will be unconditionally
908 subscribed, and if it matches the latter, it will be ignored.
910 @vindex gnus-auto-subscribed-groups
911 Yet another variable that meddles here is
912 @code{gnus-auto-subscribed-groups}. It works exactly like
913 @code{gnus-options-subscribe}, and is therefore really superfluos, but I
914 thought it would be nice to have two of these. This variable is more
915 meant for setting some ground rules, while the other variable is used
916 more for user fiddling. By default this variable makes all new groups
917 that come from mail backends (@code{nnml}, @code{nnbabyl},
918 @code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you
919 don't like that, just set this variable to @code{nil}.
921 @vindex gnus-check-new-newsgroups
922 If you are satisfied that you really never want to see any new groups,
923 you could set @code{gnus-check-new-newsgroups} to @code{nil}. This will
924 also save you some time at startup. Even if this variable is
925 @code{nil}, you can always subscribe to the new groups just by pressing
926 @kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
927 is @code{t} by default.
929 Gnus normally determines whether a group is new or not by comparing the
930 list of groups from the active file(s) with the lists of subscribed and
931 dead groups. This isn't a particularly fast method. If
932 @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
933 server for new groups since the last time. This is both faster &
934 cheaper. This also means that you can get rid of the list of killed
935 groups altogether, so you may set @code{gnus-save-killed-list} to
936 @code{nil}, which will save time both at startup, at exit, and all over.
937 Saves disk space, too. Why isn't this the default, then?
938 Unfortunately, not all servers support this function.
940 This variable can also be a list of select methods. If so, Gnus will
941 issue an @code{ask-server} command to each of the select methods, and
942 subscribe them (or not) using the normal methods. This might be handy
943 if you are monitoring a few servers for new groups. A side effect is
944 that startup will take much longer, so you can meditate while waiting.
945 Use the mantra "dingnusdingnusdingnus" to achieve permanent happiness.
948 @section Startup Files
949 @cindex startup files
952 Now, you all know about the @file{.newsrc} file. All subscription
953 information is traditionally stored in this file.
955 Things got a bit more complicated with @sc{gnus}. In addition to
956 keeping the @file{.newsrc} file updated, it also used a file called
957 @file{.newsrc.el} for storing all the information that didn't fit into
958 the @file{.newsrc} file. (Actually, it duplicated everything in the
959 @file{.newsrc} file.) @sc{gnus} would read whichever one of these files
960 that were the most recently saved, which enabled people to swap between
961 @sc{gnus} and other newsreaders.
963 That was kinda silly, so Gnus went one better: In addition to the
964 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
965 @file{.newsrc.eld}. It will read whichever of these files that are most
966 recent, but it will never write a @file{.newsrc.el} file.
968 @vindex gnus-save-newsrc-file
969 You can also turn off writing the @file{.newsrc} file by setting
970 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
971 the file and save some space, as well as making exit from Gnus faster.
972 However, this will make it impossible to use other newsreaders than
973 Gnus. But hey, who would want to, right?
975 @vindex gnus-save-killed-list
976 If @code{gnus-save-killed-list} is @code{nil}, Gnus will not save the
977 list of killed groups to the startup file. This will save both time
978 (when starting and quitting) and space (on disk). It will also means
979 that Gnus has no record of what groups are new or old, so the automatic
980 new groups subscription methods become meaningless. You should always
981 set @code{gnus-check-new-newsgroups} to @code{nil} or @code{ask-server}
982 if you set this variable to @code{nil} (@pxref{New Groups}).
984 @vindex gnus-startup-file
985 The @code{gnus-startup-file} variable says where the startup files are.
986 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
987 file being whatever that one is with a @samp{.eld} appended.
989 @vindex gnus-save-newsrc-hook
990 @vindex gnus-save-quick-newsrc-hook
991 @vindex gnus-save-standard-newsrc-hook
992 @code{gnus-save-newsrc-hook} is called before saving any of the newsrc
993 files, while @code{gnus-save-quick-newsrc-hook} is called just before
994 saving the @file{.newsrc.eld} file, and
995 @code{gnus-save-standard-newsrc-hook} is called just before saving the
996 @file{.newsrc} file. The latter two are commonly used to tern version
1001 @cindex dribble file
1004 Whenever you do something that changes the Gnus data (reading articles,
1005 catching up, killing/subscribing groups), the change is added to a
1006 special @dfn{dribble buffer}. This buffer is auto-saved the normal
1007 Emacs way. If your Emacs should crash before you have saved the
1008 @file{.newsrc} files, all changes you have made can be recovered from
1011 If Gnus detects this file at startup, it will ask the user whether to
1012 read it. The auto save file is deleted whenever the real startup file is
1015 @vindex gnus-use-dribble-file
1016 If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
1017 maintain a dribble buffer. The default is @code{t}.
1019 @vindex gnus-dribble-directory
1020 Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
1021 this variable is @code{nil}, which it is by default, Gnus will dribble
1022 into the same directory as the @file{.newsrc} file is located. (This is
1023 normally the user's home directory.)
1025 @node The Active File
1026 @section The Active File
1028 @cindex ignored groups
1030 When Gnus starts, or indeed whenever it tries to determine whether new
1031 articles have arrived, it reads the active file. This is a very large
1032 file that lists all the active groups and articles on the @sc{nntp}
1035 @vindex gnus-ignored-newsgroups
1036 Before examining the active file, Gnus deletes all lines that match the
1037 regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject
1038 any groups with bogus names, but you can use this variable to make Gnus
1039 ignore hierarchies you aren't ever interested in. This variable is
1040 @code{nil} by default, and will slow down active file handling somewhat
1041 if you set it to anything else.
1043 @vindex gnus-read-active-file
1044 The active file can be rather Huge, so if you have a slow network, you
1045 can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
1046 reading the active file. This variable is @code{t} by default.
1048 Gnus will try to make do by just getting information on the groups
1049 that you actually subscribe to.
1051 Note that if you subscribe to lots and lots of groups, setting this
1052 variable to @code{nil} will probably make Gnus slower, not faster. At
1053 present, having this variable @code{nil} will slow Gnus down
1054 considerably, unless you read news over a 2400 baud modem.
1056 This variable can also have the value @code{some}. Gnus will then
1057 attempt to read active info only on the subscribed groups. On some
1058 servers this is quite fast (on sparkling, brand new INN servers that
1059 support the @samp{LIST ACTIVE group} command), on others this is not
1060 fast at all. In any case, @code{some} should be faster than @code{nil},
1061 and is certainly faster than @code{t} over slow lines.
1063 If this variable is @code{nil}, Gnus will as for group info in total
1064 lock-step, which isn't very fast. If it is @code{some} and you use an
1065 @sc{nntp} server, Gnus will pump out commands as fast as it can, and
1066 read all the replies in one swoop. This will normally result in better
1067 performance, but if the server does not support the aforementioned
1068 @samp{LIST ACTIVE group} command, this isn't very nice to the server.
1070 In any case, if you use @code{some} or @code{nil}, you should kill all
1071 groups that you aren't interested in.
1073 @node Startup Variables
1074 @section Startup Variables
1077 @item gnus-load-hook
1078 @vindex gnus-load-hook
1079 A hook that is run while Gnus is being loaded. Note that this hook will
1080 normally be run just once in each Emacs session, no matter how many
1081 times you start Gnus.
1083 @item gnus-startup-hook
1084 @vindex gnus-startup-hook
1085 A hook that is run after starting up Gnus successfully.
1087 @item gnus-check-bogus-newsgroups
1088 @vindex gnus-check-bogus-newsgroups
1089 If non-@code{nil}, Gnus will check for and delete all bogus groups at
1090 startup. A @dfn{bogus group} is a group that you have in your
1091 @file{.newsrc} file, but doesn't exist on the news server. Checking for
1092 bogus groups isn't very quick, so to save time and resources, it's best
1093 to leave this option off, and instead do the checking for bogus groups
1094 once in a while from the group buffer (@pxref{Group Maintenance}).
1096 @item gnus-inhibit-startup-message
1097 @vindex gnus-inhibit-startup-message
1098 If non-@code{nil}, the startup message won't be displayed. That way,
1099 your boss might not notice that you are reading news instead of doing
1102 @item gnus-no-groups-message
1103 @vindex gnus-no-groups-message
1104 Message displayed by Gnus when no groups are available.
1107 @node The Group Buffer
1108 @chapter The Group Buffer
1109 @cindex group buffer
1111 The @dfn{group buffer} lists all (or parts) of the available groups. It
1112 is the first buffer shown when Gnus starts, and will never be killed as
1113 long as Gnus is active.
1116 * Group Buffer Format:: Information listed and how you can change it.
1117 * Group Maneuvering:: Commands for moving in the group buffer.
1118 * Selecting a Group:: Actually reading news.
1119 * Subscription Commands:: Unsubscribing, killing, subscribing.
1120 * Group Levels:: Levels? What are those, then?
1121 * Marking Groups:: You can mark groups for later processing.
1122 * Foreign Groups:: How to create foreign groups.
1123 * Group Parameters:: Each group may have different parameters set.
1124 * Listing Groups:: Gnus can list various subsets of the groups.
1125 * Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
1126 * Browse Foreign Server:: You can browse a server. See what if has to offer.
1127 * Exiting Gnus:: Stop reading news and get some work done.
1128 * Group Topics:: A folding group mode divided into topics.
1129 * Misc Group Stuff:: Other stuff that you can to do.
1132 @node Group Buffer Format
1133 @section Group Buffer Format
1134 @cindex group buffer format
1136 The default format of the group buffer is nice and dull, but you can
1137 make it as exciting and ugly as you feel like.
1139 Here's a couple of example group lines:
1142 25: news.announce.newusers
1143 * 0: alt.fan.andrea-dworkin
1148 You can see that there are 25 unread articles in
1149 @samp{news.announce.newusers}. There are no unread articles, but some
1150 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
1151 asterisk at the beginning of the line?)
1153 @vindex gnus-group-line-format
1154 You can fuck that up to your heart's delight by fiddling with the
1155 @code{gnus-group-line-format} variable. This variable works along the
1156 lines of a @code{format} specification, which is pretty much the same as
1157 a @code{printf} specifications, for those of you who use (feh!) C.
1159 (All these format variables can also be random elisp forms. In that
1160 case, they will be @code{eval}ed to insert the required lines.)
1162 (All these format variables can also be random elisp forms. In that
1163 case, they will be @code{eval}ed to insert the required lines.)
1165 In addition to the normal "padding" specs that @code{format} supports
1166 (eg. @samp{%7d}), specifications like @samp{%7,12s} are allowed. A spec
1167 of this type means that the field will be at least 7 characters long,
1168 and never more that 12 characters long.
1170 The default value that produced those lines above is
1171 @samp{"%M%S%5y: %(%g%)\n"}.
1173 There should always be a colon on the line; the cursor always moves to
1174 the colon after performing an operation. Nothing else is required---not
1175 even the group name. All displayed text is just window dressing, and is
1176 never examined by Gnus. Gnus stores all real information it needs using
1179 (Note that if you make a really strange, wonderful, spreadsheet-like
1180 layout, everybody will believe you are hard at work with the accounting
1181 instead of wasting time reading news.)
1183 Here's a list of all available format characters:
1187 Only marked articles.
1189 Whether the group is subscribed.
1191 Level of subscribedness.
1193 Number of unread articles.
1195 Number of dormant articles.
1197 Number of ticked articles.
1199 Number of read articles.
1201 Total number of articles.
1203 Number of unread, unticked, non-dormant articles.
1205 Number of ticked and dormant articles.
1211 Newsgroup description.
1221 A string that looks like @samp{<%s:%n>} if a foreign select method is
1224 User defined specifier. The next character in the format string should
1225 be a letter. @sc{gnus} will call the function
1226 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
1227 following @samp{%u}. The function will be passed the current headers as
1228 argument. The function should return a string, which will be inserted
1229 into the buffer just like information from any other specifier.
1233 All the "number-of" specs will be filled with an asterisk (@samp{*}) if
1234 no info is available---for instance, if it is a non-activated foreign
1235 group, or a bogus (or semi-bogus) native group.
1237 @vindex gnus-group-mode-line-format
1238 The mode line can be changed by setting
1239 (@code{gnus-group-mode-line-format}). It doesn't understand that many
1244 Default news server.
1246 Default select method.
1249 @node Group Maneuvering
1250 @section Group Maneuvering
1251 @cindex group movement
1253 All movement commands understand the numeric prefix and will behave as
1254 expected, hopefully.
1259 @findex gnus-group-next-unread-group
1260 Go to the next group that has unread articles
1261 (@code{gnus-group-next-unread-group}).
1266 @findex gnus-group-prev-unread-group
1267 Go to the previous group group that has unread articles
1268 (@code{gnus-group-prev-unread-group}).
1271 @findex gnus-group-next-group
1272 Go to the next group (@code{gnus-group-next-group}).
1275 @findex gnus-group-prev-group
1276 Go to the previous group (@code{gnus-group-prev-group}).
1279 @findex gnus-group-next-unread-group-same-level
1280 Go to the next unread group on the same level (or lower)
1281 (@code{gnus-group-next-unread-group-same-level}).
1284 @findex gnus-group-prev-unread-group-same-level
1285 Go to the previous unread group on the same level (or lower)
1286 (@code{gnus-group-prev-unread-group-same-level}).
1289 Three commands for jumping to groups:
1294 @findex gnus-group-jump-to-group
1295 Jump to a group (and make it visible if it isn't already)
1296 (@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
1300 @findex gnus-group-best-unread-group
1301 Jump to the unread group with the lowest level
1302 (@code{gnus-group-best-unread-group}).
1305 @findex gnus-group-first-unread-group
1306 Jump to the first group with unread articles
1307 (@code{gnus-group-first-unread-group}).
1310 @vindex gnus-group-goto-unread
1311 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
1312 commands will move to the next group, not the next unread group. Even
1313 the commands that say they move to the next unread group. The default
1316 @node Selecting a Group
1317 @section Selecting a Group
1318 @cindex group selection
1323 @kindex SPACE (Group)
1324 @findex gnus-group-read-group
1325 Select the current group, switch to the summary buffer and display the
1326 first unread article (@code{gnus-group-read-group}). If there are no
1327 unread articles in the group, or if you give a non-numerical prefix to
1328 this command, Gnus will offer to fetch all the old articles in this
1329 group from the server. If you give a numerical prefix @var{N}, Gnus
1330 will fetch @var{N} number of articles. If @var{N} is positive, fetch
1331 the @var{N} newest articles, if @var{N} is negative, fetch the
1332 @var{abs(N)} oldest articles.
1336 @findex gnus-group-select-group
1337 Select the current group and switch to the summary buffer
1338 (@code{gnus-group-select-group}). Takes the same arguments as
1339 @code{gnus-group-read-group}---the only difference is that this command
1340 does not display the first unread article automatically upon group
1344 @kindex M-RET (Group)
1345 @findex gnus-group-quick-select-group
1346 This does the same as the command above, but tries to do it with the
1347 minimum amount off fuzz (@code{gnus-group-quick-select-group}). No
1348 scoring/killing will be performed, there will be no highlights and no
1349 expunging. This might be useful if you're in a real hurry and have to
1350 enter some humongous groups.
1354 @findex gnus-group-catchup-current
1355 Mark all unticked articles in this group as read
1356 (@code{gnus-group-catchup-current}).
1360 @findex gnus-group-catchup-current-all
1361 Mark all articles in this group, even the ticked ones, as read
1362 (@code{gnus-group-catchup-current-all}).
1365 @vindex gnus-large-newsgroup
1366 The @code{gnus-large-newsgroup} variable says what Gnus should consider
1367 to be a big group. This is 200 by default. If the group has more
1368 unread articles than this, Gnus will query the user before entering the
1369 group. The user can then specify how many articles should be fetched
1370 from the server. If the user specifies a negative number (@samp{-n}),
1371 the @samp{n} oldest articles will be fetched. If it is positive, the
1372 @samp{n} articles that have arrived most recently will be fetched.
1374 @vindex gnus-select-group-hook
1375 @vindex gnus-auto-select-first
1376 If @code{gnus-auto-select-first} is non-@code{nil}, the first unread
1377 article in the group will be displayed when you enter the group. If you
1378 want to prevent automatic selection in some group (say, in a binary
1379 group with Huge articles) you can set this variable to @code{nil} in
1380 @code{gnus-select-group-hook}, which is called when a group is selected.
1382 @findex gnus-thread-sort-by-total-score
1383 @findex gnus-thread-sort-by-date
1384 @findex gnus-thread-sort-by-score
1385 @findex gnus-thread-sort-by-subject
1386 @findex gnus-thread-sort-by-author
1387 @findex gnus-thread-sort-by-number
1388 @vindex gnus-thread-sort-functions
1389 If you are using a threaded summary display, you can sort the threads by
1390 setting @code{gnus-thread-sort-functions}, which is a list of functions.
1391 By default, sorting is done on article numbers. Ready-made sorting
1392 functions include @code{gnus-thread-sort-by-number},
1393 @code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
1394 @code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score},
1395 @code{gnus-thread-sort-by-total-score}.
1397 Each function takes two threads and return non-@code{nil} if the first
1398 thread should be sorted before the other. If you use more than one
1399 function, the primary sort key should be the last function in the list.
1401 If you would like to sort by score, then by subject, and finally by
1402 date, you could do something like:
1405 (setq gnus-thread-sort-functions
1406 '(gnus-thread-sort-by-date
1407 gnus-thread-sort-by-subject
1408 gnus-thread-sort-by-score))
1411 @vindex gnus-thread-score-function
1412 The function in the @code{gnus-thread-score-function} variable (default
1413 @code{+}) is used for calculating the total score of a thread. Useful
1414 functions might be @code{max}, @code{min}, or squared means, or whatever
1417 @node Subscription Commands
1418 @section Subscription Commands
1426 @findex gnus-group-unsubscribe-current-group
1427 Toggle subscription to the current group
1428 (@code{gnus-group-unsubscribe-current-group}).
1433 @findex gnus-group-unsubscribe-group
1434 Prompt for a group to subscribe, and then subscribe it. If it was
1435 subscribed already, unsubscribe it instead
1436 (@code{gnus-group-unsubscribe-group}).
1441 @findex gnus-group-kill-group
1442 Kill the current group (@code{gnus-group-kill-group}).
1447 @findex gnus-group-yank-group
1448 Yank the last killed group (@code{gnus-group-yank-group}).
1453 @findex gnus-group-kill-region
1454 Kill all groups in the region (@code{gnus-group-kill-region}).
1457 @findex gnus-group-kill-all-zombies
1458 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
1461 Also @xref{Group Levels}.
1464 @section Group Levels
1467 All groups have a level of @dfn{subscribedness}. For instance, if a
1468 group is on level 2, it is more subscribed than a group on level 5. You
1469 can ask Gnus to just list groups on a given level or lower
1470 (@pxref{Listing Groups}), or to just check for new articles in groups on
1471 a given level or lower (@pxref{Misc Group Stuff}).
1476 @findex gnus-group-set-current-level
1477 Set the level of the current group. If a numeric prefix is given, the
1478 next @var{n} groups will have their levels set. The user will be
1479 prompted for a level.
1482 @vindex gnus-level-killed
1483 @vindex gnus-level-zombie
1484 @vindex gnus-level-unsubscribed
1485 @vindex gnus-level-subscribed
1486 Gnus considers groups on between levels 1 and
1487 @code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed,
1488 @code{gnus-level-subscribed} (exclusive) and
1489 @code{gnus-level-unsubscribed} (inclusive) (default 7) to be
1490 unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
1491 (default 8) and @code{gnus-level-killed} to be killed (default 9),
1492 completely dead. Gnus treats subscribed and unsubscribed groups exactly
1493 the same, but zombie and killed groups have no information on what
1494 articles you have read, etc, stored. This distinction between dead and
1495 living groups isn't done because it is nice or clever, it is done purely
1496 for reasons of efficiency.
1498 It is recommended that you keep all your mail groups (if any) on quite
1499 low levels (eg. 1 or 2).
1501 If you want to play with the level variables, you should show some care.
1502 Set them once, and don't touch them ever again. Better yet, don't touch
1503 them at all unless you know exactly what you're doing.
1505 @vindex gnus-level-default-unsubscribed
1506 @vindex gnus-level-default-subscribed
1507 Two closely related variables are @code{gnus-level-default-subscribed}
1508 (default 3) and @code{gnus-level-default-unsubscribed} (default 6),
1509 which are the levels that new groups will be put on if they are
1510 (un)subscribed. These two variables should, of course, be inside the
1511 relevant legal ranges.
1513 @vindex gnus-keep-same-level
1514 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
1515 will only move to groups that are of the same level (or lower). In
1516 particular, going from the last article in one group to the next group
1517 will go to the next group of the same level (or lower). This might be
1518 handy if you want to read the most important groups before you read the
1521 @vindex gnus-group-default-list-level
1522 All groups with a level less than or equal to
1523 @code{gnus-group-default-list-level} will be listed in the group buffer
1526 @vindex gnus-group-use-permament-levels
1527 If @code{gnus-group-use-permament-levels} is non-@code{nil}, once you
1528 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
1529 use this level as the "work" level.
1531 @node Marking Groups
1532 @section Marking Groups
1533 @cindex marking groups
1535 If you want to perform some command on several groups, and they appear
1536 subsequently in the group buffer, you would normally just give a
1537 numerical prefix to the command. Most group commands will then do your
1538 bidding on those groups.
1540 However, if the groups are not in sequential order, you can still
1541 perform a command on several groups. You simply mark the groups first
1542 with the process mark and then execute the command.
1550 @findex gnus-group-mark-group
1551 Set the mark on the current group (@code{gnus-group-mark-group}).
1557 @findex gnus-group-unmark-group
1558 Remove the mark from the current group
1559 (@code{gnus-group-unmark-group}).
1563 @findex gnus-group-mark-region
1564 Mark all groups between point and mark (@code{gnus-group-mark-region}).
1567 Also @xref{Process/Prefix}.
1570 @node Foreign Groups
1571 @section Foreign Groups
1572 @cindex foreign groups
1574 A @dfn{foreign group} is a group that is not read by the usual (or
1575 default) means. It could be, for instance, a group from a different
1576 @sc{nntp} server, it could be a virtual group, or it could be your own
1577 personal mail group.
1579 A foreign group (or any group, really) is specified by a @dfn{name} and
1580 a @dfn{select method}. To take the latter first, a select method is a
1581 list where the first element says what backend to use (eg. @code{nntp},
1582 @code{nnspool}, @code{nnml}) and the second element is the @dfn{server
1583 name}. There may be additional elements in the select method, where the
1584 value may have special meaning for the backend in question.
1586 One could say that a select method defines a @dfn{virtual server}---so
1587 we do just that (@pxref{The Server Buffer}).
1589 The @dfn{name} of the group is the name the backend will recognize the
1592 For instance, the group @samp{soc.motss} on the @sc{nntp} server
1593 @samp{some.where.edu} will have the name @samp{soc.motss} and select
1594 method @code{(nntp "some.where.edu")}. Gnus will call this group, in
1595 all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
1596 @code{nntp} backend just knows this group as @samp{soc.motss}.
1598 Here are some commands for making and editing general foreign groups,
1599 and some commands to ease the creation of some special-purpose groups:
1604 @findex gnus-group-make-group
1605 Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
1606 for a name, a method and possibly an @dfn{address}. For an easier way
1607 to subscribe to @sc{nntp} groups, @xref{Browse Foreign Server}.
1611 @findex gnus-group-rename-group
1612 Rename the current group to something else
1613 (@code{gnus-group-rename-group}). This is legal only on some groups --
1614 mail groups mostly. This command might very well be quite slow on some
1619 @findex gnus-group-edit-group-method
1620 Enter a buffer where you can edit the select method of the current
1621 group (@code{gnus-group-edit-group-method}).
1625 @findex gnus-group-edit-group-parameters
1626 Enter a buffer where you can edit the group parameters
1627 (@code{gnus-group-edit-group-parameters}).
1631 @findex gnus-group-edit-group
1632 Enter a buffer where you can edit the group info
1633 (@code{gnus-group-edit-group}).
1637 @findex gnus-group-make-directory-group
1638 Make a directory group. You will be prompted for a directory name
1639 (@code{gnus-group-make-directory-group}).
1643 @findex gnus-group-make-help-group
1644 Make the Gnus help group (@code{gnus-group-make-help-group}).
1648 @findex gnus-group-make-archive-group
1649 @vindex gnus-group-archive-directory
1650 @vindex gnus-group-recent-archive-directory
1651 Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
1652 default a group pointing to the most recent articles will be created
1653 (@code{gnus-group-recent-archibe-directory}), but given a prefix, a full
1654 group will be created from from @code{gnus-group-archive-directory}.
1658 @findex gnus-group-make-kiboze-group
1659 Make a kiboze group. You will be prompted for a name, for a regexp to
1660 match groups to be "included" in the kiboze group, and a series of
1661 strings to match on headers (@code{gnus-group-make-kiboze-group}).
1665 @findex gnus-group-enter-directory
1666 Read a random directory as if with were a newsgroup with the
1667 @code{nneething} backend (@code{gnus-group-enter-directory}).
1671 @findex gnus-group-make-doc-group
1672 Make a group based on some file or other
1673 (@code{gnus-group-make-doc-group}). You will be prompted for a file
1674 name and a file type. Currently supported types are @code{babyl},
1675 @code{mbox} and @code{digest}.
1678 @kindex G DEL (Group)
1679 @findex gnus-group-delete-group
1680 This function will delete the current group
1681 (@code{gnus-group-delete-group}). If given a prefix, this function will
1682 actually delete all the articles in the group, and forcibly remove the
1683 group itself from the face of the Earth. Use a prefix only if you are
1684 sure of what you are doing.
1688 @findex gnus-group-make-empty-virtual
1689 Make a new, fresh, empty @code{nnvirtual} group
1690 (@code{gnus-group-make-empty-virtual}).
1694 @findex gnus-group-add-to-virtual
1695 Add the current group to an @code{nnvirtual} group
1696 (@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
1699 The different methods all have their peculiarities, of course.
1702 * nntp:: Reading news from a different @sc{nntp} server.
1703 * nnspool:: Reading news from the local spool.
1704 * nnvirtual:: Combining articles from many groups.
1705 * nnkiboze:: Looking through parts of the newsfeed for articles.
1706 * nndir:: You can read a directory as if it was a newsgroup.
1707 * nneething:: Dired? Who needs dired?
1708 * nndoc:: Single files can be the basis of a group.
1709 * Reading Mail:: Reading your personal mail with Gnus.
1712 @vindex gnus-activate-foreign-newsgroups
1713 If the @code{gnus-activate-foreign-newsgroups} is a positive number,
1714 Gnus will check all foreign groups with this level or lower at startup.
1715 This might take quite a while, especially if you subscribe to lots of
1716 groups from different @sc{nntp} servers.
1722 Subscribing to a foreign group from an @sc{nntp} server is rather easy.
1723 You just specify @code{nntp} as method and the address of the @sc{nntp}
1724 server as the, uhm, address.
1726 If the @sc{nntp} server is located at a non-standard port, setting the
1727 third element of the select method to this port number should allow you
1728 to connect to the right port. You'll have to edit the group info for
1729 that (@pxref{Foreign Groups}).
1731 The name of the foreign group can be the same as a native group. In
1732 fact, you can subscribe to the same group from as many different servers
1733 you feel like. There will be no name collisions.
1735 The following variables can be used to create a virtual @code{nntp}
1739 @item nntp-server-opened-hook
1740 @vindex nntp-server-opened-hook
1741 @cindex @sc{mode reader}
1743 @cindex authentification
1744 @cindex nntp authentification
1745 @findex nntp-send-authinfo
1746 @findex nntp-send-mode-reader
1747 @code{nntp-server-opened-hook} is run after a connection has been made.
1748 It can be used to send commands to the @sc{nntp} server after it has
1749 been contacted. By default is sends the command @samp{MODE READER} to
1750 the server with the @code{nntp-send-mode-reader} function. Another
1751 popular function is @code{nntp-send-authinfo}, which will prompt you for
1752 an @sc{nntp} password and stuff.
1754 @item nntp-maximum-request
1755 @vindex nntp-maximum-request
1756 If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
1757 will collect headers by sending a series of @code{head} commands. To
1758 speed things up, the backend sends lots of these commands without
1759 waiting for reply, and then reads all the replies. This is controlled
1760 by the @code{nntp-maximum-request} variable, and is 400 by default. If
1761 your network is buggy, you should set this to 1.
1763 @item nntp-connection-timeout
1764 @vindex nntp-connection-timeout
1765 If you have lots of foreign @code{nntp} groups that you connect to
1766 regularly, you're sure to have problems with @sc{nntp} servers not
1767 responding properly, or being too loaded to reply within reasonable
1768 time. This is can lead to awkward problems, which can be helped
1769 somewhat by setting @code{nntp-connection-timeout}. This is an integer
1770 that says how many seconds the @code{nntp} backend should wait for a
1771 connection before giving up. If it is @code{nil}, which is the default,
1772 no timeouts are done.
1774 @item nntp-server-hook
1775 @vindex nntp-server-hook
1776 This hook is run as the last step when connecting to an @sc{nntp}
1779 @c @findex nntp-open-rlogin
1780 @c @findex nntp-open-network-stream
1781 @c @item nntp-open-server-function
1782 @c @vindex nntp-open-server-function
1783 @c This function is used to connect to the remote system. Two pre-made
1784 @c functions are @code{nntp-open-network-stream}, which is the default, and
1785 @c simply connects to some port or other on the remote system. The other
1786 @c is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
1787 @c and then does a telnet to the @sc{nntp} server available there.
1789 @c @item nntp-rlogin-parameters
1790 @c @vindex nntp-rlogin-parameters
1791 @c If you use @code{nntp-open-rlogin} as the
1792 @c @code{nntp-open-server-function}, this list will be used as the
1793 @c parameter list given to @code{rsh}.
1795 @c @item nntp-rlogin-user-name
1796 @c @vindex nntp-rlogin-user-name
1797 @c User name on the remote system when using the @code{rlogin} connect
1801 @vindex nntp-address
1802 The address of the remote system running the @sc{nntp} server.
1804 @item nntp-port-number
1805 @vindex nntp-port-number
1806 Port number to connect to when using the @code{nntp-open-network-stream}
1809 @item nntp-buggy-select
1810 @vindex nntp-buggy-select
1811 Set this to non-@code{nil} if your select routine is buggy.
1813 @item nntp-nov-is-evil
1814 @vindex nntp-nov-is-evil
1815 If the @sc{nntp} server does not support @sc{nov}, you could set this
1816 variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
1817 can be used automatically.
1819 @item nntp-xover-commands
1820 @vindex nntp-xover-commands
1821 List of strings that are used as commands to fetch @sc{nov} lines from a
1822 server. The default value of this variable is @code{("XOVER"
1826 @vindex nntp-nov-gap
1827 @code{nntp} normally sends just one big request for @sc{nov} lines to
1828 the server. The server responds with one huge list of lines. However,
1829 if you have read articles 2-5000 in the group, and only want to read
1830 article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
1831 lines that you do not want, and will not use. This variable says how
1832 big a gap between two consecutive articles is allowed to be before the
1833 @code{XOVER} request is split into several request. Note that if your
1834 network is fast, setting this variable to a really small number means
1835 that fetching will probably be slower. If this variable is @code{nil},
1836 @code{nntp} will never split requests.
1838 @item nntp-prepare-server-hook
1839 @vindex nntp-prepare-server-hook
1840 A hook run before attempting to connect to an @sc{nntp} server.
1842 @item nntp-async-number
1843 @vindex nntp-async-number
1844 How many articles should be pre-fetched when in asynchronous mode. If
1845 this variable is @code{t}, @code{nntp} will pre-fetch all the articles
1846 that it can without bound. If it is @code{nil}, no pre-fetching will be
1849 @item nntp-warn-about-losing-connection
1850 @vindex nntp-warn-about-losing-connection
1851 If this variable is non-@code{nil}, some noise will be made when a
1852 server closes connection.
1859 @cindex @code{nnspool}
1862 Subscribing to a foreign group from the local spool is extremely easy,
1863 and might be useful, for instance, to speed up reading groups like
1864 @samp{alt.binaries.pictures.furniture}.
1866 Anyways, you just specify @code{nnspool} as the method and @samp{""} (or
1867 anything else) as the address.
1869 If you have access to a local spool, you should probably use that as the
1870 native select method (@pxref{Finding the News}).
1873 @item nnspool-inews-program
1874 @vindex nnspool-inews-program
1875 Program used to post an article.
1877 @item nnspool-inews-switches
1878 @vindex nnspool-inews-switches
1879 Parameters given to the inews program when posting an article.
1881 @item nnspool-spool-directory
1882 @vindex nnspool-spool-directory
1883 Where @code{nnspool} looks for the articles. This is normally
1884 @file{/usr/spool/news/}.
1886 @item nnspool-nov-directory
1887 @vindex nnspool-nov-directory
1888 Where @code{nnspool} will look for @sc{nov} files. This is normally
1889 @file{/usr/spool/news/over.view/}.
1891 @item nnspool-lib-dir
1892 @vindex nnspool-lib-dir
1893 Where the news lib dir is (@file{/usr/lib/news/} by default).
1895 @item nnspool-active-file
1896 @vindex nnspool-active-file
1897 The path of the active file.
1899 @item nnspool-newsgroups-file
1900 @vindex nnspool-newsgroups-file
1901 The path of the group description file.
1903 @item nnspool-history-file
1904 @vindex nnspool-history-file
1905 The path of the news history file.
1907 @item nnspool-active-times-file
1908 @vindex nnspool-active-times-file
1909 The path of the active date file.
1911 @item nnspool-nov-is-evil
1912 @vindex nnspool-nov-is-evil
1913 If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
1916 @item nnspool-sift-nov-with-sed
1917 @vindex nnspool-sift-nov-with-sed
1918 If non-@code{nil}, which is the default, use @code{sed} to get the
1919 relevant portion from the overview file. If nil, @code{nnspool} will
1920 load the entire file into a buffer and process it there.
1925 @subsection nnvirtual
1926 @cindex @code{nnvirtual}
1927 @cindex virtual groups
1929 An @dfn{nnvirtual group} is really nothing more than a collection of
1932 For instance, if you are tired of reading many small group, you can
1933 put them all in one big group, and then grow tired of reading one
1934 big, unwieldy group. The joys of computing!
1936 You specify @code{nnvirtual} as the method. The address should be a
1937 regexp to match component groups.
1939 All marks in the virtual group will stick to the articles in the
1940 component groups. So if you tick an article in a virtual group, the
1941 article will also be ticked in the component group from whence it came.
1942 (And vice versa---marks from the component groups will also be shown in
1945 Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
1946 newsgroups into one, big, happy newsgroup:
1949 (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
1952 The component groups can be native or foreign; everything should work
1953 smoothly, but if your computer explodes, it was probably my fault.
1955 Collecting the same group from several servers might actually be a good
1956 idea if users have set the Distribution header to limit distribution.
1957 If you would like to read @samp{soc.motss} both from a server in Japan
1958 and a server in Norway, you could use the following as the group regexp:
1961 "^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
1964 This should work kinda smoothly---all articles from both groups should
1965 end up in this one, and there should be no duplicates. Threading (and
1966 the rest) will still work as usual, but there might be problems with the
1967 sequence of articles. Sorting on date might be an option here
1968 (@pxref{Selecting a Group}.
1970 One limitation, however---all groups that are included in a virtual
1971 group has to be alive (i.e., subscribed or unsubscribed). Killed or
1972 zombie groups can't be component groups for @code{nnvirtual} groups.
1975 @subsection nnkiboze
1976 @cindex @code{nnkiboze}
1979 @dfn{Kibozing} is defined by @sc{oed} as "grepping through (parts of)
1980 the news feed". @code{nnkiboze} is a backend that will do this for you. Oh
1981 joy! Now you can grind any @sc{nntp} server down to a halt with useless
1982 requests! Oh happiness!
1984 The address field of the @code{nnkiboze} method is, as with @code{nnvirtual}, a regexp
1985 to match groups to be "included" in the @code{nnkiboze} group. There most
1986 similarities between @code{nnkiboze} and @code{nnvirtual} ends.
1988 In addition to this regexp detailing component groups, an @code{nnkiboze} group
1989 must have a score file to say what articles that are to be included in
1990 the group (@pxref{Scoring}).
1992 @kindex M-x nnkiboze-generate-groups
1993 @findex nnkiboze-generate-groups
1994 You must run @kbd{M-x nnkiboze-generate-groups} after creating the
1995 @code{nnkiboze} groups you want to have. This command will take time. Lots of
1996 time. Oodles and oodles of time. Gnus has to fetch the headers from
1997 all the articles in all the components groups and run them through the
1998 scoring process to determine if there are any articles in the groups
1999 that are to be part of the @code{nnkiboze} groups.
2001 Please limit the number of component groups by using restrictive
2002 regexps. Otherwise your sysadmin may become annoyed with you, and the
2003 @sc{nntp} site may throw you off and never let you back in again.
2004 Stranger things have happened.
2006 @code{nnkiboze} component groups do not have to be alive---they can be dead,
2007 and they can be foreign. No restrictions.
2009 @vindex nnkiboze-directory
2010 The generation of an @code{nnkiboze} group means writing two files in
2011 @code{nnkiboze-directory}, which is @file{~/News/} by default. One
2012 contains the @sc{nov} header lines for all the articles in the group,
2013 and the other is an additional @file{.newsrc} file to store information
2014 on what groups that have been searched through to find component
2017 Articles that are marked as read in the @code{nnkiboze} group will have their
2018 @sc{nov} lines removed from the @sc{nov} file.
2022 @cindex @code{nndir}
2023 @cindex directory groups
2025 If you have a directory that has lots of articles in separate files in
2026 it, you might treat it as a newsgroup. The files have to have numerical
2029 This might be an opportune moment to mention @code{ange-ftp}, that most
2030 wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
2031 didn't think much about it---a backend to read directories. Big deal.
2033 @code{ange-ftp} changes that picture dramatically. For instance, if you
2034 enter @file{"/ftp@@sina.tcamc.uh.edu:/pub/emacs/ding-list/"} as the the
2035 directory name, ange-ftp will actually allow you to read this directory
2036 over at @samp{sina} as a newsgroup. Distributed news ahoy!
2038 @code{nndir} will use @sc{nov} files if they are present.
2040 @code{nndir} is a "read-only" backend---you can't delete or expire
2041 articles with this method. You can use @code{nnmh} or @code{nnml} for
2042 whatever you use @code{nndir} for, so you could switch to any of those
2043 methods if you feel the need to have a non-read-only @code{nndir}.
2046 @subsection nneething
2047 @cindex @code{nneething}
2049 From the @code{nndir} backend (which reads a single spool-like
2050 directory), it's just a hop and a skip to @code{nneething}, which
2051 pretends that any random directory is a newsgroup. Strange, but true.
2053 When @code{nneething} is presented with a directory, it will scan this
2054 directory and assign article numbers to each file. When you enter such a
2055 group, @code{nneething} must create "headers" that Gnus can use. After
2056 all, Gnus is a newsreader, in case you're forgetting. @code{nneething}
2057 does this in a two-step process. First, it snoops each file in question.
2058 If the file looks like an article (i.e., the first few lines look like
2059 headers), it will use this as the head. If this is just some random file
2060 without a head (eg. a C source file), @code{nneething} will cobble up a
2061 header out of thin air. It will use file ownership, name and date and do
2062 whatever it can with these elements.
2064 All this should happen automatically for you, and you will be presented
2065 with something that looks very much like a newsgroup. Totally like a
2066 newsgroup, to be precise. If you select an article, it will be displayed
2067 in the article buffer, just as usual.
2069 If you select a line that represents a directory, Gnus will pop you into
2070 a new summary buffer for this @code{nneething} group. And so on. You can
2071 traverse the entire disk this way, if you feel like, but remember that
2072 Gnus is not dired, really, and does not intend to be, either.
2074 There are two overall modes to this action---ephemeral or solid. When
2075 doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
2076 will not store information on what files you have read, and what files
2077 are new, and so on. If you create a solid @code{nneething} group the
2078 normal way with @kbd{G m}, Gnus will store a mapping table between
2079 article numbers and file names, and you can treat this group like any
2080 other groups. When you activate a solid @code{nneething} group, you will
2081 be told how many unread articles it contains, etc., etc.
2086 @item nneething-map-file-directory
2087 @vindex nneething-map-file-directory
2088 All the mapping files for solid @code{nneething} groups will be stored
2089 in this directory, which defaults to @file{~/.nneething/}.
2091 @item nneething-exclude-files
2092 @vindex nneething-exclude-files
2093 All files that match this regexp will be ignored. Nice to use to exclude
2094 auto-save files and the like, which is what it does by default.
2096 @item nneething-map-file
2097 @vindex nneething-map-file
2098 Name of the map files.
2104 @cindex @code{nndoc}
2105 @cindex documentation group
2108 @code{nndoc} is a cute little thing that will let you read a single file as a
2109 newsgroup. Currently supported file types are @code{babyl}, @code{mbox}
2112 @code{nndoc} will not try to change the file or insert any extra headers into
2113 it---it will simply, like, let you use the file as the basis for a
2114 group. And that's it.
2116 Virtual server variables:
2119 @item nndoc-article-type
2120 @vindex nndoc-article-type
2121 This should be one of @code{mbox}, @code{babyl} or @code{digest}.
2125 @subsection Reading Mail
2126 @cindex reading mail
2129 Reading mail with a newsreader---isn't that just plain WeIrD? But of
2132 Gnus will read the mail spool when you activate a mail group. The mail
2133 file is first copied to your home directory. What happens after that
2134 depends on what format you want to store your mail in.
2137 * Creating Mail Groups:: How to create mail groups.
2138 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
2139 * Mail & Procmail:: Reading mail groups that procmail create.
2140 * Expiring Old Mail Articles:: Getting rid of unwanted mail.
2141 * Not Reading Mail:: Using mail backends for reading other files.
2142 * nnmbox:: Using the (quite) standard Un*x mbox.
2143 * nnbabyl:: Emacs programs use the rmail babyl format.
2144 * nnml:: Store your mail in a private spool?
2145 * nnmh:: An mhspool-like backend.
2146 * nnfolder:: Having one file for each group.
2149 @vindex nnmail-read-incoming-hook
2150 The mail backends all call @code{nnmail-read-incoming-hook} after
2151 reading new mail. You can use this hook to notify any mail watch
2152 programs, if you want to.
2154 @vindex nnmail-spool-file
2155 @code{nnmail-spool-file} says where to look for new mail. If this
2156 variable is @code{nil}, the mail backends will never attempt to fetch
2157 mail by themselves. It is quite likely that Gnus supports POP-mail.
2158 Set this variable to begin with the string @samp{po:}, and everything
2159 should go smoothly, even though I have never tested this.
2161 @vindex nnmail-use-procmail
2162 If @code{nnmail-use-procmail} is non-@code{nil}, the mail backends will
2163 look in @code{nnmail-procmail-directory} for incoming mail. All the
2164 files in that directory that have names ending in
2165 @code{gnus-procmail-suffix} will be considered incoming mailboxes, and
2166 will be searched for new mail.
2168 @vindex nnmail-prepare-incoming-hook
2169 @code{nnmail-prepare-incoming-hook} is run in a buffer that holds all
2170 the new incoming mail, and can be used for, well, anything, really.
2172 @vindex nnmail-tmp-directory
2173 @code{nnmail-tmp-directory} says where to move the incoming mail to
2174 while processing it. This is usually done in the same directory that
2175 the mail backend inhabits (i.e., @file{~/Mail/}), but if this variable is
2176 non-@code{nil}, it will be used instead.
2178 @vindex nnmail-movemail-program
2179 @code{nnmail-movemail-program} is executed to move mail from the user's
2180 inbox to her home directory. The default is @samp{"movemail"}.
2182 @vindex nnmail-delete-incoming
2183 If @code{nnmail-delete-incoming} is non-@code{nil}, the mail backends
2184 will delete the temporary incoming file after splitting mail into the
2185 proper groups. This is @code{nil} by default for reasons of security.
2187 @vindex nnmail-message-id-cache-length
2188 @vindex nnmail-message-id-cache-file
2189 @vindex nnmail-delete-duplicates
2190 @cindex duplicate mails
2191 If you are a member of a couple of mailing list, you will sometime
2192 receive two copies of the same mail. This can be quite annoying, so
2193 @code{nnmail} checks for and discards any duplicates it might find. To
2194 do this, it keeps a cache of old @code{Message-ID}s -
2195 @code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
2196 default. The approximate maximum number of @code{Message-ID}s stored
2197 there is controlled by the @code{nnmail-message-id-cache-length}
2198 variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
2199 stored.) If all this sounds scary to you, you can set
2200 @code{nnmail-delete-duplicates} to @code{nil} (which is what it is by
2201 default), and @code{nnmail} won't do any duplicate checking.
2203 Here's a neat feature: If you know that the recipient reads her mail
2204 with Gnus, and that she has @code{nnmail-delete-duplicates} set to
2205 @code{t}, you can send her as many insults as you like, just by using a
2206 @code{Message-ID} of a mail that you know that she's already received.
2207 Think of all the fun! She'll never see any of it! Whee!
2209 Gnus gives you all the opportunity you could possibly want for shooting
2210 yourself in the foot. Let's say you create a group that will contain
2211 all the mail you get from your boss. And then you accidentally
2212 unsubscribe from the group. Gnus will still put all the mail from your
2213 boss in the unsubscribed group, and so, when your boss mails you "Have
2214 that report ready by Monday or you're fired!", you'll never see it and,
2215 come Tuesday, you'll still believe that you're gainfully employed while
2216 you really should be out collecting empty bottles to save up for next
2219 @node Creating Mail Groups
2220 @subsubsection Creating Mail Groups
2221 @cindex creating mail groups
2223 You can make Gnus read your personal, private, secret mail.
2225 You should first set @code{gnus-secondary-select-methods} to, for
2226 instance, @code{((nnmbox ""))}. When you start up Gnus, Gnus will ask
2227 this backend for what groups it carries (@samp{mail.misc} by default)
2228 and subscribe it the normal way. (Which means you may have to look for
2229 it among the zombie groups, I guess, all depending on your
2230 @code{gnus-subscribe-newsgroup-method} variable.)
2232 @vindex nnmail-split-methods
2233 Then you should set the variable @code{nnmail-split-methods} to specify
2234 how the incoming mail is to be split into groups.
2237 (setq nnmail-split-methods
2238 '(("mail.junk" "^From:.*Lars Ingebrigtsen")
2239 ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
2243 This variable is a list of lists, where the first element of each of
2244 these lists is the name of the mail group (they do not have to be called
2245 something beginning with @samp{mail}, by the way), and the second
2246 element is a regular expression used on the header of each mail to
2247 determine if it belongs in this mail group.
2249 The second element can also be a function. In that case, it will be
2250 called narrowed to the headers with the first element of the rule as the
2251 argument. It should return a non-@code{nil} value if it thinks that the
2252 mail belongs in that group.
2254 The last of these groups should always be a general one, and the regular
2255 expression should @emph{always} be @samp{""} so that it matches any
2256 mails that haven't been matched by any of the other regexps.
2258 If you like to tinker with this yourself, you can set this variable to a
2259 function of your choice. This function will be called without any
2260 arguments in a buffer narrowed to the headers of an incoming mail
2261 message. The function should return a list of groups names that it
2262 thinks should carry this mail message.
2264 @vindex nnmail-crosspost
2265 The mail backends all support cross-posting. If several regexps match,
2266 the mail will be "cross-posted" to all those groups.
2267 @code{nnmail-crosspost} says whether to use this mechanism or not. Note
2268 that no articles are crossposted to the general (@samp{""}) group.
2270 @node Fancy Mail Splitting
2271 @subsubsection Fancy Mail Splitting
2272 @cindex mail splitting
2273 @cindex fancy mail splitting
2275 @vindex nnmail-split-fancy
2276 @findex nnmail-split-fancy
2277 If the rather simple, standard method for specifying how to split mail
2278 doesn't allow you to do what you want, you can set
2279 @code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
2280 play with the @code{nnmail-split-fancy} variable.
2282 Let's look at an example value of this variable first:
2285 ;; Messages from the mailer daemon are not crossposted to any of
2286 ;; the ordinary groups. Warnings are put in a separate group
2287 ;; from real errors.
2288 (| ("from" mail (| ("subject" "warn.*" "mail.warning")
2290 ;; Non-error messages are crossposted to all relevant
2291 ;; groups, but we don't crosspost between the group for the
2292 ;; (ding) list and the group for other (ding) related mail.
2293 (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
2294 ("subject" "ding" "ding.misc"))
2295 ;; Other mailing lists...
2296 (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
2297 (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
2299 (any "larsi@@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
2300 ;; Unmatched mail goes to the catch all group.
2304 This variable has the format of a @dfn{split}. A split is a (possibly)
2305 recursive structure where each split may contain other splits. Here are
2306 the four possible split syntaxes:
2310 If the split is a string, that will be taken as a group name.
2311 @item (FIELD VALUE SPLIT)
2312 If the split is a list, and the first element is a string, then that
2313 means that if header FIELD (a regexp) contains VALUE (also a regexp),
2314 then store the message as specified by SPLIT.
2316 If the split is a list, and the first element is @code{|} (vertical
2317 bar), then process each SPLIT until one of them matches. A SPLIT is
2318 said to match if it will cause the mail message to be stored in one or
2321 If the split is a list, and the first element is @code{&}, then process
2322 all SPLITs in the list.
2325 In these splits, FIELD must match a complete field name. VALUE must
2326 match a complete word according to the fundamental mode syntax table.
2327 You can use @code{.*} in the regexps to match partial field names or
2330 @vindex nnmail-split-abbrev-alist
2331 FIELD and VALUE can also be lisp symbols, in that case they are expanded
2332 as specified by the variable @code{nnmail-split-abbrev-alist}. This is
2333 an alist of cons cells, where the car of the cells contains the key, and
2334 the cdr contains a string.
2336 @node Mail & Procmail
2337 @subsubsection Mail & Procmail
2340 Many people use @code{procmail} to split incoming mail into groups. If
2341 you do that, you should set @code{nnmail-spool-file} to @code{procmail}
2342 to ensure that the mail backends never ever try to fetch mail by
2345 This also means that you probably don't want to set
2346 @code{nnmail-split-methods} either, which has some, perhaps, unexpected
2349 When a mail backend is queried for what groups it carries, it replies
2350 with the contents of that variable, along with any groups it has figured
2351 out that it carries by other means. None of the backends (except
2352 @code{nnmh}) actually go out to the disk and check what groups actually
2353 exist. (It's not trivial to distinguish between what the user thinks is
2354 a basis for a newsgroup and what is just a plain old file or directory.)
2356 This means that you have to tell Gnus (and the backends) what groups
2359 Let's take the @code{nnmh} backend as an example.
2361 The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
2362 There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
2364 Go to the group buffer and type @kbd{G m}. When prompted, answer
2365 @samp{foo} for the name and @samp{nnmh} for the method. Repeat
2366 twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
2367 to include all your mail groups.
2369 That's it. You are now set to read your mail. An active file for this
2370 method will be created automatically.
2372 @vindex nnmail-procmail-suffix
2373 @vindex nnmail-procmail-directory
2374 If you use @code{nnfolder} or any other backend that store more than a
2375 single article in each file, you should never have procmail add mails to
2376 the file that Gnus sees. Instead, procmail should put all incoming mail
2377 in @code{nnmail-procmail-directory}. To arrive at the file name to put
2378 the incoming mail in, append @code{nnmail-procmail-suffix} to the group
2379 name. The mail backends will read the mail from these files.
2381 @vindex nnmail-resplit-incoming
2382 When Gnus reads a file called @file{mail.misc.spool}, this mail will be
2383 put in the @code{mail.misc}, as one would expect. However, if you want
2384 Gnus to split the mail the normal way, you could set
2385 @code{nnmail-resplit-incoming} to @code{t}.
2387 @vindex nnmail-keep-last-article
2388 If you use @code{procmail} to split things directory into an @code{nnmh}
2389 directory (which you shouldn't do), you should set
2390 @code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
2391 ever expiring the final article in a mail newsgroup. This is quite,
2395 @node Expiring Old Mail Articles
2396 @subsubsection Expiring Old Mail Articles
2397 @cindex article expiry
2399 Traditional mail readers have a tendency to remove mail articles when
2400 you mark them as read, in some way. Gnus takes a fundamentally
2401 different approach to mail reading.
2403 Gnus basically considers mail just to be news that has been received in
2404 a rather peculiar manner. It does not think that it has the power to
2405 actually change the mail, or delete any mail messages. If you enter a
2406 mail group, and mark articles as "read", or kill them in some other
2407 fashion, the mail articles will still exist on the system. I repeat:
2408 Gnus will not delete your old, read mail. Unless you ask it to, of
2411 To make Gnus get rid of your unwanted mail, you have to mark the
2412 articles as @dfn{expirable}. This does not mean that the articles will
2413 disappear right away, however. In general, a mail article will be
2414 deleted from your system if, 1) it is marked as expirable, AND 2) it is
2415 more than one week old. If you do not mark an article as expirable, it
2416 will remain on your system until hell freezes over. This bears
2417 repeating one more time, with some spurious capitalizations: IF you do
2418 NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
2420 @vindex gnus-auto-expirable-newsgroups
2421 You do not have to mark articles as expirable by hand. Groups that
2422 match the regular expression @code{gnus-auto-expirable-newsgroups} will
2423 have all articles that you read marked as expirable automatically. All
2424 articles that are marked as expirable have an @samp{E} in the first
2425 column in the summary buffer.
2427 Let's say you subscribe to a couple of mailing lists, and you want the
2428 articles you have read to disappear after a while:
2431 (setq gnus-auto-expirable-newsgroups
2432 "mail.nonsense-list\\|mail.nice-list")
2435 Another way to have auto-expiry happen is to have the element
2436 @code{auto-expire} in the select method of the group.
2438 @vindex nnmail-expiry-wait
2439 The @code{nnmail-expiry-wait} variable supplies the default time an
2440 expirable article has to live. The default is seven days.
2442 Gnus also supplies a function that lets you fine-tune how long articles
2443 are to live, based on what group they are in. Let's say you want to
2444 have one month expiry period in the @samp{mail.private} group, a one day
2445 expiry period in the @samp{mail.junk} group, and a six day expiry period
2449 (setq nnmail-expiry-wait-function
2451 (cond ((string= group "mail.private")
2453 ((string= group "mail.junk")
2459 @vindex nnmail-keep-last-article
2460 If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
2461 expire the final article in a mail newsgroup. This is to make life
2462 easier for procmail users.
2464 @vindex gnus-total-expirable-newsgroups
2465 By the way, that line up there about Gnus never expiring non-expirable
2466 articles is a lie. If you put @code{total-expire} in the group
2467 parameters, articles will not be marked as expirable, but all read
2468 articles will be put through the expiry process. Use with extreme
2469 caution. Even more dangerous is the
2470 @code{gnus-total-expirable-newsgroups} variable. All groups that match
2471 this regexp will have all read articles put through the expiry process,
2472 which means that @emph{all} old mail articles in the groups in question
2473 will be deleted after a while. Use with extreme caution, and don't come
2474 crying to me when you discover that the regexp you used matched the
2475 wrong group and all your important mail has disappeared. Be a
2476 @emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
2480 @node Not Reading Mail
2481 @subsubsection Not Reading Mail
2483 If you start using any of the mail backends, they have the annoying
2484 habit of assuming that you want to read mail with them. This might not
2485 be unreasonable, but it might not be what you want.
2487 If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
2488 will ever attempt to read incoming mail, which should help.
2490 @vindex nnbabyl-get-new-mail
2491 @vindex nnmbox-get-new-mail
2492 @vindex nnml-get-new-mail
2493 @vindex nnmh-get-new-mail
2494 @vindex nnfolder-get-new-mail
2495 This might be too much, if, for instance, you are reading mail quite
2496 happily with @code{nnml} and just want to peek at some old @sc{rmail}
2497 file you have stashed away with @code{nnbabyl}. All backends have
2498 variables called backend-@code{get-new-mail}. If you want to disable
2499 the @code{nnbabyl} mail reading, you edit the virtual server for the
2500 group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
2502 All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
2503 narrowed to the article to be saved before saving it when reading
2507 @subsubsection nnmbox
2508 @cindex @code{nnmbox}
2509 @cindex unix mail box
2511 @vindex nnmbox-active-file
2512 @vindex nnmbox-mbox-file
2513 The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
2514 mail. @code{nnmbox} will add extra headers to each mail article to say
2515 which group it belongs in.
2517 Virtual server settings:
2520 @item nnmbox-mbox-file
2521 @vindex nnmbox-mbox-file
2522 The name of the mail box in the user's home directory.
2524 @item nnmbox-active-file
2525 @vindex nnmbox-active-file
2526 The name of the active file for the mail box.
2528 @item nnmbox-get-new-mail
2529 @vindex nnmbox-get-new-mail
2530 If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
2535 @subsubsection nnbabyl
2536 @cindex @code{nnbabyl}
2539 @vindex nnbabyl-active-file
2540 @vindex nnbabyl-mbox-file
2541 The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
2542 mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
2543 article to say which group it belongs in.
2545 Virtual server settings:
2548 @item nnbabyl-mbox-file
2549 @vindex nnbabyl-mbox-file
2550 The name of the rmail mbox file.
2552 @item nnbabyl-active-file
2553 @vindex nnbabyl-active-file
2554 The name of the active file for the rmail box.
2556 @item nnbabyl-get-new-mail
2557 @vindex nnbabyl-get-new-mail
2558 If non-@code{nil}, @code{nnbabyl} will read incoming mail.
2564 @cindex mail @sc{nov} spool
2566 The @dfn{nnml} spool mail format isn't compatible with any other known
2567 format. It should be used with some caution.
2569 @vindex nnml-directory
2570 If you use this backend, Gnus will split all incoming mail into files;
2571 one file for each mail, and put the articles into the correct
2572 directories under the directory specified by the @code{nnml-directory}
2573 variable. The default value is @file{~/Mail/}.
2575 You do not have to create any directories beforehand; Gnus will take
2578 If you have a strict limit as to how many files you are allowed to store
2579 in your account, you should not use this backend. As each mail gets its
2580 own file, you might very well occupy thousands of inodes within a few
2581 weeks. If this is no problem for you, and it isn't a problem for you
2582 having your friendly systems administrator walking around, madly,
2583 shouting "Who is eating all my inodes?! Who? Who!?!", then you should
2584 know that this is probably the fastest format to use. You do not have
2585 to trudge through a big mbox file just to read your new mail.
2587 @code{nnml} is probably the slowest backend when it comes to article
2588 splitting. It has to create lots of files, and it also generates
2589 @sc{nov} databases for the incoming mails. This makes is the fastest
2590 backend when it comes to reading mail.
2592 Virtual server settings:
2595 @item nnml-directory
2596 @vindex nnml-directory
2597 All @code{nnml} directories will be placed under this directory.
2599 @item nnml-active-file
2600 @vindex nnml-active-file
2601 The active file for the @code{nnml} server.
2603 @item nnml-newsgroups-file
2604 @vindex nnml-newsgroups-file
2605 The @code{nnml} group description file.
2607 @item nnml-get-new-mail
2608 @vindex nnml-get-new-mail
2609 If non-@code{nil}, @code{nnml} will read incoming mail.
2611 @item nnml-nov-is-evil
2612 @vindex nnml-nov-is-evil
2613 If non-@code{nil}, this backend will ignore any @sc{nov} files.
2615 @item nnml-nov-file-name
2616 @vindex nnml-nov-file-name
2617 The name of the @sc{nov} files. The default is @file{.overview}.
2621 @findex nnml-generate-nov-databases
2622 If your @code{nnml} groups and @sc{nov} files get totally out of whack,
2623 you can do a complete update by typing @kbd{M-x
2624 nnml-generate-nov-databases}. This command will trawl through the
2625 entire @code{nnml} hierarchy, looking at each and every article, so it
2626 might take a while to complete.
2631 @cindex mh-e mail spool
2633 @code{nnmh} is just like @code{nnml}, except that is doesn't generate
2634 @sc{nov} databases and it doesn't keep an active file. This makes
2635 @code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
2636 makes it easier to write procmail scripts for.
2638 Virtual server settings:
2641 @item nnmh-directory
2642 @vindex nnmh-directory
2643 All @code{nnmh} directories will be located under this directory.
2645 @item nnmh-get-new-mail
2646 @vindex nnmh-get-new-mail
2647 If non-@code{nil}, @code{nnmh} will read incoming mail.
2650 @vindex nnmh-be-safe
2651 If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
2652 sure that the articles in the folder is actually what Gnus think they
2653 are. It will check date stamps, and stat everything in sight, so
2654 setting this to @code{t} will mean a serious slow-down. If you never
2655 use anything by Gnus to read the @code{nnmh} articles, you do not have to set
2656 this variable to @code{t}.
2660 @subsubsection nnfolder
2661 @cindex @code{nnfolder}
2662 @cindex mbox folders
2664 @code{nnfolder} is a backend for storing each mail group in a separate
2665 file. Each file is in the standard Un*x mbox format. @code{nnfolder}
2666 will add extra headers to keep track of article numbers and arrival
2669 Virtual server settings:
2672 @item nnfolder-directory
2673 @vindex nnfolder-directory
2674 All the @code{nnfolder} mail boxes will be stored under this directory.
2676 @item nnfolder-active-file
2677 @vindex nnfolder-active-file
2678 The name of the active file.
2680 @item nnfolder-newsgroups-file
2681 @vindex nnfolder-newsgroups-file
2682 The name of the group description file.
2684 @item nnfolder-get-new-mail
2685 @vindex nnfolder-get-new-mail
2686 If non-@code{nil}, @code{nnfolder} will read incoming mail.
2690 @node Group Parameters
2691 @section Group Parameters
2692 @cindex group parameters
2694 Gnus stores all information on a group in a list that is usually known
2695 as the @dfn{group info}. This list has from three to six elements.
2696 Here's an example info.
2699 ("nnml:mail.ding" 3 ((1 . 232) 244 (256 . 270)) ((tick 246 249))
2700 (nnml "private") ((to-address . "ding@@ifi.uio.no")))
2703 The first element is the @dfn{group name}, as Gnus knows the group,
2704 anyway. The second element is the @dfn{subscription level}, which
2705 normally is a small integer. The third element is a list of ranges of
2706 read articles. The fourth element is a list of lists of article marks
2707 of various kinds. The fifth element is the select method (or virtual
2708 server, if you like). The sixth element is a list of @dfn{group
2709 parameters}, which is what this section is about.
2711 Any of the last three elements may be missing if they are not required.
2712 In fact, the vast majority of groups will normally only have the first
2713 three elements, which saves quite a lot of cons cells.
2715 The group parameters store information local to a particular group:
2720 If the group parameter list contains an element that looks like
2721 @samp{(to-address . "some@@where.com")}, that address will be used by
2722 the backend when doing followups and posts. This is primarily useful in
2723 mail groups that represent mailing lists. You just set this address to
2724 whatever the list address is.
2726 This trick will actually work whether the group is foreign or not.
2727 Let's say there's a group on the server that is called @samp{fa.4ad-l}.
2728 This is a real newsgroup, but the server has gotten the articles from a
2729 mail-to-news gateway. Posting directly to this group is therefore
2730 impossible---you have to send mail to the mailing list address instead.
2731 Also @xref{Mail & Post}.
2735 If the group parameter list contains an element like @code{(to-group
2736 . "some.group.name")}, all posts will be sent to that group.
2740 If the group parameter list contains an element like @code{(topic
2741 . "some-topic")}, the group will become a member of the topic in
2742 question (@pxref{Group Topics}).
2746 If this symbol is present in the group parameter list, all articles that
2747 are read will be marked as expirable. For an alternative approach,
2748 @xref{Expiring Old Mail Articles}.
2751 @cindex total-expire
2752 If this symbol is present, all read articles will be put through the
2753 expiry process, even if they are not marked as expirable. Use with
2756 @item @var{(variable form)}
2757 You can use the group parameters to set variables local to the group you
2758 are entering. Say you want to turn threading off in
2759 @samp{news.answers}. You'd then put @code{(gnus-show-threads nil)} in
2760 the group parameters of that group. @code{gnus-show-threads} will be
2761 made into a local variable in the summary buffer you enter, and the form
2762 @code{nil} will be @code{eval}ed there.
2764 This can also be used as a group-specific hook function, if you'd like.
2765 If you want to hear a beep when you enter the group
2766 @samp{alt.binaries.pictures.furniture}, you could put something like
2767 @code{(dummy-variable (ding))} in the parameters of that group.
2768 @code{dummy-variable} will be set to the result of the @code{(ding)}
2769 form, but who cares?
2773 If you want to change the group info you can use the @kbd{G E} command
2774 to enter a buffer where you can edit it.
2776 You usually don't want to edit the entire group info, so you'd be better
2777 off using the @kbd{G p} command to just edit the group parameters.
2779 @node Listing Groups
2780 @section Listing Groups
2781 @cindex group listing
2783 These commands all list various slices of the groups that are available.
2791 @findex gnus-group-list-groups
2792 List all groups that have unread articles
2793 (@code{gnus-group-list-groups}). If the numeric prefix is used, this
2794 command will list only groups of level ARG and lower. By default, it
2795 only lists groups of level five or lower (i.e., just subscribed groups).
2801 @findex gnus-group-list-all-groups
2802 List all groups, whether they have unread articles or not
2803 (@code{gnus-group-list-all-groups}). If the numeric prefix is used,
2804 this command will list only groups of level ARG and lower. By default,
2805 it lists groups of level seven or lower (i.e., just subscribed and
2806 unsubscribed groups).
2810 @findex gnus-group-list-killed
2811 List all killed groups (@code{gnus-group-list-killed}). If given a
2812 prefix argument, really list all groups that are available, but aren't
2813 currently (un)subscribed. This could entail reading the active file
2818 @findex gnus-group-list-zombies
2819 List all zombie groups (@code{gnus-group-list-zombies}).
2823 @findex gnus-group-list-matching
2824 List all subscribed groups with unread articles that match a regexp
2825 (@code{gnus-group-list-matching}).
2829 @findex gnus-group-list-all-matching
2830 List groups that match a regexp (@code{gnus-group-list-all-matching}).
2834 @findex gnus-group-list-active
2835 List absolutely all groups that are in the active file(s) of the
2836 server(s) you are connected to (@code{gnus-group-list-active}). This
2837 might very well take quite a while. It might actually be a better idea
2838 to do a @kbd{A m} to list all matching, and just give @samp{.} as the
2843 @node Group Maintenance
2844 @section Group Maintenance
2845 @cindex bogus groups
2850 @findex gnus-group-check-bogus-groups
2851 Find bogus groups and delete them
2852 (@code{gnus-group-check-bogus-groups}).
2855 @findex gnus-find-new-newsgroups
2856 Find new groups and process them (@code{gnus-find-new-newsgroups}).
2858 @kindex C-c C-x (Group)
2859 @findex gnus-group-expire-articles
2860 Run all expirable articles in the current group through the expiry
2861 process (if any) (@code{gnus-group-expire-articles}).
2864 @kindex C-c M-C-x (Group)
2865 @findex gnus-group-expire-all-groups
2866 Run all articles in all groups through the expiry process
2867 (@code{gnus-group-expire-all-groups}).
2870 @kindex C-c C-s (Group)
2871 @findex gnus-group-sort-groups
2872 @vindex gnus-group-sort-function
2873 Sort the groups according to the function given by the
2874 @code{gnus-group-sort-function} variable
2875 (@code{gnus-group-sort-groups}). Available sorting functions include:
2879 @item gnus-group-sort-by-alphabet
2880 @findex gnus-group-sort-by-alphabet
2881 Sort the group names alphabetically. This is the default.
2883 @item gnus-group-sort-by-level
2884 @findex gnus-group-sort-by-level
2885 Sort by group level.
2887 @item gnus-group-sort-by-unread
2888 @findex gnus-group-sort-by-unread
2889 Sort by number of unread articles.
2891 @item gnus-group-sort-by-method
2892 @findex gnus-group-sort-by-method
2893 Sort by alphabetically on the select method.
2897 @code{gnus-group-sort-function} can also be a list of sorting
2898 functions. In that case, the most significant sort key function must be
2902 @node Browse Foreign Server
2903 @section Browse Foreign Server
2904 @cindex foreign servers
2905 @cindex browsing servers
2910 @findex gnus-group-browse-foreign-server
2911 You will be queried for a select method and a server name. Gnus will
2912 then attempt to contact this server and let you browse the groups there
2913 (@code{gnus-group-browse-foreign-server}).
2916 @findex gnus-browse-server-mode
2917 A new buffer with a list of available groups will appear. This buffer
2918 will be use the @code{gnus-browse-server-mode}. This buffer looks a bit
2919 (well, a lot) like a normal group buffer, but with one major difference
2920 - you can't enter any of the groups. If you want to read any of the
2921 news available on that server, you have to subscribe to the groups you
2922 think may be interesting, and then you have to exit this buffer. The
2923 new groups will be added to the group buffer, and then you can read them
2924 as you would any other group.
2926 Future versions of Gnus may possibly permit reading groups straight from
2929 Here's a list of keystrokes available in the browse mode:
2934 @findex gnus-group-next-group
2935 Go to the next group (@code{gnus-group-next-group}).
2939 @findex gnus-group-prev-group
2940 Go to the previous group (@code{gnus-group-prev-group}).
2943 @kindex SPC (Browse)
2944 @findex gnus-browse-read-group
2945 Enter the current group and display the first article
2946 (@code{gnus-browse-read-group}).
2949 @kindex RET (Browse)
2950 @findex gnus-browse-select-group
2951 Enter the current group (@code{gnus-browse-select-group}).
2955 @findex gnus-browse-unsubscribe-current-group
2956 Unsubscribe to the current group, or, as will be the case here,
2957 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
2963 @findex gnus-browse-exit
2964 Exit browse mode (@code{gnus-browse-exit}).
2968 @findex gnus-browse-describe-briefly
2969 Describe browse mode briefly (well, there's not much to describe, is
2970 there) (@code{gnus-browse-describe-briefly}).
2974 @section Exiting Gnus
2975 @cindex exiting Gnus
2977 Yes, Gnus is ex(c)iting.
2982 @findex gnus-group-suspend
2983 Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
2984 but it kills all buffers except the Group buffer. I'm not sure why this
2985 is a gain, but then who am I to judge?
2988 @findex gnus-group-exit
2989 Quit Gnus (@code{gnus-group-exit}).
2992 @findex gnus-group-quit
2993 Quit Gnus without saving any startup files (@code{gnus-group-quit}).
2996 @vindex gnus-exit-gnus-hook
2997 @vindex gnus-suspend-gnus-hook
2998 @code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
2999 @code{gnus-exit-gnus-hook} is called when you quit Gnus.
3003 If you wish to completely unload Gnus and all its adherents, you can use
3004 the @code{gnus-unload} command. This command is also very handy when
3005 trying to custoize meta-variables.
3010 Miss Lisa Cannifax, while sitting in English class, feels her feet go
3011 numbly heavy and herself fall into a hazy trance as the boy sitting
3012 behind her drew repeated lines with his pencil across the back of her
3018 @section Group Topics
3021 If you read lots and lots of groups, it might be convenient to group
3022 them according to topics. You put your Emacs groups over here, your sex
3023 groups over there, and the rest (what, two groups or so?) you put in
3024 some misc section that you never bother with anyway.
3026 To get this @emph{fab} functionality, you set
3027 @code{gnus-group-prepare-function} to @code{gnus-group-prepare-topics}.
3028 Go ahead, just try it. I'll still be here when you get back. La de
3029 dum... Nice tune, that... la la la... What, you're back? Yes, and now
3030 press @kbd{l}. There. All your groups are now listed under
3031 @samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
3034 @vindex gnus-group-topics
3035 To get an even more exciting division, you have to fiddle with
3036 @code{gnus-group-topics}. That is an alist where each entry looks like
3043 As you've already guessed (only geniï read manuals anyway), all
3044 groups that match @var{regexp} gets put into a section called
3045 @var{topic}. If @var{show} is non-@code{nil}, it overrides
3046 @code{gnus-group-topic-topics-only}. In specific, if @var{show} is
3047 @code{t}, all groups with this topic are always shown, and if it is a
3048 number, these groups are never shown.
3050 @vindex gnus-group-topic-topics-only
3051 Whoo, this is complicated. If @code{gnus-group-topic-topics-only} is
3052 @code{nil}, all groups and topics will be listed, as you would expect.
3053 If this variable is non-@code{nil}, only the topics will be listed, and
3054 the groups will not be listed. This makes the group buffer much shorter,
3055 I'm sure you'll agree. This is all modified on a topic-by-topic basis
3056 by the @var{show} parameter. It makes perfect sense, really.
3058 @vindex gnus-group-topic-face
3059 Topics are shown with @code{gnus-group-topic-face}.
3061 @vindex gnus-topic-unique
3062 If @code{gnus-topic-unique} is non-@code{nil}, each group will be member
3063 of (tops) one topic each. If this is @code{nil}, each group might end
3064 up being a member of several topics.
3066 You can also put a @code{topic} in the group parameters (@pxref{Group
3069 Now, if you select a topic, if will fold/unfold that topic, which is
3070 really neat, I think.
3072 Here's an example @code{gnus-group-topics}:
3075 (("Emacs - the Spice of Life" "^gnu.emacs\\|comp.emacs" t)
3076 ("Alternativeness" "^alt" 0)
3077 ("Hard Stuff" "^comp" nil)
3078 ("The Rest" "." nil))
3081 If you want to add a group to a topic, you can use the @kbd{G t}
3082 (@code{gnus-group-add-to-topic}) command. It understands the
3083 process/prefix convention (@pxref{Process/Prefix}).
3085 If you want to add a group to a topic, you can use the @kbd{G t}
3086 (@code{gnus-group-add-to-topic}) command. It understands the
3087 process/prefix convention (@pxref{Process/Prefix}).
3090 @node Misc Group Stuff
3091 @section Misc Group Stuff
3097 @findex gnus-group-get-new-news
3098 Check the server(s) for new articles. If the numerical prefix is used,
3099 this command will check only groups of level @var{arg} and lower
3100 (@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
3101 command will force a total rereading of the active file(s) from the
3106 @findex gnus-group-get-new-news-this-group
3107 Check whether new articles have arrived in the current group
3108 (@code{gnus-group-get-new-news-this-group}).
3112 @findex gnus-group-enter-server-mode
3113 Enter the server buffer (@code{gnus-group-enter-server-mode}). @xref{The
3118 @findex gnus-group-fetch-faq
3119 Try to fetch the FAQ for the current group
3120 (@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
3121 @code{gnus-group-faq-directory}, which is usually a directory on a
3122 remote machine. @code{ange-ftp} will be used for fetching the file.
3125 @findex gnus-group-restart
3126 Restart Gnus (@code{gnus-group-restart}).
3129 @findex gnus-group-read-init-file
3130 @vindex gnus-init-file
3131 Read the init file (@code{gnus-init-file}, which defaults to
3132 @file{~/.gnus}) (@code{gnus-group-read-init-file}).
3135 @findex gnus-group-save-newsrc
3136 Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
3137 (@code{gnus-group-save-newsrc}).
3140 @findex gnus-group-clear-dribble
3141 Clear the dribble buffer (@code{gnus-group-clear-dribble}).
3144 @findex gnus-group-describe-group
3145 Describe the current group (@code{gnus-group-describe-group}). If given
3146 a prefix, force Gnus to re-read the description from the server.
3149 @findex gnus-group-apropos
3150 List all groups that have names that match a regexp
3151 (@code{gnus-group-apropos}).
3154 @findex gnus-group-description-apropos
3155 List all groups that have names or descriptions that match a regexp
3156 (@code{gnus-group-description-apropos}).
3159 @findex gnus-group-post-news
3160 Post an article to a group (@code{gnus-group-post-news}).
3163 @findex gnus-group-mail
3164 Mail a message somewhere (@code{gnus-group-mail}).
3166 @kindex C-x C-t (Group)
3167 @findex gnus-group-transpose-groups
3168 Transpose two groups (@code{gnus-group-transpose-groups}).
3171 @findex gnus-version
3172 Display current Gnus version numbers (@code{gnus-version}).
3175 @findex gnus-group-describe-all-groups
3176 Describe all groups (@code{gnus-group-describe-all-groups}). If given a
3177 prefix, force Gnus to re-read the description file from the server.
3180 @findex gnus-group-describe-briefly
3181 Give a very short help message (@code{gnus-group-describe-briefly}).
3183 @kindex C-c C-i (Group)
3184 @findex gnus-info-find-node
3185 Go to the Gnus info node (@code{gnus-info-find-node}).
3188 @vindex gnus-group-prepare-hook
3189 @code{gnus-group-prepare-hook} is called after the group buffer is
3190 generated. It may be used to modify the buffer in some strange,
3193 @node The Summary Buffer
3194 @chapter The Summary Buffer
3195 @cindex summary buffer
3197 A line for each article is displayed in the summary buffer. You can
3198 move around, read articles, post articles and reply to articles.
3201 * Summary Buffer Format:: Deciding how the summary buffer is to look.
3202 * Summary Maneuvering:: Moving around the summary buffer.
3203 * Choosing Articles:: Reading articles.
3204 * Paging the Article:: Scrolling the current article.
3205 * Reply Followup and Post:: Posting articles.
3206 * Canceling and Superseding:: "Whoops, I shouldn't have called him that."
3207 * Marking Articles:: Marking articles as read, expirable, etc.
3208 * Limiting:: You can limit the summary buffer.
3209 * Threading:: How threads are made.
3210 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
3211 * Article Caching:: You may store articles in a cache.
3212 * Article Backlog:: Having already read articles hang around.
3213 * Exiting the Summary Buffer:: Returning to the Group buffer.
3214 * Process/Prefix:: A convention used by many treatment commands.
3215 * Saving Articles:: Ways of customizing article saving.
3216 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
3217 * Article Treatment:: The article buffer can be mangled at will.
3218 * Summary Sorting:: You can sort the summary buffer four ways.
3219 * Finding the Parent:: No child support? Get the parent.
3220 * Mail Group Commands:: Some commands can only be used in mail groups.
3221 * Various Summary Stuff:: What didn't fit anywhere else.
3225 @node Summary Buffer Format
3226 @section Summary Buffer Format
3227 @cindex summary buffer format
3230 * Summary Buffer Lines:: You can specify how summary lines should look.
3231 * Summary Buffer Mode Line:: You can say how the mode line should look.
3234 @findex mail-extract-address-components
3235 @findex gnus-extract-address-components
3236 @vindex gnus-extract-address-components
3237 Gnus will use the value of the @code{gnus-extract-address-components}
3238 variable as a function for getting the name and address parts of a
3239 @code{From} header. Two pre-defined function exist:
3240 @code{gnus-extract-address-components}, which is the default, quite
3241 fast, and too simplistic solution; and
3242 @code{mail-extract-address-components}, which works very nicely, but is
3245 @vindex gnus-summary-same-subject
3246 @code{gnus-summary-same-subject} is a string indicating that the current
3247 article has the same subject as the previous. This string will be used
3248 with those specs that require it. The default is @samp{""}.
3250 @node Summary Buffer Lines
3251 @subsection Summary Buffer Lines
3253 @vindex gnus-summary-line-format
3254 You can change the format of the lines in the summary buffer by changing
3255 the @code{gnus-summary-line-format} variable. It works along the same
3256 lines a a normal @code{format} string, with some extensions.
3258 The default string is @samp{"%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n"}.
3260 The following format specification characters are understood:
3268 Subject if the article is the root, @code{gnus-summary-same-subject}
3271 Full @code{From} line.
3273 The name (from the @code{From} header).
3275 The name (from the @code{From} header). This differs from the @code{n}
3276 spec in that it uses @code{gnus-extract-address-components}, which is
3277 slower, but may be more thorough.
3279 The address (from the @code{From} header). This works the same way as
3282 Number of lines in the article.
3284 Number of characters in the article.
3286 Indentation based on thread level (@pxref{Customizing Threading}).
3288 Nothing if the article is a root and lots of spaces if it isn't (it
3289 pushes everything after it off the screen).
3291 Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
3292 for adopted articles.
3294 Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
3295 for adopted articles.
3297 One space for each thread level.
3299 Twenty minus thread level spaces.
3307 @vindex gnus-summary-zcore-fuzz
3308 Zcore, @samp{+} if above the default level and @samp{-} if below the
3309 default level. If the difference between
3310 @code{gnus-summary-default-level} and the score is less than
3311 @code{gnus-summary-zcore-fuzz}, this spec will not be used.
3321 Number of articles in the current sub-thread. Using this spec will slow
3322 down summary buffer generation somewhat.
3324 A single character will be displayed if the article has any children.
3326 User defined specifier. The next character in the format string should
3327 be a letter. @sc{gnus} will call the function
3328 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
3329 following @samp{%u}. The function will be passed the current header as
3330 argument. The function should return a string, which will be inserted
3331 into the summary just like information from any other summary specifier.
3334 Text between @samp{%(} and @samp{%)} will be highlighted with
3335 @code{gnus-mouse-face} when the mouse point is placed inside the area.
3336 There can only be one such area.
3338 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
3339 have to be handled with care. For reasons of efficiency, Gnus will
3340 compute what column these characters will end up in, and "hard-code"
3341 that. This means that it is illegal to have these specs after a
3342 variable-length spec. Well, you might not be arrested, but your summary
3343 buffer will look strange, which is bad enough.
3345 The smart choice is to have these specs as far to the left as possible.
3346 (Isn't that the case with everything, though? But I digress.)
3348 This restriction may disappear in later versions of Gnus.
3350 @node Summary Buffer Mode Line
3351 @subsection Summary Buffer Mode Line
3353 @vindex gnus-summary-mode-line-format
3354 You can also change the format of the summary mode bar. Set
3355 @code{gnus-summary-mode-line-format} to whatever you like. Here are the
3356 elements you can play with:
3362 Unprefixed group name.
3364 Current article number.
3368 Number of unread articles in this group.
3370 Number of unselected articles in this group.
3372 A string with the number of unread and unselected articles represented
3373 either as @samp{<%U(+%u) more>} if there are both unread and unselected
3374 articles, and just as @samp{<%U more>} if there are just unread articles
3375 and no unselected ones.
3377 Shortish group name. For instance, @samp{rec.arts.anime} will be
3378 shortened to @samp{r.a.anime}.
3380 Subject of the current article.
3384 Name of the current score file.
3386 Number of dormant articles.
3388 Number of ticked articles.
3390 Number of articles that have been marked as read in this session.
3392 Number of articles expunged by the score files.
3396 @node Summary Maneuvering
3397 @section Summary Maneuvering
3398 @cindex summary movement
3400 All the straight movement commands understand the numeric prefix and
3401 behave pretty much as you'd expect.
3403 None of these commands select articles.
3408 @kindex M-n (Summary)
3409 @kindex G M-n (Summary)
3410 @findex gnus-summary-next-unread-subject
3411 Go to the next summary line of an unread article
3412 (@code{gnus-summary-next-unread-subject}).
3415 @kindex M-p (Summary)
3416 @kindex G M-p (Summary)
3417 @findex gnus-summary-prev-unread-subject
3418 Go to the previous summary line of an unread article
3419 (@code{gnus-summary-prev-unread-subject}).
3423 @kindex G g (Summary)
3424 @findex gnus-summary-goto-subject
3425 Ask for an article number and then go to this summary line
3426 (@code{gnus-summary-goto-subject}).
3429 @vindex gnus-auto-select-next
3430 If you are at the end of the group and issue one of the movement
3431 commands, Gnus will offer to go to the next group. If
3432 @code{gnus-auto-select-next} is @code{t} and the next group is empty,
3433 Gnus will exit summary mode and return to the group buffer. If this
3434 variable is neither @code{t} nor @code{nil}, Gnus will select the next
3435 group, no matter whether it has any unread articles or not. As a
3436 special case, if this variable is @code{quietly}, Gnus will select the
3437 next group without asking for confirmation. If this variable is
3438 @code{almost-quietly}, the same will happen only if you are located on
3439 the last article in the group. Also @xref{Group Levels}.
3441 If Gnus asks you to press a key to confirm going to the next group, you
3442 can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
3443 buffer, searching for the next group to read without actually returning
3444 to the group buffer.
3446 @vindex gnus-auto-select-same
3447 If @code{gnus-auto-select-same} is non-@code{nil}, all the movement
3448 commands will try to go to the next article with the same subject as the
3449 current. This variable is not particularly useful if you use a threaded
3452 @vindex gnus-summary-check-current
3453 If @code{gnus-summary-check-current} is non-@code{nil}, all the "unread"
3454 movement commands will not proceed to the next (or previous) article if
3455 the current article is unread. Instead, they will choose the current
3458 @vindex gnus-auto-center-summary
3459 If @code{gnus-auto-center-summary} is non-@code{nil}, Gnus will keep the
3460 point in the summary buffer centered at all times. This makes things
3461 quite tidy, but if you have a slow network connection, or simply do not
3462 like this un-Emacsism, you can set this variable to @code{nil} to get
3463 the normal Emacs scrolling action.
3465 @node Choosing Articles
3466 @section Choosing Articles
3467 @cindex selecting articles
3469 None of the following movement commands understand the numeric prefix,
3470 and they all select and display an article.
3474 @kindex SPACE (Summary)
3475 @findex gnus-summary-next-page
3476 Select the current article, or, if that one's read already, the next
3477 unread article (@code{gnus-summary-next-page}).
3481 @kindex G n (Summary)
3482 @findex gnus-summary-next-unread-article
3483 Go to next unread article (@code{gnus-summary-next-unread-article}).
3487 @findex gnus-summary-prev-unread-article
3488 Go to previous unread article (@code{gnus-summary-prev-unread-article}).
3492 @kindex G N (Summary)
3493 @findex gnus-summary-next-article
3494 Go to the next article (@code{gnus-summary-next-article}).
3498 @kindex G P (Summary)
3499 @findex gnus-summary-prev-article
3500 Go to the previous article (@code{gnus-summary-prev-article}).
3502 @kindex G C-n (Summary)
3503 @findex gnus-summary-next-same-subject
3504 Go to the next article with the same subject
3505 (@code{gnus-summary-next-same-subject}).
3507 @kindex G C-p (Summary)
3508 @findex gnus-summary-prev-same-subject
3509 Go to the previous article with the same subject
3510 (@code{gnus-summary-prev-same-subject}).
3513 @kindex G f (Summary)
3515 @findex gnus-summary-first-unread-article
3516 Go to the first unread article
3517 (@code{gnus-summary-first-unread-article}).
3520 @kindex G b (Summary)
3522 Go to the article with the highest score
3523 (@code{gnus-summary-best-unread-article}).
3527 @kindex G l (Summary)
3528 @findex gnus-summary-goto-last-article
3529 Go to the previous article read (@code{gnus-summary-goto-last-article}).
3531 @kindex G p (Summary)
3532 @findex gnus-summary-pop-article
3533 Pop an article off the summary history and go to this article
3534 (@code{gnus-summary-pop-article}). This command differs from the
3535 command above in that you can pop as many previous articles off the
3536 history as you like.
3539 Some variables that are relevant for moving and selecting articles:
3542 @item gnus-auto-extend-newsgroup
3543 @vindex gnus-auto-extend-newsgroup
3544 All the movement commands will try to go to the previous (or next)
3545 article, even if that article isn't displayed in the Summary buffer if
3546 this variable is non-@code{nil}. Gnus will then fetch the article from
3547 the server and display it in the article buffer.
3548 @item gnus-select-article-hook
3549 @vindex gnus-select-article-hook
3550 This hook is called whenever an article is selected. By default it
3551 exposes any threads hidden under the selected article.
3552 @item gnus-mark-article-hook
3553 @vindex gnus-mark-article-hook
3554 This hook is called whenever an article is selected. It is intended to
3555 be used for marking articles as read.
3556 @item gnus-visual-mark-article-hook
3557 @vindex gnus-visual-mark-article-hook
3558 This hook is run after selecting an article. It is meant to be used for
3559 highlighting the article in some way. It is not run if
3560 @code{gnus-visual} is @code{nil}.
3561 @item gnus-summary-update-hook
3562 @vindex gnus-summary-update-hook
3563 This hook is called when a summary line is changed. It is not run if
3564 @code{gnus-visual} is @code{nil}.
3565 @item gnus-summary-selected-face
3566 @vindex gnus-summary-selected-face
3567 This is the face (or @dfn{font} as some people call it) that is used to
3568 highlight the current article in the summary buffer.
3569 @item gnus-summary-highlight
3570 @vindex gnus-summary-highlight
3571 Summary lines are highlighted according to this variable, which is a
3572 list where the elements are on the format @code{(FORM . FACE)}. If you
3573 would, for instance, like ticked articles to be italic and high-scored
3574 articles to be bold, you could set this variable to something like
3576 (((eq mark gnus-ticked-mark) . italic)
3577 ((> score default) . bold))
3579 As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
3580 @var{FACE} will be applied to the line.
3583 @node Paging the Article
3584 @section Scrolling the Article
3585 @cindex article scrolling
3590 @kindex SPACE (Summary)
3591 @findex gnus-summary-next-page
3592 Pressing @kbd{SPACE} will scroll the current article forward one page,
3593 or, if you have come to the end of the current article, will choose the
3594 next article (@code{gnus-summary-next-page}).
3597 @kindex DEL (Summary)
3598 @findex gnus-summary-prev-page
3599 Scroll the current article back one page (@code{gnus-summary-prev-page}).
3601 @kindex RET (Summary)
3602 @findex gnus-summary-scroll-up
3603 Scroll the current article one line forward
3604 (@code{gnus-summary-scroll-up}).
3609 @kindex A < (Summary)
3610 @findex gnus-summary-beginning-of-article
3611 Scroll to the beginning of the article
3612 (@code{gnus-summary-beginning-of-article}).
3617 @kindex A > (Summary)
3618 @findex gnus-summary-end-of-article
3619 Scroll to the end of the article (@code{gnus-summary-end-of-article}).
3622 @kindex A s (Summary)
3623 @findex gnus-summary-isearch-article
3624 Perform an isearch in the article buffer
3625 (@code{gnus-summary-isearch-article}).
3629 @node Reply Followup and Post
3630 @section Reply, Followup and Post
3635 @kindex C-c C-c (Post)
3636 All the commands for posting and mailing will put you in a post or mail
3637 buffer where you can edit the article all you like, before you send the
3638 article by pressing @kbd{C-c C-c}. If you are in a foreign news group,
3639 and you wish to post the article using the foreign server, you can give
3640 a prefix to @kbd{C-c C-c} to make Gnus try to post using the foreign
3644 * Mail:: Mailing & replying.
3645 * Post:: Posting and following up.
3646 * Mail & Post:: Mailing and posting at the same time.
3647 * Posting Styles:: An easier way to configure some key elements.
3648 * Drafts:: Postponing messages and rejected messages.
3649 * Rejected Articles:: What happens if the server doesn't like your article?
3655 Commands for composing a mail message:
3660 @kindex S r (Summary)
3662 @findex gnus-summary-reply
3663 Mail a reply to the author of the current article
3664 (@code{gnus-summary-reply}).
3668 @kindex S R (Summary)
3669 @findex gnus-summary-reply-with-original
3670 Mail a reply to the author of the current article and include the
3671 original message (@code{gnus-summary-reply-with-original}). This
3672 command uses the process/prefix convention.
3674 @kindex S o m (Summary)
3675 @findex gnus-summary-mail-forward
3676 Forward the current article to some other person
3677 (@code{gnus-summary-mail-forward}).
3679 @kindex S o p (Summary)
3680 @findex gnus-summary-post-forward
3681 Forward the current article to a newsgroup
3682 (@code{gnus-summary-post-forward}).
3686 @kindex S m (Summary)
3687 @findex gnus-summary-mail-other-window
3688 Send a mail to some other person
3689 (@code{gnus-summary-mail-other-window}).
3691 @kindex S D b (Summary)
3692 @findex gnus-summary-resend-bounced-mail
3693 If you have sent a mail, but the mail was bounced back to you for some
3694 reason (wrong address, transient failure), you can use this command to
3695 resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
3696 will be popped into a mail buffer where you can edit the headers before
3697 sending the mail off again. The headers that match the regexp
3698 @code{gnus-bounced-headers-junk} (default @samp{^Received:}) are
3699 automatically deleted first. If you give a prefix to this command, and
3700 the bounced mail is a reply to some other mail, Gnus will try to fetch
3701 that mail and display it for easy perusal of its headers. This might
3702 very well fail, though.
3704 @kindex S O m (Summary)
3705 @findex gnus-uu-digest-mail-forward
3706 Digest the current series and forward the result using mail
3707 (@code{gnus-uu-digest-mail-forward}). This command uses the
3708 process/prefix convention (@pxref{Process/Prefix}).
3710 @kindex S O p (Summary)
3711 @findex gnus-uu-digest-post-forward
3712 Digest the current series and forward the result to a newsgroup
3713 (@code{gnus-uu-digest-mail-forward}).
3716 Variables for customizing outgoing mail:
3719 @item gnus-reply-to-function
3720 @vindex gnus-reply-to-function
3721 Gnus uses the normal methods to determine where replies are to go, but
3722 you can change the behavior to suit your needs by fiddling with this
3725 If you want the replies to go to the @samp{Sender} instead of the
3726 @samp{From} in the group @samp{mail.stupid-list}, you could do something
3730 (setq gnus-reply-to-function
3732 (cond ((string= group "mail.stupid-list")
3733 (mail-fetch-field "sender"))
3738 This function will be called narrowed to the head of the article that is
3741 As you can see, this function should return a string if it has an
3742 opinion as to what the To header should be. If it does not, it should
3743 just return @code{nil}, and the normal methods for determining the To
3744 header will be used.
3746 This function can also return a list. In that case, each list element
3747 should be a cons, where the car should be the name of an header
3748 (eg. @samp{Cc}) and the cdr should be the header value
3749 (eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into
3750 the head of the outgoing mail.
3752 @item gnus-mail-send-method
3753 @vindex gnus-mail-send-method
3754 This variable says how a mail should be mailed. It uses the function in
3755 the @code{send-mail-function} variable as the default.
3757 @item gnus-uu-digest-headers
3758 @vindex gnus-uu-digest-headers
3759 List of regexps to match headers included in digested messages. The
3760 headers will be included in the sequence they are matched.
3762 @item gnus-mail-hook
3763 @vindex gnus-mail-hook
3764 Hook called as the last thing after setting up a mail buffer.
3766 @item gnus-required-mail-headers
3767 @vindex gnus-required-mail-headers
3768 Gnus will generate headers in all outgoing mail instead of letting
3769 @code{sendmail} do it for us. This makes it possible to do more neat
3770 stuff, like putting mail without sending it, do hairy @code{Fcc}
3771 handling, and much more. This variable controls what headers Gnus will
3772 generate, and is of the exact same form as @code{gnus-required-headers},
3773 which does the same for news articles (@pxref{Post}).
3775 The @code{Newsgroups} header is illegal in this list, while @code{To} is
3776 required, and @code{X-Mailer} can be added if you so should want.
3780 @kindex C-c C-c (Mail)
3781 @kindex C-c C-p (Mail)
3782 @findex gnus-put-message
3783 You normally send a mail message by pressing @kbd{C-c C-c}. However,
3784 you may wish to just put the mail message you have just written in your
3785 own local mail group instead of sending it. Sounds quite unlikely, but
3786 I found that useful, so you can now also press @kbd{C-c C-p} to
3787 @dfn{put} the article in the current mail group, or, if there is no such
3788 thing, you will be prompted for a mail group, and then the article will
3789 be put there. This means that the article is @dfn{not} mailed.
3791 There are three "methods" for handling all mail. The default is
3792 @code{sendmail}. Some people like what @code{mh} does better, and some
3793 people prefer @code{vm}.
3795 Three variables for customizing what to use when:
3799 @vindex gnus-mail-reply-method
3800 @item gnus-mail-reply-method
3801 This function is used to compose replies. The three functions avaibale
3804 @findex gnus-mail-reply-using-vm
3805 @findex gnus-mail-reply-using-mhe
3806 @findex gnus-mail-reply-using-mail
3809 @code{gnus-mail-reply-using-mail} (sendmail)
3811 @code{gnus-mail-reply-using-mhe} (mh)
3813 @code{gnus-mail-reply-using-vm} (vm)
3816 @vindex gnus-mail-forward-method
3817 @item gnus-mail-forward-method
3818 This function is used to forward messages. The three functions avaibale
3821 @findex gnus-mail-forward-using-vm
3822 @findex gnus-mail-forward-using-mhe
3823 @findex gnus-mail-forward-using-mail
3826 @code{gnus-mail-forward-using-mail} (sendmail)
3828 @code{gnus-mail-forward-using-mhe} (mh)
3830 @code{gnus-mail-forward-using-vm} (vm)
3833 @vindex gnus-mail-other-window-method
3834 @item gnus-mail-other-window-method
3835 This function is used to send mails. The three functions avaibale are:
3837 @findex gnus-mail-other-window-using-vm
3838 @findex gnus-mail-other-window-using-mhe
3839 @findex gnus-mail-other-window-using-mail
3842 @code{gnus-mail-other-window-using-mail} (sendmail)
3844 @code{gnus-mail-other-window-using-mhe} (mh)
3846 @code{gnus-mail-other-window-using-vm} (vm)
3855 Commands for posting an article:
3861 @kindex S p (Summary)
3862 @findex gnus-summary-post-news
3863 Post an article to the current group
3864 (@code{gnus-summary-post-news}).
3868 @kindex S f (Summary)
3869 @findex gnus-summary-followup
3870 Post a followup to the current article (@code{gnus-summary-followup}).
3873 @kindex S F (Summary)
3875 @findex gnus-summary-followup-with-original
3876 Post a followup to the current article and include the original message
3877 (@code{gnus-summary-followup-with-original}). This command uses the
3878 process/prefix convention.
3880 @kindex S u (Summary)
3881 @findex gnus-uu-post-news
3882 Uuencode a file, split it into parts, and post it as a series
3883 (@code{gnus-uu-post-news}).
3884 @c (@pxref{Uuencoding & Posting}).
3887 @vindex gnus-required-headers
3888 @code{gnus-required-headers} a list of header symbols. These headers
3889 will either be automatically generated, or, if that's impossible, they
3890 will be prompted for. The following symbols are legal:
3894 This required header will be filled out with the result of the
3895 @code{gnus-inews-user-name} function, which depends on the
3896 @code{gnus-user-from-line}, @code{gnus-user-login-name},
3897 @code{gnus-local-domain} and @code{user-mail-address} variables.
3899 This required header will be prompted for if not present already.
3901 This required header says which newsgroups the article is to be posted
3902 to. If it isn't present already, it will be prompted for.
3904 @cindex organization
3905 @vindex gnus-local-organization
3906 @vindex gnus-organization-file
3907 This optional header will be filled out depending on the
3908 @code{gnus-local-organization} variable. @code{gnus-organization-file}
3909 will be used if that variable is nil.
3911 This optional header will be computed by Gnus.
3913 This required header will be generated by Gnus. A unique ID will be
3914 created based on date, time, user name and system name.
3916 This optional header will be filled out with the Gnus version numbers.
3919 In addition, you can enter conses into this list. The car of this cons
3920 should be a symbol. This symbol's name is the name of the header, and
3921 the cdr can either be a string to be entered verbatim as the value of
3922 this header, or it can be a function to be called. This function should
3923 return a string to be inserted. For instance, if you want to insert
3924 @samp{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
3925 into the list. If you want to insert a funny quote, you could enter
3926 something like @code{(X-Yow . yow)} into the list. The function
3927 @code{yow} will then be called without any arguments.
3929 The list contains a cons where the car of the cons is @code{optional},
3930 the cdr of this cons will only be inserted if it is non-@code{nil}.
3932 Other variables for customizing outgoing articles:
3935 @item gnus-post-method
3936 @vindex gnus-post-method
3937 If non-@code{nil}, Gnus will use this method instead of the default
3938 select method when posting.
3940 @item nntp-news-default-headers
3941 @vindex nntp-news-default-headers
3942 If non-@code{nil}, this variable will override
3943 @code{mail-default-headers} when posting. This variable should then be
3944 a string. This string will be inserted, as is, in the head of all
3947 @item gnus-use-followup-to
3948 @vindex gnus-use-followup-to
3949 If @code{nil}, always ignore the Followup-To header. If it is @code{t},
3950 use its value, but ignore the special value @samp{poster}, which will
3951 send the followup as a reply mail to the person you are responding to.
3952 If it is the symbol @code{ask}, query the user before posting.
3953 If it is the symbol @code{use}, always use the value.
3955 @item gnus-followup-to-function
3956 @vindex gnus-followup-to-function
3957 This variable is most useful in mail groups, where "following up" really
3958 means sending a mail to a list address. Gnus uses the normal methods to
3959 determine where follow-ups are to go, but you can change the behavior
3960 to suit your needs by fiddling with this variable.
3962 If you want the followups to go to the @samp{Sender} instead of the
3963 @samp{From} in the group @samp{mail.stupid-list}, you could do something
3967 (setq gnus-followup-to-function
3969 (cond ((string= group "mail.stupid-list")
3970 (mail-fetch-field "sender"))
3975 This function will be called narrowed to header of the article that is
3978 @item gnus-removable-headers
3979 @vindex gnus-removable-headers
3980 Some headers that are generated are toxic to the @sc{nntp} server.
3981 These include the @code{NNTP-Posting-Host}, @code{Bcc} and @code{Xref},
3982 so these headers are deleted if they are present in this list of
3985 @item gnus-deletable-headers
3986 @vindex gnus-deletable-headers
3987 Headers in this list that were previously generated by Gnus will be
3988 deleted before posting. Let's say you post an article. Then you decide
3989 to post it again to some other group, you naughty boy, so you jump back
3990 to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
3991 ship it off again. By default, this variable makes sure that the old
3992 generated @code{Message-ID} is deleted, and a new one generated. If
3993 this isn't done, the entire empire would probably crumble, anarchy would
3994 prevail, and cats would start walking on two legs and rule the world.
3997 @item gnus-signature-function
3998 @vindex gnus-signature-function
3999 If non-@code{nil}, this variable should be a function that returns a
4000 signature file name. The function will be called with the name of the
4001 group being posted to. If the function returns a string that doesn't
4002 correspond to a file, the string itself is inserted. If the function
4003 returns @code{nil}, the @code{gnus-signature-file} variable will be used
4006 @item gnus-post-prepare-function
4007 @vindex gnus-post-prepare-function
4008 This function is called with the name of the current group after the
4009 post buffer has been initialized, and can be used for inserting a
4010 signature. Nice if you use different signatures in different groups.
4012 @item gnus-post-prepare-hook
4013 @vindex gnus-post-prepare-hook
4014 This hook is called after a post buffer has been prepared. If you want
4015 to insert a signature at this point, you could put
4016 @code{gnus-inews-insert-signature} into this hook.
4018 @item news-reply-header-hook
4019 @vindex news-reply-header-hook
4020 A related variable when following up and replying is this variable,
4021 which inserts the @dfn{quote line}. The default value is:
4024 (defvar news-reply-header-hook
4026 (insert "In article " news-reply-yank-message-id
4027 " " news-reply-yank-from " writes:\n\n")))
4030 This will create lines like:
4033 In article <zngay8jrql@@eyesore.no> Lars Mars <lars@@eyesore.no> writes:
4036 Having the @code{Message-ID} in this line is probably overkill, so I
4037 would suggest this hook instead:
4040 (setq news-reply-header-hook
4041 (lambda () (insert news-reply-yank-from " writes:\n\n")))
4044 @item gnus-prepare-article-hook
4045 @vindex gnus-prepare-article-hook
4046 This hook is called before the headers have been prepared.
4048 @item gnus-inews-article-function
4049 @vindex gnus-inews-article-function
4050 This function is used to do the actual article processing and header
4051 checking/generation.
4053 @item gnus-inews-article-hook
4054 @vindex gnus-inews-article-hook
4055 This hook is called right before the article is posted. By default it
4056 handles FCC processing (i.e., saving the article to a file.)
4058 @item gnus-inews-article-header-hook
4059 @vindex gnus-inews-article-header-hook
4060 This hook is called after inserting the required headers in an article
4061 to be posted. The hook is called from the @code{*post-news*} buffer,
4062 narrowed to the head, and is intended for people who would like to
4063 insert additional headers, or just change headers in some way or other.
4065 @item gnus-check-before-posting
4066 @vindex gnus-check-before-posting
4067 If non-@code{nil}, Gnus will attempt to check the legality of the
4068 headers, as well as some other stuff, before posting. You can control
4069 the granularity of the check by adding or removing elements from this
4070 list. Legal elemetents are:
4074 Check the subject for commands.
4076 Insert a new @code{Sender} header if the @code{From} header looks odd.
4077 @item multiple-headers
4078 Check for the existence of multiple equal headers.
4080 Check for the existence of version and sendsys commands.
4082 Check whether the @code{Message-ID} looks ok.
4084 Check whether the @code{From} header seems nice.
4086 Check for too long lines.
4088 Check for illegal characters.
4090 Check for excessive size.
4092 Check whether there is any new text in the messages.
4094 Check the length of the signature.
4096 Check whether the article has an @code{Approved} header, which is
4097 something only moderators should include.
4104 @subsection Mail & Post
4106 Commands for sending mail and post at the same time:
4110 @kindex S b (Summary)
4111 @findex gnus-summary-followup-and-reply
4112 Post a followup and send a reply to the current article
4113 (@code{gnus-summary-followup-and-reply}).
4115 @kindex S B (Summary)
4116 @findex gnus-summary-followup-and-reply-with-original
4117 Post a followup and send a reply to the current article and include the
4118 original message (@code{gnus-summary-followup-and-reply-with-original}).
4119 This command uses the process/prefix convention.
4122 Here's a list of variables that are relevant to both mailing and
4126 @item gnus-signature-file
4127 @itemx mail-signature
4128 @vindex mail-signature
4129 @vindex gnus-signature-file
4130 @cindex double signature
4132 If @code{gnus-signature-file} is non-@code{nil}, it should be the name
4133 of a file containing a signature (@samp{~/.signature} by default). This
4134 signature will be appended to all outgoing post. Most people find it
4135 more convenient to use @code{mail-signature}, which (sort of) does the
4136 same, but inserts the signature into the buffer before you start editing
4137 the post (or mail). So---if you have both of these variables set, you
4138 will get two signatures. Note that @code{mail-signature} does not work
4139 the same way as @code{gnus-signature-file}, which is a bit confusing.
4140 If @code{mail-signature} is @code{t}, it will insert
4141 @file{~/.signature}. If it is a string, this string will be inserted.
4143 Note that RFC1036 says that a signature should be preceded by the three
4144 characters @samp{-- } on a line by themselves. This is to make it
4145 easier for the recipient to automatically recognize and process the
4146 signature. So don't remove those characters, even though you might feel
4147 that they ruin you beautiful design, like, totally.
4149 Also note that no signature should be more than four lines long.
4150 Including ASCII graphics is an efficient way to get everybody to believe
4151 that you are silly and have nothing important to say.
4153 @item mail-yank-prefix
4154 @vindex mail-yank-prefix
4157 When you are replying to or following up an article, you normally want
4158 to quote the person you are answering. Inserting quoted text is done by
4159 @dfn{yanking}, and each quoted line you yank will have
4160 @code{mail-yank-prefix} prepended to it. This is @samp{ } by default,
4161 which isn't very pretty. Most everybody prefers that lines are
4162 prepended with @samp{> }, so @code{(setq mail-yank-prefix "> ")} in your
4165 @item mail-yank-ignored-headers
4166 @vindex mail-yank-ignored-headers
4167 When you yank a message, you do not want to quote any headers, so
4168 @code{(setq mail-yank-ignored-headers "^")}.
4170 @item user-mail-address
4171 @vindex user-mail-address
4172 If all of @code{gnus-user-login-name}, @code{gnus-use-generic-from} and
4173 @code{gnus-local-domain} are @code{nil}, Gnus will use
4174 @code{user-mail-address} as the address part of the @code{From} header.
4176 @item gnus-local-domain
4177 @vindex gnus-local-domain
4179 The local doman name excluding the host name. If your host is called
4180 @samp{"narfi.ifi.uio.no"}, then this variable should be
4181 @samp{"ifi.uio.no"}.
4183 @item gnus-local-domain
4184 @vindex gnus-local-domain
4186 The local doman name excluding the host name. If your host is called
4187 @samp{"narfi.ifi.uio.no"}, then this variable should be
4188 @samp{"ifi.uio.no"}.
4190 @item gnus-user-from-line
4191 @vindex gnus-user-from-line
4192 Your full, complete e-mail address with name. This variable overrides
4193 the other Gnus variables if it is non-@code{nil}.
4195 Here are two example values of this variable: @samp{"larsi@@ifi.uio.no
4196 (Lars Magne Ingebrigtsen)"} and @samp{"Lars Magne Ingebrigtsen
4197 <larsi@@ifi.uio.no>"}. The latter version is recommended in news (and is
4198 probably illegal in mail), but the name has to be quoted if it contains
4199 non-alpha-numerical characters---@samp{"\"Lars M. Ingebrigtsen\"
4200 <larsi@@ifi.uio.no>"}.
4202 @item mail-default-headers
4203 @vindex mail-default-headers
4204 This is a string that will be inserted into the header of all outgoing
4205 mail messages and news articles. Convenient to use to insert standard
4206 headers. If @code{nntp-news-default-headers} is non-@code{nil}, that
4207 variable will override this one when posting articles.
4209 @item gnus-auto-mail-to-author
4210 @vindex gnus-auto-mail-to-author
4211 If @code{ask}, you will be prompted for whether you want to send a mail
4212 copy to the author of the article you are following up. If
4213 non-@code{nil} and not @code{ask}, Gnus will send a mail with a copy of
4214 all follow-ups to the authors of the articles you follow up. It's nice
4215 in one way---you make sure that the person you are responding to gets
4216 your response. Other people loathe this method and will hate you dearly
4217 for it, because it means that they will first get a mail, and then have
4218 to read the same article later when they read the news. It is
4219 @code{nil} by default.
4221 @item gnus-mail-courtesy-message
4222 @vindex gnus-mail-courtesy-message
4223 This is a string that will be prepended to all mails that are the result
4224 of using the variable described above.
4226 @item gnus-outgoing-message-group
4227 @vindex gnus-outgoing-message-group
4228 All outgoing messages will be put in this group. If you want to store
4229 all your outgoing mail and articles in the group @samp{nnml:archive},
4230 you set this variable to that value. This variable can also be a list of
4233 If you want to have greater control over what group to put each
4234 message in, you can set this variable to a function that checks the
4235 current newsgroup name and then returns a suitable group name (or list
4238 @item gnus-mailing-list-groups
4239 @findex gnus-mailing-list-groups
4240 @cindex mailing lists
4242 If your newsserver offer groups that are really mailing lists that are
4243 gatewayed to the @sc{nntp} server, you can read those groups without
4244 problems, but you can't post/followup to them without some difficulty.
4245 One solution is to add a @code{to-address} to the group parameters
4246 (@pxref{Group Parameters}). An easier thing to do is set the
4247 @code{gnus-mailing-list-groups} to a regexp that match the groups that
4248 really are mailing lists. Then, at least, followups to the mailing
4249 lists will work most of the time. Posting to these groups (@kbd{a}) is
4250 still a pain, though.
4255 You may want to do spell-checking on messages that you send out. Or, if
4256 you don't want to spell-check by hand, you could add automatic
4257 spell-checking via the @code{ispell} package:
4259 @vindex news-inews-hook
4261 (add-hook 'news-inews-hook 'ispell-message) ;For news posts
4262 (add-hook 'mail-send-hook 'ispell-message) ;for mail posts via sendmail
4265 @findex gnus-inews-insert-mime-headers
4266 If you want to insert some @sc{mime} headers into the articles you post,
4267 without doing any actual encoding, you could add
4268 @code{gnus-inews-insert-mime-headers} to @code{gnus-inews-article-hook}.
4271 @node Posting Styles
4272 @subsection Posting Styles
4273 @cindex posting styles
4276 All them variables, they make my head swim.
4278 So what if you want a different @code{Organization} and signature based
4279 on what groups you post to? And you post both from your home machine
4280 and your work machine, and you want different @code{From} lines, and so
4283 @vindex gnus-posting-styles
4284 One way to do stuff like that is to write clever hooks that change the
4285 variables you need to have changed. That's a bit boring, so somebody
4286 came up with the bright idea of letting the user specify these things in
4287 a handy alist. Here's an example of a @code{gnus-posting-styles}
4291 ((".*" (signature . "Peace and happiness") (organization . "What me?"))
4292 ("^comp" (signature . "Death to everybody"))
4293 ("comp.emacs.i-love-it" (organization . "Emacs is it")))
4296 As you might surmise from this example, this alist consists of several
4297 @dfn{styles}. Each style will be applicable if the first element
4298 "matches", in some form or other. The entire alist will be iterated
4299 over, from the beginning towards the end, and each match will be
4300 applied, which means that attributes in later styles that match override
4301 the same attributes in earlier matching styles. So
4302 @samp{comp.programming.literate} will have the @samp{Death to everybody}
4303 signature and the @samp{What me?} @code{Organization} header.
4305 The first element in each style is called the @code{match}. If it's a
4306 string, then Gnus will try to regexp match it against the group name.
4307 If it's a function symbol, that function will be called with no
4308 arguments. If it's a variable symbol, then the variable will be
4309 referenced. If it's a list, then that list will be @code{eval}ed. In
4310 any case, if this returns a non-@code{nil} value, then the style is said
4313 Each style may contain a random amount of @dfn{attributes}. Each
4314 attribute consists of a @var{(name . value)} pair. The attribute name
4315 can be one of @code{signature}, @code{organization} or @code{from}.
4316 The attribute name can also be a string. In that case, this will be
4317 used as a header name, and the value will be inserted in the headers of
4320 The attribute value can be a string (used verbatim), a function (the
4321 return value will be used), a variable (its value will be used) or a
4322 list (it will be @code{eval}ed and the return value will be used).
4324 So here's a new example:
4327 (setq gnus-posting-styles
4329 (signature . "~/.signature")
4330 (from . "user@@foo (user)")
4331 ("X-Home-Page" . (getenv "WWW_HOME"))
4332 (organization . "People's Front Against MWM"))
4334 (signature . my-funny-signature-randomizer))
4335 ((equal (system-name) "gnarly")
4336 (signature . my-quote-randomizer))
4337 (posting-from-work-p
4338 (signature . "~/.work-signature")
4339 (from . "user@@bar.foo (user)")
4340 (organization . "Important Work, Inc"))
4342 (signature . "~/.mail-signature"))))
4351 If you are writing a message (mail or news) and suddenly remember that
4352 you have a steak in the oven (or pesto in the food processor, you craazy
4353 vegetarians), you'll probably wish there was a method to save the
4354 message you are writing so that you can continue editing it some other
4355 day, and send it when you feel its finished.
4357 @kindex C-c C-d (Mail)
4358 @kindex C-c C-d (Post)
4359 @findex gnus-enter-into-draft-group
4360 @vindex gnus-draft-group-directory
4361 What you then do is simply push @kbd{C-c C-d}
4362 (@code{gnus-enter-into-draft-group}). This will put the current
4363 (unfinished) message in a special draft group (which is implemented as
4364 an @code{nndir} group, if you absolutely have to know) called
4365 @samp{nndir:drafts}. The variable @code{gnus-draft-group-directory}
4366 controls both the name of the group and the location---the leaf element
4367 in the path will be used as the name of the group.
4369 If the group doesn't exist, it will be created and you'll be subscribed
4372 @findex gnus-summary-send-draft
4373 @kindex S D c S (Summary)
4374 When you want to continue editing the article, you simply enter the
4375 draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
4376 that. You will be placed in a buffer where you left off.
4378 Rejected articles will also be put in this draft group (@pxref{Rejected
4381 @findex gnus-summary-send-all-drafts
4382 If you have lots of rejected messages you want to post (or mail) without
4383 doing further editing, you can use the @kbd{S D a} command
4384 (@code{gnus-summary-send-all-drafts}). This command understands the
4385 process/prefix convention (@pxref{Process/Prefix}).
4388 @node Rejected Articles
4389 @subsection Rejected Articles
4390 @cindex rejected articles
4392 Sometimes a news server will reject an article. Perhaps the server
4393 doesn't like your face. Perhaps it just feels miserable. Perhaps
4394 @emph{there be demons}. Perhaps you have included too much cited text.
4395 Perhaps the disk is full. Perhaps the server is down.
4397 These situations are, of course, totally beyond the control of Gnus.
4398 (Gnus, of course, loves the way you look, always feels great, has angels
4399 fluttering around inside of it, doesn't care about how much cited text
4400 you include, never runs full and never goes down.) So Gnus saves these
4401 articles until some later time when the server feels better.
4403 The rejected articles will automatically be put in a special draft group
4404 (@pxref{Drafts}). When the server comes back up again, you'd then
4405 typically enter that group and send all the articles off.
4408 @node Canceling and Superseding
4409 @section Canceling Articles
4410 @cindex canceling articles
4411 @cindex superseding articles
4413 Have you ever written something, and then decided that you really,
4414 really, really wish you hadn't posted that?
4416 Well, you can't cancel mail, but you can cancel posts.
4418 @findex gnus-summary-cancel-article
4420 Find the article you wish to cancel (you can only cancel your own
4421 articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
4422 c} (@code{gnus-summary-cancel-article}). Your article will be
4423 canceled---machines all over the world will be deleting your article.
4425 Be aware, however, that not all sites honor cancels, so your article may
4426 live on here and there, while most sites will delete the article in
4429 If you discover that you have made some mistakes and want to do some
4430 corrections, you can post a @dfn{superseding} article that will replace
4431 your original article.
4433 @findex gnus-summary-supersede-article
4435 Go to the original article and press @kbd{S s}
4436 (@code{gnus-summary-supersede-article}). You will be put in a buffer
4437 where you can edit the article all you want before sending it off the
4440 @vindex gnus-delete-supersedes-headers
4441 You probably want to delete some of the old headers before sending the
4442 superseding article---@code{Path} and @code{Date} are probably
4443 incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
4444 match the lines you want removed. The default is
4445 @samp{"^Path:\\|^Date"}.
4447 The same goes for superseding as for canceling, only more so: Some
4448 sites do not honor superseding. On those sites, it will appear that you
4449 have posted almost the same article twice.
4451 If you have just posted the article, and change your mind right away,
4452 there is a trick you can use to cancel/supersede the article without
4453 waiting for the article to appear on your site first. You simply return
4454 to the post buffer (which is called @code{*post-buf*}). There you will
4455 find the article you just posted, with all the headers intact. Change
4456 the @samp{Message-ID} header to a @samp{Cancel} or @samp{Supersedes}
4457 header by substituting one of those words for @samp{Message-ID}. Then
4458 just press @kbd{C-c C-c} to send the article as you would do normally.
4459 The previous article will be canceled/superseded.
4461 Just remember, kids: There is no 'c' in 'supersede'.
4463 @node Marking Articles
4464 @section Marking Articles
4465 @cindex article marking
4466 @cindex article ticking
4469 There are several marks you can set on an article.
4471 You have marks that decide the @dfn{readed-ness} (whoo, neato-keano
4472 neologism ohoy!) of the article. Alphabetic marks generally mean
4473 @dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
4475 In addition, you also have marks that do not affect readedness.
4478 * Unread Articles:: Marks for unread articles.
4479 * Read Articles:: Marks for read articles.
4480 * Other Marks:: Marks that do not affect readedness.
4484 There's a plethora of commands for manipulating these marks:
4488 * Setting Marks:: How to set and remove marks.
4489 * Setting Process Marks:: How to mark articles for later processing.
4492 @node Unread Articles
4493 @subsection Unread Articles
4495 The following marks mark articles as unread, in one form or other.
4497 @vindex gnus-dormant-mark
4498 @vindex gnus-ticked-mark
4501 @dfn{Ticked articles} are articles that will remain visible always. If
4502 you see an article that you find interesting, or you want to put off
4503 reading it, or replying to it, until sometime later, you'd typically
4504 tick it. However, articles can be expired, so if you want to keep an
4505 article forever, you'll have to save it. Ticked articles have a
4506 @samp{!} (@code{gnus-ticked-mark}) in the first column.
4508 A @dfn{dormant} article is marked with a @samp{?}
4509 (@code{gnus-dormant-mark}), and will only appear in the summary buffer
4510 if there are followups to it.
4512 An @dfn{unread} article is marked with a @samp{SPC}
4513 (@code{gnus-unread-mark}). These are articles that haven't been read at
4518 @subsection Read Articles
4519 @cindex expirable mark
4521 All the following marks mark articles as read.
4525 Articles that are marked as read. They have a @samp{r}
4526 (@code{gnus-del-mark}) in the first column. These are articles that the
4527 user has marked as read more or less manually.
4529 Articles that are actually read are marked with @samp{R}
4530 (@code{gnus-read-mark}).
4532 Articles that were marked as read in previous sessions are now
4533 @dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
4535 Marked as killed (@code{gnus-killed-mark}).
4537 Marked as killed by kill files (@code{gnus-kill-file-mark}).
4539 Marked as read by having a too low score (@code{gnus-low-score-mark}).
4541 Marked as read by a catchup (@code{gnus-catchup-mark}).
4543 Canceled article (@code{gnus-cancelled-mark})
4546 All these marks just mean that the article is marked as read, really.
4547 They are interpreted differently by the adaptive scoring scheme,
4550 One more special mark, though:
4554 You can also mark articles as @dfn{expirable} (or have them marked as
4555 such automatically). That doesn't make much sense in normal groups,
4556 because a user does not control the expiring of news articles, but in
4557 mail groups, for instance, articles that are marked as @dfn{expirable}
4558 can be deleted by Gnus at any time. Expirable articles are marked with
4559 @samp{E} (@code{gnus-expirable-mark}).
4563 @subsection Other Marks
4564 @cindex process mark
4567 There are some marks that have nothing to do with whether the article is
4570 You can set a bookmark in the current article. Say you are reading a
4571 long thesis on cat's urinary tracts, and have to go home for dinner
4572 before you've finished reading the thesis. You can then set a bookmark
4573 in the article, and Gnus will jump to this bookmark the next time it
4574 encounters the article.
4576 All articles that you have replied to or made a followup to (i.e., have
4577 answered) will be marked with an @samp{A} in the second column
4578 (@code{gnus-replied-mark}).
4580 @vindex gnus-not-empty-thread-mark
4581 @vindex gnus-empty-thread-mark
4582 It the @samp{%e} spec is used, the presence of threads or not will be
4583 marked with @code{gnus-not-empty-thread-mark} and
4584 @code{gnus-empty-thread-mark}, respectively.
4586 @vindex gnus-process-mark
4587 Finally we have the @dfn{process mark} (@code{gnus-process-mark}. A
4588 variety of commands react to the presence of the process mark. For
4589 instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
4590 all articles that have been marked with the process mark. Articles
4591 marked with the process mark have a @samp{#} in the second column.
4594 @subsection Setting Marks
4595 @cindex setting marks
4597 All the marking commands understand the numeric prefix.
4603 @kindex M t (Summary)
4604 @findex gnus-summary-tick-article-forward
4605 Tick the current article (@code{gnus-summary-tick-article-forward}).
4609 @kindex M ? (Summary)
4610 @findex gnus-summary-mark-as-dormant
4611 Mark the current article as dormant
4612 (@code{gnus-summary-mark-as-dormant}).
4615 @kindex M d (Summary)
4617 @findex gnus-summary-mark-as-read-forward
4618 Mark the current article as read
4619 (@code{gnus-summary-mark-as-read-forward}).
4623 @kindex M k (Summary)
4624 @findex gnus-summary-kill-same-subject-and-select
4625 Mark all articles that have the same subject as the current one as read,
4626 and then select the next unread article
4627 (@code{gnus-summary-kill-same-subject-and-select}).
4630 @kindex M K (Summary)
4631 @kindex C-k (Summary)
4632 @findex gnus-summary-kill-same-subject
4633 Mark all articles that have the same subject as the current one as read
4634 (@code{gnus-summary-kill-same-subject}).
4636 @kindex M C (Summary)
4637 @findex gnus-summary-catchup
4638 Mark all unread articles in the group as read
4639 (@code{gnus-summary-catchup}).
4641 @kindex M C-c (Summary)
4642 @findex gnus-summary-catchup-all
4643 Mark all articles in the group as read---even the ticked and dormant
4644 articles (@code{gnus-summary-catchup-all}).
4646 @kindex M H (Summary)
4647 @findex gnus-summary-catchup-to-here
4648 Catchup the current group to point
4649 (@code{gnus-summary-catchup-to-here}).
4651 @kindex C-w (Summary)
4652 @findex gnus-summary-mark-region-as-read
4653 Mark all articles between point and mark as read
4654 (@code{gnus-summary-mark-region-as-read}).
4656 @kindex M V k (Summary)
4657 @findex gnus-summary-kill-below
4658 Kill all articles with scores below the default score (or below the
4659 numeric prefix) (@code{gnus-summary-kill-below}).
4662 @kindex M c (Summary)
4663 @kindex M-u (Summary)
4664 @findex gnus-summary-clear-mark-forward
4665 Clear all readedness-marks from the current article
4666 (@code{gnus-summary-clear-mark-forward}).
4669 @kindex M e (Summary)
4671 @findex gnus-summary-mark-as-expirable
4672 Mark the current article as expirable
4673 (@code{gnus-summary-mark-as-expirable}).
4675 @kindex M b (Summary)
4676 @findex gnus-summary-set-bookmark
4677 Set a bookmark in the current article
4678 (@code{gnus-summary-set-bookmark}).
4680 @kindex M B (Summary)
4681 @findex gnus-summary-remove-bookmark
4682 Remove the bookmark from the current article
4683 (@code{gnus-summary-remove-bookmark}).
4685 @kindex M V c (Summary)
4686 @findex gnus-summary-clear-above
4687 Clear all marks from articles with scores over the default score (or
4688 over the numeric prefix) (@code{gnus-summary-clear-above}).
4690 @kindex M V u (Summary)
4691 @findex gnus-summary-tick-above
4692 Tick all articles with scores over the default score (or over the
4693 numeric prefix) (@code{gnus-summary-tick-above}).
4695 @kindex M V m (Summary)
4696 @findex gnus-summary-mark-above
4697 Prompt for a mark, and mark all articles with scores over the default
4698 score (or over the numeric prefix) with this mark
4699 (@code{gnus-summary-clear-above}).
4702 @code{gnus-summary-goto-unread}
4703 The @code{gnus-summary-goto-unread} variable controls what action should
4704 be taken after setting a mark. If non-@code{nil}, point will move to
4705 the next/previous unread article. If @code{nil}, point will just move
4706 one line up or down. The default is @code{t}.
4709 @node Setting Process Marks
4710 @subsection Setting Process Marks
4711 @cindex setting process marks
4717 @kindex M P p (Summary)
4718 @findex gnus-summary-mark-as-processable
4719 Mark the current article with the process mark
4720 (@code{gnus-summary-mark-as-processable}).
4721 @findex gnus-summary-unmark-as-processable
4724 @kindex M P u (Summary)
4725 @kindex M-# (Summary)
4726 Remove the process mark, if any, from the current article
4727 (@code{gnus-summary-unmark-as-processable}).
4729 @kindex M P U (Summary)
4730 @findex gnus-summary-unmark-all-processable
4731 Remove the process mark from all articles
4732 (@code{gnus-summary-unmark-all-processable}).
4734 @kindex M P R (Summary)
4735 @findex gnus-uu-mark-by-regexp
4736 Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
4738 @kindex M P r (Summary)
4739 @findex gnus-uu-mark-region
4740 Mark articles in region (@code{gnus-uu-mark-region}).
4742 @kindex M P t (Summary)
4743 @findex gnus-uu-mark-thread
4744 Mark all articles in the current (sub)thread
4745 (@code{gnus-uu-mark-thread}).
4747 @kindex M P T (Summary)
4748 @findex gnus-uu-unmark-thread
4749 Unmark all articles in the current (sub)thread
4750 (@code{gnus-uu-unmark-thread}).
4752 @kindex M P s (Summary)
4753 @findex gnus-uu-mark-series
4754 Mark all articles in the current series (@code{gnus-uu-mark-series}).
4756 @kindex M P S (Summary)
4757 @findex gnus-uu-mark-sparse
4758 Mark all series that have already had some articles marked
4759 (@code{gnus-uu-mark-sparse}).
4761 @kindex M P a (Summary)
4762 @findex gnus-uu-mark-all
4763 Mark all articles in series order (@code{gnus-uu-mark-series}).
4765 @kindex M P b (Summary)
4766 @findex gnus-uu-mark-buffer
4767 Mark all articles in the buffer in the order they appear
4768 (@code{gnus-uu-mark-buffer}).
4776 It can be convenient to limit the summary buffer to just show some
4777 subset of the articles currently in the group. The effect most limit
4778 commands have is to remove a few (or many) articles from the summary
4784 @kindex / / (Summary)
4785 @findex gnus-summary-limit-to-subject
4786 Limit the summary buffer to articles that match some subject
4787 (@code{gnus-summary-limit-to-subject}).
4791 @kindex / u (Summary)
4793 @findex gnus-summary-limit-to-unread
4794 Limit the summary buffer to articles that are not marked as read
4795 (@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
4796 buffer to articles that are strictly unread. This means that ticked and
4797 dormant articles will also be excluded.
4800 @kindex / m (Summary)
4801 @findex gnus-summary-limit-to-marks
4802 Ask for a mark and then limit to all articles that have not been marked
4803 with that mark (@code{gnus-summary-limit-to-marks}).
4806 @kindex / n (Summary)
4808 Limit the summary buffer to the current article
4809 (@code{gnus-summary-limit-to-articles}). Uses the process/prefix
4810 convention (@pxref{Process/Prefix}).
4813 @kindex / w (Summary)
4814 @findex gnus-summary-pop-limit
4815 Pop the previous limit off the stack and restore it
4816 (@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
4821 @kindex / s (Summary)
4823 @findex gnus-summary-limit-to-subject
4824 Limit the summary buffer to articles that have a subject that matches a
4825 regexp (@code{gnus-summary-limit-to-subject}).
4828 @kindex / v (Summary)
4829 @findex gnus-summary-limit-to-score
4830 Limit the summary buffer to articles that have a score at or above some
4831 score (@code{gnus-summary-limit-to-score}).
4835 @kindex M S (Summary)
4836 @kindex / E (Summary)
4837 @findex gnus-summary-limit-include-expunged
4838 Display all expunged articles
4839 (@code{gnus-summary-limit-include-expunged}).
4842 @kindex / D (Summary)
4843 @findex gnus-summary-limit-include-dormant
4844 Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
4847 @kindex / d (Summary)
4848 @findex gnus-summary-limit-exclude-dormant
4849 Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
4852 @kindex / c (Summary)
4853 @findex gnus-summary-limit-exclude-childless-dormant
4854 Hide all dormant articles that have no children
4855 (@code{gnus-summary-limit-exclude-childless-dormant}).
4863 @cindex article threading
4865 Gnus threads articles by default. @dfn{To thread} is to put replies to
4866 articles directly after the articles they reply to---in a hierarchical
4870 * Customizing Threading:: Variables you can change to affect the threading.
4871 * Thread Commands:: Thread based commands in the summary buffer.
4874 @node Customizing Threading
4875 @subsection Customizing Threading
4876 @cindex customizing threading
4881 @item gnus-show-threads
4882 @vindex gnus-show-threads
4883 If this variable is @code{nil}, no threading will be done, and all of
4884 the rest of the variables here will have no effect. Turning threading
4885 off will speed group selection up a bit, but it is sure to make reading
4886 slower and more awkward.
4888 @item gnus-fetch-old-headers
4889 @vindex gnus-fetch-old-headers
4890 If non-@code{nil}, Gnus will attempt to build old threads by fetching
4891 more old headers---headers to articles that are marked as read. If you
4892 would like to display as few summary lines as possible, but still
4893 connect as many loose threads as possible, you should set this variable
4894 to @code{some} or a number. If you set it to a number, no more than
4895 that number of extra old headers will be fetched. In either case,
4896 fetching old headers only works if the backend you are using carries
4897 overview files---this would normally be @code{nntp}, @code{nnspool} and
4898 @code{nnml}. Also remember that if the root of the thread has been
4899 expired by the server, there's not much Gnus can do about that.
4901 @item gnus-summary-gather-subject-limit
4902 Loose threads are gathered by comparing subjects of articles. If this
4903 variable is @code{nil}, Gnus requires an exact match between the
4904 subjects of the loose threads before gathering them into one big
4905 super-thread. This might be too strict a requirement, what with the
4906 presence of stupid newsreaders that chop off long subjects lines. If
4907 you think so, set this variable to, say, 20 to require that only the
4908 first 20 characters of the subjects have to match. If you set this
4909 variable to a real low number, you'll find that Gnus will gather
4910 everything in sight into one thread, which isn't very helpful.
4912 @cindex fuzzy article gathering
4913 If you set this variable to the special value @code{fuzzy}, Gnus will
4914 use a fuzzy string comparison algorithm on the subjects.
4916 @vindex gnus-summary-gather-exclude-subject
4917 Since loose thread gathering is done on subjects only, that might lead
4918 to many false hits, especially with certain common subjects like
4919 @samp{""} and @samp{"(none)"}. To make the situation slightly better,
4920 you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
4921 what subjects should be excluded from the gathering process. The
4922 default is @samp{"^ *$\\|^(none)$"}.
4924 @item gnus-summary-make-false-root
4925 @vindex gnus-summary-make-false-root
4926 If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
4927 and create a dummy root at the top. (Wait a minute. Root at the top?
4928 Yup.) Loose subtrees occur when the real root has expired, or you've
4929 read or killed the root in a previous session.
4931 When there is no real root of a thread, Gnus will have to fudge
4932 something. This variable says what fudging method Gnus should use.
4933 There are four possible values:
4935 @cindex adopting articles
4939 Gnus will make the first of the orphaned articles the parent. This
4940 parent will adopt all the other articles. The adopted articles will be
4941 marked as such by pointy brackets (@samp{<>}) instead of the standard
4942 square brackets (@samp{[]}). This is the default method.
4945 Gnus will create a dummy summary line that will pretend to be the
4946 parent. This dummy line does not correspond to any real article, so
4947 selecting it will just select the first real article after the dummy
4951 Gnus won't actually make any article the parent, but simply leave the
4952 subject field of all orphans except the first empty. (Actually, it will
4953 use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
4957 Don't make any article parent at all. Just gather the threads and
4958 display them after one another.
4961 Don't gather loose threads.
4964 @item gnus-thread-hide-subtree
4965 @vindex gnus-thread-hide-subtree
4966 If non-@code{nil}, all threads will be hidden when the summary buffer is
4969 @item gnus-thread-hide-killed
4970 @vindex gnus-thread-hide-killed
4971 if you kill a thread and this variable is non-@code{nil}, the subtree
4974 @item gnus-thread-ignore-subject
4975 @vindex gnus-thread-ignore-subject
4976 Sometimes somebody changes the subject in the middle of a thread. If
4977 this variable is non-@code{nil}, the subject change is ignored. If it
4978 is @code{nil}, which is the default, a change in the subject will result
4981 @item gnus-thread-indent-level
4982 @vindex gnus-thread-indent-level
4983 This is a number that says how much each sub-thread should be indented.
4984 The default is @samp{4}.
4987 @node Thread Commands
4988 @subsection Thread Commands
4989 @cindex thread commands
4995 @kindex T k (Summary)
4996 @kindex M-C-k (Summary)
4997 @findex gnus-summary-kill-thread
4998 Mark all articles in the current sub-thread as read
4999 (@code{gnus-summary-kill-thread}). If the prefix argument is positive,
5000 remove all marks instead. If the prefix argument is negative, tick
5005 @kindex T l (Summary)
5006 @kindex M-C-l (Summary)
5007 @findex gnus-summary-lower-thread
5008 Lower the score of the current thread
5009 (@code{gnus-summary-lower-thread}).
5012 @kindex T i (Summary)
5013 @findex gnus-summary-raise-thread
5014 Increase the score of the current thread
5015 (@code{gnus-summary-raise-thread}).
5018 @kindex T # (Summary)
5019 @findex gnus-uu-mark-thread
5020 Set the process mark on the current thread
5021 (@code{gnus-uu-mark-thread}).
5024 @kindex T M-# (Summary)
5025 @findex gnus-uu-unmark-thread
5026 Remove the process mark from the current thread
5027 (@code{gnus-uu-unmark-thread}).
5030 @kindex T T (Summary)
5031 @findex gnus-summary-toggle-threads
5032 Toggle threading (@code{gnus-summary-toggle-threads}).
5035 @kindex T s (Summary)
5036 @findex gnus-summary-show-thread
5037 Expose the thread hidden under the current article, if any
5038 (@code{gnus-summary-show-thread}).
5041 @kindex T h (Summary)
5042 @findex gnus-summary-hide-thread
5043 Hide the current (sub)thread (@code{gnus-summary-hide-thread}).
5046 @kindex T S (Summary)
5047 @findex gnus-summary-show-all-threads
5048 Expose all hidden threads (@code{gnus-summary-show-all-threads}).
5051 @kindex T H (Summary)
5052 @findex gnus-summary-hide-all-threads
5053 Hide all threads (@code{gnus-summary-hide-all-threads}).
5056 The following commands are thread movement commands. They all
5057 understand the numeric prefix.
5061 @kindex T n (Summary)
5062 @findex gnus-summary-next-thread
5063 Go to the next thread (@code{gnus-summary-next-thread}).
5065 @kindex T p (Summary)
5066 @findex gnus-summary-prev-thread
5067 Go to the previous thread (@code{gnus-summary-prev-thread}).
5069 @kindex T d (Summary)
5070 @findex gnus-summary-down-thread
5071 Descend the thread (@code{gnus-summary-down-thread}).
5073 @kindex T u (Summary)
5074 @findex gnus-summary-up-thread
5075 Ascend the thread (@code{gnus-summary-up-thread}).
5078 @vindex gnus-thread-operation-ignore-subject
5079 If you ignore subject while threading, you'll naturally end up with
5080 threads that have several different subjects in them. If you then issue
5081 a command like `T k' (@code{gnus-summary-kill-thread}) you might not
5082 wish to kill the entire thread, but just those parts of the thread that
5083 have the same subject as the current article. If you like this idea,
5084 you can fiddle with @code{gnus-thread-operation-ignore-subject}. If is
5085 is non-@code{nil} (which it is by default), subjects will be ignored
5086 when doing thread commands. If this variable is @code{nil}, articles in
5087 the same thread with different subjects will not be included in the
5088 operation in question. If this variable is @code{fuzzy}, only articles
5089 that have subjects that are fuzzily equal will be included.
5092 @node Asynchronous Fetching
5093 @section Asynchronous Article Fetching
5094 @cindex asynchronous article fetching
5096 If you read your news from an @sc{nntp} server that's far away, the
5097 network latencies may make reading articles a chore. You have to wait
5098 for a while after pressing @kbd{n} to go to the next article before the
5099 article appears. Why can't Gnus just go ahead and fetch the article
5100 while you are reading the previous one? Why not, indeed.
5102 First, some caveats. There are some pitfalls to using asynchronous
5103 article fetching, especially the way Gnus does it.
5105 Let's say you are reading article 1, which is short, and article 2 is
5106 quite long, and you are not interested in reading that. Gnus does not
5107 know this, so it goes ahead and fetches article 2. You decide to read
5108 article 3, but since Gnus is in the process of fetching article 2, the
5109 connection is blocked.
5111 To avoid these situations, Gnus will open two (count 'em two)
5112 connections to the server. Some people may think this isn't a very nice
5113 thing to do, but I don't see any real alternatives. Setting up that
5114 extra connection takes some time, so Gnus startup will be slower.
5116 Gnus will fetch more articles than you will read. This will mean that
5117 the link between your machine and the @sc{nntp} server will become more
5118 loaded than if you didn't use article pre-fetch. The server itself will
5119 also become more loaded---both with the extra article requests, and the
5122 Ok, so now you know that you shouldn't really use this thing... unless
5125 @vindex gnus-asynchronous
5126 Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
5127 happen automatically.
5129 @vindex nntp-async-number
5130 You can control how many articles that are to be pre-fetched by setting
5131 @code{nntp-async-number}. This is five by default, which means that when
5132 you read an article in the group, @code{nntp} will pre-fetch the next
5133 five articles. If this variable is @code{t}, @code{nntp} will pre-fetch
5134 all the articles that it can without bound. If it is @code{nil}, no
5135 pre-fetching will be made.
5137 @vindex gnus-asynchronous-article-function
5138 You may wish to create some sort of scheme for choosing which articles
5139 that @code{nntp} should consider as candidates for pre-fetching. For
5140 instance, you may wish to pre-fetch all articles with high scores, and
5141 not pre-fetch low-scored articles. You can do that by setting the
5142 @code{gnus-asynchronous-article-function}, which will be called with an
5143 alist where the keys are the article numbers. Your function should
5144 return an alist where the articles you are not interested in have been
5145 removed. You could also do sorting on article score and the like.
5147 @node Article Caching
5148 @section Article Caching
5149 @cindex article caching
5152 If you have an @emph{extremely} slow @sc{nntp} connection, you may
5153 consider turning article caching on. Each article will then be stored
5154 locally under your home directory. As you may surmise, this could
5155 potentially use @emph{huge} amounts of disk space, as well as eat up all
5156 your inodes so fast it will make your head swim. In vodka.
5158 Used carefully, though, it could be just an easier way to save articles.
5160 @vindex gnus-use-long-file-name
5161 @vindex gnus-cache-directory
5162 @vindex gnus-use-cache
5163 To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
5164 all articles that are ticked or marked as dormant will then be copied
5165 over to your local cache (@code{gnus-cache-directory}). Whether this
5166 cache is flat or hierarchal is controlled by the
5167 @code{gnus-use-long-file-name} variable, as usual.
5169 When re-select a ticked or dormant article, it will be fetched from the
5170 cache instead of from the server. As articles in your cache will never
5171 expire, this might serve as a method of saving articles while still
5172 keeping them where they belong. Just mark all articles you want to save
5173 as dormant, and don't worry.
5175 When an article is marked as read, is it removed from the cache.
5177 @vindex gnus-cache-remove-articles
5178 @vindex gnus-cache-enter-articles
5179 The entering/removal of articles from the cache is controlled by the
5180 @code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
5181 variables. Both are lists of symbols. The first is @code{(ticked
5182 dormant)} by default, meaning that ticked and dormant articles will be
5183 put in the cache. The latter is @code{(read)} by default, meaning that
5184 articles that are marked as read are removed from the cache. Possibly
5185 symbols in these two lists are @code{ticked}, @code{dormant},
5186 @code{unread} and @code{read}.
5188 @findex gnus-jog-cache
5189 So where does the massive article-fetching and storing come into the
5190 picture? The @code{gnus-jog-cache} command will go through all
5191 subscribed newsgroups, request all unread articles, and store them in
5192 the cache. You should only ever, ever ever ever, use this command if 1)
5193 your connection to the @sc{nntp} server is really, really, really slow
5194 and 2) you have a really, really, really huge disk. Seriously.
5196 @vindex gnus-uncacheable-groups
5197 It is likely that you do not want caching on some groups. For instance,
5198 if your @code{nnml} mail is located under your home directory, it makes no
5199 sense to cache it somewhere else under your home directory. Unless you
5200 feel that it's neat to use twice as much space. To limit the caching,
5201 you could set the @code{gnus-uncacheable-groups} regexp to
5202 @samp{"^nnml"}, for instance. This variable is @samp{"^nnvirtual"} by
5203 default, since caching doesn't really work in @code{nnvirtual} groups,
5204 since @code{nnvirtual} assigns random article numbers to its articles.
5207 @node Article Backlog
5208 @section Article Backlog
5210 @cindex article backlog
5212 If you have a slow connection, but the idea of using caching seems
5213 unappealing to you (and it is, really), you can help the situation some
5214 by switching on the @dfn{backlog}. This is where Gnus will buffer
5215 already read articles so that it doesn't have to re-fetch articles
5216 you've already read. This only helps if you are in the habit of
5217 re-selecting articles you've recently read, of course. If you never do
5218 that, turning the backlog on will slow Gnus down a little bit, and
5219 increase memory usage some.
5221 @vindex gnus-keep-backlog
5222 If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store
5223 at most @var{n} old articles in a buffer for later re-fetching. If this
5224 variable is non-@code{nil} and is not a number, Gnus will store
5225 @emph{all} read articles, which means that your Emacs will group without
5226 bound before exploding and taking your machine down with you. I put
5227 that in there just to keep y'all on your toes.
5229 This variable is @code{nil} by default.
5232 @node Exiting the Summary Buffer
5233 @section Exiting the Summary Buffer
5234 @cindex summary exit
5236 Exiting from the summary buffer will normally update all info on the
5237 group and return you to the group buffer.
5242 @kindex Z Z (Summary)
5244 @findex gnus-summary-exit
5245 @vindex gnus-summary-exit-hook
5246 @vindex gnus-summary-prepare-exit-hook
5247 Exit the current group and update all information on the group
5248 (@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
5249 called before doing much of the exiting, and calls
5250 @code{gnus-summary-expire-articles} by default.
5251 @code{gnus-summary-exit-hook} is called after finishing the exiting
5255 @kindex Z E (Summary)
5257 @findex gnus-summary-exit-no-update
5258 Exit the current group without updating any information on the group
5259 (@code{gnus-summary-exit-no-update}).
5262 @kindex Z c (Summary)
5264 @findex gnus-summary-catchup-and-exit
5265 Mark all unticked articles in the group as read and then exit
5266 (@code{gnus-summary-catchup-and-exit}).
5268 @kindex Z C (Summary)
5269 @findex gnus-summary-catchup-all-and-exit
5270 Mark all articles, even the ticked ones, as read and then exit
5271 (@code{gnus-summary-catchup-all-and-exit}).
5273 @kindex Z n (Summary)
5274 @findex gnus-summary-catchup-and-goto-next-group
5275 Mark all articles as read and go to the next group
5276 (@code{gnus-summary-catchup-and-goto-next-group}).
5278 @kindex Z R (Summary)
5279 @findex gnus-summary-reselect-current-group
5280 Exit this group, and then enter it again
5281 (@code{gnus-summary-reselect-current-group}). If given a prefix, select
5282 all articles, both read and unread.
5285 @kindex Z G (Summary)
5286 @kindex M-g (Summary)
5287 @findex gnus-summary-rescan-group
5288 Exit the group, check for new articles in the group, and select the
5289 group (@code{gnus-summary-rescan-group}). If given a prefix, select all
5290 articles, both read and unread.
5292 @kindex Z N (Summary)
5293 @findex gnus-summary-next-group
5294 Exit the group and go to the next group
5295 (@code{gnus-summary-next-group}).
5297 @kindex Z P (Summary)
5298 @findex gnus-summary-prev-group
5299 Exit the group and go to the previous group
5300 (@code{gnus-summary-prev-group}).
5303 @vindex gnus-exit-group-hook
5304 @code{gnus-exit-group-hook} is called when you exit the current
5307 @vindex gnus-use-cross-reference
5308 The data on the current group will be updated (which articles you have
5309 read, which articles you have replied to, etc.) when you exit the
5310 summary buffer. If the @code{gnus-use-cross-reference} variable is
5311 @code{t} (which is the default), articles that are cross-referenced to
5312 this group and are marked as read, will also be marked as read in the
5313 other subscribed groups they were cross-posted to. If this variable is
5314 neither @code{nil} nor @code{t}, the article will be marked as read in
5315 both subscribed and unsubscribed groups.
5317 Marking cross-posted articles as read ensures that you'll never have to
5318 read the same article more than once. Unless, of course, somebody has
5319 posted it to several groups separately. Posting the same article to
5320 several groups (not cross-posting) is called @dfn{spamming}, and you are
5321 by law required to send nasty-grams to anyone who perpetrates such a
5324 Remember: Cross-posting is kinda ok, but posting the same article
5325 separately to several groups is not.
5327 One thing that may cause Gnus to not do the cross-posting thing
5328 correctly is if you use an @sc{nntp} server that supports @sc{xover}
5329 (which is very nice, because it speeds things up considerably) which
5330 does not include the @code{Xref} header in its @sc{nov} lines. This is
5331 Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
5332 even with @sc{xover} by registering the @code{Xref} lines of all
5333 articles you actually read, but if you kill the articles, or just mark
5334 them as read without reading them, Gnus will not get a chance to snoop
5335 the @code{Xref} lines out of these articles, and will be unable to use
5336 the cross reference mechanism.
5338 @vindex gnus-nov-is-evil
5339 If you want Gnus to get the @code{Xref}s right all the time, you have to
5340 set @code{gnus-nov-is-evil} to @code{t}, which slows things down
5345 @node Process/Prefix
5346 @section Process/Prefix
5347 @cindex process/prefix convention
5349 Many functions, among them functions for moving, decoding and saving
5350 articles, use what is known as the @dfn{Process/Prefix convention}.
5352 This is a method for figuring out what articles that the user wants the
5353 command to be performed on.
5357 If the numeric prefix is N, perform the operation on the next N
5358 articles, starting with the current one. If the numeric prefix is
5359 negative, perform the operation on the previous N articles, starting
5360 with the current one.
5362 If there is no numeric prefix, but some articles are marked with the
5363 process mark, perform the operation on the articles that are marked with
5366 If there is neither a numeric prefix nor any articles marked with the
5367 process mark, just perform the operation on the current article.
5369 Quite simple, really, but it needs to be made clear so that surprises
5372 @node Saving Articles
5373 @section Saving Articles
5374 @cindex saving articles
5376 Gnus can save articles in a number of ways. Below is the documentation
5377 for saving articles in a fairly straight-forward fashion (i.e., little
5378 processing of the article is done before it is saved). For a different
5379 approach (uudecoding, unsharing) you should use @code{gnus-uu}
5380 (@pxref{Decoding Articles}).
5382 @vindex gnus-save-all-headers
5383 If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
5384 unwanted headers before saving the article.
5386 @vindex gnus-saved-headers
5387 If the preceeding variable is @code{nil}, all headers that match the
5388 @code{gnus-saved-headers} regexp will be kept, while the rest will be
5389 deleted before saving.
5395 @kindex O o (Summary)
5397 @findex gnus-summary-save-article
5398 Save the current article using the default article saver
5399 (@code{gnus-summary-save-article}).
5402 @kindex O m (Summary)
5403 @findex gnus-summary-save-article-mail
5404 Save the current article in mail format
5405 (@code{gnus-summary-save-article-mail}).
5408 @kindex O r (Summary)
5409 @findex gnus-summary-save-article-mail
5410 Save the current article in rmail format
5411 (@code{gnus-summary-save-article-rmail}).
5414 @kindex O f (Summary)
5415 @findex gnus-summary-save-article-file
5416 Save the current article in plain file format
5417 (@code{gnus-summary-save-article-file}).
5420 @kindex O b (Summary)
5421 @findex gnus-summary-save-article-body-file
5422 Save the current article body in plain file format
5423 (@code{gnus-summary-save-article-body-file}).
5426 @kindex O h (Summary)
5427 @findex gnus-summary-save-article-folder
5428 Save the current article in mh folder format
5429 (@code{gnus-summary-save-article-folder}).
5432 @kindex O p (Summary)
5433 @findex gnus-summary-pipe-output
5434 Save the current article in a pipe. Uhm, like, what I mean is---Pipe
5435 the current article to a process (@code{gnus-summary-pipe-output}).
5438 @vindex gnus-prompt-before-saving
5439 All these commands use the process/prefix convention
5440 (@pxref{Process/Prefix}). If you save bunches of articles using these
5441 functions, you might get tired of being prompted for files to save each
5442 and every article in. The prompting action is controlled by
5443 the @code{gnus-prompt-before-saving} variable, which is @code{always} by
5444 default, giving you that excessive prompting action you know and
5445 loathe. If you set this variable to @code{t} instead, you'll be promted
5446 just once for each series of articles you save. If you like to really
5447 have Gnus do all your thinking for you, you can even set this variable
5448 to @code{nil}, which means that you will never be prompted for files to
5449 save articles in. Gnus will simply save all the articles in the default
5453 @vindex gnus-default-article-saver
5454 You can customize the @code{gnus-default-article-saver} variable to make
5455 Gnus do what you want it to. You can use any of the four ready-made
5456 functions below, or you can create your own.
5460 @item gnus-summary-save-in-rmail
5461 @findex gnus-summary-save-in-rmail
5462 This is the default format, @dfn{babyl}. Uses the function in the
5463 @code{gnus-rmail-save-name} variable to get a file name to save the
5464 article in. The default is @code{gnus-plain-save-name}.
5466 @item gnus-summary-save-in-mail
5467 @findex gnus-summary-save-in-mail
5468 Save in a Unix mail (mbox) file. Uses the function in the
5469 @code{gnus-mail-save-name} variable to get a file name to save the
5470 article in. The default is @code{gnus-plain-save-name}.
5472 @item gnus-summary-save-in-file
5473 @findex gnus-summary-save-in-file
5474 Append the article straight to an ordinary file. Uses the function in
5475 the @code{gnus-file-save-name} variable to get a file name to save the
5476 article in. The default is @code{gnus-numeric-save-name}.
5478 @item gnus-summary-save-body-in-file
5479 @findex gnus-summary-save-body-in-file
5480 Append the article body to an ordinary file. Uses the function in the
5481 @code{gnus-file-save-name} variable to get a file name to save the
5482 article in. The default is @code{gnus-numeric-save-name}.
5484 @item gnus-summary-save-in-folder
5485 @findex gnus-summary-save-in-folder
5486 Save the article to an MH folder using @code{rcvstore} from the MH
5489 @item gnus-summary-save-in-vm
5490 @findex gnus-summary-save-in-vm
5491 Save the article in a VM folder. You have to have the VM mail
5492 reader to use this setting.
5495 All of these functions, except for the last one, will save the article
5496 in the @code{gnus-article-save-directory}, which is initialized from the
5497 @samp{SAVEDIR} environment variable. This is @file{~/News/} by
5500 As you can see above, the functions use different functions to find a
5501 suitable name of a file to save the article in. Below is a list of
5502 available functions that generate names:
5505 @item gnus-Numeric-save-name
5506 @findex gnus-Numeric-save-name
5507 Generates file names that look like @samp{~/News/Alt.andrea-dworkin/45}.
5508 @item gnus-numeric-save-name
5509 @findex gnus-numeric-save-name
5510 Generates file names that look like @samp{~/News/alt.andrea-dworkin/45}.
5511 @item gnus-Plain-save-name
5512 @findex gnus-Plain-save-name
5513 Generates file names that look like @samp{~/News/Alt.andrea-dworkin}.
5514 @item gnus-plain-save-name
5515 @findex gnus-plain-save-name
5516 Generates file names that look like @samp{~/News/alt.andrea-dworkin}.
5519 @vindex gnus-split-methods
5520 You can have Gnus suggest where to save articles by plonking regexp into
5521 the @code{gnus-split-methods} alist. The syntax of this variable is the
5522 same as @code{nnmail-split-methods}. For instance, if you would like to
5523 save articles related to Gnus in the file @file{gnus-stuff}, and articles
5524 related to VM in @code{vm-stuff}, you could set this variable to something
5528 (("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
5529 ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff"))
5532 @vindex gnus-split-methods
5533 You can have Gnus suggest where to save articles by plonking regexp into
5534 the @code{gnus-split-methods} alist. The syntax of this variable is the
5535 same as @code{nnmail-split-methods}. For instance, if you would like to
5536 save articles related to Gnus in the file @file{gnus-stuff}, and articles
5537 related to VM in @code{vm-stuff}, you could set this variable to something
5541 (("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
5542 ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff"))
5545 @vindex gnus-use-long-file-name
5546 Finally, you have the @code{gnus-use-long-file-name} variable. If it is
5547 @code{nil}, all the preceding functions will replace all periods
5548 (@samp{.}) in the group names with slashes (@samp{/})---which means that
5549 the functions will generate hierarchies of directories instead of having
5550 all the files in the toplevel directory
5551 (@samp{~/News/alt/andrea-dworkin} instead of
5552 @samp{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default
5553 on most systems. However, for historical reasons, this is @code{nil} on
5554 Xenix and usg-unix-v machines by default.
5556 This function also affects kill and score file names. If this variable
5557 is a list, and the list contains the element @code{not-score}, long file
5558 names will not be used for score files, if it contains the element
5559 @code{not-save}, long file names will not be used for saving, and if it
5560 contains the element @code{not-kill}, long file names will not be used
5563 If you'd like to save articles in a hierarchy that looks something like
5567 (setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
5568 (setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
5571 Then just save with @kbd{o}. You'd then read this hierarchy with
5572 ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
5573 the toplevel directory as the argument (@file{~/News/}). Then just walk
5574 around to the groups/directories with @code{nneething}.
5577 @node Decoding Articles
5578 @section Decoding Articles
5579 @cindex decoding articles
5581 Sometime users post articles (or series of articles) that have been
5582 encoded in some way or other. Gnus can decode them for you.
5585 * Uuencoded Articles:: Uudecode articles.
5586 * Shared Articles:: Unshar articles.
5587 * PostScript Files:: Split PostScript.
5588 * Decoding Variables:: Variables for a happy decoding.
5589 * Viewing Files:: You want to look at the result of the decoding?
5592 All these functions use the process/prefix convention
5593 (@pxref{Process/Prefix}) for finding out what articles to work on, with
5594 the extension that a "single article" means "a single series". Gnus can
5595 find out by itself what articles belong to a series, decode all the
5596 articles and unpack/view/save the resulting file(s).
5598 Gnus guesses what articles are in the series according to the following
5599 simplish rule: The subjects must be (nearly) identical, except for the
5600 last two numbers of the line. (Spaces are largely ignored, however.)
5602 For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus
5603 will find all the articles that match the regexp @samp{^cat.gif
5604 ([0-9]+/[0-9]+).*$}.
5606 Subjects that are nonstandard, like @samp{cat.gif (2/3) Part 6 of a
5607 series}, will not be properly recognized by any of the automatic viewing
5608 commands, and you have to mark the articles manually with @key{#}.
5610 @node Uuencoded Articles
5611 @subsection Uuencoded Articles
5613 @cindex uuencoded articles
5617 @kindex X u (Summary)
5618 @findex gnus-uu-decode-uu
5619 Uudecodes the current series (@code{gnus-uu-decode-uu}).
5621 @kindex X U (Summary)
5622 @findex gnus-uu-decode-uu-and-save
5623 Uudecodes and saves the current series
5624 (@code{gnus-uu-decode-uu-and-save}).
5626 @kindex X v u (Summary)
5627 @findex gnus-uu-decode-uu-view
5628 Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
5630 @kindex X v U (Summary)
5631 @findex gnus-uu-decode-uu-and-save-view
5632 Uudecodes, views and saves the current series
5633 (@code{gnus-uu-decode-uu-and-save-view}).
5636 Remember that these all react to the presence of articles marked with
5637 the process mark. If, for instance, you'd like to uncode and save an
5638 entire newsgroup, you'd typically do @kbd{M P a}
5639 (@code{gnus-uu-mark-all}) and then @kbd{X U}
5640 (@code{gnus-uu-decode-uu-and-save}).
5642 All this is very much different from how @code{gnus-uu} worked with
5643 @sc{gnus 4.1}, where you had explicit keystrokes for everything under
5644 the sun. This version of @code{gnus-uu} generally assumes that you mark
5645 articles in some way (@pxref{Setting Process Marks}) and then press
5648 Note: When trying to decode articles that have names matching
5649 @code{gnus-uu-notify-files}, which is hard-coded to
5650 @samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
5651 automatically post an article on @samp{comp.unix.wizards} saying that
5652 you have just viewed the file in question. This feature can't be turned
5655 @node Shared Articles
5656 @subsection Shared Articles
5658 @cindex shared articles
5662 @kindex X s (Summary)
5663 @findex gnus-uu-decode-unshar
5664 Unshars the current series (@code{gnus-uu-decode-unshar}).
5666 @kindex X S (Summary)
5667 @findex gnus-uu-decode-unshar-and-save
5668 Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
5670 @kindex X v s (Summary)
5671 @findex gnus-uu-decode-unshar-view
5672 Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
5674 @kindex X v S (Summary)
5675 @findex gnus-uu-decode-unshar-and-save-view
5676 Unshars, views and saves the current series
5677 (@code{gnus-uu-decode-unshar-and-save-view}).
5680 @node PostScript Files
5681 @subsection PostScript Files
5686 @kindex X p (Summary)
5687 @findex gnus-uu-decode-postscript
5688 Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
5690 @kindex X P (Summary)
5691 @findex gnus-uu-decode-postscript-and-save
5692 Unpack and save the current PostScript series
5693 (@code{gnus-uu-decode-postscript-and-save}).
5695 @kindex X v p (Summary)
5696 @findex gnus-uu-decode-postscript-view
5697 View the current PostScript series
5698 (@code{gnus-uu-decode-postscript-view}).
5700 @kindex X v P (Summary)
5701 @findex gnus-uu-decode-postscript-and-save-view
5702 View and save the current PostScript series
5703 (@code{gnus-uu-decode-postscript-and-save-view}).
5706 @node Decoding Variables
5707 @subsection Decoding Variables
5709 Adjective, not verb.
5712 * Rule Variables:: Variables that say how a file is to be viewed.
5713 * Other Decode Variables:: Other decode variables.
5714 * Uuencoding & Posting:: Variables for customizing uuencoding.
5717 @node Rule Variables
5718 @subsubsection Rule Variables
5719 @cindex rule variables
5721 Gnus uses @dfn{rule variables} to decide how to view a file. All these
5722 variables are on the form
5725 (list '(regexp1 command2)
5731 @item gnus-uu-user-view-rules
5732 @vindex gnus-uu-user-view-rules
5733 This variable is consulted first when viewing files. If you wish to use,
5734 for instance, @code{sox} to convert an @samp{.au} sound file, you could
5737 (setq gnus-uu-user-view-rules
5738 (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
5740 @item gnus-uu-user-view-rules-end
5741 @vindex gnus-uu-user-view-rules-end
5742 This variable is consulted if Gnus couldn't make any matches from the
5743 user and default view rules.
5744 @item gnus-uu-user-archive-rules
5745 @vindex gnus-uu-user-archive-rules
5746 This variable can be used to say what commands should be used to unpack
5750 @node Other Decode Variables
5751 @subsubsection Other Decode Variables
5754 @item gnus-uu-ignore-files-by-name
5755 @vindex gnus-uu-ignore-files-by-name
5756 Files with name matching this regular expression won't be viewed.
5758 @item gnus-uu-ignore-files-by-type
5759 @vindex gnus-uu-ignore-files-by-type
5760 Files with a @sc{mime} type matching this variable won't be viewed.
5761 Note that Gnus tries to guess what type the file is based on the name.
5762 @code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
5765 @item gnus-uu-tmp-dir
5766 @vindex gnus-uu-tmp-dir
5767 Where @code{gnus-uu} does its work.
5769 @item gnus-uu-do-not-unpack-archives
5770 @vindex gnus-uu-do-not-unpack-archives
5771 Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
5772 looking for files to display.
5774 @item gnus-uu-view-and-save
5775 @vindex gnus-uu-view-and-save
5776 Non-@code{nil} means that the user will always be asked to save a file
5779 @item gnus-uu-ignore-default-view-rules
5780 @vindex gnus-uu-ignore-default-view-rules
5781 Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
5784 @item gnus-uu-ignore-default-archive-rules
5785 @vindex gnus-uu-ignore-default-archive-rules
5786 Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
5789 @item gnus-uu-kill-carriage-return
5790 @vindex gnus-uu-kill-carriage-return
5791 Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
5794 @item gnus-uu-unmark-articles-not-decoded
5795 @vindex gnus-uu-unmark-articles-not-decoded
5796 Non-@code{nil} means that @code{gnus-uu} will mark articles that were
5797 unsuccessfully decoded as unread.
5799 @item gnus-uu-correct-stripped-uucode
5800 @vindex gnus-uu-correct-stripped-uucode
5801 Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
5802 uuencoded files that have had trailing spaces deleted.
5804 @item gnus-uu-view-with-metamail
5805 @vindex gnus-uu-view-with-metamail
5806 Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
5807 commands defined by the rule variables and just fudge a @sc{mime}
5808 content type based on the file name. The result will be fed to
5809 @code{metamail} for viewing.
5811 @item gnus-uu-save-in-digest
5812 @vindex gnus-uu-save-in-digest
5813 Non-@code{nil} means that @code{gnus-uu}, when asked to save without
5814 decoding, will save in digests. If this variable is @code{nil},
5815 @code{gnus-uu} will just save everything in a file without any
5816 embellishments. The digesting almost conforms to RFC1153---no easy way
5817 to specify any meaningful volume and issue numbers were found, so I
5818 simply dropped them.
5822 @node Uuencoding & Posting
5823 @subsubsection Uuencoding & Posting
5827 @item gnus-uu-post-include-before-composing
5828 @vindex gnus-uu-post-include-before-composing
5829 Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
5830 before you compose the article. If this variable is @code{t}, you can
5831 either include an encoded file with @key{C-c C-i} or have one included
5832 for you when you post the article.
5834 @item gnus-uu-post-length
5835 @vindex gnus-uu-post-length
5836 Maximum length of an article. The encoded file will be split into how
5837 many articles it takes to post the entire file.
5839 @item gnus-uu-post-threaded
5840 @vindex gnus-uu-post-threaded
5841 Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
5842 thread. This may not be smart, as no other decoder I have seen are able
5843 to follow threads when collecting uuencoded articles. (Well, I have
5844 seen one package that does that---@code{gnus-uu}, but somehow, I don't
5845 think that counts...) Default is @code{nil}.
5847 @item gnus-uu-post-separate-description
5848 @vindex gnus-uu-post-separate-description
5849 Non-@code{nil} means that the description will be posted in a separate
5850 article. The first article will typically be numbered (0/x). If this
5851 variable is @code{nil}, the description the user enters will be included
5852 at the beginning of the first article, which will be numbered (1/x).
5853 Default is @code{t}.
5858 @subsection Viewing Files
5859 @cindex viewing files
5860 @cindex pseudo-articles
5862 After decoding, if the file is some sort of archive, Gnus will attempt
5863 to unpack the archive and see if any of the files in the archive can be
5864 viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
5865 containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
5866 uncompress and detar the main file, and then view the two pictures.
5867 This unpacking process is recursive, so if the archive contains archives
5868 of archives, it'll all be unpacked.
5870 Finally, Gnus will normally insert a @dfn{pseudo-article} for each
5871 extracted file into the summary buffer. If you go to these "articles",
5872 you will be prompted for a command to run (usually Gnus will make a
5873 suggestion), and then the command will be run.
5875 @vindex gnus-view-pseudo-asynchronously
5876 If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
5877 until the viewing is done before proceeding.
5879 @vindex gnus-view-pseudos
5880 If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
5881 the pseudo-articles into the summary buffer, but view them
5882 immediately. If this variable is @code{not-confirm}, the user won't even
5883 be asked for a confirmation before viewing is done.
5885 @vindex gnus-view-pseudos-separately
5886 If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
5887 pseudo-article will be created for each file to be viewed. If
5888 @code{nil}, all files that use the same viewing command will be given as
5889 a list of parameters to that command.
5891 So; there you are, reading your @emph{pseudo-articles} in your
5892 @emph{virtual newsgroup} from the @emph{virtual server}; and you think:
5893 Why isn't anything real anymore? How did we get here?
5896 @node Article Treatment
5897 @section Article Treatment
5899 Reading through this huge manual, you may have quite forgotten that the
5900 object of newsreaders are to actually, like, read what people have
5901 written. Reading articles. Unfortunately, people are quite bad at
5902 writing, so there are tons of functions and variables to make reading
5903 these articles easier.
5906 * Article Highlighting:: You want to make the article look like fruit salad.
5907 * Article Hiding:: You also want to make certain info go away.
5908 * Article Washing:: Lots of way-neat functions to make life better.
5909 * Article Buttons:: Clcik on URLs, Message-IDs, addresses and the like.
5910 * Article Date:: Grumble, UT!
5914 @node Article Highlighting
5915 @subsection Article Highlighting
5918 Not only do you want your article buffer to look like fruit salad, but
5919 you want it to look like technicolor fruit salad.
5924 @kindex W H a (Summary)
5925 @findex gnus-article-highlight
5926 Highlight the current article (@code{gnus-article-highlight}).
5929 @kindex W H h (Summary)
5930 @findex gnus-article-highlight-headers
5931 @vindex gnus-header-face-alist
5932 Highlight the headers (@code{gnus-article-highlight-headers}). The
5933 highlighting will be done according to the @code{gnus-header-face-alist}
5934 variable, which is a list where each element has the form @var{(regexp
5935 name content)}. @var{regexp} is a regular expression for matching the
5936 header, @var{name} is the face used for highling the header name and
5937 @var{content} is the face for highlighting the header value. The first
5938 match made will be used.
5941 @kindex W H c (Summary)
5942 @findex gnus-article-highlight-citation
5943 Highlight cited text (@code{gnus-article-highlight-citation}).
5945 Some variables to customize the citation highlights:
5948 @vindex gnus-cite-parse-max-size
5949 @item gnus-cite-parse-max-size
5950 If the article size if bigger than this variable (which is 25000 by
5951 default), no citation highlighting will be performed.
5953 @item gnus-cite-prefix-regexp
5954 @vindex gnus-cite-prefix-regexp
5955 Regexp mathcing the longest possible citation prefix on a line.
5957 @item gnus-cite-max-prefix
5958 @vindex gnus-cite-max-prefix
5959 Maximum possible length for a citation prefix (default 20).
5961 @item gnus-supercite-regexp
5962 @vindex gnus-supercite-regexp
5963 Regexp matching normal SuperCite attribution lines.
5965 @item gnus-supercite-secondary-regexp
5966 @vindex gnus-supercite-secondary-regexp
5967 Regexp matching mangled SuperCite attribution lines.
5969 @item gnus-cite-minimum-match-count
5970 @vindex gnus-cite-minimum-match-count
5971 Minimum number of identical prefixes we have to see before we believe
5972 that it's a citation.
5974 @item gnus-cite-attribution-prefix
5975 @vindex gnus-cite-attribution-prefix
5976 Regexp matching the beginning of an attribution line.
5978 @item gnus-cite-addtribution-suffix
5979 @vindex gnus-cite-addtribution-suffix
5980 Regexp matching the end of an attribution line.
5982 @item gnus-cite-attribution-face
5983 @vindex gnus-cite-attribution-face
5984 Face used for attribution lines. It is merged with the face for the
5985 cited text belonging to the attribution.
5991 @kindex W H s (Summary)
5992 @vindex gnus-signature-separator
5993 @findex gnus-article-highlight-signature
5994 Highlight the signature (@code{gnus-article-highlight-signature}).
5995 Everything after @code{gnus-signature-separator} in an article will be
5996 considered a signature.
6001 @node Article Hiding
6002 @subsection Article Hiding
6003 @cindex article hiding
6005 Or rather, hiding certain things in each article. There usually is much
6006 to much gruft in most articles.
6011 @kindex W W a (Summary)
6012 @findex gnus-article-hide
6013 Do maximum hiding on the summary buffer (@kbd{gnus-article-hide}).
6016 @kindex W W h (Summary)
6017 @findex gnus-article-hide-headers
6018 Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
6022 @kindex W W s (Summary)
6023 @findex gnus-article-hide-signature
6024 Hide signature (@code{gnus-article-hide-signature}).
6027 @kindex W W p (Summary)
6028 @findex gnus-article-hide-pgp
6029 Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}).
6032 @kindex W W c (Summary)
6033 @findex gnus-article-hide-citation
6034 Hide citation (@code{gnus-article-hide-citation}). Two variables for
6035 customizing the hiding:
6039 @item gnus-cite-hide-percentage
6040 @vindex gnus-cite-hide-percentage
6041 If the cited text is of a bigger percentage than this variable (default
6042 50), hide the cited text.
6044 @item gnus-cite-hide-absolute
6045 @vindex gnus-cite-hide-absolute
6046 The cited text must be have at least this length (default 10) before it
6051 Also see @xref{Article Highlighting} for further variables for
6052 citation customization.
6057 @node Article Washing
6058 @subsection Article Washing
6060 @cindex article washing
6062 We call this "article washing" for a really good reason. Namely, the
6063 @kbd{A} key was taken, so we had to use the @kbd{W} key instead.
6065 @dfn{Washing} is defined by us as "changing something from something to
6066 something else", but normally results in something looking better.
6072 @kindex W l (Summary)
6073 @findex gnus-summary-stop-page-breaking
6074 Remove page breaks from the current article
6075 (@code{gnus-summary-stop-page-breaking}).
6078 @kindex W r (Summary)
6079 @findex gnus-summary-caesar-message
6080 Do a Caesar rotate (rot13) on the article buffer
6081 (@code{gnus-summary-caesar-message}).
6084 @kindex A g (Summary)
6085 @findex gnus-summary-show-article
6086 (Re)fetch the current article (@code{gnus-summary-show-article}). If
6087 given a prefix, fetch the current article, but don't run any of the
6088 article treatment functions. This will give you a "raw" article, just
6089 the way it came from the server.
6092 @kindex W t (Summary)
6093 @findex gnus-summary-toggle-header
6094 Toggle whether to display all headers in the article buffer
6095 (@code{gnus-summary-toggle-header}).
6098 @kindex W m (Summary)
6099 @findex gnus-summary-toggle-mime
6100 Toggle whether to run the article through @sc{mime} before displaying
6101 (@code{gnus-summary-toggle-mime}).
6104 @kindex W o (Summary)
6105 @findex gnus-article-treat-overstrike
6106 Treat overstrike (@code{gnus-article-treat-overstrike}).
6109 @kindex W w (Summary)
6110 @findex gnus-article-word-wrap
6111 Do word wrap (@code{gnus-article-word-wrap}).
6114 @kindex W c (Summary)
6115 @findex gnus-article-remove-cr
6116 Remove CR (@code{gnus-article-remove-cr}).
6119 @kindex W q (Summary)
6120 @findex gnus-article-de-quoted-unreadable
6121 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
6124 @kindex W f (Summary)
6126 @findex gnus-article-display-x-face
6127 @findex gnus-article-x-face-command
6128 @vindex gnus-article-x-face-command
6129 @vindex gnus-article-x-face-too-ugly
6130 Look for and display any X-Face headers
6131 (@code{gnus-article-display-x-face}). The command executed by this
6132 function is given by the @code{gnus-article-x-face-command} variable. If
6133 this variable is a string, this string will be executed in a sub-shell.
6134 If it is a function, this function will be called with the face as the
6135 argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
6136 matches the @code{From} header, the face will not be shown.
6139 @kindex W b (Summary)
6140 @findex gnus-article-add-buttons
6141 Add clickable buttons to the article (@code{gnus-article-add-buttons}).
6144 @kindex W B (Summary)
6145 @findex gnus-article-add-buttons-to-head
6146 Add clickable buttons to the article headers
6147 (@code{gnus-article-add-buttons-to-head}).
6152 @node Article Buttons
6153 @subsection Article Buttons
6156 People often include references to other stuff in articles, and it would
6157 be nice if Gnus could just fetch whatever it is that people talk about
6158 with the minimum of fuzz.
6160 Gnus adds @dfn{buttons} to certain standard references by default:
6161 Well-formed URLs, mail addresses and Message-IDs. This is controlled by
6162 two variables, one that handles article bodies and one that handles
6167 @item gnus-button-alist
6168 @vindex gnus-header-button-alist
6169 This is an alist where each entry has this form:
6172 (REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
6178 All text that match this regular expression will be considered an
6179 external reference. Here's a typical regexp that match embedded URLs:
6180 @samp{"<URL:\\([^\n\r>]*\\)>"}.
6183 Gnus has to know which parts of the match is to be highlighted. This is
6184 a number that says what sub-expression of the regexp that is to be
6185 highlighted. If you want it all highlighted, you use @samp{0} here.
6188 This form will be @code{eval}ed, and if the result is non-@code{nil},
6189 this is considered a match. This is useful if you want extra sifting to
6190 avoid false matches.
6193 This function will be called when you click on this button.
6196 As with @var{button-par}, this is a sub-expression number, but this one
6197 says which part of the match is to be sent as data to @var{function}.
6201 So the full entry for buttonizing URLs is then
6204 ("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
6207 @item gnus-header-button-alist
6208 @vindex gnus-header-button-alist
6209 This is just like the other alist, except that it is applied to the
6210 article head only, and that each entry has an additional element that is
6211 used to say what headers to apply the buttonize coding to:
6214 (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
6217 @var{header} is a regular expression.
6221 @vindex gnus-article-button-face
6222 @vindex gnus-article-mouse-face
6223 Buttons are highlighted with @code{gnus-article-button-face}, while
6224 @code{gnus-article-mouse-face} is used when the mouse cursor is over the
6229 @subsection Article Date
6231 The date is most likely generated in some obscure timezone you've never
6232 heard of, so it's quite nice to be able to find out what the time was
6233 when the article was sent.
6238 @kindex W T u (Summary)
6239 @findex gnus-article-date-ut
6240 Display the date in UT (aka. GMT, aka ZULU)
6241 (@code{gnus-article-date-ut}).
6244 @kindex W T l (Summary)
6245 @findex gnus-article-date-local
6246 Display the date in the local timezone (@code{gnus-article-date-local}).
6249 @kindex W T e (Summary)
6250 @findex gnus-article-date-lapsed
6251 Say how much time has (e)lapsed between the article was posted and now
6252 (@code{gnus-article-date-lapsed}).
6255 @kindex W T o (Summary)
6256 @findex gnus-article-date-original
6257 Display the original date (@code{gnus-article-date-original}). This can
6258 be useful if you normally use some other conversion function and is
6259 worried that it might be doing something totally wrong. Say, claiming
6260 that the article was posted in 1854. Although something like that is
6261 @emph{totally} impossible. Don't you trust me? *titter*
6266 @node Summary Sorting
6267 @section Summary Sorting
6268 @cindex summary sorting
6270 You can have the summary buffer sorted in various ways, even though I
6271 can't really see why you'd want that.
6275 @kindex C-c C-s C-n (Summary)
6276 @findex gnus-summary-sort-by-number
6277 Sort by article number (@code{gnus-summary-sort-by-number}).
6279 @kindex C-c C-s C-a (Summary)
6280 @findex gnus-summary-sort-by-author
6281 Sort by author (@code{gnus-summary-sort-by-author}).
6283 @kindex C-c C-s C-s (Summary)
6284 @findex gnus-summary-sort-by-subject
6285 Sort by subject (@code{gnus-summary-sort-by-subject}).
6287 @kindex C-c C-s C-d (Summary)
6288 @findex gnus-summary-sort-by-date
6289 Sort by date (@code{gnus-summary-sort-by-date}).
6291 @kindex C-c C-s C-i (Summary)
6292 @findex gnus-summary-sort-by-score
6293 Sort by score (@code{gnus-summary-sort-by-score}).
6296 These functions will work both when you use threading and when you don't
6297 use threading. In the latter case, all summary lines will be sorted,
6298 line by line. In the former case, sorting will be done on a
6299 root-by-root basis, which might not be what you were looking for. To
6300 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
6304 @node Finding the Parent
6305 @section Finding the Parent
6306 @cindex parent articles
6307 @cindex referring articles
6309 @findex gnus-summary-refer-parent-article
6311 If you'd like to read the parent of the current article, and it is not
6312 displayed in the article buffer, you might still be able to. That is,
6313 if the current group is fetched by @sc{nntp}, the parent hasn't expired
6314 and the @code{References} in the current article are not mangled, you
6315 can just press @kbd{^} or @kbd{A r}
6316 (@code{gnus-summary-refer-parent-article}). If everything goes well,
6317 you'll get the parent. If the parent is already displayed in the
6318 summary buffer, point will just move to this article.
6320 @findex gnus-summary-refer-references
6321 @kindex A R (Summary)
6322 You can have Gnus fetch all articles mentioned in the @code{References}
6323 header of the article by pushing @kbd{A R}
6324 (@code{gnus-summary-refer-references}).
6326 @findex gnus-summary-refer-article
6327 @kindex M-^ (Summary)
6328 You can also ask the @sc{nntp} server for an arbitrary article, no
6329 matter what group it belongs to. @kbd{M-^}
6330 (@code{gnus-summary-refer-article}) will ask you for a
6331 @code{Message-ID}, which is one of those long thingies that look
6332 something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
6333 it all exactly right. No fuzzy searches, I'm afraid.
6335 @vindex gnus-refer-article-method
6336 If the group you are reading is located on a backend that does not
6337 support fetching by @code{Message-ID} very well (like @code{nnspool}),
6338 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
6339 would, perhaps, be best if the @sc{nntp} server you consult is the same
6340 as the one that keeps the spool you are reading from updated, but that's
6341 not really necessary.
6343 Most of the mail backends support fetching by @code{Message-ID}, but do
6344 not do a particularly excellent job of it. That is, @code{nnmbox} and
6345 @code{nnbabyl} are able to locate articles from any groups, while
6346 @code{nnml} and @code{nnfolder} are only able to locate articles that
6347 have been posted to the current group. (Anything else would be too time
6348 consuming.) @code{nnmh} does not support this at all.
6351 @node Mail Group Commands
6352 @section Mail Group Commands
6353 @cindex mail group commands
6355 Some commands only make sense in mail groups. If these commands are
6356 illegal in the current group, they will raise a hell and let you know.
6358 All these commands (except the expiry and edit commands) use the
6359 process/prefix convention (@pxref{Process/Prefix}).
6363 @kindex B e (Summary)
6364 @findex gnus-summary-expire-articles
6365 Expire all expirable articles in the group
6366 (@code{gnus-summary-expire-articles}).
6369 @kindex B M-C-e (Summary)
6370 @findex gnus-summary-expire-articles-now
6371 Expunge all the expirable articles in the group
6372 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
6373 articles that are eligeble for expiry in the current group will
6374 disappear forever into that big @file{/dev/null} in the sky.
6377 @kindex B DEL (Summary)
6378 @findex gnus-summary-delete-articles
6379 Delete the mail article. This is "delete" as in "delete it from your
6380 disk forever and ever, never to return again." Use with caution.
6381 (@code{gnus-summary-delete-article}).
6384 @kindex B m (Summary)
6386 @findex gnus-summary-move-article
6387 Move the article from one mail group to another
6388 (@code{gnus-summary-move-article}).
6391 @kindex B c (Summary)
6393 @findex gnus-summary-copy-article
6394 Copy the article from one group (mail group or not) to a mail group
6395 (@code{gnus-summary-copy-article}).
6398 @kindex B i (Summary)
6399 @findex gnus-summary-import-article
6400 Import a random file into the current mail newsgroup
6401 (@code{gnus-summary-import-article}). You will be prompted for a file
6402 name, a @code{From} header and a @code{Subject} header.
6404 Something similar can be done by just starting to compose a mail
6405 message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
6406 @kbd{C-c C-p} instead. This will put the message you have just created
6407 into the current mail group.
6410 @kindex B r (Summary)
6411 @findex gnus-summary-respool-article
6412 Respool the mail article (@code{gnus-summary-move-article}).
6416 @kindex B w (Summary)
6418 @findex gnus-summary-edit-article
6419 @kindex C-c C-c (Article)
6420 Edit the current article (@code{gnus-summary-edit-article}). To finish
6421 editing and make the changes permanent, type @kbd{C-c C-c}
6422 (@kbd{gnus-summary-edit-article-done}).
6425 @kindex B q (Summary)
6426 @findex gnus-summary-respool-query
6427 If you want to respool an article, you might be curious as to what group
6428 the article will end up in before you do the respooling. This command
6429 will tell you (@code{gnus-summary-fancy-query}).
6432 @node Various Summary Stuff
6433 @section Various Summary Stuff
6436 * Group Information:: Information oriented commands.
6437 * Searching for Articles:: Multiple article commands.
6438 * Really Various Summary Commands:: Those pesky non-conformant commands.
6441 @vindex gnus-summary-prepare-hook
6442 @code{gnus-summary-prepare-hook} is called after the summary buffer has
6443 been generated. You might use it to, for instance, highlight lines or
6444 modify the look of the buffer in some other ungodly manner. I don't
6447 @node Group Information
6448 @subsection Group Information
6452 @kindex H f (Summary)
6453 @findex gnus-summary-fetch-faq
6454 @vindex gnus-group-faq-directory
6455 Try to fetch the FAQ (list of frequently asked questions) for the
6456 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
6457 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
6458 on a remote machine. This variable can also be a list of directories.
6459 In that case, giving a prefix to this command will allow you to choose
6460 between the various sites. @code{ange-ftp} probably will be used for
6463 @kindex H d (Summary)
6464 @findex gnus-summary-describe-group
6465 Give a brief description of the current group
6466 (@code{gnus-summary-describe-group}). If given a prefix, force
6467 rereading the description from the server.
6469 @kindex H h (Summary)
6470 @findex gnus-summary-describe-briefly
6471 Give a very brief description of the most important summary keystrokes
6472 (@code{gnus-summary-describe-briefly}).
6474 @kindex H i (Summary)
6475 @findex gnus-info-find-node
6476 Go to the Gnus info node (@code{gnus-info-find-node}).
6479 @node Searching for Articles
6480 @subsection Searching for Articles
6484 @kindex M-s (Summary)
6485 @findex gnus-summary-search-article-forward
6486 Search through all subsequent articles for a regexp
6487 (@code{gnus-summary-search-article-forward}).
6489 @kindex M-r (Summary)
6490 @findex gnus-summary-search-article-backward
6491 Search through all previous articles for a regexp
6492 (@code{gnus-summary-search-article-backward}).
6495 @findex gnus-summary-execute-command
6496 This command will prompt you for a header field, a regular expression to
6497 match on this field, and a command to be executed if the match is made
6498 (@code{gnus-summary-execute-command}).
6500 @kindex M-& (Summary)
6501 @findex gnus-summary-universal-argument
6502 Perform any operation on all articles that have been marked with
6503 the process mark (@code{gnus-summary-universal-argument}).
6506 @node Really Various Summary Commands
6507 @subsection Really Various Summary Commands
6511 @kindex A D (Summary)
6512 @findex gnus-summary-enter-digest-group
6513 If the current article is a digest, you might use this command to enter
6514 you into a group based on the current digest to ease reading
6515 (@code{gnus-summary-enter-digest-group}).
6517 @kindex C-t (Summary)
6518 @findex gnus-summary-toggle-truncation
6519 Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
6522 @findex gnus-summary-expand-window
6523 Expand the summary buffer window (@code{gnus-summary-expand-window}).
6524 If given a prefix, force an @code{article} window configuration.
6527 @node The Article Buffer
6528 @chapter The Article Buffer
6529 @cindex article buffer
6531 The articles are displayed in the article buffer, of which there is only
6532 one. All the summary buffer share the same article buffer.
6535 * Hiding Headers:: Deciding what headers should be displayed.
6536 * Using Mime:: Pushing articles through @sc{mime} before reading them.
6537 * Customizing Articles:: Tailoring the look of the articles.
6538 * Article Keymap:: Keystrokes available in the article buffer
6539 * Misc Article:: Other stuff.
6542 @node Hiding Headers
6543 @section Hiding Headers
6544 @cindex hiding headers
6545 @cindex deleting headers
6547 The top section of each article is the @dfn{head}. (The rest is the
6548 @dfn{body}, but you may have guessed that already.)
6550 @vindex gnus-show-all-headers
6551 There is a lot of useful information in the head: the name of the person
6552 who wrote the article, the date it was written and the subject of the
6553 article. That's well and nice, but there's also lots of information
6554 most people do not want to see---what systems the article has passed
6555 through before reaching you, the @code{Message-ID}, the
6556 @code{References}, etc. ad nauseum---and you'll probably want to get rid
6557 of some of those lines. If you want to keep all those lines in the
6558 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
6560 Gnus provides you with two variables for sifting headers:
6563 @item gnus-visible-headers
6564 @vindex gnus-visible-headers
6565 If this variable is non-@code{nil}, it should be a regular expression
6566 that says what headers you wish to keep in the article buffer. All
6567 headers that do not match this variable will be hidden.
6569 For instance, if you only want to see the name of the person who wrote
6570 the article and the subject, you'd say:
6573 (setq gnus-visible-headers "^From:\\|^Subject:")
6576 @item gnus-ignored-headers
6577 @vindex gnus-ignored-headers
6578 This variable is the reverse of @code{gnus-visible-headers}. If this
6579 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
6580 should be a regular expression that matches all lines that you want to
6581 hide. All lines that do not match this variable will remain visible.
6583 For instance, if you just want to get rid of the @code{References} line
6584 and the @code{Xref} line, you might say:
6587 (setq gnus-ignored-headers "^References:\\|^Xref:")
6590 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
6591 variable will have no effect.
6594 @vindex gnus-sorted-header-list
6595 Gnus can also sort the headers for you. (It does this by default.) You
6596 can control the sorting by setting the @code{gnus-sorted-header-list}
6597 variable. It is a list of regular expressions that says in what order
6598 the headers are to be displayed.
6600 For instance, if you want the name of the author of the article first,
6601 and then the subject, you might say something like:
6604 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
6607 Any headers that are to remain visible, but are not listed in this
6608 variable, will be displayed in random order after all the headers that
6609 are listed in this variable.
6615 Mime is a standard for waving your hands through the air, aimlessly,
6616 while people stand around yawning.
6618 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
6619 while all newsreaders die of fear.
6621 @sc{mime} may specify what character set the article uses, the encoding
6622 of the characters, and it also makes it possible to embed pictures and
6623 other naughty stuff in innocent-looking articles.
6625 @vindex gnus-show-mime
6626 @vindex gnus-show-mime-method
6627 Gnus handles @sc{mime} by shoving the articles through
6628 @code{gnus-show-mime-method}, which is @code{metamail-buffer} by
6629 default. If @code{gnus-strict-mime} is non-@code{nil}, the @sc{mime}
6630 method will only be used it there are @sc{mime} headers in the article.
6631 Set @code{gnus-show-mime} to @code{t} if you want to use @sc{mime} all
6632 the time; it might be best to just use the toggling functions from the
6633 summary buffer to avoid getting nasty surprises. (For instance, you
6634 enter the group @samp{alt.sing-a-long} and, before you know it,
6635 @sc{mime} has decoded the sound file in the article and some horrible
6636 sing-a-long song comes streaming out out your speakers, and you can't
6637 find the volume button, because there isn't one, and people are starting
6638 to look at you, and you try to stop the program, but you can't, and you
6639 can't find the program to control the volume, and everybody else in the
6640 room suddenly decides to look at you disdainfully, and you'll feel
6643 Any similarity to real events and people is purely coincidental. Ahem.
6646 @node Customizing Articles
6647 @section Customizing Articles
6648 @cindex article customization
6650 @vindex gnus-article-display-hook
6651 The @code{gnus-article-display-hook} is called after the article has
6652 been inserted into the article buffer. It is meant to handle all
6653 treatment of the article before it is displayed.
6655 By default it contains @code{gnus-article-hide-headers},
6656 @code{gnus-article-treat-overstrike}, and
6657 @code{gnus-article-maybe-highlight}, but there are thousands, nay
6658 millions, of functions you can put in this hook. For an overview of
6659 functions @xref{Article Highlighting}, @xref{Article Hiding},
6660 @xref{Article Washing}, @xref{Article Buttons} and @xref{Article Date}.
6662 You can, of course, write your own functions. The functions are called
6663 from the article buffer, and you can do anything you like, pretty much.
6664 There is no information that you have to keep in the buffer---you can
6665 change everything. However, you shouldn't delete any headers. Instead
6666 make them invisible if you want to make them go away.
6669 @node Article Keymap
6670 @section Article Keymap
6672 @c Most of the keystrokes in the summary buffer can also be used in the
6673 @c article buffer. They should behave as if you typed them in the summary
6674 @c buffer, which means that you don't actually have to have a summary
6675 @c buffer displayed while reading. You can do it all from the article
6678 A few additional keystrokes are available:
6682 @kindex SPACE (Article)
6683 @findex gnus-article-next-page
6684 Scroll forwards one page (@code{gnus-article-next-page}).
6686 @kindex DEL (Article)
6687 @findex gnus-article-prev-page
6688 Scroll backwards one page (@code{gnus-article-prev-page}).
6690 @kindex C-c ^ (Article)
6691 @findex gnus-article-refer-article
6692 If point is in the neighborhood of a @code{Message-ID} and you press
6693 @kbd{r}, Gnus will try to get that article from the server
6694 (@code{gnus-article-refer-article}).
6696 @kindex C-c C-m (Article)
6697 @findex gnus-article-mail
6698 Send a reply to the address near point (@code{gnus-article-mail}). If
6699 given a prefix, include the mail.
6702 @findex gnus-article-show-summary
6703 Reconfigure the buffers so that the summary buffer becomes visible
6704 (@code{gnus-article-show-summary}).
6707 @findex gnus-article-describe-briefly
6708 Give a very brief description of the available keystrokes
6709 (@code{gnus-article-describe-briefly}).
6713 @section Misc Article
6716 @vindex gnus-article-prepare-hook
6717 @item gnus-article-prepare-hook
6718 This hook is called right after the article has been inserted into the
6719 article buffer. It is mainly intended for functions that do something
6720 depending on the contents; it should probably not be used for changing
6721 the contents of the article buffer.
6722 @vindex gnus-article-display-hook
6723 @item gnus-article-display-hook
6724 This hook is called as the last thing when displaying an article, and is
6725 intended for modifying the contents of the buffer, doing highlights,
6726 hiding headers, and the like.
6727 @vindex gnus-article-mode-line-format
6728 @item gnus-article-mode-line-format
6729 This variable is a format string along the same lines as
6730 @code{gnus-summary-mode-line-format}. It accepts exactly the same
6731 format specifications as that variable.
6732 @vindex gnus-break-pages
6733 @item gnus-break-pages
6734 Controls whether @dfn{page breaking} is to take place. If this variable
6735 is non-@code{nil}, the articles will be divided into pages whenever a
6736 page delimiter appears in the article. If this variable is @code{nil},
6737 paging will not be done.
6738 @item gnus-page-delimiter
6739 @vindex gnus-page-delimiter
6740 This is the delimiter mentioned above. By default, it is @samp{^L}
6744 @node The Server Buffer
6745 @chapter The Server Buffer
6747 Traditionally, a @dfn{server} is a machine or a piece of software that
6748 one connects to, and then requests information from. Gnus does not
6749 connect directly to any real servers, but does all transactions through
6750 one backend or other. But that's just putting one layer more between
6751 the actual media and Gnus, so we might just as well say that each
6752 backend represents a virtual server.
6754 For instance, the @code{nntp} backend may be used to connect to several
6755 different actual @sc{nntp} servers, or, perhaps, to many different ports
6756 on the same actual @sc{nntp} server. You tell Gnus which backend to
6757 use, and what parameters to set by specifying a @dfn{select method}.
6759 These select methods specifications can sometimes become quite
6760 complicated---say, for instance, that you want to read from the
6761 @sc{nntp} server @samp{news.funet.fi} on port number @samp{13}, which
6762 hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
6763 Anyways, if you had to specify that for each group that used this
6764 server, that would be too much work, so Gnus offers a way of putting
6765 names to methods, which is what you do in the server buffer.
6767 To enter the server buffer, user the @kbd{^}
6768 (@code{gnus-group-enter-server-mode}) command in the group buffer.
6771 * Server Buffer Format:: You can customize the look of this buffer.
6772 * Server Commands:: Commands to manipulate servers.
6773 * Example Methods:: Examples server specifications.
6774 * Servers & Methods:: You can use server names as select methods.
6775 * Unavailable Servers:: Some servers you try to contact may be down.
6778 @node Server Buffer Format
6779 @section Server Buffer Format
6780 @cindex server buffer format
6782 @vindex gnus-server-line-format
6783 You can change the look of the server buffer lines by changing the
6784 @code{gnus-server-line-format} variable. This is a @code{format}-like
6785 variable, with some simple extensions:
6789 How the news is fetched---the backend name.
6791 The name of this server.
6793 Where the news is to be fetched from---the address.
6796 @node Server Commands
6797 @section Server Commands
6798 @cindex server commands
6802 Browse the current server (@code{gnus-server-read-server}).
6804 Return to the group buffer (@code{gnus-server-exit}).
6806 List all servers (@code{gnus-server-list-servers}).
6808 Kill the current server (@code{gnus-server-kill-server}).
6810 Yank the previously killed server (@code{gnus-server-yank-server}).
6812 Copy the current server (@code{gnus-server-copy-server}).
6814 Add a new server (@code{gnus-server-add-server}).
6816 Edit a server (@code{gnus-server-edit-server}).
6819 @node Example Methods
6820 @section Example Methods
6822 Most select methods are pretty simple and self-explanatory:
6825 (nntp "news.funet.fi")
6828 Reading directly from the spool is even simpler:
6834 As you can see, the first element in a select method is the name of the
6835 backend, and the second is the @dfn{address}, or @dfn{name}, if you
6838 After these two elements, there may be a random number of @var{(variable
6841 To go back to the first example---imagine that you want to read from
6842 port @code{15} from that machine. This is what the select method should
6846 (nntp "news.funet.fi" (nntp-port-number 15))
6849 You should read the documentation to each backend to find out what
6850 variables are relevant, but here's an @code{nnmh} example.
6852 @code{nnmh} is a mail backend that reads a spool-like structure. Say
6853 you have two structures that you wish to access: One is your private
6854 mail spool, and the other is a public one. Here's the possible spec for
6858 (nnmh "private" (nnmh-directory "~/private/mail/"))
6861 (This server is then called @samp{private}, but you may have guessed
6864 Here's the method for the public spool:
6868 (nnmh-directory "/usr/information/spool/")
6869 (nnmh-get-new-mail nil))
6872 @node Servers & Methods
6873 @section Servers & Methods
6875 Wherever you would normally use a select method
6876 (eg. @code{gnus-secondary-select-method}, in the group select method,
6877 when browsing a foreign server) you can use a virtual server name
6878 instead. This could potentially save lots of typing. And it's nice all
6882 @node Unavailable Servers
6883 @section Unavailable Servers
6885 If a server seems to be unreachable, Gnus will mark that server as
6886 @code{denied}. That means that any subsequent attempt to make contact
6887 with that server will just be ignored. "It can't be opened," Gnus will
6888 tell you, without making the least effort to see whether that is
6889 actually the case or not.
6891 That might seem quite naughty, but it does make sense most of the time.
6892 Let's say you have 10 groups subscribed to the server
6893 @samp{nepholococcygia.com}. This server is located somewhere quite far
6894 away from you, the machine is quite, so it takes 1 minute just to find
6895 out that it refuses connection from you today. If Gnus were to attempt
6896 to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
6897 that. Once it has gotten a single "connection refused", it will regard
6898 that server as "down".
6900 So, what happens if the machine was only feeling unwell temporarily?
6901 How do you test to see whether the machine has come up again?
6903 You jump to the server buffer (@pxref{The Server Buffer}) and poke ut
6904 with the following commands:
6910 @findex gnus-server-open-server
6911 Try to establish connection to the server on the current line
6912 (@code{gnus-server-open-server}).
6916 @findex gnus-server-close-server
6917 Close the connection (if any) to the server
6918 (@code{gnus-server-close-server}).
6922 @findex gnus-server-deny-server
6923 Mark the current server as unreachable
6924 (@code{gnus-server-deny-server}).
6928 @findex gnus-server-remove-denials
6929 Remove all marks to whether Gnus was denied connection from all servers
6930 (@code{gnus-server-remove-denials}).
6939 Other people use @dfn{kill files}, but we here at Gnus Towers like
6940 scoring better than killing, so we'd rather switch than fight. They do
6941 something completely different as well, so sit up straight and pay
6944 @vindex gnus-summary-mark-below
6945 All articles have a default score (@code{gnus-summary-default-score}),
6946 which is 0 by default. This score may be raised or lowered either
6947 interactively or by score files. Articles that have a score lower than
6948 @code{gnus-summary-mark-below} are marked as read.
6950 Gnus will read any @dfn{score files} that apply to the current group
6951 before generating the summary buffer.
6953 There are several commands in the summary buffer that insert score
6954 entries based on the current article. You can, for instance, ask Gnus to
6955 lower or increase the score of all articles with a certain subject.
6957 There are two sorts of scoring entries: Permanent and temporary.
6958 Temporary score entries are self-expiring entries. Any entries that are
6959 temporary and have not been used for, say, a week, will be removed
6960 silently to help keep the sizes of the score files down.
6963 * Summary Score Commands:: Adding score entries for the current group.
6964 * Group Score Commands:: General score commands.
6965 * Score Variables:: Customize your scoring. (My, what terminology).
6966 * Score File Format:: What a score file may contain.
6967 * Score File Editing:: You can edit score files by hand as well.
6968 * Adaptive Scoring:: Big Sister Gnus *knows* what you read.
6969 * Scoring Tips:: How to score effectively.
6970 * Reverse Scoring:: That problem child of old is not problem.
6971 * Global Score Files:: Earth-spanning, ear-splitting score files.
6972 * Kill Files:: They are still here, but they can be ignored.
6975 @node Summary Score Commands
6976 @section Summary Score Commands
6977 @cindex score commands
6979 The score commands that alter score entries do not actually modify real
6980 score files. That would be too inefficient. Gnus maintains a cache of
6981 previously loaded score files, one of which is considered the
6982 @dfn{current score file alist}. The score commands simply insert
6983 entries into this list, and upon group exit, this list is saved.
6985 The current score file is by default the group's local score file, even
6986 if no such score file actually exists. To insert score commands into
6987 some other score file (eg. @file{all.SCORE}), you must first make this
6988 score file the current one.
6990 General score commands that don't actually change the score file:
6994 @kindex V s (Summary)
6995 @findex gnus-summary-set-score
6996 Set the score of the current article (@code{gnus-summary-set-score}).
6999 @kindex V S (Summary)
7000 @findex gnus-summary-current-score
7001 Display the score of the current article
7002 (@code{gnus-summary-current-score}).
7005 @kindex V t (Summary)
7006 @findex gnus-score-find-trace
7007 Display all score rules that have been used on the current article
7008 (@code{gnus-score-find-trace}).
7011 @kindex V a (Summary)
7012 @findex gnus-summary-score-entry
7013 Add a new score entry, and allow specifying all elements
7014 (@code{gnus-summary-score-entry}).
7017 @kindex V c (Summary)
7018 @findex gnus-score-change-score-file
7019 Make a different score file the current
7020 (@code{gnus-score-change-score-file}).
7023 @kindex V e (Summary)
7024 @findex gnus-score-edit-alist
7025 Edit the current score file (@code{gnus-score-edit-alist}). You will be
7026 popped into a @code{gnus-score-mode} buffer (@pxref{Score File
7030 @kindex V f (Summary)
7031 @findex gnus-score-edit-file
7032 Edit a score file and make this score file the current one
7033 (@code{gnus-score-edit-file}).
7036 @kindex V C (Summary)
7037 @findex gnus-score-customize
7038 Customize a score file in a visually pleasing manner
7039 (@code{gnus-score-customize}).
7042 @kindex I C-i (Summary)
7043 @findex gnus-summary-raise-score
7044 Increase the score of the current article
7045 (@code{gnus-summary-raise-score}).
7048 @kindex L C-l (Summary)
7049 @findex gnus-summary-lower-score
7050 Lower the score of the current article
7051 (@code{gnus-summary-lower-score}).
7054 The rest of these commands modify the local score file.
7058 @kindex V m (Summary)
7059 @findex gnus-score-set-mark-below
7060 Prompt for a score, and mark all articles with a score below this as
7061 read (@code{gnus-score-set-mark-below}).
7063 @kindex V E (Summary)
7064 @findex gnus-score-set-expunge-below
7065 Expunge all articles with a score below the default score (or the
7066 numeric prefix) (@code{gnus-score-set-expunge-below}).
7069 The keystrokes for actually making score entries follow a very regular
7070 pattern, so there's no need to list all the commands. (Hundreds of
7075 The first key is either @kbd{I} (upper case i) for increasing the score
7076 or @kbd{L} for lowering the score.
7078 The second key says what header you want to score on. The following
7082 Score on the author name.
7084 Score on the subject line.
7086 Score on the Xref line---i.e., the cross-posting line.
7088 Score on thread---the References line.
7092 Score on the number of lines.
7094 Score on the Message-ID.
7104 The third key is the match type. Which match types are legal depends on
7105 what headers you are scoring on.
7138 Greater than number.
7143 The fourth and final key says whether this is a temporary (i.e., expiring)
7144 score entry, or a permanent (i.e., non-expiring) score entry, or whether
7145 it is to be done immediately, without adding to the score file.
7148 Temporary score entry.
7150 Permanent score entry.
7152 Immediately scoring.
7157 So, let's say you want to increase the score on the current author with
7158 exact matching permanently: @kbd{I a e p}. If you want to lower the
7159 score based on the subject line, using substring matching, and make a
7160 temporary score entry: @kbd{L s s t}. Pretty easy.
7162 To make things a bit more complicated, there are shortcuts. If you use
7163 a capital letter on either the second or third keys, Gnus will use
7164 defaults for the remaining one or two keystrokes. The defaults are
7165 "substring" and "temporary". So @kbd{I A} is the same as @kbd{I a s t},
7166 and @kbd{I a R} is the same as @kbd{I a r t}.
7168 @vindex gnus-score-mimic-keymap
7169 The @code{gnus-score-mimic-keymap} says whether these commands will
7170 pretend they are keymaps or not.
7173 @node Group Score Commands
7174 @section Group Score Commands
7175 @cindex group score commands
7177 There aren't many of these as yet, I'm afraid.
7183 @findex gnus-score-flush-cache
7184 Gnus maintains a cache of score alists to avoid having to reload them
7185 all the time. This command will flush the cache
7186 (@code{gnus-score-flush-cache}).
7191 @node Score Variables
7192 @section Score Variables
7193 @cindex score variables
7196 @item gnus-use-scoring
7197 @vindex gnus-use-scoring
7198 If @code{nil}, Gnus will not check for score files, and will not, in
7199 general, do any score-related work. This is @code{t} by default.
7201 @item gnus-kill-killed
7202 @vindex gnus-kill-killed
7203 If this variable is @code{nil}, Gnus will never apply score files to
7204 articles that have already been through the kill process. While this
7205 may save you lots of time, it also means that if you apply a kill file
7206 to a group, and then change the kill file and want to run it over you
7207 group again to kill more articles, it won't work. You have to set this
7208 variable to @code{t} to do that. (It is @code{t} by default.)
7210 @item gnus-kill-files-directory
7211 @vindex gnus-kill-files-directory
7212 All kill and score files will be stored in this directory, which is
7213 initialized from the @samp{SAVEDIR} environment variable by default.
7214 This is @file{~/News/} by default.
7216 @item gnus-score-file-suffix
7217 @vindex gnus-score-file-suffix
7218 Suffix to add to the group name to arrive at the score file name
7219 (@samp{SCORE} by default.)
7221 @item gnus-score-uncacheable-files
7222 @vindex gnus-score-uncacheable-files
7224 All score files are normally cached to avoid excessive re-loading of
7225 score files. However, if this might make you Emacs grow big and
7226 bloated, so this regexp can be used to weed out score files that are
7227 unlikely to be needed again. It would be a bad idea to deny caching of
7228 @file{all.SCORE}, while it might be a good idea to not cache
7229 @file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
7230 variable is @samp{"ADAPT$"} by default, so no adaptive score files will
7233 @item gnus-save-score
7234 @vindex gnus-save-score
7235 If you have really complicated score files, and do lots of batch
7236 scoring, then you might set this variable to @code{t}. This will make
7237 Gnus save the scores into the @file{.newsrc.eld} file.
7239 @item gnus-save-score
7240 @vindex gnus-save-score
7241 If you have really complicated score files, and do lots of batch
7242 scoring, then you might set this variable to @code{t}. This will make
7243 Gnus save the scores into the @file{.newsrc.eld} file.
7245 @item gnus-score-interactive-default-score
7246 @vindex gnus-score-interactive-default-score
7247 Score used by all the interactive raise/lower commands to raise/lower
7248 score with. Default is 1000, which may seem excessive, but this is to
7249 ensure that the adaptive scoring scheme gets enough room to play with.
7250 We don't want the small changes from the adaptive scoring to overwrite
7251 manually entered data.
7253 @item gnus-summary-default-score
7254 @vindex gnus-summary-default-score
7255 Default score of an article, which is 0 by default.
7257 @item gnus-score-over-mark
7258 @vindex gnus-score-over-mark
7259 Mark (in the third column) used for articles with a score over the
7260 default. Default is @samp{+}.
7262 @item gnus-score-below-mark
7263 @vindex gnus-score-below-mark
7264 Mark (in the third column) used for articles with a score below the
7265 default. Default is @samp{-}.
7267 @item gnus-score-find-score-files-function
7268 @vindex gnus-score-find-score-files-function
7269 Function used to find score files for the current group. This function
7270 is called with the name of the group as the argument.
7272 Predefined functions available are:
7275 @item gnus-score-find-single
7276 @findex gnus-score-find-single
7277 Only apply the group's own score file.
7279 @item gnus-score-find-bnews
7280 @findex gnus-score-find-bnews
7281 Apply all score files that match, using bnews syntax. This is the
7282 default. For instance, if the current group is @samp{gnu.emacs.gnus},
7283 @samp{all.emacs.all.SCORE}, @samp{not.alt.all.SCORE} and
7284 @samp{gnu.all.SCORE} would all apply. In short, the instances of
7285 @samp{all} in the score file names are translated into @samp{.*}, and
7286 then a regexp match is done.
7288 If @code{gnus-use-long-file-name} is non-@code{nil}, this won't work
7289 very will. It will find stuff like @file{gnu/all/SCORE}, but will not
7290 find files like @file{not/gnu/all/SCORE}.
7292 @item gnus-score-find-hierarchical
7293 @findex gnus-score-find-hierarchical
7294 Apply all score files from all the parent groups.
7296 This variable can also be a list of functions. In that case, all these
7297 functions will be called, and all the returned lists of score files will
7298 be applied. These functions can also return lists of score alists
7299 directly. In that case, the functions that return these non-file score
7300 alists should probably be placed before the "real" score file functions,
7301 to ensure that the last score file returned is the local score file.
7303 @item gnus-score-expiry-days
7304 @vindex gnus-score-expiry-days
7305 This variable says how many days should pass before an unused score file
7306 entry is expired. The default is 7.
7309 @node Score File Format
7310 @section Score File Format
7311 @cindex score file format
7313 A score file is an @code{emacs-lisp} file that normally contains just a
7314 single form. Casual users are not expected to edit these files;
7315 everything can be changed from the summary buffer.
7317 Anyway, if you'd like to dig into it yourself, here's an example:
7321 ("Lars Ingebrigtsen" -10000)
7323 ("larsi\\|lmi" -50000 nil R))
7325 ("Ding is Badd" nil 728373))
7327 ("alt.politics" -1000 728372 s))
7332 (mark-and-expunge -10)
7336 (files "/hom/larsi/News/gnu.SCORE")
7337 (exclude-files "all.SCORE")
7338 (local (gnus-newsgroup-auto-expire t)
7339 (gnus-summary-make-false-root 'empty))
7343 This example demonstrates absolutely everything about a score file.
7345 Even though this looks much like lisp code, nothing here is actually
7346 @code{eval}ed. The lisp reader is used to read this form, though, so it
7347 has to be legal syntactically, if not semantically.
7349 Six keys are supported by this alist:
7353 If the key is a string, it is the name of the header to perform the
7354 match on. Scoring can only be performed on these eight headers:
7355 @samp{From}, @samp{Subject}, @samp{References}, @samp{Message-ID},
7356 @samp{Xref}, @samp{Lines}, @samp{Chars} and @samp{Date}. In addition to
7357 these headers, there are three strings to tell Gnus to fetch the entire
7358 article and do the match on larger parts of the article: @samp{Body}
7359 will perform the match on the body of the article, @samp{Head} will
7360 perform the match on the head of the article, and @samp{All} will
7361 perform the match on the entire article. Note that using any of these
7362 last three keys will slow down group entry @emph{considerably}. The
7363 final "header" you can score on is @samp{Followup}. These score entries
7364 will result in new score entries being added for all follow-ups to
7365 articles that matches these score entries.
7367 Following this key is a random number of score entries, where each score
7368 entry has one to four elements.
7371 The first element is the @dfn{match element}. On most headers this will
7372 be a string, but on the Lines and Chars headers, this must be an
7375 If the second element is present, it should be a number---the @dfn{score
7376 element}. This number should be an integer in the neginf to posinf
7377 interval. This number is added to the score of the article if the match
7378 is successful. If this element is not present, the
7379 @code{gnus-score-interactive-default-score} number will be used
7380 instead. This is 1000 by default.
7382 If the third element is present, it should be a number---the @dfn{date
7383 element}. This date says when the last time this score entry matched,
7384 which provides a mechanism for expiring the score entries. It this
7385 element is not present, the score entry is permanent. The date is
7386 represented by the number of days since December 31, 1 ce.
7388 If the fourth element is present, it should be a symbol---the @dfn{type
7389 element}. This element specifies what function should be used to see
7390 whether this score entry matches the article. What match types that can
7391 be used depends on what header you wish to perform the match on.
7393 @item From, Subject, References, Xref, Message-ID
7394 For most header types, there are the @code{r} and @code{R} (regexp) as
7395 well as @code{s} and @code{S} (substring) types and @code{e} and
7396 @code{E} (exact match) types. If this element is not present, Gnus will
7397 assume that substring matching should be used. @code{R} and @code{S}
7398 differ from the other two in that the matches will be done in a
7399 case-sensitive manner. All these one-letter types are really just
7400 abbreviations for the @code{regexp}, @code{string} and @code{exact}
7401 types, which you can use instead, if you feel like.
7403 These two headers use different match types: @code{<}, @code{>},
7404 @code{=}, @code{>=} and @code{<=}.
7406 For the Date header we have three match types: @code{before}, @code{at}
7407 and @code{after}. I can't really imagine this ever being useful, but,
7408 like, it would feel kinda silly not to provide this function. Just in
7409 case. You never know. Better safe than sorry. Once burnt, twice shy.
7410 Don't judge a book by its cover. Never not have sex on a first date.
7411 @item Head, Body, All
7412 These three match keys use the same match types as the @code{From} (etc)
7415 This match key will add a score entry on all articles that followup to
7416 some author. Uses the same match types as the @code{From} header uses.
7421 The value of this entry should be a number. Any articles with a score
7422 lower than this number will be marked as read.
7424 The value of this entry should be a number. Any articles with a score
7425 lower than this number will be removed from the summary buffer.
7426 @item mark-and-expunge
7427 The value of this entry should be a number. Any articles with a score
7428 lower than this number will be marked as read and removed from the
7431 The value of this entry should be any number of file names. These files
7432 are assumed to be score files as well, and will be loaded the same way
7435 The clue of this entry should be any number of files. This files will
7436 not be loaded, even though they would normally be so, for some reason or
7439 The value of this entry will be @code{eval}el. This element will be
7440 ignored when handling global score files.
7442 Read-only score files will not be updated or saved. Global score files
7443 should feature this atom (@pxref{Global Score Files}).
7445 The value of this entry should be a number. Articles that do not have
7446 parents will get this number added to their scores.
7448 This entry controls the adaptive scoring. If it is @code{t}, the
7449 default adaptive scoring rules will be used. If it is @code{ignore}, no
7450 adaptive scoring will be performed on this group. If it is a list, this
7451 list will be used as the adaptive scoring rules. If it isn't present,
7452 or is something other than @code{t} or @code{ignore}, the default
7453 adaptive scoring rules will be used. If you want to use adaptive
7454 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
7455 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
7456 not want adaptive scoring. If you only want adaptive scoring in a few
7457 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
7458 insert @code{(adapt t)} in the score files of the groups where you want
7461 @cindex local variables
7462 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
7463 Each @var{var} will be made buffer-local to the current summary buffer,
7464 and set to the value specified. This is a convenient, if somewhat
7465 strange, way of setting variables in some groups if you don't like hooks
7469 @node Score File Editing
7470 @section Score File Editing
7472 You normally enter all scoring commands from the summary buffer, but you
7473 might feel the urge to edit them by hand as well, so we've supplied you
7474 with a mode for that.
7476 It's simply a slightly customized @code{emacs-lisp} mode, with these
7477 additional commands:
7481 @kindex C-c C-c (Score)
7482 @findex gnus-score-edit-done
7483 Save the changes you have made and return to the summary buffer
7484 (@code{gnus-score-edit-done}).
7486 @kindex C-c C-d (Score)
7487 @findex gnus-score-edit-insert-date
7488 Insert the current date in numerical format
7489 (@code{gnus-score-edit-insert-date}). This is really the day number, if
7493 @node Adaptive Scoring
7494 @section Adaptive Scoring
7495 @cindex adaptive scoring
7497 If all this scoring is getting you down, Gnus has a way of making it all
7498 happen automatically---as if by magic. Or rather, as if by artificial
7499 stupidity, to be precise.
7501 @vindex gnus-use-adaptive-scoring
7502 When you read an article, or mark an article as read, or kill an
7503 article, you leave marks behind. On exit from the group, Gnus can sniff
7504 these marks and add score elements depending on what marks it finds.
7505 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
7508 @vindex gnus-default-adaptive-score-alist
7509 To give you complete control over the scoring process, you can customize
7510 the @code{gnus-default-adaptive-score-alist} variable. By default, it
7511 looks something like this:
7514 (defvar gnus-default-adaptive-score-alist
7515 '((gnus-unread-mark)
7516 (gnus-ticked-mark (from 4))
7517 (gnus-dormant-mark (from 5))
7518 (gnus-del-mark (from -4) (subject -1))
7519 (gnus-read-mark (from 4) (subject 2))
7520 (gnus-expirable-mark (from -1) (subject -1))
7521 (gnus-killed-mark (from -1) (subject -3))
7522 (gnus-kill-file-mark)
7523 (gnus-catchup-mark (from -1) (subject -1))))
7526 As you see, each element in this alist has a mark as a key (either a
7527 variable name or a "real" mark---a character). Following this key is a
7528 random number of header/score pairs.
7530 To take @code{gnus-del-mark} as an example---this alist says that all
7531 articles that have that mark (i.e., are marked with @samp{D}) will have a
7532 score entry added to lower based on the @code{From} header by -4, and
7533 lowered by @code{Subject} by -1. Change this to fit your prejudices.
7535 The headers you can score on are @code{from}, @code{subject},
7536 @code{message-id}, @code{references}, @code{xref}, @code{lines},
7537 @code{chars} and @code{date}. In addition, you can score on
7538 @code{followup}, which will create an adaptive score entry that matches
7539 on the @code{References} header using the @code{Message-ID} of the
7540 current article, thereby matching the following thread.
7542 If you use this scheme, you should set @code{mark-below} to something
7543 small---like -300, perhaps, to avoid having small random changes result
7544 in articles getting marked as read.
7546 After using adaptive scoring for a week or so, Gnus should start to
7547 become properly trained and enhance the authors you like best, and kill
7548 the authors you like least, without you having to say so explicitly.
7550 You can control what groups the adaptive scoring is to be performed on
7551 by using the score files (@pxref{Score File Format}). This will also
7552 let you use different rules in different groups.
7554 @vindex gnus-adaptive-file-suffix
7555 The adaptive score entries will be put into a file where the name is the
7556 group name with @code{gnus-adaptive-file-suffix} appended. The default
7559 @vindex gnus-score-exact-adapt-limit
7560 When doing adaptive scoring, substring or fuzzy matching would probably
7561 give you the best results in most cases. However, if the header one
7562 matches is short, the possibility for false positives is great, so if
7563 the length of the match is less than
7564 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
7565 this variable is @code{nil}, exact matching will always be used to avoid
7569 @section Scoring Tips
7570 @cindex scoring tips
7574 If you want to lower the score of crossposts, the line to match on is
7575 the @code{Xref} header.
7577 ("xref" (" talk.politics.misc:" -1000))
7579 @item Multiple crossposts
7580 If you want to lower the score of articles that have been crossposted to
7581 more than, say, 3 groups:
7583 ("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
7585 @item Matching on the body
7586 This is generally not a very good idea---it takes a very long time.
7587 Gnus actually has to fetch each individual article from the server. But
7588 you might want to anyway, I guess. Even though there are three match
7589 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
7590 and stick with it in each score file. If you use any two, each article
7591 will be fetched @emph{twice}. If you want to match a bit on the
7592 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
7594 @item Marking as read
7595 You will probably want to mark articles that has a score below a certain
7596 number as read. This is most easily achieved by putting the following
7597 in your @file{all.SCORE} file:
7601 You may also consider doing something similar with @code{expunge}.
7603 @item Negated charater classes
7604 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
7605 That will match newlines, which might lead to, well, The Unknown. Say
7606 @code{[^abcd\n]*} instead.
7609 @node Reverse Scoring
7610 @section Reverse Scoring
7611 @cindex reverse scoring
7613 If you want to keep just articles that have @samp{Sex with Emacs} in the
7614 subject header, and expunge all other articles, you could put something
7615 like this in your score file:
7619 ("Sex with Emacs" 2))
7624 So, you raise all articles that match @samp{Sex with Emacs} and mark the
7625 rest as read, and expunge them to boot.
7627 @node Global Score Files
7628 @section Global Score Files
7629 @cindex global score files
7631 Sure, other newsreaders have "global kill files". These are usually
7632 nothing more than a single kill file that applies to all groups, stored
7633 in the user's home directory. Bah! Puny, weak newsreaders!
7635 What I'm talking about here are Global Score Files. Score files from
7636 all over the world, from users everywhere, uniting all nations in one
7637 big, happy score file union! Ange-score! New and untested!
7639 @vindex gnus-global-score-files
7640 All you have to do to use other people's score files is to set the
7641 @code{gnus-global-score-files} variable. One entry for each score file,
7642 or each score file directory. Gnus will decide by itself what score
7643 files are applicable to which group.
7645 Say you want to use all score files in the
7646 @file{/ftp@@ftp.some-where:/pub/score} directory and the single score
7647 file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
7650 (setq gnus-global-score-files
7651 '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
7652 "/ftp@@ftp.some-where:/pub/score/"))
7655 @findex gnus-score-search-global-directories
7656 Simple, eh? Directory names must end with a @samp{/}. These
7657 directories are typically scanned only once during each Gnus session.
7658 If you feel the need to manually re-scan the remote directories, you can
7659 use the @code{gnus-score-search-global-directories} command.
7661 Note that, at present, using this option will slow down group entry
7662 somewhat. (That is---a lot.)
7664 If you want to start maintaining score files for other people to use,
7665 just put your score file up for anonymous ftp and announce it to the
7666 world. Become a retro-moderator! Participate in the retro-moderator
7667 wars sure to ensue, where retro-moderators battle it out for the
7668 sympathy of the people, luring them to use their score files on false
7669 premises! Yay! The net is saved!
7671 Here are some tips for the would-be retro-moderator, off the top of my
7676 Articles that are heavily crossposted are probably junk.
7678 To lower a single inappropriate article, lower by @code{Message-ID}.
7680 Particularly brilliant authors can be raised on a permanent basis.
7682 Authors that repeatedly post off-charter for the group can safely be
7683 lowered out of existence.
7685 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
7686 articles completely.
7688 Use expiring score entries to keep the size of the file down. You
7689 should probably have a long expiry period, though, as some sites keep
7690 old articles for a long time.
7693 ... I wonder whether other newsreaders will support global score files
7694 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
7695 Wave, xrn and 1stReader are bound to implement scoring. Should we start
7696 holding our breath yet?
7703 Gnus still supports those pesky old kill files. In fact, the kill file
7704 entries can now be expiring, which is something I wrote before Daniel
7705 Quinlan thought of doing score files, so I've left the code in there.
7707 In short, kill processing is a lot slower (and I do mean @emph{a lot})
7708 than score processing, so it might be a good idea to rewrite your kill
7709 files into score files.
7711 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
7712 forms into this file, which means that you can use kill files as some
7713 sort of primitive hook function to be run on group entry, even though
7714 that isn't a very good idea.
7716 XCNormal kill files look like this:
7719 (gnus-kill "From" "Lars Ingebrigtsen")
7720 (gnus-kill "Subject" "ding")
7724 This will mark every article written by me as read, and remove them from
7725 the summary buffer. Very useful, you'll agree.
7727 Other programs use a totally different kill file syntax. If Gnus
7728 encounters what looks like a @code{rn} kill file, it will take a stab at
7731 Two functions for editing a GNUS kill file:
7735 @kindex M-k (Summary)
7736 @findex gnus-summary-edit-local-kill
7737 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
7740 @kindex M-K (Summary)
7741 @findex gnus-summary-edit-global-kill
7742 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
7745 @vindex gnus-kill-file-name
7746 A kill file for the group @samp{soc.motss} is normally called
7747 @file{soc.motss.KILL}. The suffix appended to the group name to get
7748 this file name is detailed by the @code{gnus-kill-file-name} variable.
7749 The "global" kill file (not in the score file sense of "global", of
7750 course) is called just @file{KILL}.
7752 @vindex gnus-kill-save-kill-file
7753 If @code{gnus-kill-save-kill-file} is non-@code{nil}, Gnus will save the
7754 kill file after processing, which is necessary if you use expiring
7764 * Interactive:: Making Gnus ask you many questions.
7765 * Windows Configuration:: Configuring the Gnus buffer windows.
7766 * Buttons:: Get tendonitis in ten easy steps!
7767 * Compilation & Init File:: How to speed Gnus up.
7768 * Daemons:: Gnus can do things behind your back.
7769 * NoCeM:: How to avoid spam and other fatty foods.
7770 * Various Various:: Things that are really various.
7774 @section Interactive
7778 @item gnus-novice-user
7779 @vindex gnus-novice-user
7780 If this variable is non-@code{nil}, you are either a newcomer to the
7781 World of Usenet, or you are very cautious, which is a nice thing to be,
7782 really. You will be given questions of the type "Are you sure you want
7783 to do this?" before doing anything dangerous. This is @code{t} by
7786 @item gnus-expert-user
7787 @vindex gnus-expert-user
7788 If this variable is non-@code{nil}, you will never ever be asked any
7789 questions by Gnus. It will simply assume you know what your are doing,
7790 no matter how strange.
7792 @item gnus-interactive-catchup
7793 @vindex gnus-interactive-catchup
7794 Require confirmation before catching up a group if non-@code{nil}. It
7795 is @code{t} by default.
7797 @item gnus-interactive-post
7798 @vindex gnus-interactive-post
7799 If non-@code{nil}, the user will be prompted for a group name when
7800 posting an article. It is @code{t} by default.
7802 @item gnus-interactive-exit
7803 @vindex gnus-interactive-exit
7804 Require confirmation before exiting Gnus. This variable is @code{t} by
7809 @node Windows Configuration
7810 @section Windows Configuration
7811 @cindex windows configuration
7813 No, there's nothing here about X, so be quiet.
7816 @item gnus-use-full-window
7817 @vindex gnus-use-full-window
7818 If non-@code{nil}, Gnus will delete all other windows and occupy the
7819 entire Emacs screen by itself. It is @code{t} by default.
7821 @item gnus-buffer-configuration
7822 @vindex gnus-buffer-configuration
7823 This variable describes how much space each Gnus buffer should be given.
7824 Here's an excerpt of this variable:
7827 ((group ([group 1.0 point]
7828 (if gnus-carpal [group-carpal 4])))
7829 (article ([summary 0.25 point]
7833 This is an alist. The @dfn{key} is a symbol that names some action or
7834 other. For instance, when displaying the group buffer, the window
7835 configuration function will use @code{group} as the key. A full list of
7836 possible names is listed below.
7838 The @dfn{value} is a @dfn{rule} that says how much space each buffer
7839 should occupy. To take the @code{article} rule as an example -
7842 (article ([summary 0.25 point]
7846 This rule says that the summary buffer should occupy 25% of the screen,
7847 and that it is placed over the article buffer. As you may have noticed,
7848 100% + 25% is actually 125% (yup, I saw y'all reaching for that
7849 calculator there). However, the special number @code{1.0} is used to
7850 signal that this buffer should soak up all the rest of the space
7851 avaiable after the rest of the buffers have taken whatever they need.
7852 There should be only one buffer with the @code{1.0} size spec.
7854 Point will be put in the buffer that has the optional third element
7857 Here's a more complicated example:
7861 [summary 0.25 point]
7862 (if gnus-carpal [summary-carpal 4])
7866 If the size spec is an integer instead of a floating point number,
7867 then that number will be used to say how many lines a buffer should
7868 occupy, not a percentage.
7870 If an element is a list instead of a vector, this list will be
7871 @code{eval}ed. If the result is non-@code{nil}, it will be used. This
7872 means that there will be three buffers if @code{gnus-carpal} is
7873 @code{nil}, and four buffers if @code{gnus-carpal} is non-@code{nil}.
7875 Not complicated enough for you? Well, try this on for size:
7878 (article ([group 1.0]
7881 [summary 0.25 point]
7886 Whoops. Two buffers with the mystery 100% tag. And what's that
7887 @code{horizontal} thingie?
7889 If the first element in one of the rule lists is a list with
7890 @code{horizontal} as the first element, Gnus will split the window
7891 horizontally, giving you two windows side-by-side. Inside each of these
7892 strips you may carry on all you like in the normal fashion. The number
7893 following @code{horizontal} says what percentage of the screen is to be
7894 given to this strip.
7896 For each horizontal split, there @emph{must} be one element that has the
7897 100% tag. The splitting is never accurate, and this buffer will eat any
7898 leftover lines from the splits.
7900 Here's a list of all possible keys:
7902 @code{group}, @code{summary}, @code{article}, @code{server},
7903 @code{browse}, @code{group-mail}, @code{summary-mail},
7904 @code{summary-reply}, @code{info}, @code{summary-faq},
7905 @code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
7906 @code{followup}, @code{followup-yank}, @code{edit-score}.
7908 @findex gnus-add-configuration
7909 Since this variable is so long and complicated, there's a function you
7910 can use to ease changing the config of a single setting:
7911 @code{gnus-add-configuration}. If, for instance, you want to change the
7912 @code{article} setting, you could say:
7915 (gnus-add-configuration
7916 '(article ([group 4]
7929 Those new-fangled @dfn{mouse} contraptions is very popular with the
7930 young, hep kids who don't want to learn the proper way to do things
7931 these days. Why, I remember way back in the summer of '89, when I was
7932 using Emacs on a Tops 20 system. Three hundred users on one single
7933 machine, and every user was running Simula compilers. Bah!
7938 Well, you can make Gnus display bufferfuls of buttons you can click to
7939 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
7940 really. Tell the chiropractor I sent you.
7944 @item gnus-carpal-mode-hook
7945 @vindex gnus-carpal-mode-hook
7946 Hook run in all carpal mode buffers.
7947 @item gnus-carpal-button-face
7948 @vindex gnus-carpal-button-face
7949 Face used on buttons.
7950 @item gnus-carpal-group-buffer-buttons
7951 @vindex gnus-carpal-group-buffer-buttons
7952 Buttons in the group buffer.
7953 @item gnus-carpal-summary-buffer-buttons
7954 @vindex gnus-carpal-summary-buffer-buttons
7955 Buttons in the summary buffer.
7956 @item gnus-carpal-server-buffer-buttons
7957 @vindex gnus-carpal-server-buffer-buttons
7958 Buttons in the server buffer.
7959 @item gnus-carpal-browse-buffer-buttons
7960 @vindex gnus-carpal-browse-buffer-buttons
7961 Buttons in the browse buffer.
7964 All the @code{buttons} variables are lists. The elements in these list
7965 is either a cons cell where the car contains a text to be displayed and
7966 the cdr contains a function symbol, or a simple string.
7969 @node Compilation & Init File
7970 @section Compilation & Init File
7973 @cindex byte-compilation
7975 @vindex gnus-init-file
7976 @findex gnus-compile
7977 When Gnus starts up, it will read the Gnus init file
7978 @code{gnus-init-file}, which is @file{.gnus} by default. It is
7979 recommended that you keep any Gnus-related functions that you have
7980 written in that file. If you want to byte-compile the file, Gnus offers
7981 the handy @kbd{M-x gnus-compile} function that will do that for you.
7983 That's not really why that function was written, though.
7985 Remember all those line format specification variables?
7986 @code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
7987 on. Now, Gnus will of course heed whatever these variables are, but,
7988 unfortunately, changing them will mean a quite significant slow-down.
7989 (The default values of these variables have byte-compiled functions
7990 associated with them, while the user-generated versions do not, of
7993 To help with this, you can run @code{gnus-compile} after you've fiddled
7994 around with the variables and feel that you're (kind of) satisfied.
7995 This will result in the new specs being byte-compiled, and you'll get
7998 The result of these byte-compilations will be written to
7999 @file{.gnus.elc} by default.
8001 Note that Gnus will read @file{.gnus.elc} instead of @file{.gnus} if
8002 @file{.gnus.elc} exists, so if you change @file{.gnus}, you should
8003 remove @file{.gnus.elc}.
8011 Gnus, being larger than any program ever written (allegedly), does lots
8012 of strange stuff that you may wish to have done while you're not
8013 present. For instance, you may want it to check for new mail once in a
8014 while. Or you may want it to close down all connections to all servers
8015 when you leave Emacs idle. And stuff like that.
8017 Gnus will let you do stuff like that by defining various
8018 @dfn{handlers}. Each handler consists of three elements: A
8019 @var{function}, a @var{time}, and an @var{idle} parameter.
8021 Here's an example of a handler that closes connections when Emacs has
8022 been idle for thirty minutes:
8025 (gnus-demon-close-connections nil 30)
8028 Here's a handler that scans for PGP headers every hour when Emacs is
8032 (gnus-demon-scan-pgp 60 t)
8035 This @var{time} parameter and than @var{idle} parameter works together
8036 in a strange, but wonderful fashion. Basically, if @var{idle} is
8037 @code{nil}, then the function will be called every @var{time} minutes.
8039 If @var{idle} is @code{t}, then the function will be called after
8040 @var{time} minutes only if Emacs is idle. So if Emacs is never idle,
8041 the function will never be called. But once Emacs goes idle, the
8042 function will be called every @var{time} minutes.
8044 If @var{idle} is a number and @var{time} is a number, the function will
8045 be called every @var{time} minutes only when Emacs has been idle for
8048 If @var{idle} is a number and @var{time} is @code{nil}, the function
8049 will be called once every time Emacs has been idle for @var{idle}
8052 And if @var{time} is a string, it should look like @samp{"07:31"}, and
8053 the function will then be called once every day somewhere near that
8054 time. Modified by the @var{idle} parameter, of course.
8056 @vindex gnus-demon-timestep
8057 (When I say "minute" here, I really mean @code{gnus-demon-timestep}
8058 seconds. This is @samp{60} by default. If you change that variable,
8059 all the timings in the handlers will be affected.)
8061 @vindex gnus-use-demon
8062 To set the whole thing in motion, though, you have to set
8063 @code{gnus-use-demon} to @code{t}.
8065 @vindex gnus-use-demon
8066 To set the whole thing in motion, though, you have to set
8067 @code{gnus-use-demon} to @code{t}.
8069 So, if you want to add a handler, you could put something like this in
8070 your @file{.gnus} file:
8072 @findex gnus-demon-add-handler
8074 (gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
8077 @findex gnus-demon-add-nocem
8078 @findex gnus-demon-add-scanmail
8079 @findex gnus-demon-add-disconnection
8080 Some ready-made functions to do this has been created:
8081 @code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, and
8082 @code{gnus-demon-add-scanmail}. Just put those functions in your
8083 @file{.gnus} if you want those abilities.
8085 @findex gnus-demon-init
8086 @findex gnus-demon-cancel
8087 @vindex gnus-demon-handlers
8088 If you add handlers to @code{gnus-demon-handlers} directly, you should
8089 run @code{gnus-demon-init} to make the changes take hold. To cancel all
8090 daemons, you can use the @code{gnus-demon-cancel} function.
8092 Note that adding daemons can be pretty naughty if you overdo it. Adding
8093 functions that scan all news and mail from all servers every two seconds
8094 is a sure-fire way of getting booted off any respectable system. So
8105 @node Various Various
8106 @section Various Various
8112 @vindex gnus-verbose
8113 This variable is an integer between zero and ten. The higher the value,
8114 the more messages will be displayed. If this variable is zero, Gnus
8115 will never flash any messages, if it is seven (which is the default),
8116 most important messages will be shown, and if it is ten, Gnus won't ever
8117 shut up, but will flash so many messages it will make your head swim.
8119 @item gnus-updated-mode-lines
8120 @vindex gnus-updated-mode-lines
8121 This is a list of buffers that should keep their mode lines updated.
8122 The list may contain the symbols @code{group}, @code{article} and
8123 @code{summary}. If the corresponding symbol is present, Gnus will keep
8124 that mode line updated with information that may be pertinent. If this
8125 variable is @code{nil}, screen refresh may be quicker.
8127 @cindex display-time
8128 @item gnus-mode-non-string-length
8129 @vindex gnus-mode-non-string-length
8130 By default, Gnus displays information on the current article in the mode
8131 lines of the summary and article buffers. The information Gnus wishes
8132 to display (eg. the subject of the article) is often longer than the
8133 mode lines, and therefore have to be cut off at some point. This
8134 variable says how long the other elements on the line is (i.e., the
8135 non-info part). If you put additional elements on the mode line (eg. a
8136 clock), you should modify this variable:
8137 @c Hook written by Keinonen Kari <kk85613@cs.tut.fi>.
8139 (add-hook 'display-time-hook
8141 (setq gnus-mode-non-string-length
8142 (+ 21 (length display-time-string)))))
8148 @cindex highlighting
8151 If @code{nil}, Gnus won't attempt to create menus or use fancy colors
8152 or fonts. This will also inhibit loading the @file{gnus-visual.el}
8155 This variable can also be a list of visual properties that are enabled.
8156 The following elements are legal, and are all set by default:
8160 @item summary-highlight
8161 Perform various highlighting in the summary buffer.
8163 @item article-highlight
8164 Perform various highlighting in the article buffer.
8167 Turn on highlighting in all buffers.
8170 Create menus in the group buffer.
8173 Create menus in the summary buffer.
8176 Create menus in the article buffer.
8179 Create menus in the browse buffer.
8182 Create menus in the server buffer.
8185 Create menus in all buffers.
8189 So if you only want highlighting in the article buffer and menus in all
8190 buffers, you couls say something like:
8193 (setq gnus-visual '(article-highlight menu))
8196 If you want only highlighting and no menus whatsoever, you'd say:
8199 (setq gnus-visual '(highlight))
8202 @item gnus-mouse-face
8203 @vindex gnus-mouse-face
8204 This is the face (i.e., font) used for mouse highlighting in Gnus. No
8205 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
8207 @item gnus-display-type
8208 @vindex gnus-display-type
8209 This variable is symbol indicating the display Emacs is running under.
8210 The symbol should be one of @code{color}, @code{grayscale} or
8211 @code{mono}. If Gnus guesses this display attribute wrongly, either set
8212 this variable in your @file{~/.emacs} or set the resource
8213 @code{Emacs.displayType} in your @file{~/.Xdefaults}.
8215 @item gnus-background-mode
8216 @vindex gnus-background-mode
8217 This is a symbol indicating the Emacs background brightness. The symbol
8218 should be one of @code{light} or @code{dark}. If Gnus guesses this
8219 frame attribute wrongly, either set this variable in your @file{~/.emacs} or
8220 set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
8221 `gnus-display-type'.
8223 @item nnheader-max-head-length
8224 @vindex nnheader-max-head-length
8225 When the backends read straight heads of articles, they all try to read
8226 as little as possible. This variable (default @code{4096}) specifies
8227 the absolute max length the backends will try to read before giving up
8228 on finding a separator line between the head and the body. If this
8229 variable is @code{nil}, there is no upper read bound. If it is
8230 @code{t}, the backends won't try to read the articles piece by piece,
8231 but read the entire articles. This makes sense with some versions of
8238 @chapter Customization
8239 @cindex general customization
8241 All variables are properly documented elsewhere in this manual. This
8242 section is designed to give general pointers on how to customize Gnus
8243 for some quite common situations.
8246 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
8247 * Slow Terminal Connection:: You run a remote Emacs.
8248 * Little Disk Space:: You feel that having large setup files is icky.
8249 * Slow Machine:: You feel like buying a faster machine.
8252 @node Slow/Expensive Connection
8253 @section Slow/Expensive @sc{nntp} Connection
8255 If you run Emacs on a machine locally, and get your news from a machine
8256 over some very thin strings, you want to cut down on the amount of data
8257 Gnus has to get from the @sc{nntp} server.
8260 @item gnus-read-active-file
8261 Set this to @code{nil}, which will inhibit Gnus from requesting the
8262 entire active file from the server. This file is often v. large. You
8263 also have to set @code{gnus-check-new-news} and
8264 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
8265 doesn't suddenly decide to fetch the active file anyway.
8266 @item gnus-nov-is-evil
8267 This one has to be @code{nil}. If not, grabbing article headers from
8268 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
8269 support @sc{xover}; Gnus will detect this by itself.
8272 @node Slow Terminal Connection
8273 @section Slow Terminal Connection
8275 Let's say you use your home computer for dialing up the system that
8276 runs Emacs and Gnus. If your modem is slow, you want to reduce the
8277 amount of data that is sent over the wires as much as possible.
8280 @item gnus-auto-center-summary
8281 Set this to @code{nil} to inhibit Gnus from recentering the summary
8282 buffer all the time.
8283 @item gnus-visible-headers
8284 Cut down on the headers that are included in the articles to the
8285 minimum. You can, in fact, make do without them altogether---most of the
8286 useful data is in the summary buffer, anyway. Set this variable to
8287 @samp{"^NEVVVVER"} or @samp{"From:"}, or whatever you feel you need.
8288 @item gnus-article-display-hook
8289 Set this hook to all the available hiding commands:
8291 (setq gnus-article-display-hook
8292 '(gnus-article-hide-headers gnus-article-hide-signature
8293 gnus-article-hide-citation))
8295 @item gnus-use-full-window
8296 By setting this to @code{nil}, you can make all the windows smaller.
8297 While this doesn't really cut down much generally, it means that you
8298 have to see smaller portions of articles before deciding that you didn't
8299 want to read them anyway.
8300 @item gnus-thread-hide-subtree
8301 If this is non-@code{nil}, all threads in the summary buffer will be
8303 @item gnus-updated-mode-lines
8304 If this is @code{nil}, Gnus will not put information in the buffer mode
8305 lines, which might save some time.
8308 @node Little Disk Space
8309 @section Little Disk Space
8311 The startup files can get rather large, so you may want to cut their
8312 sizes a bit if you are running out of space.
8315 @item gnus-save-newsrc-file
8316 If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
8317 only save @file{.newsrc.eld}. This means that you will not be able to
8318 use any other newsreaders than Gnus. This variable is @code{t} by
8321 @item gnus-save-killed-list
8322 If this is @code{nil}, Gnus will not save the list of dead groups. You
8323 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
8324 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
8325 variable to @code{nil}. This variable is @code{t} by default.
8331 @section Slow Machine
8333 If you have a slow machine, or are just really impatient, there are a
8334 few things you can do to make Gnus run faster.
8336 Set@code{gnus-check-new-newsgroups} and
8337 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
8339 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
8340 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
8341 summary buffer faster.
8343 Set @code{gnus-article-display-hook} to @code{nil} to make article
8344 processing a bit faster.
8347 @node Troubleshooting
8348 @chapter Troubleshooting
8349 @cindex troubleshooting
8351 Gnus works @emph{so} well straight out of the box---I can't imagine any
8359 Make sure your computer is switched on.
8362 Make sure that you really load the current Gnus version. If you have
8363 been running @sc{gnus}, you need to exit Emacs and start it up again before
8367 Try doing an @kbd{M-x gnus-version}. If you get something that looks
8368 like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
8369 on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
8370 flee}, you have some old @file{.el} files lying around. Delete these.
8373 Read the help group (@kbd{M h} in the group buffer) for a FAQ and a
8377 If all else fails, report the problem as a bug.
8380 @cindex reporting bugs
8382 @kindex M-x gnus-bug
8384 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
8385 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
8386 me the backtrace. I will fix bugs, but I can only fix them if you send
8387 me a precise description as to how to reproduce the bug.
8389 You really can never be too detailed in a bug report. Always use the
8390 @kbd{M-x gnus-bug} command when you make bug reports, even if it creates
8391 a 10Kb mail each time you use it, and even if you have sent me your
8392 environment 500 times before. I don't care. I want the full info each
8395 It is also important to remember that I have no memory whatsoever. If
8396 you send a bug report, and I send you a reply, and then you send back
8397 just "No, it's not! Moron!", I will have no idea what you are insulting
8398 me about. Always overexplain everything. It's much easier for all of
8399 us---if I don't have all the information I need, I will just mail you
8400 and ask for more info, and everything takes more time.
8402 If you just need help, you are better off asking on
8403 @samp{gnu.emacs.gnus}. I'm not very helpful.
8409 Well, that's the manual---you can get on with your life now. Keep in
8410 touch. Say hello to your cats from me.
8412 My @strong{ghod}---I just can't stand goodbyes. Sniffle.
8414 Ol' Chuck Reznikoff said it pretty well, so I leave the floor to him:
8419 Not because of victories @*
8422 but for the common sunshine,@*
8424 the largess of the spring.
8427 but for the day's work done@*
8428 as well as I was able;@*
8429 not for a seat upon the dais@*
8430 but at the common table.@*
8437 * A Programmer's Guide to Gnus:: Rilly, rilly technical stuff.
8438 * Emacs for Heathens:: A short intruduction to Emacsian terms.
8439 * Frequently Asked Questions:: A question-and-answer session.
8443 @node A Programmer's Guide to Gnus
8444 @section A Programmer's Guide to Gnus
8446 It is my hope that other people will figure out smart stuff that Gnus
8447 can do, and that other people will write those smart things as well. To
8448 facilitate that I thought it would be a good idea to describe the inner
8449 workings of Gnus. And some of the not-so-inner workings, while I'm at
8452 You can never expect the internals of a program not to change, but I
8453 will be defining (in some details) the interface between Gnus and its
8454 backends (this is written in stone), the format of the score files
8455 (ditto), data structures (some are less likely to change than others)
8456 and general method of operations.
8459 * Backend Interface:: How Gnus communicates with the servers.
8460 * Score File Syntax:: A BNF definition of the score file standard.
8461 * Headers:: How Gnus stores headers internally.
8462 * Ranges:: A handy format for storing mucho numbers.
8463 * Group Info:: The group info format.
8467 @node Backend Interface
8468 @subsection Backend Interface
8470 Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
8471 groups. It only knows how to talk to @dfn{virtual servers}. A virtual
8472 server is a @dfn{backend} and some @dfn{backend variables}. As examples
8473 of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
8474 examples of the latter we have @code{nntp-port-number} and
8475 @code{nnmbox-directory}.
8477 When Gnus asks for information from a backend---say @code{nntp}---on
8478 something, it will normally include a virtual server name in the
8479 function parameters. (If not, the backend should use the "current"
8480 virtual server.) For instance, @code{nntp-request-list} takes a virtual
8481 server as its only (optional) parameter. If this virtual server hasn't
8482 been opened, the function should fail.
8484 Note that a virtual server name has no relation to some physical server
8485 name. Take this example:
8489 (nntp-address "ifi.uio.no")
8490 (nntp-port-number 4324))
8493 Here the virtual server name is @samp{"odd-one"} while the name of
8494 the physical server is @samp{"ifi.uio.no"}.
8496 The backends should be able to switch between several virtual servers.
8497 The standard backends implement this by keeping an alist of virtual
8498 server environments that it pulls down/pushes up when needed.
8500 There are two groups of interface functions: @dfn{required functions},
8501 which must be present, and @dfn{optional functions}, which Gnus will
8502 always check whether are present before attempting to call.
8504 All these functions are expected to return data in the buffer
8505 @code{nntp-server-buffer} (@samp{" *nntpd*"}), which is somewhat
8506 unfortunately named, but we'll have to live with it. When I talk about
8507 "resulting data", I always refer to the data in that buffer. When I
8508 talk about "return value", I talk about the function value returned by
8511 Some backends could be said to be @dfn{server-forming} backends, and
8512 some might be said to not be. The latter are backends that generally
8513 only operate on one group at a time, and have no concept of "server" --
8514 they have a group, and they deliver info on that group and nothing more.
8516 In the examples and definitions I will refer to the imaginary backend
8519 @cindex @code{nnchoke}
8522 * Required Backend Functions:: Functions that must be implemented.
8523 * Optional Backend Functions:: Functions that need not be implemented.
8527 @node Required Backend Functions
8528 @subsubsection Required Backend Functions
8532 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
8534 @var{articles} is either a range of article numbers or a list of
8535 @code{Message-ID}s. Current backends do not fully support either---only
8536 sequences (lists) of article numbers, and most backends do not support
8537 retrieval of @code{Message-ID}s. But they should try for both.
8539 The result data should either be HEADs or NOV lines, and the result
8540 value should either be @code{headers} or @code{nov} to reflect this.
8541 This might later be expanded to @code{various}, which will be a mixture
8542 of HEADs and NOV lines, but this is currently not supported by Gnus.
8544 If @var{fetch-old} is non-@code{nil} it says to try to fetch "extra
8545 headers, in some meaning of the word. This is generally done by
8546 fetching (at most) @var{fetch-old} extra headers less than the smallest
8547 article number in @code{articles}, and fill in the gaps as well. The
8548 presence of this parameter can be ignored if the backend finds it
8549 cumbersome to follow the request. If this is non-@code{nil} and not a
8550 number, do maximum fetches.
8552 Here's an example HEAD:
8555 221 1056 Article retrieved.
8556 Path: ifi.uio.no!sturles
8557 From: sturles@@ifi.uio.no (Sturle Sunde)
8558 Newsgroups: ifi.discussion
8559 Subject: Re: Something very droll
8560 Date: 27 Oct 1994 14:02:57 +0100
8561 Organization: Dept. of Informatics, University of Oslo, Norway
8563 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
8564 References: <38jdmq$4qu@@visbur.ifi.uio.no>
8565 NNTP-Posting-Host: holmenkollen.ifi.uio.no
8569 So a @code{headers} return value would imply that there's a number of
8570 these in the data buffer.
8572 Here's a BNF definition of such a buffer:
8576 head = error / valid-head
8577 error-message = [ "4" / "5" ] 2number " " <error message> eol
8578 valid-head = valid-message *header "." eol
8579 valid-message = "221 " <number> " Article retrieved." eol
8583 If the return value is @code{nov}, the data buffer should contain
8584 @dfn{network overview database} lines. These are basically fields
8588 nov-buffer = *nov-line
8589 nov-line = 8*9 [ field <TAB> ] eol
8590 field = <text except TAB>
8593 For a closer explanation what should be in those fields,
8597 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
8599 @var{server} is here the virtual server name. @var{definitions} is a
8600 list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
8602 If the server can't be opened, no error should be signaled. The backend
8603 may then choose to refuse further attempts at connecting to this
8604 server. In fact, it should do so.
8606 If the server is opened already, this function should return a
8607 non-@code{nil} value. There should be no data returned.
8610 @item (nnchoke-close-server &optional SERVER)
8612 Close connection to @var{server} and free all resources connected
8615 There should be no data returned.
8618 @item (nnchoke-request-close)
8620 Close connection to all servers and free all resources that the backend
8621 have reserved. All buffers that have been created by that backend
8622 should be killed. (Not the @code{nntp-server-buffer}, though.)
8624 There should be no data returned.
8627 @item (nnchoke-server-opened &optional SERVER)
8629 This function should return whether @var{server} is opened, and that the
8630 connection to it is still alive. This function should under no
8631 circumstances attempt to reconnect to a server that is has lost
8634 There should be no data returned.
8637 @item (nnchoke-status-message &optional SERVER)
8639 This function should return the last error message from @var{server}.
8641 There should be no data returned.
8644 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
8646 The result data from this function should be the article specified by
8647 @var{article}. This might either be a @code{Message-ID} or a number.
8648 It is optional whether to implement retrieval by @code{Message-ID}, but
8649 it would be nice if that were possible.
8651 If @var{to-buffer} is non-@code{nil}, the result data should be returned
8652 in this buffer instead of the normal data buffer. This is to make it
8653 possible to avoid copying large amounts of data from one buffer to
8654 another, and Gnus mainly request articles to be inserted directly into
8658 @item (nnchoke-open-group GROUP &optional SERVER)
8660 Make @var{group} the current group.
8662 There should be no data returned by this function.
8665 @item (nnchoke-request-group GROUP &optional SERVER)
8667 Get data on @var{group}. This function also has the side effect of
8668 making @var{group} the current group.
8670 Here's an example of some result data and a definition of the same:
8673 211 56 1000 1059 ifi.discussion
8676 The first number is the status, which should be @samp{211}. Next is the
8677 total number of articles in the group, the lowest article number, the
8678 highest article number, and finally the group name. Note that the total
8679 number of articles may be less than one might think while just
8680 considering the highest and lowest article numbers, but some articles
8681 may have been cancelled. Gnus just discards the total-number, so
8682 whether one should take the bother to generate it properly (if that is a
8683 problem) is left as an excercise to the reader.
8686 group-status = [ error / info ] eol
8687 error = [ "4" / "5" ] 2<number> " " <Error message>
8688 info = "211 " 3* [ <number> " " ] <string>
8692 @item (nnchoke-close-group GROUP &optional SERVER)
8694 Close @var{group} and free any resources connected to it. This will be
8695 a no-op on most backends.
8697 There should be no data returned.
8700 @item (nnchoke-request-list &optional SERVER)
8702 Return a list of all groups available on @var{server}. And that means
8705 Here's an example from a server that only carries two groups:
8708 ifi.test 0000002200 0000002000 y
8709 ifi.discussion 3324 3300 n
8712 On each line we have a group name, then the highest article number in
8713 that group, the lowest article number, and finally a flag.
8716 active-file = *active-line
8717 active-line = name " " <number> " " <number> " " flags eol
8719 flags = "n" / "y" / "m" / "x" / "j" / "=" name
8722 The flag says whether the group is read-only (@samp{n}), is moderated
8723 (@samp{m}), is dead (@samp{x}), is aliased to some other group
8724 (@samp{=other-group} or none of the above (@samp{y}).
8727 @item (nnchoke-request-post &optional SERVER)
8729 This function should post the current buffer. It might return whether
8730 the posting was successful or not, but that's not required. If, for
8731 instance, the posting is done asynchronously, it has generally not been
8732 completed by the time this function concludes. In that case, this
8733 function should set up some kind of sentinel to beep the user loud and
8734 clear if the posting could not be completed.
8736 There should be no result data from this function.
8739 @item (nnchoke-request-post-buffer POST GROUP SUBJECT HEADER ARTICLE-BUFFER INFO FOLLOW-TO RESPECT-POSTER)
8741 This function should return a buffer suitable for composing an article
8742 to be posted by @code{nnchoke-request-post}. If @var{post} is
8743 non-@code{nil}, this is not a followup, but a totally new article.
8744 @var{group} is the name of the group to be posted to. @var{subject} is
8745 the subject of the message. @var{article-buffer} is the buffer being
8746 followed up, if that is the case. @var{info} is the group info.
8747 @var{follow-to} is the group that one is supposed to re-direct the
8748 article ot. If @var{respect-poster} is non-@code{nil}, the special
8749 @samp{"poster"} value of a @code{Followup-To} header is to be respected.
8751 There should be no result data returned.
8755 @node Optional Backend Functions
8756 @subsubsection Optional Backend Functions
8760 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
8762 @var{groups} is a list of groups, and this function should request data
8763 on all those groups. How it does it is of no concern to Gnus, but it
8764 should attempt to do this in a speedy fashion.
8766 The return value of this function can be either @code{active} or
8767 @code{group}, which says what the format of the result data is. The
8768 former is in the same format as the data from
8769 @code{nnchoke-request-list}, while the latter is a buffer full of lines
8770 in the same format as @code{nnchoke-request-group} gives.
8773 group-buffer = *active-line / *group-status
8777 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
8779 A Gnus group info (@pxref{Group Info}) is handed to the backend for
8780 alterations. This comes in handy if the backend really carries all the
8781 information (as is the case with virtual an imap groups). This function
8782 may alter the info in any manner it sees fit, and should return the
8783 (altered) group info. This function may alter the group info
8784 destructively, so no copying is needed before boogying.
8786 There should be no result data from this function.
8789 @item (nnchoke-request-scan &optional GROUP SERVER)
8791 This function may be called at any time (by Gnus or anything else) to
8792 request that the backend check for incoming articles, in one way or
8793 another. A mail backend will typically read the spool file or query the
8794 POP server when this function is invoked. The @var{group} doesn't have
8795 to be heeded---if the backend decides that it is too much work just
8796 scanning for a single group, it may do a total scan of all groups. It
8797 would be nice, however, to keep things local if that's practical.
8799 There should be no result data from this function.
8802 @item (nnchoke-request-asynchronous GROUP &optional SERVER ARTICLES)
8804 This is a request to fetch articles asynchronously later.
8805 @var{articles} is an alist of @var{(article-number line-number)}. One
8806 would generally expect that if one later fetches article number 4, for
8807 instance, some sort of asynchronous fetching of the articles after 4
8808 (which might be 5, 6, 7 or 11, 3, 909 depending on the order in that
8809 alist) would be fetched asynchronouly, but that is left up to the
8810 backend. Gnus doesn't care.
8812 There should be no result data from this function.
8815 @item (nnchoke-request-group-description GROUP &optional SERVER)
8817 The result data from this function should be a description of
8821 description-line = name <TAB> description eol
8823 description = <text>
8826 @item (nnchoke-request-list-newsgroups &optional SERVER)
8828 The result data from this function should be the description of all
8829 groups available on the server.
8832 description-buffer = *description-line
8836 @item (nnchoke-request-newgroups DATE &optional SERVER)
8838 The result data from this function should be all groups that were
8839 created after @samp{date}, which is in normal human-readable date
8840 format. The data should be in the active buffer format.
8843 @item (nnchoke-request-create-groups GROUP &optional SERVER)
8845 This function should create an empty group with name @var{group}.
8847 There should be no return data.
8850 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
8852 This function should run the expiry process on all articles in the
8853 @var{articles} range (which is currently a simple list of article
8854 numbers.) It is left up to the backend to decide how old articles
8855 should be before they are removed by this function. If @var{force} is
8856 non-@code{nil}, all @var{articles} should be deleted, no matter how new
8859 This function should return a list of articles that it did not/was not
8862 There should be no result data returned.
8865 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
8868 This function should move @var{article} (which is a number) from
8869 @var{group} by calling @var{accept-form}.
8871 This function should ready the article in question for moving by
8872 removing any header lines it has added to the article, and generally
8873 should "tidy up" the article. Then it should @code{eval}
8874 @var{accept-form} in the buffer where the "tidy" article is. This will
8875 do the actual copying. If this @code{eval} returns a non-@code{nil}
8876 value, the article should be removed.
8878 If @var{last} is @code{nil}, that means that there is a high likelihood
8879 that there will be more requests issued shortly, so that allows some
8882 There should be no data returned.
8885 @item (nnchoke-request-accept-article GROUP &optional LAST)
8887 This function takes the current buffer and inserts it into @var{group}.
8888 If @var{last} in @code{nil}, that means that there will be more calls to
8889 this function in short order.
8891 There should be no data returned.
8894 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
8896 This function should remove @var{article} (which is a number) from
8897 @var{group} and insert @var{buffer} there instead.
8899 There should be no data returned.
8902 @item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
8904 This function should delete @var{group}. If @var{force}, it should
8905 really delete all the articles in the group, and then delete the group
8906 itself. (If there is such a thing as "the group itself".)
8908 There should be no data returned.
8911 @item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
8913 This function should rename @var{group} into @var{new-name}. All
8914 articles that are in @var{group} should move to @var{new-name}.
8916 There should be no data returned.
8922 @node Score File Syntax
8923 @subsection Score File Syntax
8925 Score files are meant to be easily parsable, but yet extremely
8926 mallable. It was decided that something that had the same read syntax
8927 as an Emacs Lisp list would fit that spec.
8929 Here's a typical score file:
8933 ("win95" -10000 nil s)
8940 BNF definition of a score file:
8943 score-file = "" / "(" *element ")"
8944 element = rule / atom
8945 rule = string-rule / number-rule / date-rule
8946 string-rule = "(" quote string-header quote space *string-match ")"
8947 number-rule = "(" quote number-header quote space *number-match ")"
8948 date-rule = "(" quote date-header quote space *date-match ")"
8950 string-header = "subject" / "from" / "references" / "message-id" /
8951 "xref" / "body" / "head" / "all" / "followup"
8952 number-header = "lines" / "chars"
8953 date-header = "date"
8954 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
8955 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
8956 score = "nil" / <integer>
8957 date = "nil" / <natural number>
8958 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
8959 "r" / "regex" / "R" / "Regex" /
8960 "e" / "exact" / "E" / "Exact" /
8961 "f" / "fuzzy" / "F" / "Fuzzy"
8962 number-match = "(" <integer> [ "" / [ space score [ "" /
8963 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
8964 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
8965 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
8966 space date [ "" / [ space date-match-t ] ] ] ] ")"
8967 date-match-t = "nil" / "at" / "before" / "after"
8968 atom = "(" [ required-atom / optional-atom ] ")"
8969 required-atom = mark / expunge / mark-and-expunge / files /
8970 exclude-files / read-only / touched
8971 optional-atom = adapt / local / eval
8972 mark = "mark" space nil-or-number
8973 nil-or-number = "nil" / <integer>
8974 expunge = "expunge" space nil-or-number
8975 mark-and-expunge = "mark-and-expunge" space nil-or-number
8976 files = "files" *[ space <string> ]
8977 exclude-files = "exclude-files" *[ space <string> ]
8978 read-only = "read-only" [ space "nil" / space "t" ]
8979 adapt = "adapt" [ space "nil" / space "t" / space adapt-rule ]
8980 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
8981 local = "local" *[ space "(" <string> space <form> ")" ]
8982 eval = "eval" space <form>
8983 space = *[ " " / <TAB> / <NEWLINE> ]
8986 Any unrecognized elements in a score file should be ignored, but not
8989 As you can see, white space is needed, but the type and amount of white
8990 space is irrelevant. This means that formatting of the score file is
8991 left up to the programmer---if it's simpler to just spew it all out on
8992 one looong line, then that's ok.
8994 The meaning of the various atoms are explained elsewhere in this
9000 Gnus uses internally a format for storing article headers that
9001 corresponds to the @sc{nov} format in a mysterious fashion. One could
9002 almost suspect that the author looked at the @sc{nov} specification and
9003 just shamelessly @emph{stole} the entire thing, and one would be right.
9005 @dfn{Header} is a severly overloaded term. "Header" is used in RFC1036
9006 to talk about lines in the head of an article (eg., @code{From}). It is
9007 used by many people as a synonym for "head"---"the header and the
9008 body". (That should be avoided, in my opinion.) And Gnus uses a format
9009 interanally that it calls "header", which is what I'm talking about
9010 here. This is a 9-element vector, basically, with each header (ouch)
9013 These slots are, in order: @code{number}, @code{subject}, @code{from},
9014 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
9015 @code{xref}. There are macros for accessing and setting these slots --
9016 they all have predicatable names beginning with @code{mail-header-} and
9017 @code{mail-header-set-}, respectively.
9019 The @code{xref} slot is really a @code{misc} slot. Any extra info will
9025 @sc{gnus} introduced a concept that I found so useful that I've started
9026 using it a lot and have elaborated on it greatly.
9028 The question is simple: If you have a large amount of objects that are
9029 identified by numbers (say, articles, to take a @emph{wild} example)
9030 that you want to callify as being "included", a normal sequence isn't
9031 very useful. (A 200,000 length sequence is a bit long-winded.)
9033 The solution is as simple as the question: You just collapse the
9037 (1 2 3 4 5 6 10 11 12)
9046 To avoid having those nasty @samp{(13 . 13)} elements to denote a
9047 lonesome object, a @samp{13} is a valid element:
9050 ((1 . 6) 7 (10 . 12))
9053 This means that comparing two ranges to find out whether they are equal
9057 ((1 . 6) 7 8 (10 . 12))
9063 ((1 . 5) (7 . 8) (10 . 12))
9066 are equal. In fact, any non-descending list is a range:
9072 is a perfectly valid range, although a pretty longwinded one. This is
9079 and is equal to the previous range.
9081 Here's a BNF definition of ranges. Of course, one must remember the
9082 semantic requirement that the numbers are non-descending. (Any number
9083 of repetition of the same number is allowed, but apt to disappear in
9087 range = simple-range / normal-range
9088 simple-range = "(" number " . " number ")"
9089 normal-range = "(" start-contents ")"
9090 contents = "" / simple-range *[ " " contents ] /
9091 number *[ " " contents ]
9094 Gnus currently uses ranges to keep track of read articles and article
9095 marks. I plan on implementing a number of range operators in C if The
9096 Powers That Be are willing to let me. (I haven't asked yet, because I
9097 need to do some more thinking on what operators I need to make life
9098 totally range-based without ever having to convert back to normal
9103 @subsection Group Info
9105 Gnus stores all permanent info on groups in a @dfn{group info} list.
9106 This list is from three to six elements (or more) long and exhaustively
9107 describes the group.
9109 Here are two example group infos; one is a very simple group while the
9110 second is a more complex one:
9113 ("no.group" 5 (1 . 54324))
9115 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
9116 ((tick (15 . 19)) (replied 3 6 (19 . 23)))
9118 (auto-expire (to-address "ding@@ifi.uio.no")))
9121 The first element is the group name as Gnus knows the group; the second
9122 is the group level; the third is the read articles in range format; the
9123 fourth is a list of article marks lists; the fifth is the select method;
9124 and the sixth contains the group parameters.
9126 Here's a BNF definition of the group info format:
9129 info = "(" group space level space read
9130 [ "" / [ space marks-list [ "" / [ space method [ "" /
9131 space parameters ] ] ] ] ] ")"
9132 group = quote <string> quote
9133 level = <integer in the range of 1 to inf>
9135 marks-lists = nil / "(" *marks ")"
9136 marks = "(" <string> range ")"
9137 method = "(" <string> *elisp-forms ")"
9138 parameters = "(" *elisp-forms ")"
9141 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
9142 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
9146 @node Emacs for Heathens
9147 @section Emacs for Heathens
9149 Believe it or not, but some people who use Gnus haven't really used
9150 Emacs much before they embarked on their journey on the Gnus Love Boat.
9151 If you are one of those unfortunates whom "@kbd{M-C-a}", "kill the
9152 region", and "set @code{gnus-flargblossen} to an alist where the key is
9153 a regexp that is used for matching on the group name" are magical
9154 phrases with little or no meaning, then this appendix is for you. If
9155 you are already familiar with Emacs, just ignore this and go fondle your
9159 * Keystrokes:: Entering text and executing commands.
9160 * Emacs Lisp:: The built-in Emacs programming language.
9165 @subsection Keystrokes
9169 Q: What is an experienced Emacs user?
9171 A: A person who wishes that the terminal had pedals.
9174 Yes, when you use Emacs, you are apt to use the control key, the shift
9175 key and the meta key a lot. This is very annoying to some people
9176 (notably @code{vi}le users), and the rest of us just love the hell out
9177 of it. Just give up and submit. Emacs really does stand for
9178 "Escape-Meta-Alt-Control-Shift", and not "Editin Macros", as you may
9179 have heard from other disreputable sources (like the Emacs author).
9181 The shift key is normally located near your pinky fingers, and are
9182 normally used to get capital letters and stuff. You probably use it all
9183 the time. The control key is normally marked "CTRL" or something like
9184 that. The meta key is, funnily enough, never marked as such on any
9185 keyboards. The one I'm curretly at has a key that's marked "Alt", which
9186 is the meta key on this keyboard. It's usually located somewhere to the
9187 left hand side of the keyboard, usually on the bottom row.
9189 Now, us Emacs people doesn't say "press the meta-control-m key", because
9190 that's just too inconvenient. We say "press the @kbd{M-C-m} key".
9191 @kbd{M-} is the prefix that means "meta" and "C-" is the prefix that
9192 means "control". So "press @kbd{C-k}" means "press down the control
9193 key, and hold it down while you press @kbd{k}". "Press @kbd{M-C-k}"
9194 means "press down and hold down the meta key and the control key and
9195 then press @kbd{k}". Simple, ay?
9197 This is somewhat complicated by the fact that not all keyboards have a
9198 meta key. In that case you can use the "escape" key. Then @kbd{M-k}
9199 means "press escape, release escape, press @kbd{k}". That's much more
9200 work than if you have a meta key, so if that's the case, I respectfully
9201 suggest you get a real keyboard with a meta key. You can't live without
9207 @subsection Emacs Lisp
9209 Emacs is the King of Editors because it's really a Lisp interpreter.
9210 Each and every key you tap runs some Emacs Lisp code snippet, and since
9211 Emacs Lisp is an interpreted language, that means that you can configure
9212 any key to run any random code. You just, like, do it.
9214 Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
9215 functions. (These are byte-compiled for speed, but it's still
9216 interpreted.) If you decide that you don't like the way Gnus does
9217 certain things, it's trivial to have it do something a different way.
9218 (Well, at least if you know how to write Lisp code.) However, that's
9219 beyond the scope of this manual, so we are simply going to talk about
9220 some common constructs that you normally use in your @file{.emacs} file
9223 If you want to set the variable @code{gnus-florgbnize} to four (4), you
9224 write the following:
9227 (setq gnus-florgbnize 4)
9230 This function (really "special form") @code{setq} is the one that can
9231 set a variable to some value. This is really all you need to know. Now
9232 you can go and fill your @code{.emacs} file with lots of these to change
9235 If you have put that thing in your @code{.emacs} file, it will be read
9236 and @code{eval}ed (which is lispese for "run") the next time you start
9237 Emacs. If you want to change the variable right away, simply say
9238 @kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
9239 previous "form", which here is a simple @code{setq} statement.
9241 Go ahead---just try it, if you're located at your Emacs. After you
9242 @kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
9243 is the return value of the form you @code{eval}ed.
9247 If the manual says "set @code{gnus-read-active-file} to @code{some}",
9251 (setq gnus-read-active-file 'some)
9254 On the other hand, if the manual says "set @code{gnus-nntp-server} to
9255 @samp{"nntp.ifi.uio.no"}", that means:
9258 (setq gnus-nntp-server "nntp.ifi.uio.no")
9261 So be careful not to mix up strings (the latter) with symbols (the
9262 former). The manual is unambiguous, but it can be confusing.
9266 @node Frequently Asked Questions
9267 @section Frequently Asked Questions
9285 @c outline-regexp: "@chap\\|@\\(sub\\)*section\\|@appendix \\|@appendix\\(sub\\)*sec\\|\^L"