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.
53 @title September Gnus Manual
55 @author by Lars Magne Ingebrigtsen
57 @vskip 0pt plus 1filll
58 Copyright @copyright{} 1995 Free Software Foundation, Inc.
60 Permission is granted to make and distribute verbatim copies of
61 this manual provided the copyright notice and this permission notice
62 are preserved on all copies.
64 Permission is granted to copy and distribute modified versions of this
65 manual under the conditions for verbatim copying, provided that the
66 entire resulting derived work is distributed under the terms of a
67 permission notice identical to this one.
69 Permission is granted to copy and distribute translations of this manual
70 into another language, under the above conditions for modified versions.
72 Cover art by Etienne Suvasa.
79 @top The Gnus Newsreader
81 You can read news (and mail) from within Emacs by using Gnus. The news
82 can be gotten by any nefarious means you can think of---@sc{nntp}, local
83 spool or your mbox file. All at the same time, if you want to push your
87 * History:: How Gnus got where it is today.
88 * Terminology:: We use really difficult, like, words here.
89 * Starting Up:: Finding news can be a pain.
90 * The Group Buffer:: Selecting, subscribing and killing groups.
91 * The Summary Buffer:: Reading, saving and posting articles.
92 * The Article Buffer:: Displaying and handling articles.
93 * The Server Buffer:: Making and editing virtual servers.
94 * Scoring:: Assigning values to articles.
95 * Various:: General purpose settings.
96 * Customization:: Tailoring Gnus to your needs.
97 * Troubleshooting:: What you might try if things do not work.
98 * The End:: Farewell and goodbye.
99 * Appendices:: Technical stuff, Emacs intro, FAQ
100 * Index:: Variable, function and concept index.
101 * Key Index:: Key Index.
108 @sc{gnus} was written by Masanobu UMEDA. When autumn crept up in '94,
109 Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
111 If you want to investigate the person responsible for this outrage, you
112 can point your (feh!) web browser to
113 @file{http://www.ifi.uio.no/~larsi/}. This is also the primary
114 distribution point for the new and spiffy versions of Gnus, also know as
115 The Site That Destroys Newsrcs And Drives People Mad.
117 During the first extended alpha period of develpment, the new Gnus was
118 called "(ding) Gnus". @dfn{(ding)}, is, of course, short for @dfn{ding
119 is not Gnus}, which is a total and utter lie, but who cares? (Besides,
120 the "Gnus" in this abbreviation should probably be pronounced "news" as
121 UMEDA intended, which makes it a more appropriate name, don't you
124 In any case, after spending all that energy with coming up with a new
125 and spiffy name, we decided that the name was @emph{too} spiffy, so we
126 renamamed it back again to "Gnus". But in mixed case. "Gnus" vs.
127 "@sc{gnus}". New vs. old.
129 Incidentally, the next Gnus generation will be called "September Gnus",
130 and won't be released until February. Confused? You will be.
133 * Why?:: What's the point of Gnus?
134 * Compatibility:: Just how compatible is Gnus with @sc{gnus}?
135 * Conformity:: Gnus tries to conform to all standards.
136 * Emacsen:: Gnus can be run on a few modern Emacsen.
137 * Contributors:: Oodles of people.
138 * New Features:: Pointers to some of the new stuff in Gnus.
139 * Newest Features:: Features so new that they haven't been written yet.
145 What's the point of Gnus?
147 I want to provide a "rad", "happening", "way cool" and "hep" newsreader,
148 that lets you do anything you can think of. That was my original
149 motivation, but while working on Gnus, it has become clear to me that
150 this generation of newsreaders really belong in the stone age.
151 Newsreaders haven't developed much since the infancy of the net. If the
152 volume continues to rise with the current rate of increase, all current
153 newsreaders will be pretty much useless. How do you deal with
154 newsgroups that have hundreds (or thousands) of new articles each day?
156 Gnus offer no real solutions to these questions, but I would very much
157 like to see Gnus being used as a testing ground for new methods of
158 reading and fetching news. Expanding on Umeda-san's wise decision to
159 separate the newsreader from the backends, Gnus now offers a simple
160 interface for anybody who wants to write new backends for fetching mail
161 and news from different sources. I have added hooks for customizations
162 everywhere I can imagine useful. By doing so, I'm inviting every one of
163 you to explore and invent new ways of reading news.
165 May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
168 @section Compatibility
170 @cindex compatibility
171 Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
172 bindings have been kept. More key bindings have been added, of course,
173 but only in one or two obscure cases have old bindings been changed.
178 @center In a cloud bones of steel.
182 All commands have kept their names. Some internal functions have changed
185 The @code{gnus-uu} package has changed drastically. @xref{Decoding
188 One major compatibility question is the presence of several summary
189 buffers. All variables that are relevant while reading a group are
190 buffer-local to the summary buffer they belong in. Although most
191 important variables have their values copied into their global
192 counterparts whenever a command is executed in the summary buffer, this
193 change might lead to incorrect values being used unless you are careful.
195 All code that relies on knowledge of @sc{gnus} internals will probably
196 fail. To take two examples: Sorting @code{gnus-newsrc-assoc} (or
197 changing it in any way, as a matter of fact) is strictly verboten. Gnus
198 maintains a hash table that points to the entries in this assoc (which
199 speeds up many functions), and changing the assoc directly will lead to
204 Old hilit19 code does not work at all. In fact, you should probably
205 remove all hilit code from all Gnus hooks
206 (@code{gnus-group-prepare-hook}, @code{gnus-summary-prepare-hook} and
207 @code{gnus-summary-article-hook}). (Well, at the very least the first
208 two.) Gnus provides various integrated functions for highlighting.
209 These are faster and more accurate. To make life easier for everybody,
210 Gnus will by default remove all hilit calls from all hilit hooks.
213 Packages like @code{expire-kill} will no longer work. As a matter of
214 fact, you should probably remove all old @sc{gnus} packages (and other
215 code) when you start using Gnus. More likely than not, Gnus already
216 does what you have written code to make @sc{gnus} do. (Snicker.)
218 Even though old methods of doing things are still supported, only the
219 new methods are documented in this manual. If you detect a new method of
220 doing something while reading this manual, that does not mean you have
221 to stop doing it the old way.
223 Gnus understands all @sc{gnus} startup files.
226 Overall, a casual user who hasn't written much code that depends on
227 @sc{gnus} internals should suffer no problems. If problems occur,
228 please let me know (@kbd{M-x gnus-bug}).
234 No rebels without a clue here, ma'am. We conform to all standards known
235 to (wo)man. Except for those standards and/or conventions we disagree
241 There are no known breaches of this standard.
244 There are no known breaches of this standard, either.
246 @item Usenet Seal of Approval
247 Gnus hasn't been formally through the Seal process, but I have read
248 through the Seal text and I think Gnus would pass.
250 @item Son-of-RFC 1036
251 We do have some breaches to this one.
256 Gnus does no MIME handling, and this standard-to-be seems to think that
257 MIME is the bees' knees, so we have major breakage here.
260 This is considered to be a "vanity header", while I consider it to be
261 consumer information. After seeing so many badly formatted articles
262 coming from @code{tin} and @code{Netscape} I know not to use either of
263 those for posting articles. I would not have known that if it wasn't
264 for the @code{X-Newsreader} header.
267 Gnus breaks lines if this header is long. I infer from RFC1036 that
268 being conservative in what you output is not creating 5000-character
269 lines, so it seems like a good idea to me. However, this standard-to-be
270 says that whitespace in the @code{References} header is to be preserved,
271 so... It doesn't matter one way or the other to Gnus, so if somebody
272 tells me what The Way is, I'll change it. Or not.
277 If you ever see Gnus act noncompliantly to the texts mentioned above,
278 don't hesitate to drop a note to Gnus Towers and let us know.
288 Gnus should work on :
299 Mule versions based on Emacs 19.30 and up.
303 Gnus will absolutely not work on any Emacsen older than that. Not
306 There are some vague differences in what Gnus does, though:
311 The mouse-face on Gnus lines under Emacs and Mule is delimited to
312 certain parts of the lines while they cover the entire line under
316 The same with current-article marking---XEmacs puts an underline under
317 the entire summary line while Emacs and Mule are nicer and kinder.
320 XEmacs features more graphics---a logo and a toolbar.
323 Citation highlighting us better under Emacs and Mule than under XEmacs.
326 Emacs 19.26-19.28 have tangible hidden headers, which can be a bit
333 @section Contributors
336 The new Gnus version couldn't have been done without the help of all the
337 people on the (ding) mailing list. Every day for months I have gotten
338 tens of nice bug reports from them, filling me with joy, every single
339 one of them. Smooches. The people on the list have been tried beyond
340 endurance, what with my "oh, that's a neat idea <type type>, yup, I'll
341 release it right away <ship off> no wait, that doesn't work at all <type
342 type>, yup, I'll ship that one off right away <ship off> no, wait, that
343 absolutely does not work" policy for releases. Micro$oft---bah.
344 Amateurs. I'm @emph{much} worse. (Or is that "worser"? "much worser"?
347 I would like to take this opportunity to thank the Academy for... oops,
352 Of course, GNUS was written by Masanobu UMEDA.
354 Many excellent functions, especially dealing with scoring and
355 highlighting (as well as the @sc{soup} support) was written
358 Innumerable bug fixes were written by Sudish Joseph.
360 @code{gnus-topic} was written by Ilja Weis.
362 Lots and lots of bugs were found and fixed by Steven L. Baur.
364 The refcard was written by Vladimir Alexiev.
366 I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
368 @code{nnfolder} has been much enhanced by Scott Byer.
370 The orphan scoring was written by Peter Mutsaers.
372 GNU XEmacs support has been added by Fabrice Popineau.
374 POP mail support was written by Ken Raeburn.
376 Various bits and pieces, especially dealing with .newsrc files, were
377 suggested and added by Hallvard B Furuseth.
379 Brian Edmonds has written @code{gnus-bbdb}.
381 Ricardo Nassif did the proof-reading.
383 Kevin Davidson came up with the name @dfn{ding}, so blame him.
385 Peter Arius, Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel
386 Quinlan, Frank D. Cringle, Geoffrey T. Dairiki and Andrew Eskilsson have
387 all contributed code and suggestions.
392 @section New Features
398 The look of all buffers can be changed by setting format-like variables
399 (@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
402 Local spool and several @sc{nntp} servers can be used at once
403 (@pxref{Foreign Groups}).
406 You can combine groups into virtual groups (@pxref{nnvirtual}).
409 You can read a number of different mail formats (@pxref{Reading Mail}).
410 All the mail backends implement a convenient mail expiry scheme
411 (@pxref{Expiring Old Mail Articles}).
414 Gnus can use various strategies for gathering threads that have lost
415 their roots (thereby gathering loose sub-threads into one thread) or it
416 can go back and retrieve enough headers to build a complete thread
417 (@pxref{Customizing Threading}).
420 Killed groups can be displayed in the group buffer, and you can read
424 Gnus can do partial group updates---you do not have to retrieve the
425 entire active file just to check for new articles in a few groups
426 (@pxref{The Active File}).
429 Gnus implements a sliding scale of subscribedness to groups
430 (@pxref{Group Levels}).
433 You can score articles according to any number of criteria
434 (@pxref{Scoring}). You can even get Gnus to find out how to score
435 articles for you (@pxref{Adaptive Scoring}).
438 Gnus maintains a dribble buffer that is auto-saved the normal Emacs
439 manner, so it should be difficult to lose much data on what you have
440 read if your machine should go down (@pxref{Auto Save}).
443 Gnus now has its own startup file to avoid cluttering up the
447 You can set the process mark on both groups and articles and perform
448 operations on all the marked items (@pxref{Process/Prefix}).
451 You can grep through a subset of groups and create a group from the
452 results (@pxref{nnkiboze}).
455 You can list subsets of groups according to, well, anything
456 (@pxref{Listing Groups}).
459 You can browse foreign servers and subscribe to groups from those
460 servers (@pxref{Browse Foreign Server}).
463 Gnus can fetch articles asynchronously on a second connection to the
464 server (@pxref{Asynchronous Fetching}).
467 You can cache articles locally (@pxref{Article Caching}).
470 The uudecode functions have been expanded and generalized
471 (@pxref{Decoding Articles}).
474 You can still post uuencoded articles, which was a little-known feature
475 of @sc{gnus}' past (@pxref{Uuencoding & Posting}).
478 Fetching parents (and other articles) now actually works without
479 glitches (@pxref{Finding the Parent}).
482 Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
485 Digests (and other files) can be used as the basis for groups
489 Articles can be highlighted and customized (@pxref{Customizing
493 URLs and other external references can be buttonized (@pxref{Article
497 All Gnus buffers can be customized in a difficult fashion
498 (@pxref{Windows Configuration}).
501 You can click on buttons instead of using the keyboard
505 Gnus can use NoCeM files to weed out spam (@pxref{NoCeM}).
509 This is, of course, just a @emph{short} overview of the @emph{most}
510 important new features. No, really. There are tons more. Yes, we have
511 feeping creaturism in full effect, but nothing too gratuitous, I would
515 @node Newest Features
516 @section Newest Features
519 Also known as the @dfn{todo list}. Sure to be implemented before the
522 Be afraid. Be very afraid.
526 Native @sc{mime} support is something that should be done.
528 A better and simpler method for specifying mail composing methods.
530 Allow posting through mail-to-news gateways.
532 Really do unbinhexing.
535 And much, much, much more. There is more to come than has already been
536 implemented. (But that's always true, isn't it?)
538 @code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>} is where the actual
539 up-to-the-second todo list is located, so if you're really curious, you
540 could point your Web browser over that-a-way.
551 This is what you are supposed to use this thing for---reading news.
552 News is generally fetched from a nearby @sc{nntp} server, and is
553 generally publicly available to everybody. If you post news, the entire
554 world is likely to read just what you have written, and they'll all
555 snigger mischievously. Behind your back.
559 Everything that's delivered to you personally is mail. Some news/mail
560 readers (like Gnus) blur the distinction between mail and news, but
561 there is a difference. Mail is private. News is public. Mailing is
562 not posting, and replying is not following up.
565 Send a mail to the person who has written what you are reading.
568 Post an article to the current newsgroup responding to the article you
572 Gnus gets fed articles from a number of backends, both news and mail
573 backends. Gnus does not handle the underlying media, so to speak---this
574 is all done by the backends.
577 Gnus will always use one method (and backend) as the @dfn{native}, or
578 default, way of getting news.
581 You can also have any number of foreign groups at the same time. These
582 are groups that use different backends for getting news.
586 The top part of an article, where administration information (etc.) is
591 The rest of an article. Everything that is not in the head is in the
596 A line from the head of an article.
600 A collection of such lines, or a collection of heads. Or even a
601 collection of @sc{nov} lines.
605 When Gnus enters a group, it asks the backend for the headers for all
606 the unread articles in the group. Most servers support the News OverView
607 format, which is much smaller and much faster to read than the normal
612 Each group is subscribed at some @dfn{level} or other (1-9). The ones
613 that have a lower level are "more" subscribed than the groups with a
614 higher level. In fact, groups on levels 1-5 are considered
615 @dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
616 are @dfn{killed}. Commands for listing groups and scanning for new
617 articles will all use the numeric prefix as @dfn{working level}.
620 @cindex killed groups
621 No information on killed groups is stored or updated, which makes killed
622 groups much easier to handle than subscribed groups.
625 @cindex zombie groups
626 Just like killed groups, only slightly less dead.
630 The news server has to keep track of what articles it carries, and what
631 groups exist. All this information in stored in the active file, which
632 is rather large, as you might surmise.
636 A group that exists in the @file{.newsrc} file, but isn't known to the
637 server (i. e., it isn't in the active file), is a @emph{bogus group}.
638 This means that the group probably doesn't exist (any more).
643 @chapter Starting Gnus
648 If your system administrator has set things up properly, starting Gnus
649 and reading news is extremely easy---you just type @kbd{M-x gnus}.
651 @findex gnus-other-frame
652 @kindex M-x gnus-other-frame
653 If you want to start Gnus in a different frame, you can use the command
654 @kbd{M-x gnus-other-frame} instead.
656 If things do not go smoothly at startup, you have to twiddle some
660 * Finding the News:: Choosing a method for getting news.
661 * The First Time:: What does Gnus do the first time you start it?
662 * The Server is Down:: How can I read my mail then?
663 * Slave Gnusii:: You can have more than one Gnus active at a time.
664 * Fetching a Group:: Starting Gnus just to read a group.
665 * New Groups:: What is Gnus supposed to do with new groups?
666 * Startup Files:: Those pesky startup files---@file{.newsrc}.
667 * Auto Save:: Recovering from a crash.
668 * The Active File:: Reading the active file over a slow line Takes Time.
669 * Startup Variables:: Other variables you might change.
672 @node Finding the News
673 @section Finding the News
675 @vindex gnus-select-method
676 The @code{gnus-select-method} variable controls how Gnus finds news.
677 This variable should be a list where the first element says @dfn{how}
678 and the second element says @dfn{where}. This method is your native
679 method. All groups that are not fetched with this method are foreign
682 For instance, if you want to get your daily dosage of news from the
683 @samp{news.somewhere.edu} @sc{nntp} server, you'd say:
686 (setq gnus-select-method '(nntp "news.somewhere.edu"))
689 If you want to read directly from the local spool, say:
692 (setq gnus-select-method '(nnspool ""))
695 If you can use a local spool, you probably should, as it will almost
696 certainly be much faster.
698 @vindex gnus-nntpserver-file
700 @cindex @sc{nntp} server
701 If this variable is not set, Gnus will take a look at the
702 @code{NNTPSERVER} environment variable. If that variable isn't set,
703 Gnus will see whether @code{gnus-nntpserver-file} (default
704 @file{/etc/nntpserver}) has any opinions in the matter. It that fails
705 as well, Gnus will will try to use the machine that is running Emacs as
706 an @sc{nntp} server. That's a longshot, though.
708 @vindex gnus-nntp-server
709 If @code{gnus-nntp-server} is set, this variable will override
710 @code{gnus-select-method}. You should therefore set
711 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
713 @vindex gnus-secondary-servers
714 You can also make Gnus prompt you interactively for the name of an
715 @sc{nntp} server. If you give a non-numerical prefix to @code{gnus}
716 (i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
717 in the @code{gnus-secondary-servers} list (if any). You can also just
718 type in the name of any server you feel like visiting.
720 However, if you use one @sc{nntp} server regularly, and are just
721 interested in a couple of groups from a different server, you would be
722 better served by using the @code{gnus-group-browse-foreign-server}
723 command from the group buffer. It will let you have a look at what
724 groups are available, and you can subscribe to any of the groups you
725 want to. This also makes @file{.newsrc} maintenance much tidier.
726 @xref{Foreign Groups}.
728 @vindex gnus-secondary-select-methods
729 A slightly different approach to foreign groups is to set the
730 @code{gnus-secondary-select-methods} variable. The select methods
731 listed in this variable are in many ways just as native as the
732 @code{gnus-select-method} server. They will also be queried for active
733 files during startup (if that's required), and new newsgroups that
734 appear on these servers will be subscribed (or not) just as native
737 For instance, if you use the @code{nnmbox} backend to read you mail, you
738 would typically set this variable to
741 (setq gnus-secondary-select-methods '((nnmbox "")))
745 @section The First Time
746 @cindex first time usage
748 If no startup files exist, Gnus will try to determine what groups should
749 be subscribed by default.
751 @vindex gnus-default-subscribed-newsgroups
752 If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
753 will subscribe you to just those groups in that list, leaving the rest
754 killed. Your system administrator should have set this variable to
757 Since she hasn't, Gnus will just subscribe you to a few randomly picked
758 groups (i.e., @samp{*.newusers}). (@dfn{Random} is here defined as
759 "whatever Lars thinks you should read".)
761 You'll also be subscribed to the Gnus documentation group, which should
762 help you with most common problems.
764 If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
765 use the normal functions for handling new groups, and not do anything
768 @node The Server is Down
769 @section The Server is Down
770 @cindex server errors
772 If the default server is down, Gnus will understandably have some
773 problems starting. However, if you have some mail groups in addition to
774 the news groups, you may want to start Gnus anyway.
776 Gnus, being the trusting sort of program, will ask whether to proceed
777 without a native select method if that server can't be contacted. This
778 will happen whether the server doesn't actually exist (i.e., you have
779 given the wrong address) or the server has just momentarily taken ill
780 for some reason or other.
782 If Gnus says "nntp server on <your server> can't be opened. Continue?",
783 you do not want to continue unless you have some foreign groups that you
784 want to read. Even if you don't, Gnus will let you continue, but you'll
785 find it difficult to actually do anything in the group buffer. But,
786 hey, that's your problem. Blllrph!
788 @findex gnus-no-server
789 If you know that the server is definitely down, or you just want to read
790 your mail without bothering with the server at all, you can use the
791 @code{gnus-no-server} command to start Gnus. That might come in handy
792 if you're in a hurry as well.
796 @section Slave Gnusiï
799 You might want to run more than one Emacs with more than one Gnus at the
800 same time. If you are using different @file{.newsrc} files (eg., if you
801 are using the two different Gnusiï to read from two different servers),
802 that is no problem whatsoever. You just do it.
804 The problem appears when you want to run two Gnusiï that use the same
807 To work around that problem some, we here at the Think-Tank at the Gnus
808 Towers have come up with a new concept: @dfn{Masters} and
809 @dfn{servants}. (We have applied for a patent on this concept, and have
810 taken out a copyright on those words. If you wish to use those words in
811 conjunction with each other, you have to send $1 per usage instance to
812 me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
813 Applications}) will be much more expensive, of course.)
815 Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
816 however you do it). Each subsequent slave Gnusiï should be started with
817 @kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
818 files, but some slave files that contains information only on what
819 groups have been read in the slave session. When a master Gnus starts,
820 it will read (and delete) these slave files, incorporating all
821 information from all of them. (The slave files will be read in the
822 sequence they were created, so the latest changes will have precedence.)
824 Information from the slave files has, of course, presedence over the
825 information in the normal (i. e., master) @code{.newsrc} file.
828 @node Fetching a Group
829 @section Fetching a Group
831 @findex gnus-fetch-group
832 It it sometime convenient to be able to just say "I want to read this
833 group and I don't care whether Gnus has been started or not". This is
834 perhaps more useful for people who write code than for users, but the
835 command @code{gnus-fetch-group} provides this functionality in any
836 case. It takes the group name as a paramenter.
843 @vindex gnus-subscribe-newsgroup-method
844 What Gnus does when it encounters a new group is determined by the
845 @code{gnus-subscribe-newsgroup-method} variable.
847 This variable should contain a function. Some handy pre-fab values
852 @item gnus-subscribe-randomly
853 @vindex gnus-subscribe-randomly
854 Subscribe all new groups randomly.
856 @item gnus-subscribe-alphabetically
857 @vindex gnus-subscribe-alphabetically
858 Subscribe all new groups alphabetically.
860 @item gnus-subscribe-hierarchically
861 @vindex gnus-subscribe-hierarchically
862 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.
869 @item gnus-subscribe-killed
870 @vindex gnus-subscribe-killed
873 @item gnus-subscribe-zombies
874 @vindex gnus-subscribe-zombies
875 Make all new groups zombies. You can browse the zombies later (with
876 @kbd{A z}) and either kill them all off properly, or subscribe to them.
880 @vindex gnus-subscribe-hierarchical-interactive
881 A closely related variable is
882 @code{gnus-subscribe-hierarchical-interactive}. (That's quite a
883 mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a
884 hierarchical fashion whether to subscribe to new groups or not. Gnus
885 will ask you for each sub-hierarchy whether you want to descend the
888 One common way to control which new newsgroups should be subscribed or
889 ignored is to put an @dfn{options} line at the start of the
890 @file{.newsrc} file. Here's an example:
893 options -n !alt.all !rec.all sci.all
896 @vindex gnus-subscribe-options-newsgroup-method
897 This line obviously belongs to a serious-minded intellectual scientific
898 person (or she may just be plain old boring), because it says that all
899 groups that have names beginning with @samp{alt} and @samp{rec} should
900 be ignored, and all groups with names beginning with @samp{sci} should
901 be subscribed. Gnus will not use the normal subscription method for
902 subscribing these groups.
903 @code{gnus-subscribe-options-newsgroup-method} is used instead. This
904 variable defaults to @code{gnus-subscribe-alphabetically}.
906 @vindex gnus-options-not-subscribe
907 @vindex gnus-options-subscribe
908 If you don't want to mess with your @file{.newsrc} file, you can just
909 set the two variables @code{gnus-options-subscribe} and
910 @code{gnus-options-not-subscribe}. These two variables do exactly the
911 same as the @file{.newsrc} options -n trick. Both are regexps, and if
912 the the new group matches the first, it will be unconditionally
913 subscribed, and if it matches the latter, it will be ignored.
915 @vindex gnus-auto-subscribed-groups
916 Yet another variable that meddles here is
917 @code{gnus-auto-subscribed-groups}. It works exactly like
918 @code{gnus-options-subscribe}, and is therefore really superfluos, but I
919 thought it would be nice to have two of these. This variable is more
920 meant for setting some ground rules, while the other variable is used
921 more for user fiddling. By default this variable makes all new groups
922 that come from mail backends (@code{nnml}, @code{nnbabyl},
923 @code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you
924 don't like that, just set this variable to @code{nil}.
926 @vindex gnus-check-new-newsgroups
927 If you are satisfied that you really never want to see any new groups,
928 you could set @code{gnus-check-new-newsgroups} to @code{nil}. This will
929 also save you some time at startup. Even if this variable is
930 @code{nil}, you can always subscribe to the new groups just by pressing
931 @kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
932 is @code{t} by default.
934 Gnus normally determines whether a group is new or not by comparing the
935 list of groups from the active file(s) with the lists of subscribed and
936 dead groups. This isn't a particularly fast method. If
937 @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
938 server for new groups since the last time. This is both faster &
939 cheaper. This also means that you can get rid of the list of killed
940 groups altogether, so you may set @code{gnus-save-killed-list} to
941 @code{nil}, which will save time both at startup, at exit, and all over.
942 Saves disk space, too. Why isn't this the default, then?
943 Unfortunately, not all servers support this function.
945 I bet I know what you're thinking now: How do I find out whether my
946 server supports @code{ask-server}? No? Good, because I don't have a
947 fail-safe answer. I would suggest just setting this variable to
948 @code{ask-server} and see whether any new groups appear after a few
949 days. If they do, then it works. If they don't, then it doesn't work.
950 I could write a function to make Gnus guess whether the server supports
951 @code{ask-server}, but it would just be a guess. So I won't. You could
952 @code{telnet} to the server and say @samp{HELP} and see whether it lists
953 @samp{NEWGROUPS} among the commands it understands. If it does, then it
954 might work. (But there are servers that lists @samp{NEWGROUPS} without
955 supporting the function properly.)
957 This variable can also be a list of select methods. If so, Gnus will
958 issue an @code{ask-server} command to each of the select methods, and
959 subscribe them (or not) using the normal methods. This might be handy
960 if you are monitoring a few servers for new groups. A side effect is
961 that startup will take much longer, so you can meditate while waiting.
962 Use the mantra "dingnusdingnusdingnus" to achieve permanent happiness.
965 @section Startup Files
966 @cindex startup files
969 Now, you all know about the @file{.newsrc} file. All subscription
970 information is traditionally stored in this file.
972 Things got a bit more complicated with @sc{gnus}. In addition to
973 keeping the @file{.newsrc} file updated, it also used a file called
974 @file{.newsrc.el} for storing all the information that didn't fit into
975 the @file{.newsrc} file. (Actually, it duplicated everything in the
976 @file{.newsrc} file.) @sc{gnus} would read whichever one of these files
977 that were the most recently saved, which enabled people to swap between
978 @sc{gnus} and other newsreaders.
980 That was kinda silly, so Gnus went one better: In addition to the
981 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
982 @file{.newsrc.eld}. It will read whichever of these files that are most
983 recent, but it will never write a @file{.newsrc.el} file.
985 @vindex gnus-save-newsrc-file
986 You can also turn off writing the @file{.newsrc} file by setting
987 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
988 the file and save some space, as well as making exit from Gnus faster.
989 However, this will make it impossible to use other newsreaders than
990 Gnus. But hey, who would want to, right?
992 @vindex gnus-save-killed-list
993 If @code{gnus-save-killed-list} is @code{nil}, Gnus will not save the
994 list of killed groups to the startup file. This will save both time
995 (when starting and quitting) and space (on disk). It will also means
996 that Gnus has no record of what groups are new or old, so the automatic
997 new groups subscription methods become meaningless. You should always
998 set @code{gnus-check-new-newsgroups} to @code{nil} or @code{ask-server}
999 if you set this variable to @code{nil} (@pxref{New Groups}).
1001 @vindex gnus-startup-file
1002 The @code{gnus-startup-file} variable says where the startup files are.
1003 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
1004 file being whatever that one is with a @samp{.eld} appended.
1006 @vindex gnus-save-newsrc-hook
1007 @vindex gnus-save-quick-newsrc-hook
1008 @vindex gnus-save-standard-newsrc-hook
1009 @code{gnus-save-newsrc-hook} is called before saving any of the newsrc
1010 files, while @code{gnus-save-quick-newsrc-hook} is called just before
1011 saving the @file{.newsrc.eld} file, and
1012 @code{gnus-save-standard-newsrc-hook} is called just before saving the
1013 @file{.newsrc} file. The latter two are commonly used to turn version
1014 control on or off. Version control is off by default when saving.
1018 @cindex dribble file
1021 Whenever you do something that changes the Gnus data (reading articles,
1022 catching up, killing/subscribing groups), the change is added to a
1023 special @dfn{dribble buffer}. This buffer is auto-saved the normal
1024 Emacs way. If your Emacs should crash before you have saved the
1025 @file{.newsrc} files, all changes you have made can be recovered from
1028 If Gnus detects this file at startup, it will ask the user whether to
1029 read it. The auto save file is deleted whenever the real startup file is
1032 @vindex gnus-use-dribble-file
1033 If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
1034 maintain a dribble buffer. The default is @code{t}.
1036 @vindex gnus-dribble-directory
1037 Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
1038 this variable is @code{nil}, which it is by default, Gnus will dribble
1039 into the same directory as the @file{.newsrc} file is located. (This is
1040 normally the user's home directory.)
1042 @node The Active File
1043 @section The Active File
1045 @cindex ignored groups
1047 When Gnus starts, or indeed whenever it tries to determine whether new
1048 articles have arrived, it reads the active file. This is a very large
1049 file that lists all the active groups and articles on the @sc{nntp}
1052 @vindex gnus-ignored-newsgroups
1053 Before examining the active file, Gnus deletes all lines that match the
1054 regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject
1055 any groups with bogus names, but you can use this variable to make Gnus
1056 ignore hierarchies you aren't ever interested in.
1058 @c @code{nil} by default, and will slow down active file handling somewhat
1059 @c if you set it to anything else.
1061 @vindex gnus-read-active-file
1062 The active file can be rather Huge, so if you have a slow network, you
1063 can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
1064 reading the active file. This variable is @code{t} by default.
1066 Gnus will try to make do by just getting information on the groups
1067 that you actually subscribe to.
1069 Note that if you subscribe to lots and lots of groups, setting this
1070 variable to @code{nil} will probably make Gnus slower, not faster. At
1071 present, having this variable @code{nil} will slow Gnus down
1072 considerably, unless you read news over a 2400 baud modem.
1074 This variable can also have the value @code{some}. Gnus will then
1075 attempt to read active info only on the subscribed groups. On some
1076 servers this is quite fast (on sparkling, brand new INN servers that
1077 support the @samp{LIST ACTIVE group} command), on others this is not
1078 fast at all. In any case, @code{some} should be faster than @code{nil},
1079 and is certainly faster than @code{t} over slow lines.
1081 If this variable is @code{nil}, Gnus will as for group info in total
1082 lock-step, which isn't very fast. If it is @code{some} and you use an
1083 @sc{nntp} server, Gnus will pump out commands as fast as it can, and
1084 read all the replies in one swoop. This will normally result in better
1085 performance, but if the server does not support the aforementioned
1086 @samp{LIST ACTIVE group} command, this isn't very nice to the server.
1088 In any case, if you use @code{some} or @code{nil}, you should kill all
1089 groups that you aren't interested in.
1091 @node Startup Variables
1092 @section Startup Variables
1096 @item gnus-load-hook
1097 @vindex gnus-load-hook
1098 A hook that is run while Gnus is being loaded. Note that this hook will
1099 normally be run just once in each Emacs session, no matter how many
1100 times you start Gnus.
1102 @item gnus-startup-hook
1103 @vindex gnus-startup-hook
1104 A hook that is run after starting up Gnus successfully.
1106 @item gnus-check-bogus-newsgroups
1107 @vindex gnus-check-bogus-newsgroups
1108 If non-@code{nil}, Gnus will check for and delete all bogus groups at
1109 startup. A @dfn{bogus group} is a group that you have in your
1110 @file{.newsrc} file, but doesn't exist on the news server. Checking for
1111 bogus groups isn't very quick, so to save time and resources, it's best
1112 to leave this option off, and instead do the checking for bogus groups
1113 once in a while from the group buffer (@pxref{Group Maintenance}).
1115 @item gnus-inhibit-startup-message
1116 @vindex gnus-inhibit-startup-message
1117 If non-@code{nil}, the startup message won't be displayed. That way,
1118 your boss might not notice that you are reading news instead of doing
1121 @item gnus-no-groups-message
1122 @vindex gnus-no-groups-message
1123 Message displayed by Gnus when no groups are available.
1126 @node The Group Buffer
1127 @chapter The Group Buffer
1128 @cindex group buffer
1130 The @dfn{group buffer} lists all (or parts) of the available groups. It
1131 is the first buffer shown when Gnus starts, and will never be killed as
1132 long as Gnus is active.
1135 * Group Buffer Format:: Information listed and how you can change it.
1136 * Group Maneuvering:: Commands for moving in the group buffer.
1137 * Selecting a Group:: Actually reading news.
1138 * Subscription Commands:: Unsubscribing, killing, subscribing.
1139 * Group Levels:: Levels? What are those, then?
1140 * Group Score:: A mechanism for finding out what groups you like.
1141 * Marking Groups:: You can mark groups for later processing.
1142 * Foreign Groups:: How to create foreign groups.
1143 * Group Parameters:: Each group may have different parameters set.
1144 * Listing Groups:: Gnus can list various subsets of the groups.
1145 * Sorting Groups:: Re-arrange the group order.
1146 * Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
1147 * Browse Foreign Server:: You can browse a server. See what if has to offer.
1148 * Exiting Gnus:: Stop reading news and get some work done.
1149 * Group Topics:: A folding group mode divided into topics.
1150 * Misc Group Stuff:: Other stuff that you can to do.
1153 @node Group Buffer Format
1154 @section Group Buffer Format
1155 @cindex group buffer format
1157 The default format of the group buffer is nice and dull, but you can
1158 make it as exciting and ugly as you feel like.
1160 Here's a couple of example group lines:
1163 25: news.announce.newusers
1164 * 0: alt.fan.andrea-dworkin
1169 You can see that there are 25 unread articles in
1170 @samp{news.announce.newusers}. There are no unread articles, but some
1171 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
1172 asterisk at the beginning of the line?)
1174 @vindex gnus-group-line-format
1175 You can fuck that up to your heart's delight by fiddling with the
1176 @code{gnus-group-line-format} variable. This variable works along the
1177 lines of a @code{format} specification, which is pretty much the same as
1178 a @code{printf} specifications, for those of you who use (feh!) C.
1179 @xref{Formatting Variables}.
1181 The default value that produced those lines above is
1182 @samp{"%M%S%5y: %(%g%)\n"}.
1184 There should always be a colon on the line; the cursor always moves to
1185 the colon after performing an operation. Nothing else is required---not
1186 even the group name. All displayed text is just window dressing, and is
1187 never examined by Gnus. Gnus stores all real information it needs using
1190 (Note that if you make a really strange, wonderful, spreadsheet-like
1191 layout, everybody will believe you are hard at work with the accounting
1192 instead of wasting time reading news.)
1194 Here's a list of all available format characters:
1199 Only marked articles.
1202 Whether the group is subscribed.
1205 Level of subscribedness.
1208 Number of unread articles.
1211 Number of dormant articles.
1214 Number of ticked articles.
1217 Number of read articles.
1220 Total number of articles.
1223 Number of unread, unticked, non-dormant articles.
1226 Number of ticked and dormant articles.
1235 Newsgroup description.
1250 A string that looks like @samp{<%s:%n>} if a foreign select method is
1254 Indentation based on the level of the topic (@pxref{Group Topics}).
1257 @vindex gnus-group-uncollapsed-levels
1258 Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels}
1259 variable says how many levels to leave at the end of the group name.
1260 The default is @samp{1}.
1263 User defined specifier. The next character in the format string should
1264 be a letter. @sc{gnus} will call the function
1265 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
1266 following @samp{%u}. The function will be passed the current headers as
1267 argument. The function should return a string, which will be inserted
1268 into the buffer just like information from any other specifier.
1272 All the "number-of" specs will be filled with an asterisk (@samp{*}) if
1273 no info is available---for instance, if it is a non-activated foreign
1274 group, or a bogus (or semi-bogus) native group.
1276 @vindex gnus-group-mode-line-format
1277 The mode line can be changed by setting
1278 (@code{gnus-group-mode-line-format}). It doesn't understand that many
1283 The native news server.
1285 The native select method.
1288 @node Group Maneuvering
1289 @section Group Maneuvering
1290 @cindex group movement
1292 All movement commands understand the numeric prefix and will behave as
1293 expected, hopefully.
1299 @findex gnus-group-next-unread-group
1300 Go to the next group that has unread articles
1301 (@code{gnus-group-next-unread-group}).
1308 @findex gnus-group-prev-unread-group
1309 Go to the previous group group that has unread articles
1310 (@code{gnus-group-prev-unread-group}).
1314 @findex gnus-group-next-group
1315 Go to the next group (@code{gnus-group-next-group}).
1319 @findex gnus-group-prev-group
1320 Go to the previous group (@code{gnus-group-prev-group}).
1324 @findex gnus-group-next-unread-group-same-level
1325 Go to the next unread group on the same level (or lower)
1326 (@code{gnus-group-next-unread-group-same-level}).
1330 @findex gnus-group-prev-unread-group-same-level
1331 Go to the previous unread group on the same level (or lower)
1332 (@code{gnus-group-prev-unread-group-same-level}).
1335 Three commands for jumping to groups:
1341 @findex gnus-group-jump-to-group
1342 Jump to a group (and make it visible if it isn't already)
1343 (@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
1348 @findex gnus-group-best-unread-group
1349 Jump to the unread group with the lowest level
1350 (@code{gnus-group-best-unread-group}).
1354 @findex gnus-group-first-unread-group
1355 Jump to the first group with unread articles
1356 (@code{gnus-group-first-unread-group}).
1359 @vindex gnus-group-goto-unread
1360 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
1361 commands will move to the next group, not the next unread group. Even
1362 the commands that say they move to the next unread group. The default
1366 @node Selecting a Group
1367 @section Selecting a Group
1368 @cindex group selection
1373 @kindex SPACE (Group)
1374 @findex gnus-group-read-group
1375 Select the current group, switch to the summary buffer and display the
1376 first unread article (@code{gnus-group-read-group}). If there are no
1377 unread articles in the group, or if you give a non-numerical prefix to
1378 this command, Gnus will offer to fetch all the old articles in this
1379 group from the server. If you give a numerical prefix @var{N}, Gnus
1380 will fetch @var{N} number of articles. If @var{N} is positive, fetch
1381 the @var{N} newest articles, if @var{N} is negative, fetch the
1382 @var{abs(N)} oldest articles.
1386 @findex gnus-group-select-group
1387 Select the current group and switch to the summary buffer
1388 (@code{gnus-group-select-group}). Takes the same arguments as
1389 @code{gnus-group-read-group}---the only difference is that this command
1390 does not display the first unread article automatically upon group
1394 @kindex M-RET (Group)
1395 @findex gnus-group-quick-select-group
1396 This does the same as the command above, but tries to do it with the
1397 minimum amount off fuzz (@code{gnus-group-quick-select-group}). No
1398 scoring/killing will be performed, there will be no highlights and no
1399 expunging. This might be useful if you're in a real hurry and have to
1400 enter some humongous groups.
1403 @kindex M-RET (Group)
1404 @findex gnus-group-visible-select-group
1405 This is yet one more command that does the same as the one above, but
1406 this one does it without expunging and hiding dormants
1407 (@code{gnus-group-visible-select-group}).
1411 @findex gnus-group-catchup-current
1412 Mark all unticked articles in this group as read
1413 (@code{gnus-group-catchup-current}).
1417 @findex gnus-group-catchup-current-all
1418 Mark all articles in this group, even the ticked ones, as read
1419 (@code{gnus-group-catchup-current-all}).
1422 @vindex gnus-large-newsgroup
1423 The @code{gnus-large-newsgroup} variable says what Gnus should consider
1424 to be a big group. This is 200 by default. If the group has more
1425 unread articles than this, Gnus will query the user before entering the
1426 group. The user can then specify how many articles should be fetched
1427 from the server. If the user specifies a negative number (@samp{-n}),
1428 the @samp{n} oldest articles will be fetched. If it is positive, the
1429 @samp{n} articles that have arrived most recently will be fetched.
1431 @vindex gnus-select-group-hook
1432 @vindex gnus-auto-select-first
1433 @code{gnus-auto-select-first} control whether any articles are selected
1434 automatically when entering a group.
1439 Don't select any articles when entering the group. Just display the
1440 full summary buffer.
1443 Select the first unread article when entering the group.
1446 Select the most high-scored article in the group when entering the
1450 If you want to prevent automatic selection in some group (say, in a
1451 binary group with Huge articles) you can set this variable to @code{nil}
1452 in @code{gnus-select-group-hook}, which is called when a group is
1455 @findex gnus-thread-sort-by-total-score
1456 @findex gnus-thread-sort-by-date
1457 @findex gnus-thread-sort-by-score
1458 @findex gnus-thread-sort-by-subject
1459 @findex gnus-thread-sort-by-author
1460 @findex gnus-thread-sort-by-number
1461 @vindex gnus-thread-sort-functions
1462 If you are using a threaded summary display, you can sort the threads by
1463 setting @code{gnus-thread-sort-functions}, which is a list of functions.
1464 By default, sorting is done on article numbers. Ready-made sorting
1465 predicate functions include @code{gnus-thread-sort-by-number},
1466 @code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
1467 @code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and
1468 @code{gnus-thread-sort-by-total-score}.
1470 Each function takes two threads and return non-@code{nil} if the first
1471 thread should be sorted before the other. Note that sorting really is
1472 normally done by looking only at the roots of each thread. If you use
1473 more than one function, the primary sort key should be the last function
1474 in the list. You should probably always include
1475 @code{gnus-thread-sort-by-number} in the list of sorting
1476 functions---preferably first. This will ensure that threads that are
1477 equal with respect to the other sort criteria will be displayed in
1478 ascending article order.
1480 If you would like to sort by score, then by subject, and finally by
1481 number, you could do something like:
1484 (setq gnus-thread-sort-functions
1485 '(gnus-thread-sort-by-number
1486 gnus-thread-sort-by-subject
1487 gnus-thread-sort-by-score))
1490 The threads that have highest score will be displayed first in the
1491 summary buffer. When threads have the same score, they will be sorted
1492 alphabetically. The threads that have the same score and the same
1493 subject will be sorted by number, which is (normally) the sequence in
1494 which the articles arrived.
1496 If you want to sort by score and then reverse arrival order, you could
1500 (setq gnus-thread-sort-functions
1502 (not (gnus-thread-sort-by-number t1 t2)))
1503 gnus-thread-sort-by-score))
1506 @vindex gnus-thread-score-function
1507 The function in the @code{gnus-thread-score-function} variable (default
1508 @code{+}) is used for calculating the total score of a thread. Useful
1509 functions might be @code{max}, @code{min}, or squared means, or whatever
1512 @findex gnus-article-sort-functions
1513 @findex gnus-article-sort-by-date
1514 @findex gnus-article-sort-by-score
1515 @findex gnus-article-sort-by-subject
1516 @findex gnus-article-sort-by-author
1517 @findex gnus-article-sort-by-number
1518 If you are using an unthreaded display for some strange reason or other,
1519 you have to fiddle with the @code{gnus-article-sort-functions} variable.
1520 It is very similar to the @code{gnus-thread-sort-functions}, except that
1521 is uses slightly different functions for article comparison. Available
1522 sorting predicate functions are @code{gnus-article-sort-by-number},
1523 @code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject},
1524 @code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}.
1526 If you want to sort an unthreaded summary display by subject, you could
1530 (setq gnus-article-sort-functions
1531 '(gnus-article-sort-by-number
1532 gnus-article-sort-by-subject))
1536 @node Subscription Commands
1537 @section Subscription Commands
1546 @findex gnus-group-unsubscribe-current-group
1547 Toggle subscription to the current group
1548 (@code{gnus-group-unsubscribe-current-group}).
1554 @findex gnus-group-unsubscribe-group
1555 Prompt for a group to subscribe, and then subscribe it. If it was
1556 subscribed already, unsubscribe it instead
1557 (@code{gnus-group-unsubscribe-group}).
1563 @findex gnus-group-kill-group
1564 Kill the current group (@code{gnus-group-kill-group}).
1570 @findex gnus-group-yank-group
1571 Yank the last killed group (@code{gnus-group-yank-group}).
1577 @findex gnus-group-kill-region
1578 Kill all groups in the region (@code{gnus-group-kill-region}).
1582 @findex gnus-group-kill-all-zombies
1583 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
1586 @kindex S C-k (Group)
1587 @findex gnus-group-kill-level
1588 Kill all groups on a certain level (@code{gnus-group-kill-level}).
1589 These groups can't be yanked back after killing, so this command should
1590 be used with some caution. The only thing where this command comes in
1591 really handy is when you have a @file{.newsrc} with lots of unsubscribed
1592 groups that you want to get rid off. @kbd{S C-k} on level @code{7} will
1593 kill off all unsubscribed groups that do not have message numbers in the
1594 @file{.newsrc} file.
1598 Also @xref{Group Levels}.
1601 @section Group Levels
1604 All groups have a level of @dfn{subscribedness}. For instance, if a
1605 group is on level 2, it is more subscribed than a group on level 5. You
1606 can ask Gnus to just list groups on a given level or lower
1607 (@pxref{Listing Groups}), or to just check for new articles in groups on
1608 a given level or lower (@pxref{Misc Group Stuff}).
1614 @findex gnus-group-set-current-level
1615 Set the level of the current group. If a numeric prefix is given, the
1616 next @var{n} groups will have their levels set. The user will be
1617 prompted for a level.
1620 @vindex gnus-level-killed
1621 @vindex gnus-level-zombie
1622 @vindex gnus-level-unsubscribed
1623 @vindex gnus-level-subscribed
1624 Gnus considers groups on between levels 1 and
1625 @code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed,
1626 @code{gnus-level-subscribed} (exclusive) and
1627 @code{gnus-level-unsubscribed} (inclusive) (default 7) to be
1628 unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
1629 (default 8) and @code{gnus-level-killed} to be killed (default 9),
1630 completely dead. Gnus treats subscribed and unsubscribed groups exactly
1631 the same, but zombie and killed groups have no information on what
1632 articles you have read, etc, stored. This distinction between dead and
1633 living groups isn't done because it is nice or clever, it is done purely
1634 for reasons of efficiency.
1636 It is recommended that you keep all your mail groups (if any) on quite
1637 low levels (eg. 1 or 2).
1639 If you want to play with the level variables, you should show some care.
1640 Set them once, and don't touch them ever again. Better yet, don't touch
1641 them at all unless you know exactly what you're doing.
1643 @vindex gnus-level-default-unsubscribed
1644 @vindex gnus-level-default-subscribed
1645 Two closely related variables are @code{gnus-level-default-subscribed}
1646 (default 3) and @code{gnus-level-default-unsubscribed} (default 6),
1647 which are the levels that new groups will be put on if they are
1648 (un)subscribed. These two variables should, of course, be inside the
1649 relevant legal ranges.
1651 @vindex gnus-keep-same-level
1652 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
1653 will only move to groups that are of the same level (or lower). In
1654 particular, going from the last article in one group to the next group
1655 will go to the next group of the same level (or lower). This might be
1656 handy if you want to read the most important groups before you read the
1659 @vindex gnus-group-default-list-level
1660 All groups with a level less than or equal to
1661 @code{gnus-group-default-list-level} will be listed in the group buffer
1664 @vindex gnus-group-list-inactive-groups
1665 If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active
1666 groups will be listed along with the unread groups. This variable is
1667 @code{t} by default. If it is @code{nil}, inactive groups won't be
1670 @vindex gnus-group-use-permament-levels
1671 If @code{gnus-group-use-permament-levels} is non-@code{nil}, once you
1672 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
1673 use this level as the "work" level.
1675 @vindex gnus-activate-level
1676 Gnus will normally just activate groups that are on level
1677 @code{gnus-activate-level} or less. If you don't want to activate
1678 unsubscribed groups, for instance, you might set this variable to
1683 @section Group Score
1686 You would normally keep important groups on high levels, but that scheme
1687 is somewhat restrictive. Don't you wish you could have Gnus sort the
1688 group buffer according to how often you read groups, perhaps? Within
1691 This is what @dfn{group score} is for. You can assign a score to each
1692 group. You can then sort the group buffer based on this score.
1693 Alternatively, you can sort on score and then level. (Taken together,
1694 the level and the score is called the @dfn{rank} of the group. A group
1695 that is on level 4 and has a score of 1 has a higher rank than a group
1696 on level 5 that has a score of 300. (The level is the most significant
1697 part and the score is the least significant part.)
1699 @findex gnus-summary-bubble-group
1700 If you want groups you read often to get higher scores than groups you
1701 read seldom you can add the @code{gnus-summary-bubble-group} function to
1702 the @code{gnus-summary-exit-hook} hook. This will result (after
1703 sorting) in a bubbling sort of action. If you want to see that in
1704 action after each summary exit, you can add
1705 @code{gnus-group-sort-groups-by-rank} or
1706 @code{gnus-group-sort-groups-by-score} to the same hook, but that will
1707 slow things down somewhat.
1710 @node Marking Groups
1711 @section Marking Groups
1712 @cindex marking groups
1714 If you want to perform some command on several groups, and they appear
1715 subsequently in the group buffer, you would normally just give a
1716 numerical prefix to the command. Most group commands will then do your
1717 bidding on those groups.
1719 However, if the groups are not in sequential order, you can still
1720 perform a command on several groups. You simply mark the groups first
1721 with the process mark and then execute the command.
1729 @findex gnus-group-mark-group
1730 Set the mark on the current group (@code{gnus-group-mark-group}).
1736 @findex gnus-group-unmark-group
1737 Remove the mark from the current group
1738 (@code{gnus-group-unmark-group}).
1742 @findex gnus-group-unmark-all-groups
1743 Remove the mark from all groups (@code{gnus-group-unmark-all-groups}).
1747 @findex gnus-group-mark-region
1748 Mark all groups between point and mark (@code{gnus-group-mark-region}).
1752 @findex gnus-group-mark-buffer
1753 Mark all groups in the buffer (@code{gnus-group-mark-buffer}).
1757 @findex gnus-group-mark-regexp
1758 Mark all groups that match some regular expression
1759 (@code{gnus-group-mark-regexp}).
1762 Also @xref{Process/Prefix}.
1764 If you want to execute some command on all groups that have been marked
1765 with the process mark, you can use the @kbd{M-&}
1766 (@code{gnus-group-universal-argument}) command. It will prompt you for
1767 the command to be executed.
1771 @node Foreign Groups
1772 @section Foreign Groups
1773 @cindex foreign groups
1775 A @dfn{foreign group} is a group that is not read by the usual (or
1776 default) means. It could be, for instance, a group from a different
1777 @sc{nntp} server, it could be a virtual group, or it could be your own
1778 personal mail group.
1780 A foreign group (or any group, really) is specified by a @dfn{name} and
1781 a @dfn{select method}. To take the latter first, a select method is a
1782 list where the first element says what backend to use (eg. @code{nntp},
1783 @code{nnspool}, @code{nnml}) and the second element is the @dfn{server
1784 name}. There may be additional elements in the select method, where the
1785 value may have special meaning for the backend in question.
1787 One could say that a select method defines a @dfn{virtual server}---so
1788 we do just that (@pxref{The Server Buffer}).
1790 The @dfn{name} of the group is the name the backend will recognize the
1793 For instance, the group @samp{soc.motss} on the @sc{nntp} server
1794 @samp{some.where.edu} will have the name @samp{soc.motss} and select
1795 method @code{(nntp "some.where.edu")}. Gnus will call this group, in
1796 all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
1797 @code{nntp} backend just knows this group as @samp{soc.motss}.
1799 Here are some commands for making and editing general foreign groups,
1800 and some commands to ease the creation of some special-purpose groups:
1806 @findex gnus-group-make-group
1807 Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
1808 for a name, a method and possibly an @dfn{address}. For an easier way
1809 to subscribe to @sc{nntp} groups, @xref{Browse Foreign Server}.
1813 @findex gnus-group-rename-group
1814 Rename the current group to something else
1815 (@code{gnus-group-rename-group}). This is legal only on some groups --
1816 mail groups mostly. This command might very well be quite slow on some
1821 @findex gnus-group-edit-group-method
1822 Enter a buffer where you can edit the select method of the current
1823 group (@code{gnus-group-edit-group-method}).
1827 @findex gnus-group-edit-group-parameters
1828 Enter a buffer where you can edit the group parameters
1829 (@code{gnus-group-edit-group-parameters}).
1833 @findex gnus-group-edit-group
1834 Enter a buffer where you can edit the group info
1835 (@code{gnus-group-edit-group}).
1839 @findex gnus-group-make-directory-group
1840 Make a directory group. You will be prompted for a directory name
1841 (@code{gnus-group-make-directory-group}).
1845 @findex gnus-group-make-help-group
1846 Make the Gnus help group (@code{gnus-group-make-help-group}).
1850 @findex gnus-group-make-archive-group
1851 @vindex gnus-group-archive-directory
1852 @vindex gnus-group-recent-archive-directory
1853 Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
1854 default a group pointing to the most recent articles will be created
1855 (@code{gnus-group-recent-archibe-directory}), but given a prefix, a full
1856 group will be created from from @code{gnus-group-archive-directory}.
1860 @findex gnus-group-make-kiboze-group
1861 Make a kiboze group. You will be prompted for a name, for a regexp to
1862 match groups to be "included" in the kiboze group, and a series of
1863 strings to match on headers (@code{gnus-group-make-kiboze-group}).
1867 @findex gnus-group-enter-directory
1868 Read a random directory as if with were a newsgroup with the
1869 @code{nneething} backend (@code{gnus-group-enter-directory}).
1873 @findex gnus-group-make-doc-group
1874 Make a group based on some file or other
1875 (@code{gnus-group-make-doc-group}). If you give a prefix to this
1876 command, you will be prompted for a file name and a file type.
1877 Currently supported types are @code{babyl}, @code{mbox}, @code{digest},
1878 @code{mmdf}, @code{news}, @code{rnews}, @code{clari-briefs}, and
1879 @code{forward}. If you run this command without a prefix, Gnus will
1880 guess at the file type.
1883 @kindex G DEL (Group)
1884 @findex gnus-group-delete-group
1885 This function will delete the current group
1886 (@code{gnus-group-delete-group}). If given a prefix, this function will
1887 actually delete all the articles in the group, and forcibly remove the
1888 group itself from the face of the Earth. Use a prefix only if you are
1889 sure of what you are doing.
1893 @findex gnus-group-make-empty-virtual
1894 Make a new, fresh, empty @code{nnvirtual} group
1895 (@code{gnus-group-make-empty-virtual}).
1899 @findex gnus-group-add-to-virtual
1900 Add the current group to an @code{nnvirtual} group
1901 (@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
1904 The different methods all have their peculiarities, of course.
1907 * nntp:: Reading news from a different @sc{nntp} server.
1908 * nnspool:: Reading news from the local spool.
1909 * nnvirtual:: Combining articles from many groups.
1910 * nnkiboze:: Looking through parts of the newsfeed for articles.
1911 * nndir:: You can read a directory as if it was a newsgroup.
1912 * nneething:: Dired? Who needs dired?
1913 * nndoc:: Single files can be the basis of a group.
1914 * SOUP:: Reading @sc{SOUP} packets "offline".
1915 * Reading Mail:: Reading your personal mail with Gnus.
1918 @vindex gnus-activate-foreign-newsgroups
1919 If the @code{gnus-activate-foreign-newsgroups} is a positive number,
1920 Gnus will check all foreign groups with this level or lower at startup.
1921 This might take quite a while, especially if you subscribe to lots of
1922 groups from different @sc{nntp} servers.
1928 Subscribing to a foreign group from an @sc{nntp} server is rather easy.
1929 You just specify @code{nntp} as method and the address of the @sc{nntp}
1930 server as the, uhm, address.
1932 If the @sc{nntp} server is located at a non-standard port, setting the
1933 third element of the select method to this port number should allow you
1934 to connect to the right port. You'll have to edit the group info for
1935 that (@pxref{Foreign Groups}).
1937 The name of the foreign group can be the same as a native group. In
1938 fact, you can subscribe to the same group from as many different servers
1939 you feel like. There will be no name collisions.
1941 The following variables can be used to create a virtual @code{nntp}
1946 @item nntp-server-opened-hook
1947 @vindex nntp-server-opened-hook
1948 @cindex @sc{mode reader}
1950 @cindex authentification
1951 @cindex nntp authentification
1952 @findex nntp-send-authinfo
1953 @findex nntp-send-mode-reader
1954 @code{nntp-server-opened-hook} is run after a connection has been made.
1955 It can be used to send commands to the @sc{nntp} server after it has
1956 been contacted. By default is sends the command @samp{MODE READER} to
1957 the server with the @code{nntp-send-mode-reader} function. Another
1958 popular function is @code{nntp-send-authinfo}, which will prompt you for
1959 an @sc{nntp} password and stuff.
1961 @item nntp-server-action-alist
1962 @vindex nntp-server-action-alist
1963 This is an list of regexps to match on server types and actions to be
1964 taken when matches are made. For instance, if you want Gnus to beep
1965 every time you connect to innd, you could say something like:
1968 (setq nntp-server-action-alist
1972 You probably don't want to do that, though.
1974 The default value is
1977 '(("nntpd 1\\.5\\.11t"
1978 (remove-hook 'nntp-server-opened-hook nntp-send-mode-reader)))
1981 This ensures that Gnus doesn't send the @samp{MODE READER} command to
1982 nntpd 1.5.11t, since that command chokes that server, I've been told.
1984 @item nntp-maximum-request
1985 @vindex nntp-maximum-request
1986 If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
1987 will collect headers by sending a series of @code{head} commands. To
1988 speed things up, the backend sends lots of these commands without
1989 waiting for reply, and then reads all the replies. This is controlled
1990 by the @code{nntp-maximum-request} variable, and is 400 by default. If
1991 your network is buggy, you should set this to 1.
1993 @item nntp-connection-timeout
1994 @vindex nntp-connection-timeout
1995 If you have lots of foreign @code{nntp} groups that you connect to
1996 regularly, you're sure to have problems with @sc{nntp} servers not
1997 responding properly, or being too loaded to reply within reasonable
1998 time. This is can lead to awkward problems, which can be helped
1999 somewhat by setting @code{nntp-connection-timeout}. This is an integer
2000 that says how many seconds the @code{nntp} backend should wait for a
2001 connection before giving up. If it is @code{nil}, which is the default,
2002 no timeouts are done.
2004 @item nntp-server-hook
2005 @vindex nntp-server-hook
2006 This hook is run as the last step when connecting to an @sc{nntp}
2009 @c @findex nntp-open-rlogin
2010 @c @findex nntp-open-network-stream
2011 @c @item nntp-open-server-function
2012 @c @vindex nntp-open-server-function
2013 @c This function is used to connect to the remote system. Two pre-made
2014 @c functions are @code{nntp-open-network-stream}, which is the default, and
2015 @c simply connects to some port or other on the remote system. The other
2016 @c is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
2017 @c and then does a telnet to the @sc{nntp} server available there.
2019 @c @item nntp-rlogin-parameters
2020 @c @vindex nntp-rlogin-parameters
2021 @c If you use @code{nntp-open-rlogin} as the
2022 @c @code{nntp-open-server-function}, this list will be used as the
2023 @c parameter list given to @code{rsh}.
2025 @c @item nntp-rlogin-user-name
2026 @c @vindex nntp-rlogin-user-name
2027 @c User name on the remote system when using the @code{rlogin} connect
2031 @vindex nntp-address
2032 The address of the remote system running the @sc{nntp} server.
2034 @item nntp-port-number
2035 @vindex nntp-port-number
2036 Port number to connect to when using the @code{nntp-open-network-stream}
2039 @item nntp-buggy-select
2040 @vindex nntp-buggy-select
2041 Set this to non-@code{nil} if your select routine is buggy.
2043 @item nntp-nov-is-evil
2044 @vindex nntp-nov-is-evil
2045 If the @sc{nntp} server does not support @sc{nov}, you could set this
2046 variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
2047 can be used automatically.
2049 @item nntp-xover-commands
2050 @vindex nntp-xover-commands
2051 List of strings that are used as commands to fetch @sc{nov} lines from a
2052 server. The default value of this variable is @code{("XOVER"
2056 @vindex nntp-nov-gap
2057 @code{nntp} normally sends just one big request for @sc{nov} lines to
2058 the server. The server responds with one huge list of lines. However,
2059 if you have read articles 2-5000 in the group, and only want to read
2060 article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
2061 lines that you do not want, and will not use. This variable says how
2062 big a gap between two consecutive articles is allowed to be before the
2063 @code{XOVER} request is split into several request. Note that if your
2064 network is fast, setting this variable to a really small number means
2065 that fetching will probably be slower. If this variable is @code{nil},
2066 @code{nntp} will never split requests.
2068 @item nntp-prepare-server-hook
2069 @vindex nntp-prepare-server-hook
2070 A hook run before attempting to connect to an @sc{nntp} server.
2072 @item nntp-async-number
2073 @vindex nntp-async-number
2074 How many articles should be pre-fetched when in asynchronous mode. If
2075 this variable is @code{t}, @code{nntp} will pre-fetch all the articles
2076 that it can without bound. If it is @code{nil}, no pre-fetching will be
2079 @item nntp-warn-about-losing-connection
2080 @vindex nntp-warn-about-losing-connection
2081 If this variable is non-@code{nil}, some noise will be made when a
2082 server closes connection.
2089 @cindex @code{nnspool}
2092 Subscribing to a foreign group from the local spool is extremely easy,
2093 and might be useful, for instance, to speed up reading groups like
2094 @samp{alt.binaries.pictures.furniture}.
2096 Anyways, you just specify @code{nnspool} as the method and @samp{""} (or
2097 anything else) as the address.
2099 If you have access to a local spool, you should probably use that as the
2100 native select method (@pxref{Finding the News}). It is normally faster
2101 than using an @code{nntp} select method, but might not be. It depends.
2102 You just have to try to find out what's best at your site.
2106 @item nnspool-inews-program
2107 @vindex nnspool-inews-program
2108 Program used to post an article.
2110 @item nnspool-inews-switches
2111 @vindex nnspool-inews-switches
2112 Parameters given to the inews program when posting an article.
2114 @item nnspool-spool-directory
2115 @vindex nnspool-spool-directory
2116 Where @code{nnspool} looks for the articles. This is normally
2117 @file{/usr/spool/news/}.
2119 @item nnspool-nov-directory
2120 @vindex nnspool-nov-directory
2121 Where @code{nnspool} will look for @sc{nov} files. This is normally
2122 @file{/usr/spool/news/over.view/}.
2124 @item nnspool-lib-dir
2125 @vindex nnspool-lib-dir
2126 Where the news lib dir is (@file{/usr/lib/news/} by default).
2128 @item nnspool-active-file
2129 @vindex nnspool-active-file
2130 The path of the active file.
2132 @item nnspool-newsgroups-file
2133 @vindex nnspool-newsgroups-file
2134 The path of the group descriptions file.
2136 @item nnspool-history-file
2137 @vindex nnspool-history-file
2138 The path of the news history file.
2140 @item nnspool-active-times-file
2141 @vindex nnspool-active-times-file
2142 The path of the active date file.
2144 @item nnspool-nov-is-evil
2145 @vindex nnspool-nov-is-evil
2146 If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
2149 @item nnspool-sift-nov-with-sed
2150 @vindex nnspool-sift-nov-with-sed
2151 If non-@code{nil}, which is the default, use @code{sed} to get the
2152 relevant portion from the overview file. If nil, @code{nnspool} will
2153 load the entire file into a buffer and process it there.
2159 @subsection nnvirtual
2160 @cindex @code{nnvirtual}
2161 @cindex virtual groups
2163 An @dfn{nnvirtual group} is really nothing more than a collection of
2166 For instance, if you are tired of reading many small group, you can
2167 put them all in one big group, and then grow tired of reading one
2168 big, unwieldy group. The joys of computing!
2170 You specify @code{nnvirtual} as the method. The address should be a
2171 regexp to match component groups.
2173 All marks in the virtual group will stick to the articles in the
2174 component groups. So if you tick an article in a virtual group, the
2175 article will also be ticked in the component group from whence it came.
2176 (And vice versa---marks from the component groups will also be shown in
2179 Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
2180 newsgroups into one, big, happy newsgroup:
2183 (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
2186 The component groups can be native or foreign; everything should work
2187 smoothly, but if your computer explodes, it was probably my fault.
2189 Collecting the same group from several servers might actually be a good
2190 idea if users have set the Distribution header to limit distribution.
2191 If you would like to read @samp{soc.motss} both from a server in Japan
2192 and a server in Norway, you could use the following as the group regexp:
2195 "^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
2198 This should work kinda smoothly---all articles from both groups should
2199 end up in this one, and there should be no duplicates. Threading (and
2200 the rest) will still work as usual, but there might be problems with the
2201 sequence of articles. Sorting on date might be an option here
2202 (@pxref{Selecting a Group}.
2204 One limitation, however---all groups that are included in a virtual
2205 group has to be alive (i.e., subscribed or unsubscribed). Killed or
2206 zombie groups can't be component groups for @code{nnvirtual} groups.
2208 @vindex nnvirtual-always-rescan
2209 If the @code{nnvirtual-always-rescan} is non-@code{nil},
2210 @code{nnvirtual} will always scan groups for unread articles when
2211 entering a virtual group. If this variable is @code{nil} (which is the
2212 default) and you read articles in a component group after the virtual
2213 group has been activated, the read articles from the component group
2214 will show up when you enter the virtual group. You'll also see this
2215 effect if you have two virtual groups that contain the same component
2216 group. If that's the case, you should set this variable to @code{t}.
2217 Or you can just tap @code{M-g} on the virtual group every time before
2218 you enter it---it'll have much the same effect.
2222 @subsection nnkiboze
2223 @cindex @code{nnkiboze}
2226 @dfn{Kibozing} is defined by @sc{oed} as "grepping through (parts of)
2227 the news feed". @code{nnkiboze} is a backend that will do this for you. Oh
2228 joy! Now you can grind any @sc{nntp} server down to a halt with useless
2229 requests! Oh happiness!
2231 The address field of the @code{nnkiboze} method is, as with
2232 @code{nnvirtual}, a regexp to match groups to be "included" in the
2233 @code{nnkiboze} group. There most similarities between @code{nnkiboze}
2234 and @code{nnvirtual} ends.
2236 In addition to this regexp detailing component groups, an @code{nnkiboze} group
2237 must have a score file to say what articles that are to be included in
2238 the group (@pxref{Scoring}).
2240 @kindex M-x nnkiboze-generate-groups
2241 @findex nnkiboze-generate-groups
2242 You must run @kbd{M-x nnkiboze-generate-groups} after creating the
2243 @code{nnkiboze} groups you want to have. This command will take time. Lots of
2244 time. Oodles and oodles of time. Gnus has to fetch the headers from
2245 all the articles in all the components groups and run them through the
2246 scoring process to determine if there are any articles in the groups
2247 that are to be part of the @code{nnkiboze} groups.
2249 Please limit the number of component groups by using restrictive
2250 regexps. Otherwise your sysadmin may become annoyed with you, and the
2251 @sc{nntp} site may throw you off and never let you back in again.
2252 Stranger things have happened.
2254 @code{nnkiboze} component groups do not have to be alive---they can be dead,
2255 and they can be foreign. No restrictions.
2257 @vindex nnkiboze-directory
2258 The generation of an @code{nnkiboze} group means writing two files in
2259 @code{nnkiboze-directory}, which is @file{~/News/} by default. One
2260 contains the @sc{nov} header lines for all the articles in the group,
2261 and the other is an additional @file{.newsrc} file to store information
2262 on what groups that have been searched through to find component
2265 Articles that are marked as read in the @code{nnkiboze} group will have their
2266 @sc{nov} lines removed from the @sc{nov} file.
2271 @cindex @code{nndir}
2272 @cindex directory groups
2274 If you have a directory that has lots of articles in separate files in
2275 it, you might treat it as a newsgroup. The files have to have numerical
2278 This might be an opportune moment to mention @code{ange-ftp}, that most
2279 wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
2280 didn't think much about it---a backend to read directories. Big deal.
2282 @code{ange-ftp} changes that picture dramatically. For instance, if you
2283 enter @file{"/ftp@@sina.tcamc.uh.edu:/pub/emacs/ding-list/"} as the the
2284 directory name, ange-ftp will actually allow you to read this directory
2285 over at @samp{sina} as a newsgroup. Distributed news ahoy!
2287 @code{nndir} will use @sc{nov} files if they are present.
2289 @code{nndir} is a "read-only" backend---you can't delete or expire
2290 articles with this method. You can use @code{nnmh} or @code{nnml} for
2291 whatever you use @code{nndir} for, so you could switch to any of those
2292 methods if you feel the need to have a non-read-only @code{nndir}.
2296 @subsection nneething
2297 @cindex @code{nneething}
2299 From the @code{nndir} backend (which reads a single spool-like
2300 directory), it's just a hop and a skip to @code{nneething}, which
2301 pretends that any random directory is a newsgroup. Strange, but true.
2303 When @code{nneething} is presented with a directory, it will scan this
2304 directory and assign article numbers to each file. When you enter such a
2305 group, @code{nneething} must create "headers" that Gnus can use. After
2306 all, Gnus is a newsreader, in case you're forgetting. @code{nneething}
2307 does this in a two-step process. First, it snoops each file in question.
2308 If the file looks like an article (i.e., the first few lines look like
2309 headers), it will use this as the head. If this is just some random file
2310 without a head (eg. a C source file), @code{nneething} will cobble up a
2311 header out of thin air. It will use file ownership, name and date and do
2312 whatever it can with these elements.
2314 All this should happen automatically for you, and you will be presented
2315 with something that looks very much like a newsgroup. Totally like a
2316 newsgroup, to be precise. If you select an article, it will be displayed
2317 in the article buffer, just as usual.
2319 If you select a line that represents a directory, Gnus will pop you into
2320 a new summary buffer for this @code{nneething} group. And so on. You can
2321 traverse the entire disk this way, if you feel like, but remember that
2322 Gnus is not dired, really, and does not intend to be, either.
2324 There are two overall modes to this action---ephemeral or solid. When
2325 doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
2326 will not store information on what files you have read, and what files
2327 are new, and so on. If you create a solid @code{nneething} group the
2328 normal way with @kbd{G m}, Gnus will store a mapping table between
2329 article numbers and file names, and you can treat this group like any
2330 other groups. When you activate a solid @code{nneething} group, you will
2331 be told how many unread articles it contains, etc., etc.
2336 @item nneething-map-file-directory
2337 @vindex nneething-map-file-directory
2338 All the mapping files for solid @code{nneething} groups will be stored
2339 in this directory, which defaults to @file{~/.nneething/}.
2341 @item nneething-exclude-files
2342 @vindex nneething-exclude-files
2343 All files that match this regexp will be ignored. Nice to use to exclude
2344 auto-save files and the like, which is what it does by default.
2346 @item nneething-map-file
2347 @vindex nneething-map-file
2348 Name of the map files.
2354 @cindex @code{nndoc}
2355 @cindex documentation group
2358 @code{nndoc} is a cute little thing that will let you read a single file
2359 as a newsgroup. Several files types are supported:
2366 The babyl (rmail) mail box.
2371 The standard Unix mbox file.
2373 @cindex MMDF mail box
2375 The MMDF mail box format.
2378 Several news articles appended into a file.
2381 @cindex rnews batch files
2382 The rnews batch transport format.
2383 @cindex forwarded messages
2392 @cindex RFC 1153 digest
2393 @cindex RFC 341 digest
2394 MIME (RFC 1341) digest format.
2396 @item standard-digest
2397 The standard (RFC 1153) digest format.
2400 Non-standard digest format---matches most things, but does it badly.
2403 You can also use the special "file type" @code{guess}, which means that
2404 @code{nndoc} will try to guess what file type it is looking at.
2405 @code{digest} means that @code{nndoc} should guess what digest type the
2408 @code{nndoc} will not try to change the file or insert any extra headers into
2409 it---it will simply, like, let you use the file as the basis for a
2410 group. And that's it.
2412 If you have some old archived articles that you want to insert into your
2413 new & spiffy Gnus mail backend, @code{nndoc} can probably help you with
2414 that. Say you have an old @file{RMAIL} file with mail that you now want
2415 to split into your new @code{nnml} groups. You look at that file using
2416 @code{nndoc}, set the process mark on all the articles in the buffer
2417 (@kbd{M P b}, for instance), and then respool (@kbd{B r}) using
2418 @code{nnml}. If all goes well, all the mail in the @file{RMAIL} file is
2419 now also stored in lots of @code{nnml} directories, and you can delete
2420 that pesky @file{RMAIL} file. If you have the guts!
2422 Virtual server variables:
2425 @item nndoc-article-type
2426 @vindex nndoc-article-type
2427 This should be one of @code{mbox}, @code{babyl}, @code{digest},
2428 @code{mmdf}, @code{forward}, @code{news}, @code{rnews},
2429 @code{mime-difest}, @code{clari-briefs}, or @code{guess}.
2431 @item nndoc-post-type
2432 @vindex nndoc-post-type
2433 This variable says whether Gnus is to consider the group a news group or
2434 a mail group. There are two legal values: @code{mail} (the default)
2440 @subsection @sc{soup}
2444 In the PC world people often talk about "offline" newsreaders. These
2445 are thingies that are combined reader/news transport monstrosities.
2446 With built-in modem programs. Yecchh!
2448 Of course, us Unix Weenie types of human beans use things like
2449 @code{uucp} and, like, @code{nntpd} and set up proper news and mail
2450 transport things like Ghod inteded. And then we just use normal
2453 However, it can sometimes be convenient to do something a that's a bit
2454 easier on the brain if you have a very slow modem, and you're not really
2455 that interested in doing things properly.
2457 A file format called @sc{soup} has been developed for transporting news
2458 and mail from servers to home machines and back again. It can be a bit
2464 You log in on the server and create a @sc{soup} packet. You can either
2465 use a dedicated @sc{soup} thingie, or you can use Gnus to create the
2466 packet with the @kbd{O s} command.
2469 You transfer the packet home. Rail, boat, car or modem will do fine.
2472 You put the packet in your home directory.
2475 You fire up Gnus using the @code{nnsoup} backend as the native server.
2478 You read articles and mail and answer and followup to the things you
2482 You do the @kbd{G s r} command to pack these replies into a @sc{soup}
2486 You transfer this packet to the server.
2489 You use Gnus to mail this packet out with the @kbd{G s s} command.
2492 You then repeat until you die.
2496 So you basically have a bipartite system---you use @code{nnsoup} for
2497 reading and Gnus for packing/sending these @sc{soup} packets.
2500 * SOUP Commands:: Commands for creating and sending @sc{soup} packets
2501 * nnsoup:: A backend for reading @sc{soup} packets.
2502 * SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
2507 @subsubsection @sc{soup} Commands
2511 @kindex G s b (Group)
2512 @findex gnus-group-brew-soup
2513 Pack all unread articles in the current group
2514 (@code{gnus-group-brew-soup}). This command understands the
2515 process/prefix convention.
2518 @kindex G s w (Group)
2519 @findex gnus-soup-save-areas
2520 Save all data files (@code{gnus-soup-save-areas}).
2523 @kindex G s s (Group)
2524 @findex gnus-soup-send-replies
2525 Send all replies from the replies packet
2526 (@code{gnus-soup-send-replies}).
2529 @kindex G s p (Group)
2530 @findex gnus-soup-pack-packet
2531 Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
2534 @kindex G s r (Group)
2535 @findex nnsoup-pack-replies
2536 Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
2539 @kindex O s (Summary)
2540 @findex gnus-soup-add-article
2541 This summary-mode command adds the current article to a @sc{soup} packet
2542 (@code{gnus-soup-add-article}). It understands the process/prefix
2548 There are a few variables to customize where Gnus will put all these
2553 @item gnus-soup-directory
2554 @vindex gnus-soup-directory
2555 Directory where Gnus will save intermediate files while composing
2556 @sc{soup} packets. The default is @file{~/SoupBrew/}.
2558 @item gnus-soup-replies-directory
2559 @vindex gnus-soup-replies-directory
2560 This is what Gnus will use as a temporary directory while sending our
2561 reply packets. The default is @file{~/SoupBrew/SoupReplies/}.
2563 @item gnus-soup-prefix-file
2564 @vindex gnus-soup-prefix-file
2565 Name of the file where Gnus stores the last used prefix. The default is
2566 @samp{"gnus-prefix"}.
2568 @item gnus-soup-packer
2569 @vindex gnus-soup-packer
2570 A format string command for packing a @sc{soup} packet. The default is
2571 @samp{ "tar cf - %s | gzip > $HOME/Soupout%d.tgz"}.
2573 @item gnus-soup-unpacker
2574 @vindex gnus-soup-unpacker
2575 Format string command for unpacking a @sc{soup} packet. The default is
2576 @samp{"gunzip -c %s | tar xvf -"}.
2578 @item gnus-soup-packet-directory
2579 @vindex gnus-soup-packet-directory
2580 Wehre Gnus will look for reply packets. The default is @file{~/}.
2582 @item gnus-soup-packet-regexp
2583 @vindex gnus-soup-packet-regexp
2584 Regular expression matching @sc{soup} reply packets in
2585 @code{gnus-soup-packet-directory}.
2591 @subsubsection nnsoup
2592 @cindex @code{nnsoup}
2594 @code{nnsoup} is the backend for reading @sc{soup} packets. It will
2595 read incoming packets, unpack them, and put them in a directory where
2596 you can read them at leisure.
2598 These are the variables you can use to customize its behavior:
2602 @item nnsoup-directory
2603 @vindex nnsoup-directory
2604 @code{nnsoup} will move all incoming @sc{soup} packets to this directory
2605 and unpack them there. The default is @file{~/SOUP/}.
2607 @item nnsoup-replies-directory
2608 @vindex nnsoup-replies-directory
2609 All replies will stored in this directory before being packed into a
2610 reply packet. The default is @file{~/SOUP/replies/"}.
2612 @item nnsoup-replies-format-type
2613 @vindex nnsoup-replies-format-type
2614 The @sc{soup} format of the replies packets. The default is @samp{?n}
2615 (rnews), and I don't think you should touch that variable. I probaly
2616 shouldn't even have documented it. Drats! Too late!
2618 @item nnsoup-replies-index-type
2619 @vindex nnsoup-replies-index-type
2620 The index type of the replies packet. The is @samp{?n}, which means
2621 "none". Don't fiddle with this one either!
2623 @item nnsoup-active-file
2624 @vindex nnsoup-active-file
2625 Where @code{nnsoup} stores lots of information. This is not an "active
2626 file" in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
2627 this file or mess it up in any way, you're dead. The default is
2628 @file{~/SOUP/active}.
2631 @vindex nnsoup-packer
2632 Format string command for packing a reply @sc{soup} packet. The default
2633 is @samp{"tar cf - %s | gzip > $HOME/Soupin%d.tgz"}.
2635 @item nnsoup-unpacker
2636 @vindex nnsoup-unpacker
2637 Format string command for unpacking incoming @sc{soup} packets. The
2638 default is @samp{"gunzip -c %s | tar xvf -"}.
2640 @item nnsoup-packet-directory
2641 @vindex nnsoup-packet-directory
2642 Where @code{nnsoup} will look for incoming packets. The default is
2645 @item nnsoup-packet-regexp
2646 @vindex nnsoup-packet-regexp
2647 Regular expression matching incoming @sc{soup} packets. The default is
2654 @subsubsection @sc{SOUP} Replies
2656 Just using @code{nnsoup} won't mean that your postings and mailings end
2657 up in @sc{soup} reply packets automagically. You have to work a bit
2658 more for that to happen.
2660 @findex nnsoup-set-variables
2661 The @code{nnsoup-set-variables} command will set the appropriate
2662 variables to ensure that all your followups and replies end up in the
2665 In specific, this is what it does:
2668 (setq gnus-inews-article-function 'nnsoup-request-post)
2669 (setq send-mail-function 'nnsoup-request-mail)
2672 And that's it, really. If you only want news to go into the @sc{soup}
2673 system you just use the first line. If you only want mail to be
2674 @sc{soup}ed you use the second.
2678 @subsection Reading Mail
2679 @cindex reading mail
2682 Reading mail with a newsreader---isn't that just plain WeIrD? But of
2685 Gnus will read the mail spool when you activate a mail group. The mail
2686 file is first copied to your home directory. What happens after that
2687 depends on what format you want to store your mail in.
2690 * Creating Mail Groups:: How to create mail groups.
2691 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
2692 * Mail & Procmail:: Reading mail groups that procmail create.
2693 * Expiring Old Mail Articles:: Getting rid of unwanted mail.
2694 * Not Reading Mail:: Using mail backends for reading other files.
2695 * nnmbox:: Using the (quite) standard Un*x mbox.
2696 * nnbabyl:: Emacs programs use the rmail babyl format.
2697 * nnml:: Store your mail in a private spool?
2698 * nnmh:: An mhspool-like backend.
2699 * nnfolder:: Having one file for each group.
2702 @vindex nnmail-read-incoming-hook
2703 The mail backends all call @code{nnmail-read-incoming-hook} after
2704 reading new mail. You can use this hook to notify any mail watch
2705 programs, if you want to.
2707 @vindex nnmail-spool-file
2710 @code{nnmail-spool-file} says where to look for new mail. If this
2711 variable is @code{nil}, the mail backends will never attempt to fetch
2712 mail by themselves. If you are using a POP mail server and your name is
2713 @samp{"larsi"}, you should set this variable to @samp{"po:larsi"}. If
2714 your name is not @samp{"larsi"}, you should probably modify that
2715 slightly, but you may have guessed that already, you smart & handsome
2716 devil! You can also set this variable to @code{pop}, and Gnus will try
2717 to figure out the POP mail string by itself. In any case, Gnus will
2718 call @code{movemail} which will contact the POP server named in the
2719 @samp{MAILHOST} environment variable.
2721 When you use a mail backend, Gnus will slurp all your mail from your
2722 inbox and plonk it down in your home directory. Gnus doesn't move any
2723 mail if you're not using a mail backend---you have to do a lot of magic
2724 invocations first. At the time when you have finished drawing the
2725 pentagram, lightened the candles, and sacrificed the goat, you really
2726 shouldn't be too suprised when Gnus moves your mail.
2728 @vindex nnmail-use-procmail
2729 If @code{nnmail-use-procmail} is non-@code{nil}, the mail backends will
2730 look in @code{nnmail-procmail-directory} for incoming mail. All the
2731 files in that directory that have names ending in
2732 @code{gnus-procmail-suffix} will be considered incoming mailboxes, and
2733 will be searched for new mail.
2735 @vindex nnmail-prepare-incoming-hook
2736 @code{nnmail-prepare-incoming-hook} is run in a buffer that holds all
2737 the new incoming mail, and can be used for, well, anything, really.
2739 @vindex nnmail-pre-get-new-mail-hook
2740 @vindex nnmail-post-get-new-mail-hook
2741 There are two more useful hooks executed when treating new incoming
2742 mail---@code{nnmail-pre-get-new-mail-hook} (which is called just before
2743 starting to handle the new mail) and
2744 @code{nnmail-post-get-new-mail-hook} (which is called when the mail
2745 handling is done). Here's and example of using these two hooks to
2746 change the default file modes the new mail files get:
2749 (add-hook 'gnus-pre-get-new-mail-hook
2750 (lambda () (set-default-file-modes 511)))
2752 (add-hook 'gnus-post-get-new-mail-hook
2753 (lambda () (set-default-file-modes 551)))
2756 @vindex nnmail-tmp-directory
2757 @code{nnmail-tmp-directory} says where to move the incoming mail to
2758 while processing it. This is usually done in the same directory that
2759 the mail backend inhabits (i.e., @file{~/Mail/}), but if this variable is
2760 non-@code{nil}, it will be used instead.
2762 @vindex nnmail-movemail-program
2763 @code{nnmail-movemail-program} is executed to move mail from the user's
2764 inbox to her home directory. The default is @samp{"movemail"}.
2766 @vindex nnmail-delete-incoming
2767 If @code{nnmail-delete-incoming} is non-@code{nil}, the mail backends
2768 will delete the temporary incoming file after splitting mail into the
2769 proper groups. This is @code{nil} by default for reasons of security.
2771 @vindex nnmail-use-long-file-names
2772 If @code{nnmail-use-long-file-names} is non-@code{nil} the mail backends
2773 will use long file and directory names. Groups like @samp{mail.misc}
2774 will end up in directories like @file{mail.misc/}. If it is @code{nil},
2775 the same group will end up in @file{mail/misc/}.
2777 @vindex nnmail-message-id-cache-length
2778 @vindex nnmail-message-id-cache-file
2779 @vindex nnmail-treat-duplicates
2780 @cindex duplicate mails
2781 If you are a member of a couple of mailing list, you will sometime
2782 receive two copies of the same mail. This can be quite annoying, so
2783 @code{nnmail} checks for and treats any duplicates it might find. To do
2784 this, it keeps a cache of old @code{Message-ID}s -
2785 @code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
2786 default. The approximate maximum number of @code{Message-ID}s stored
2787 there is controlled by the @code{nnmail-message-id-cache-length}
2788 variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
2789 stored.) If all this sounds scary to you, you can set
2790 @code{nnmail-delete-duplicates} to @code{warn} (which is what it is by
2791 default), and @code{nnmail} won't delete duplicate mails. Instead it
2792 will generate a brand new @code{Message-ID} for the mail and insert a
2793 warning into the head of the mail saying that it thinks that this is a
2794 duplicate of a different message.
2796 This variable can also be a function. If that's the case, the function
2797 will be called from a buffer narrowed to the message in question with
2798 the @code{Message-ID} as a parameter. The function must return either
2799 @code{nil}, @code{warn}, or @code{delete}.
2801 You can turn this feature off completely by setting the variable to
2804 Here's a neat feature: If you know that the recipient reads her mail
2805 with Gnus, and that she has @code{nnmail-treat-duplicates} set to
2806 @code{delete}, you can send her as many insults as you like, just by
2807 using a @code{Message-ID} of a mail that you know that she's already
2808 received. Think of all the fun! She'll never see any of it! Whee!
2810 Gnus gives you all the opportunity you could possibly want for shooting
2811 yourself in the foot. Let's say you create a group that will contain
2812 all the mail you get from your boss. And then you accidentally
2813 unsubscribe from the group. Gnus will still put all the mail from your
2814 boss in the unsubscribed group, and so, when your boss mails you "Have
2815 that report ready by Monday or you're fired!", you'll never see it and,
2816 come Tuesday, you'll still believe that you're gainfully employed while
2817 you really should be out collecting empty bottles to save up for next
2820 @node Creating Mail Groups
2821 @subsubsection Creating Mail Groups
2822 @cindex creating mail groups
2824 You can make Gnus read your personal, private, secret mail.
2826 You should first set @code{gnus-secondary-select-methods} to, for
2827 instance, @code{((nnmbox ""))}. When you start up Gnus, Gnus will ask
2828 this backend for what groups it carries (@samp{mail.misc} by default)
2829 and subscribe it the normal way. (Which means you may have to look for
2830 it among the zombie groups, I guess, all depending on your
2831 @code{gnus-subscribe-newsgroup-method} variable.)
2833 @vindex nnmail-split-methods
2834 Then you should set the variable @code{nnmail-split-methods} to specify
2835 how the incoming mail is to be split into groups.
2838 (setq nnmail-split-methods
2839 '(("mail.junk" "^From:.*Lars Ingebrigtsen")
2840 ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
2844 This variable is a list of lists, where the first element of each of
2845 these lists is the name of the mail group (they do not have to be called
2846 something beginning with @samp{mail}, by the way), and the second
2847 element is a regular expression used on the header of each mail to
2848 determine if it belongs in this mail group.
2850 The second element can also be a function. In that case, it will be
2851 called narrowed to the headers with the first element of the rule as the
2852 argument. It should return a non-@code{nil} value if it thinks that the
2853 mail belongs in that group.
2855 The last of these groups should always be a general one, and the regular
2856 expression should @emph{always} be @samp{""} so that it matches any
2857 mails that haven't been matched by any of the other regexps.
2859 If you like to tinker with this yourself, you can set this variable to a
2860 function of your choice. This function will be called without any
2861 arguments in a buffer narrowed to the headers of an incoming mail
2862 message. The function should return a list of groups names that it
2863 thinks should carry this mail message.
2865 Note that the mail backends are free to maul the poor, innocent
2866 incoming headers all they want to. They all add @code{Lines} headers;
2867 some add @code{X-Gnus-Group} headers; most rename the Unix mbox
2868 @code{From<SPC>} line to something else.
2870 @vindex nnmail-crosspost
2871 The mail backends all support cross-posting. If several regexps match,
2872 the mail will be "cross-posted" to all those groups.
2873 @code{nnmail-crosspost} says whether to use this mechanism or not. Note
2874 that no articles are crossposted to the general (@samp{""}) group.
2876 @vindex nnmail-crosspost-link-function
2879 @code{nnmh} and @code{nnml} makes crossposts by creating hard links to
2880 the crossposted articles. However, not all files systems support hard
2881 links. If that's the case for you, set
2882 @code{nnmail-crosspost-link-function} to @code{copy-file}. (This
2883 variable is @code{add-name-to-file} by default.)
2886 @node Fancy Mail Splitting
2887 @subsubsection Fancy Mail Splitting
2888 @cindex mail splitting
2889 @cindex fancy mail splitting
2891 @vindex nnmail-split-fancy
2892 @findex nnmail-split-fancy
2893 If the rather simple, standard method for specifying how to split mail
2894 doesn't allow you to do what you want, you can set
2895 @code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
2896 play with the @code{nnmail-split-fancy} variable.
2898 Let's look at an example value of this variable first:
2901 ;; Messages from the mailer daemon are not crossposted to any of
2902 ;; the ordinary groups. Warnings are put in a separate group
2903 ;; from real errors.
2904 (| ("from" mail (| ("subject" "warn.*" "mail.warning")
2906 ;; Non-error messages are crossposted to all relevant
2907 ;; groups, but we don't crosspost between the group for the
2908 ;; (ding) list and the group for other (ding) related mail.
2909 (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
2910 ("subject" "ding" "ding.misc"))
2911 ;; Other mailing lists...
2912 (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
2913 (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
2915 (any "larsi@@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
2916 ;; Unmatched mail goes to the catch all group.
2920 This variable has the format of a @dfn{split}. A split is a (possibly)
2921 recursive structure where each split may contain other splits. Here are
2922 the four possible split syntaxes:
2927 If the split is a string, that will be taken as a group name.
2929 @item (FIELD VALUE SPLIT)
2930 If the split is a list, and the first element is a string, then that
2931 means that if header FIELD (a regexp) contains VALUE (also a regexp),
2932 then store the message as specified by SPLIT.
2935 If the split is a list, and the first element is @code{|} (vertical
2936 bar), then process each SPLIT until one of them matches. A SPLIT is
2937 said to match if it will cause the mail message to be stored in one or
2941 If the split is a list, and the first element is @code{&}, then process
2942 all SPLITs in the list.
2945 In these splits, FIELD must match a complete field name. VALUE must
2946 match a complete word according to the fundamental mode syntax table.
2947 You can use @code{.*} in the regexps to match partial field names or
2950 @vindex nnmail-split-abbrev-alist
2951 FIELD and VALUE can also be lisp symbols, in that case they are expanded
2952 as specified by the variable @code{nnmail-split-abbrev-alist}. This is
2953 an alist of cons cells, where the car of the cells contains the key, and
2954 the cdr contains a string.
2956 @node Mail & Procmail
2957 @subsubsection Mail & Procmail
2960 Many people use @code{procmail} to split incoming mail into groups. If
2961 you do that, you should set @code{nnmail-spool-file} to @code{procmail}
2962 to ensure that the mail backends never ever try to fetch mail by
2965 This also means that you probably don't want to set
2966 @code{nnmail-split-methods} either, which has some, perhaps, unexpected
2969 When a mail backend is queried for what groups it carries, it replies
2970 with the contents of that variable, along with any groups it has figured
2971 out that it carries by other means. None of the backends (except
2972 @code{nnmh}) actually go out to the disk and check what groups actually
2973 exist. (It's not trivial to distinguish between what the user thinks is
2974 a basis for a newsgroup and what is just a plain old file or directory.)
2976 This means that you have to tell Gnus (and the backends) what groups
2979 Let's take the @code{nnmh} backend as an example.
2981 The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
2982 There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
2984 Go to the group buffer and type @kbd{G m}. When prompted, answer
2985 @samp{foo} for the name and @samp{nnmh} for the method. Repeat
2986 twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
2987 to include all your mail groups.
2989 That's it. You are now set to read your mail. An active file for this
2990 method will be created automatically.
2992 @vindex nnmail-procmail-suffix
2993 @vindex nnmail-procmail-directory
2994 If you use @code{nnfolder} or any other backend that store more than a
2995 single article in each file, you should never have procmail add mails to
2996 the file that Gnus sees. Instead, procmail should put all incoming mail
2997 in @code{nnmail-procmail-directory}. To arrive at the file name to put
2998 the incoming mail in, append @code{nnmail-procmail-suffix} to the group
2999 name. The mail backends will read the mail from these files.
3001 @vindex nnmail-resplit-incoming
3002 When Gnus reads a file called @file{mail.misc.spool}, this mail will be
3003 put in the @code{mail.misc}, as one would expect. However, if you want
3004 Gnus to split the mail the normal way, you could set
3005 @code{nnmail-resplit-incoming} to @code{t}.
3007 @vindex nnmail-keep-last-article
3008 If you use @code{procmail} to split things directory into an @code{nnmh}
3009 directory (which you shouldn't do), you should set
3010 @code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
3011 ever expiring the final article in a mail newsgroup. This is quite,
3015 @node Expiring Old Mail Articles
3016 @subsubsection Expiring Old Mail Articles
3017 @cindex article expiry
3019 Traditional mail readers have a tendency to remove mail articles when
3020 you mark them as read, in some way. Gnus takes a fundamentally
3021 different approach to mail reading.
3023 Gnus basically considers mail just to be news that has been received in
3024 a rather peculiar manner. It does not think that it has the power to
3025 actually change the mail, or delete any mail messages. If you enter a
3026 mail group, and mark articles as "read", or kill them in some other
3027 fashion, the mail articles will still exist on the system. I repeat:
3028 Gnus will not delete your old, read mail. Unless you ask it to, of
3031 To make Gnus get rid of your unwanted mail, you have to mark the
3032 articles as @dfn{expirable}. This does not mean that the articles will
3033 disappear right away, however. In general, a mail article will be
3034 deleted from your system if, 1) it is marked as expirable, AND 2) it is
3035 more than one week old. If you do not mark an article as expirable, it
3036 will remain on your system until hell freezes over. This bears
3037 repeating one more time, with some spurious capitalizations: IF you do
3038 NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
3040 @vindex gnus-auto-expirable-newsgroups
3041 You do not have to mark articles as expirable by hand. Groups that
3042 match the regular expression @code{gnus-auto-expirable-newsgroups} will
3043 have all articles that you read marked as expirable automatically. All
3044 articles that are marked as expirable have an @samp{E} in the first
3045 column in the summary buffer.
3047 Let's say you subscribe to a couple of mailing lists, and you want the
3048 articles you have read to disappear after a while:
3051 (setq gnus-auto-expirable-newsgroups
3052 "mail.nonsense-list\\|mail.nice-list")
3055 Another way to have auto-expiry happen is to have the element
3056 @code{auto-expire} in the select method of the group.
3058 @vindex nnmail-expiry-wait
3059 The @code{nnmail-expiry-wait} variable supplies the default time an
3060 expirable article has to live. The default is seven days.
3062 Gnus also supplies a function that lets you fine-tune how long articles
3063 are to live, based on what group they are in. Let's say you want to
3064 have one month expiry period in the @samp{mail.private} group, a one day
3065 expiry period in the @samp{mail.junk} group, and a six day expiry period
3069 (setq nnmail-expiry-wait-function
3071 (cond ((string= group "mail.private")
3073 ((string= group "mail.junk")
3075 ((string= group "important")
3081 The group names that this function is fed are "unadorned" group
3082 names---no @samp{"nnml:"} prefixes and the like.
3084 The @code{nnmail-expiry-wait} variable and
3085 @code{nnmail-expiry-wait-function} function can be either a number (not
3086 necessarily an integer) or the symbols @code{immediate} or
3089 You can also use the @code{expiry-wait} group parameter to selectively
3090 change the expiry period (@pxref{Group Parameters}).
3092 @vindex nnmail-keep-last-article
3093 If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
3094 expire the final article in a mail newsgroup. This is to make life
3095 easier for procmail users.
3097 @vindex gnus-total-expirable-newsgroups
3098 By the way, that line up there about Gnus never expiring non-expirable
3099 articles is a lie. If you put @code{total-expire} in the group
3100 parameters, articles will not be marked as expirable, but all read
3101 articles will be put through the expiry process. Use with extreme
3102 caution. Even more dangerous is the
3103 @code{gnus-total-expirable-newsgroups} variable. All groups that match
3104 this regexp will have all read articles put through the expiry process,
3105 which means that @emph{all} old mail articles in the groups in question
3106 will be deleted after a while. Use with extreme caution, and don't come
3107 crying to me when you discover that the regexp you used matched the
3108 wrong group and all your important mail has disappeared. Be a
3109 @emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
3113 @node Not Reading Mail
3114 @subsubsection Not Reading Mail
3116 If you start using any of the mail backends, they have the annoying
3117 habit of assuming that you want to read mail with them. This might not
3118 be unreasonable, but it might not be what you want.
3120 If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
3121 will ever attempt to read incoming mail, which should help.
3123 @vindex nnbabyl-get-new-mail
3124 @vindex nnmbox-get-new-mail
3125 @vindex nnml-get-new-mail
3126 @vindex nnmh-get-new-mail
3127 @vindex nnfolder-get-new-mail
3128 This might be too much, if, for instance, you are reading mail quite
3129 happily with @code{nnml} and just want to peek at some old @sc{rmail}
3130 file you have stashed away with @code{nnbabyl}. All backends have
3131 variables called backend-@code{get-new-mail}. If you want to disable
3132 the @code{nnbabyl} mail reading, you edit the virtual server for the
3133 group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
3135 All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
3136 narrowed to the article to be saved before saving it when reading
3140 @subsubsection nnmbox
3141 @cindex @code{nnmbox}
3142 @cindex unix mail box
3144 @vindex nnmbox-active-file
3145 @vindex nnmbox-mbox-file
3146 The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
3147 mail. @code{nnmbox} will add extra headers to each mail article to say
3148 which group it belongs in.
3150 Virtual server settings:
3153 @item nnmbox-mbox-file
3154 @vindex nnmbox-mbox-file
3155 The name of the mail box in the user's home directory.
3157 @item nnmbox-active-file
3158 @vindex nnmbox-active-file
3159 The name of the active file for the mail box.
3161 @item nnmbox-get-new-mail
3162 @vindex nnmbox-get-new-mail
3163 If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
3168 @subsubsection nnbabyl
3169 @cindex @code{nnbabyl}
3172 @vindex nnbabyl-active-file
3173 @vindex nnbabyl-mbox-file
3174 The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
3175 mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
3176 article to say which group it belongs in.
3178 Virtual server settings:
3181 @item nnbabyl-mbox-file
3182 @vindex nnbabyl-mbox-file
3183 The name of the rmail mbox file.
3185 @item nnbabyl-active-file
3186 @vindex nnbabyl-active-file
3187 The name of the active file for the rmail box.
3189 @item nnbabyl-get-new-mail
3190 @vindex nnbabyl-get-new-mail
3191 If non-@code{nil}, @code{nnbabyl} will read incoming mail.
3197 @cindex mail @sc{nov} spool
3199 The @dfn{nnml} spool mail format isn't compatible with any other known
3200 format. It should be used with some caution.
3202 @vindex nnml-directory
3203 If you use this backend, Gnus will split all incoming mail into files;
3204 one file for each mail, and put the articles into the correct
3205 directories under the directory specified by the @code{nnml-directory}
3206 variable. The default value is @file{~/Mail/}.
3208 You do not have to create any directories beforehand; Gnus will take
3211 If you have a strict limit as to how many files you are allowed to store
3212 in your account, you should not use this backend. As each mail gets its
3213 own file, you might very well occupy thousands of inodes within a few
3214 weeks. If this is no problem for you, and it isn't a problem for you
3215 having your friendly systems administrator walking around, madly,
3216 shouting "Who is eating all my inodes?! Who? Who!?!", then you should
3217 know that this is probably the fastest format to use. You do not have
3218 to trudge through a big mbox file just to read your new mail.
3220 @code{nnml} is probably the slowest backend when it comes to article
3221 splitting. It has to create lots of files, and it also generates
3222 @sc{nov} databases for the incoming mails. This makes is the fastest
3223 backend when it comes to reading mail.
3225 Virtual server settings:
3228 @item nnml-directory
3229 @vindex nnml-directory
3230 All @code{nnml} directories will be placed under this directory.
3232 @item nnml-active-file
3233 @vindex nnml-active-file
3234 The active file for the @code{nnml} server.
3236 @item nnml-newsgroups-file
3237 @vindex nnml-newsgroups-file
3238 The @code{nnml} group descriptions file. @xref{Newsgroups File
3241 @item nnml-get-new-mail
3242 @vindex nnml-get-new-mail
3243 If non-@code{nil}, @code{nnml} will read incoming mail.
3245 @item nnml-nov-is-evil
3246 @vindex nnml-nov-is-evil
3247 If non-@code{nil}, this backend will ignore any @sc{nov} files.
3249 @item nnml-nov-file-name
3250 @vindex nnml-nov-file-name
3251 The name of the @sc{nov} files. The default is @file{.overview}.
3255 @findex nnml-generate-nov-databases
3256 If your @code{nnml} groups and @sc{nov} files get totally out of whack,
3257 you can do a complete update by typing @kbd{M-x
3258 nnml-generate-nov-databases}. This command will trawl through the
3259 entire @code{nnml} hierarchy, looking at each and every article, so it
3260 might take a while to complete.
3265 @cindex mh-e mail spool
3267 @code{nnmh} is just like @code{nnml}, except that is doesn't generate
3268 @sc{nov} databases and it doesn't keep an active file. This makes
3269 @code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
3270 makes it easier to write procmail scripts for.
3272 Virtual server settings:
3275 @item nnmh-directory
3276 @vindex nnmh-directory
3277 All @code{nnmh} directories will be located under this directory.
3279 @item nnmh-get-new-mail
3280 @vindex nnmh-get-new-mail
3281 If non-@code{nil}, @code{nnmh} will read incoming mail.
3284 @vindex nnmh-be-safe
3285 If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
3286 sure that the articles in the folder are actually what Gnus thinks they
3287 are. It will check date stamps and stat everything in sight, so
3288 setting this to @code{t} will mean a serious slow-down. If you never
3289 use anything but Gnus to read the @code{nnmh} articles, you do not have
3290 to set this variable to @code{t}.
3295 @subsubsection nnfolder
3296 @cindex @code{nnfolder}
3297 @cindex mbox folders
3299 @code{nnfolder} is a backend for storing each mail group in a separate
3300 file. Each file is in the standard Un*x mbox format. @code{nnfolder}
3301 will add extra headers to keep track of article numbers and arrival
3304 Virtual server settings:
3307 @item nnfolder-directory
3308 @vindex nnfolder-directory
3309 All the @code{nnfolder} mail boxes will be stored under this directory.
3311 @item nnfolder-active-file
3312 @vindex nnfolder-active-file
3313 The name of the active file.
3315 @item nnfolder-newsgroups-file
3316 @vindex nnfolder-newsgroups-file
3317 The name of the group descriptions file. @xref{Newsgroups File Format}.
3319 @item nnfolder-get-new-mail
3320 @vindex nnfolder-get-new-mail
3321 If non-@code{nil}, @code{nnfolder} will read incoming mail.
3324 @findex nnfolder-generate-active-file
3325 @kindex M-x nnfolder-generate-active-file
3326 If you have lots of @code{nnfolder}-like files you'd like to read with
3327 @code{nnfolder}, you can use the @key{M-x nnfolder-generate-active-file}
3328 command to make @code{nnfolder} aware of all likely files in
3329 @code{nnfolder-directory}.
3332 @node Group Parameters
3333 @section Group Parameters
3334 @cindex group parameters
3336 Gnus stores all information on a group in a list that is usually known
3337 as the @dfn{group info}. This list has from three to six elements.
3338 Here's an example info.
3341 ("nnml:mail.ding" 3 ((1 . 232) 244 (256 . 270)) ((tick 246 249))
3342 (nnml "private") ((to-address . "ding@@ifi.uio.no")))
3345 The first element is the @dfn{group name}, as Gnus knows the group,
3346 anyway. The second element is the @dfn{subscription level}, which
3347 normally is a small integer. The third element is a list of ranges of
3348 read articles. The fourth element is a list of lists of article marks
3349 of various kinds. The fifth element is the select method (or virtual
3350 server, if you like). The sixth element is a list of @dfn{group
3351 parameters}, which is what this section is about.
3353 Any of the last three elements may be missing if they are not required.
3354 In fact, the vast majority of groups will normally only have the first
3355 three elements, which saves quite a lot of cons cells.
3357 The group parameters store information local to a particular group:
3362 If the group parameter list contains an element that looks like
3363 @samp{(to-address . "some@@where.com")}, that address will be used by
3364 the backend when doing followups and posts. This is primarily useful in
3365 mail groups that represent closed mailing lists---mailing lists where
3366 it's expected that everybody that writes to the mailing list is
3367 subscribed to it. Since using this parameter ensures that the mail only
3368 goes to the mailing list itself, it means that members won't receive two
3369 copies of your followups.
3371 Using @code{to-address} will actually work whether the group is foreign
3372 or not. Let's say there's a group on the server that is called
3373 @samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten
3374 the articles from a mail-to-news gateway. Posting directly to this
3375 group is therefore impossible---you have to send mail to the mailing
3376 list address instead. Also @xref{Mail & Post}.
3380 If the group parameter list has an element that looks like
3381 @code{(to-list . "some@@where.com")}, that address will be used when
3382 doing a @kbd{a} in any group. It is totally ignored when doing a
3383 followup---except that if it is present in a news group, you'll get mail
3384 group semantics when doing @kbd{f}.
3386 @item broken-reply-to
3387 @cindex broken-reply-to
3388 Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To}
3389 headers in this group are to be ignored. This can be useful if you're
3390 reading a mailing list group where the listserv has inserted
3391 @code{Reply-To} headers that point back to the listserv itself. This is
3392 broken behavior. So there!
3396 If the group parameter list contains an element like @code{(to-group
3397 . "some.group.name")}, all posts will be sent to that group.
3401 If this symbol is present in the group parameter list, all articles that
3402 are read will be marked as expirable. For an alternative approach,
3403 @xref{Expiring Old Mail Articles}.
3406 @cindex total-expire
3407 If this symbol is present, all read articles will be put through the
3408 expiry process, even if they are not marked as expirable. Use with
3413 If the group parameter has an element that looks like @samp{(expiry-wait
3414 . 10)}, this value will override any @code{nnmail-expiry-wait} and
3415 @code{nnmail-expiry-wait-functions} when expiring expirable messages.
3416 The value can either be a number of days (not necessarily an integer) or
3417 the symbols @code{never} or @code{immediate}.
3420 Elements that look like @samp{(score-file . "file")} will make
3421 @samp{file} into the current score file for the group in question. This
3422 means that all score commands you issue will end up in that file.
3425 When unsubscribing to a mailing list you should never send the
3426 unsubscription notice to the mailing list itself. Instead, you'd send
3427 messages to the administrative address. This parameter allows you to
3428 put the admin address somewhere convenient.
3431 This parameter allows you to enter a random comment on the group.
3433 @item @var{(variable form)}
3434 You can use the group parameters to set variables local to the group you
3435 are entering. Say you want to turn threading off in
3436 @samp{news.answers}. You'd then put @code{(gnus-show-threads nil)} in
3437 the group parameters of that group. @code{gnus-show-threads} will be
3438 made into a local variable in the summary buffer you enter, and the form
3439 @code{nil} will be @code{eval}ed there.
3441 This can also be used as a group-specific hook function, if you'd like.
3442 If you want to hear a beep when you enter the group
3443 @samp{alt.binaries.pictures.furniture}, you could put something like
3444 @code{(dummy-variable (ding))} in the parameters of that group.
3445 @code{dummy-variable} will be set to the result of the @code{(ding)}
3446 form, but who cares?
3450 If you want to change the group info you can use the @kbd{G E} command
3451 to enter a buffer where you can edit it.
3453 You usually don't want to edit the entire group info, so you'd be better
3454 off using the @kbd{G p} command to just edit the group parameters.
3456 @node Listing Groups
3457 @section Listing Groups
3458 @cindex group listing
3460 These commands all list various slices of the groups that are available.
3468 @findex gnus-group-list-groups
3469 List all groups that have unread articles
3470 (@code{gnus-group-list-groups}). If the numeric prefix is used, this
3471 command will list only groups of level ARG and lower. By default, it
3472 only lists groups of level five or lower (i.e., just subscribed groups).
3478 @findex gnus-group-list-all-groups
3479 List all groups, whether they have unread articles or not
3480 (@code{gnus-group-list-all-groups}). If the numeric prefix is used,
3481 this command will list only groups of level ARG and lower. By default,
3482 it lists groups of level seven or lower (i.e., just subscribed and
3483 unsubscribed groups).
3487 @findex gnus-group-list-level
3488 List all unread groups on a specific level
3489 (@code{gnus-group-list-level}). If given a prefix, also list the groups
3490 with no unread articles.
3494 @findex gnus-group-list-killed
3495 List all killed groups (@code{gnus-group-list-killed}). If given a
3496 prefix argument, really list all groups that are available, but aren't
3497 currently (un)subscribed. This could entail reading the active file
3502 @findex gnus-group-list-zombies
3503 List all zombie groups (@code{gnus-group-list-zombies}).
3507 @findex gnus-group-list-matching
3508 List all subscribed groups with unread articles that match a regexp
3509 (@code{gnus-group-list-matching}).
3513 @findex gnus-group-list-all-matching
3514 List groups that match a regexp (@code{gnus-group-list-all-matching}).
3518 @findex gnus-group-list-active
3519 List absolutely all groups that are in the active file(s) of the
3520 server(s) you are connected to (@code{gnus-group-list-active}). This
3521 might very well take quite a while. It might actually be a better idea
3522 to do a @kbd{A m} to list all matching, and just give @samp{.} as the
3527 @vindex gnus-permanently-visible-groups
3528 @cindex visible group paramenter
3529 Groups that match the @code{gnus-permanently-visible-groups} regexp will
3530 always be shown, whether they have unread articles or not. You can also
3531 add the @code{visible} element to the group parameters in question to
3532 get the same effect.
3534 @vindex gnus-list-groups-with-ticked-articles
3535 Groups that have just ticked articles in it are normally listed in the
3536 group buffer. If @code{gnus-list-groups-with-ticked-articles} is
3537 @code{nil}, these groups will be treated just like totally empty
3538 groups. It is @code{t} by default.
3541 @node Sorting Groups
3542 @section Sorting Groups
3543 @cindex sorting groups
3545 @kindex C-c C-s (Group)
3546 @findex gnus-group-sort-groups
3547 @vindex gnus-group-sort-function
3548 The @kbd{C-c C-s} (@code{gnus-group-srot-groups}) command sorts the
3549 group buffer according to the function(s) given by the
3550 @code{gnus-group-sort-function} variable. Available sorting functions
3555 @item gnus-group-sort-by-alphabet
3556 @findex gnus-group-sort-by-alphabet
3557 Sort the group names alphabetically. This is the default.
3559 @item gnus-group-sort-by-level
3560 @findex gnus-group-sort-by-level
3561 Sort by group level.
3563 @item gnus-group-sort-by-score
3564 @findex gnus-group-sort-by-score
3565 Sort by group score.
3567 @item gnus-group-sort-by-rank
3568 @findex gnus-group-sort-by-rank
3569 Sort by group score and then the group level. The level and the score
3570 are, when taken together, the group's @dfn{rank}.
3572 @item gnus-group-sort-by-unread
3573 @findex gnus-group-sort-by-unread
3574 Sort by number of unread articles.
3576 @item gnus-group-sort-by-method
3577 @findex gnus-group-sort-by-method
3578 Sort by alphabetically on the select method.
3583 @code{gnus-group-sort-function} can also be a list of sorting
3584 functions. In that case, the most significant sort key function must be
3588 There are also a number of commands for sorting directly according to
3589 some sorting criteria:
3593 @kindex G S a (Group)
3594 @findex gnus-group-sort-groups-by-alphabet
3595 Sort the group buffer alphabetically by group name
3596 (@code{gnus-group-sort-groups-by-alphabet}).
3599 @kindex G S u (Group)
3600 @findex gnus-group-sort-groups-by-unread
3601 Sort the group buffer by the number of unread articles
3602 (@code{gnus-group-sort-groups-by-unread}).
3605 @kindex G S l (Group)
3606 @findex gnus-group-sort-groups-by-level
3607 Sort the group buffer by group level
3608 (@code{gnus-group-sort-groups-by-level}).
3611 @kindex G S v (Group)
3612 @findex gnus-group-sort-groups-by-score
3613 Sort the group buffer by group score
3614 (@code{gnus-group-sort-groups-by-score}).
3617 @kindex G S r (Group)
3618 @findex gnus-group-sort-groups-by-rank
3619 Sort the group buffer by group level
3620 (@code{gnus-group-sort-groups-by-rank}).
3623 @kindex G S m (Group)
3624 @findex gnus-group-sort-groups-by-method
3625 Sort the group buffer alphabetically by backend name
3626 (@code{gnus-group-sort-groups-by-method}).
3630 When given a prefix, all these commands will sort in reverse order.
3634 @node Group Maintenance
3635 @section Group Maintenance
3636 @cindex bogus groups
3641 @findex gnus-group-check-bogus-groups
3642 Find bogus groups and delete them
3643 (@code{gnus-group-check-bogus-groups}).
3647 @findex gnus-find-new-newsgroups
3648 Find new groups and process them (@code{gnus-find-new-newsgroups}). If
3649 given a prefix, use the @code{ask-server} method to query the server for
3653 @kindex C-c C-x (Group)
3654 @findex gnus-group-expire-articles
3655 Run all expirable articles in the current group through the expiry
3656 process (if any) (@code{gnus-group-expire-articles}).
3659 @kindex C-c M-C-x (Group)
3660 @findex gnus-group-expire-all-groups
3661 Run all articles in all groups through the expiry process
3662 (@code{gnus-group-expire-all-groups}).
3667 @node Browse Foreign Server
3668 @section Browse Foreign Server
3669 @cindex foreign servers
3670 @cindex browsing servers
3675 @findex gnus-group-browse-foreign-server
3676 You will be queried for a select method and a server name. Gnus will
3677 then attempt to contact this server and let you browse the groups there
3678 (@code{gnus-group-browse-foreign-server}).
3681 @findex gnus-browse-server-mode
3682 A new buffer with a list of available groups will appear. This buffer
3683 will be use the @code{gnus-browse-server-mode}. This buffer looks a bit
3684 (well, a lot) like a normal group buffer, but with one major difference
3685 - you can't enter any of the groups. If you want to read any of the
3686 news available on that server, you have to subscribe to the groups you
3687 think may be interesting, and then you have to exit this buffer. The
3688 new groups will be added to the group buffer, and then you can read them
3689 as you would any other group.
3691 Future versions of Gnus may possibly permit reading groups straight from
3694 Here's a list of keystrokes available in the browse mode:
3699 @findex gnus-group-next-group
3700 Go to the next group (@code{gnus-group-next-group}).
3704 @findex gnus-group-prev-group
3705 Go to the previous group (@code{gnus-group-prev-group}).
3708 @kindex SPACE (Browse)
3709 @findex gnus-browse-read-group
3710 Enter the current group and display the first article
3711 (@code{gnus-browse-read-group}).
3714 @kindex RET (Browse)
3715 @findex gnus-browse-select-group
3716 Enter the current group (@code{gnus-browse-select-group}).
3720 @findex gnus-browse-unsubscribe-current-group
3721 Unsubscribe to the current group, or, as will be the case here,
3722 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
3728 @findex gnus-browse-exit
3729 Exit browse mode (@code{gnus-browse-exit}).
3733 @findex gnus-browse-describe-briefly
3734 Describe browse mode briefly (well, there's not much to describe, is
3735 there) (@code{gnus-browse-describe-briefly}).
3739 @section Exiting Gnus
3740 @cindex exiting Gnus
3742 Yes, Gnus is ex(c)iting.
3747 @findex gnus-group-suspend
3748 Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
3749 but it kills all buffers except the Group buffer. I'm not sure why this
3750 is a gain, but then who am I to judge?
3754 @findex gnus-group-exit
3755 Quit Gnus (@code{gnus-group-exit}).
3759 @findex gnus-group-quit
3760 Quit Gnus without saving any startup files (@code{gnus-group-quit}).
3763 @vindex gnus-exit-gnus-hook
3764 @vindex gnus-suspend-gnus-hook
3765 @code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
3766 @code{gnus-exit-gnus-hook} is called when you quit Gnus.
3770 If you wish to completely unload Gnus and all its adherents, you can use
3771 the @code{gnus-unload} command. This command is also very handy when
3772 trying to custoize meta-variables.
3777 Miss Lisa Cannifax, while sitting in English class, feels her feet go
3778 numbly heavy and herself fall into a hazy trance as the boy sitting
3779 behind her drew repeated lines with his pencil across the back of her
3785 @section Group Topics
3788 If you read lots and lots of groups, it might be convenient to group
3789 them hierarchically according to topics. You put your Emacs groups over
3790 here, your sex groups over there, and the rest (what, two groups or so?)
3791 you put in some misc section that you never bother with anyway. You can
3792 even group the Emacs sex groups as a sub-topic to either the Emacs
3793 groups or the sex groups---or both! Go wild!
3795 @findex gnus-topic-mode
3797 To get this @emph{fab} functionality you simply turn on (ooh!) the
3798 @code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This
3799 is a toggling command.)
3801 Go ahead, just try it. I'll still be here when you get back. La de
3802 dum... Nice tune, that... la la la... What, you're back? Yes, and now
3803 press @kbd{l}. There. All your groups are now listed under
3804 @samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
3807 If you want this permanently enabled, you should add that minor mode to
3808 the hook for the group mode:
3811 (add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
3815 * Topic Variables:: How to customize the topics the Lisp Way.
3816 * Topic Commands:: Interactive E-Z commands.
3817 * Topic Topology:: A map of the world.
3821 @node Topic Variables
3822 @subsection Topic Variables
3823 @cindex topic variables
3826 @vindex gnus-group-topic-topics-only
3827 Whoo, this is complicated. If @code{gnus-group-topic-topics-only} is
3828 @code{nil}, all groups and topics will be listed, as you would expect.
3829 If this variable is non-@code{nil}, only the topics will be listed, and
3830 the groups will not be listed. This makes the group buffer much shorter,
3831 I'm sure you'll agree. This is all modified on a topic-by-topic basis
3832 by the @var{show} parameter. It makes perfect sense, really.
3834 @vindex gnus-topic-unique
3835 If @code{gnus-topic-unique} is non-@code{nil}, each group will be member
3836 of (tops) one topic each. If this is @code{nil}, each group might end
3837 up being a member of several topics.
3839 Now, if you select a topic, if will fold/unfold that topic, which is
3840 really neat, I think.
3842 @vindex gnus-topic-line-format
3843 The topic lines themselves are created according to the
3844 @code{gnus-topic-line-format} variable. @xref{Formatting Variables}.
3845 Elements allowed are:
3857 Number of groups in the topic.
3859 Number of unread articles in the topic.
3861 Number of unread articles in the topic and all its subtopics.
3865 @node Topic Commands
3866 @subsection Topic Commands
3867 @cindex topic commands
3869 When the topic minor mode is turned on, a new @kbd{T} submap will be
3870 available. In addition, a few of the standard keys change their
3871 definitions slightly.
3877 @findex gnus-topic-create-topic
3878 Create a new topic (@code{gnus-topic-create-subtopic}). You will be
3879 prompted for a topic name and the name of the parent topic.
3883 @findex gnus-topic-move-group
3884 Move the current group to some other topic
3885 (@code{gnus-topic-move-group}). This command understands the
3886 process/prefix convention (@pxref{Process/Prefix}).
3890 @findex gnus-topic-copy-group
3891 Copy the current group to some other topic
3892 (@code{gnus-topic-copy-group}). This command understands the
3893 process/prefix convention (@pxref{Process/Prefix}).
3897 @findex gnus-topic-move-matching
3898 Move all groups that match some regular expression to a topic
3899 (@code{gnus-topic-move-matching}).
3903 @findex gnus-topic-copy-matching
3904 Copy all groups that match some regular expression to a topic
3905 (@code{gnus-topic-copy-matching}).
3909 @findex gnus-topic-select-group
3911 Either select a group or fold a topic (@code{gnus-topic-select-group}).
3912 When you perform this command on a group, you'll enter the group, as
3913 usual. When done on a topic line, the topic will be folded (if it was
3914 visible) or unfolded (if it was folded already). So it's basically a
3915 toggling command on topics. In addition, if you give a numerical
3916 prefix, group on that level (and lower) will be displayed.
3920 @findex gnus-topic-kill-group
3921 Kill a group or topic (@code{gnus-topic-kill-group}).
3925 @findex gnus-topic-yank-group
3926 Yank the previosuly killed group or topic (@code{gnus-topic-yank-group}).
3927 Note that all topics will be yanked before all groups.
3931 @findex gnus-topic-rename
3932 Rename a topic (@code{gnus-topic-rename}).
3935 @kindex T DEL (Group)
3936 @findex gnus-topic-delete
3937 Delete an empty topic (@code{gnus-topic-delete}).
3941 @findex gnus-topic-list-active
3942 List all groups that Gnus knows about in a topicsified way
3943 (@code{gnus-topic-list-active}).
3948 @node Topic Topology
3949 @subsection Topic Topology
3950 @cindex topic topology
3953 So, let's have a look at an example group buffer:
3959 2: alt.religion.emacs
3962 0: comp.talk.emacs.recovery
3964 8: comp.binaries.fractals
3965 13: comp.sources.unix
3968 So, here we have one top-level topic, two topics under that, and one
3969 sub-topic under one of the sub-topics. (There is always just one (1)
3970 top-level topic). This topology can be expressed as follows:
3974 (("Emacs -- I wuw it!" visible)
3975 (("Naughty Emacs" visible)))
3979 This is in fact how the variable @code{gnus-topic-topology} would look
3980 for the display above. That variable is saved in the @file{.newsrc.eld}
3981 file, and shouldn't be messed with manually---unless you really want
3982 to. Since this variable is read from the @file{.newsrc.eld} file,
3983 setting it in any other startup files will have no effect.
3985 This topology shows what topics are sub-topics of what topics (right),
3986 and which topics are visible. Two settings are currently
3987 allowed---@code{visible} and @code{invisible}.
3990 @node Misc Group Stuff
3991 @section Misc Group Stuff
3997 @findex gnus-group-get-new-news
3998 Check the server(s) for new articles. If the numerical prefix is used,
3999 this command will check only groups of level @var{arg} and lower
4000 (@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
4001 command will force a total rereading of the active file(s) from the
4006 @findex gnus-group-get-new-news-this-group
4007 @vindex gnus-goto-next-group-when-activating
4008 Check whether new articles have arrived in the current group
4009 (@code{gnus-group-get-new-news-this-group}). The
4010 @code{gnus-goto-next-group-when-activating} variable controls whether
4011 this command is to move point to the next group or not. It is @code{t}
4014 @findex gnus-activate-all-groups
4016 @kindex C-c M-g (Group)
4017 Activate absolutely all groups (@code{gnus-activate-all-groups}).
4021 @findex gnus-group-enter-server-mode
4022 Enter the server buffer (@code{gnus-group-enter-server-mode}). @xref{The
4027 @findex gnus-group-fetch-faq
4028 Try to fetch the FAQ for the current group
4029 (@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
4030 @code{gnus-group-faq-directory}, which is usually a directory on a
4031 remote machine. @code{ange-ftp} will be used for fetching the file.
4035 @findex gnus-group-restart
4036 Restart Gnus (@code{gnus-group-restart}).
4040 @findex gnus-group-read-init-file
4041 @vindex gnus-init-file
4042 Read the init file (@code{gnus-init-file}, which defaults to
4043 @file{~/.gnus}) (@code{gnus-group-read-init-file}).
4047 @findex gnus-group-save-newsrc
4048 Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
4049 (@code{gnus-group-save-newsrc}). If given a prefix, force saving the
4050 file(s) whether Gnus thinks it is necessary or not.
4054 @findex gnus-group-clear-dribble
4055 Clear the dribble buffer (@code{gnus-group-clear-dribble}).
4059 @findex gnus-group-describe-group
4060 Describe the current group (@code{gnus-group-describe-group}). If given
4061 a prefix, force Gnus to re-read the description from the server.
4065 @findex gnus-group-apropos
4066 List all groups that have names that match a regexp
4067 (@code{gnus-group-apropos}).
4071 @findex gnus-group-description-apropos
4072 List all groups that have names or descriptions that match a regexp
4073 (@code{gnus-group-description-apropos}).
4077 @findex gnus-group-post-news
4078 Post an article to a group (@code{gnus-group-post-news}). The current
4079 group name will be used as the default.
4083 @findex gnus-group-mail
4084 Mail a message somewhere (@code{gnus-group-mail}).
4087 @kindex C-x C-t (Group)
4088 @findex gnus-group-transpose-groups
4089 Transpose two groups (@code{gnus-group-transpose-groups}).
4093 @findex gnus-version
4094 Display current Gnus version numbers (@code{gnus-version}).
4098 @findex gnus-group-describe-all-groups
4099 Describe all groups (@code{gnus-group-describe-all-groups}). If given a
4100 prefix, force Gnus to re-read the description file from the server.
4104 @findex gnus-group-describe-briefly
4105 Give a very short help message (@code{gnus-group-describe-briefly}).
4108 @kindex C-c C-i (Group)
4109 @findex gnus-info-find-node
4110 Go to the Gnus info node (@code{gnus-info-find-node}).
4113 @vindex gnus-group-prepare-hook
4114 @code{gnus-group-prepare-hook} is called after the group buffer is
4115 generated. It may be used to modify the buffer in some strange,
4118 @node The Summary Buffer
4119 @chapter The Summary Buffer
4120 @cindex summary buffer
4122 A line for each article is displayed in the summary buffer. You can
4123 move around, read articles, post articles and reply to articles.
4126 * Summary Buffer Format:: Deciding how the summary buffer is to look.
4127 * Summary Maneuvering:: Moving around the summary buffer.
4128 * Choosing Articles:: Reading articles.
4129 * Paging the Article:: Scrolling the current article.
4130 * Reply Followup and Post:: Posting articles.
4131 * Canceling and Superseding:: "Whoops, I shouldn't have called him that."
4132 * Marking Articles:: Marking articles as read, expirable, etc.
4133 * Limiting:: You can limit the summary buffer.
4134 * Threading:: How threads are made.
4135 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
4136 * Article Caching:: You may store articles in a cache.
4137 * Persistent Articles:: Making articles expiry-resistant.
4138 * Article Backlog:: Having already read articles hang around.
4139 * Exiting the Summary Buffer:: Returning to the Group buffer.
4140 * Process/Prefix:: A convention used by many treatment commands.
4141 * Saving Articles:: Ways of customizing article saving.
4142 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
4143 * Article Treatment:: The article buffer can be mangled at will.
4144 * Summary Sorting:: You can sort the summary buffer four ways.
4145 * Finding the Parent:: No child support? Get the parent.
4146 * Alternative Approaches:: Reading using non-default summaries.
4147 * Tree Display:: A more visual display of threads.
4148 * Mail Group Commands:: Some commands can only be used in mail groups.
4149 * Various Summary Stuff:: What didn't fit anywhere else.
4153 @node Summary Buffer Format
4154 @section Summary Buffer Format
4155 @cindex summary buffer format
4158 * Summary Buffer Lines:: You can specify how summary lines should look.
4159 * Summary Buffer Mode Line:: You can say how the mode line should look.
4162 @findex mail-extract-address-components
4163 @findex gnus-extract-address-components
4164 @vindex gnus-extract-address-components
4165 Gnus will use the value of the @code{gnus-extract-address-components}
4166 variable as a function for getting the name and address parts of a
4167 @code{From} header. Two pre-defined function exist:
4168 @code{gnus-extract-address-components}, which is the default, quite
4169 fast, and too simplistic solution; and
4170 @code{mail-extract-address-components}, which works very nicely, but is
4173 @vindex gnus-summary-same-subject
4174 @code{gnus-summary-same-subject} is a string indicating that the current
4175 article has the same subject as the previous. This string will be used
4176 with those specs that require it. The default is @samp{""}.
4178 @node Summary Buffer Lines
4179 @subsection Summary Buffer Lines
4181 @vindex gnus-summary-line-format
4182 You can change the format of the lines in the summary buffer by changing
4183 the @code{gnus-summary-line-format} variable. It works along the same
4184 lines a a normal @code{format} string, with some extensions.
4186 The default string is @samp{"%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n"}.
4188 The following format specification characters are understood:
4196 Subject if the article is the root, @code{gnus-summary-same-subject}
4199 Full @code{From} line.
4201 The name (from the @code{From} header).
4203 The name (from the @code{From} header). This differs from the @code{n}
4204 spec in that it uses @code{gnus-extract-address-components}, which is
4205 slower, but may be more thorough.
4207 The address (from the @code{From} header). This works the same way as
4210 Number of lines in the article.
4212 Number of characters in the article.
4214 Indentation based on thread level (@pxref{Customizing Threading}).
4216 Nothing if the article is a root and lots of spaces if it isn't (it
4217 pushes everything after it off the screen).
4219 Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
4220 for adopted articles.
4222 Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
4223 for adopted articles.
4225 One space for each thread level.
4227 Twenty minus thread level spaces.
4235 @vindex gnus-summary-zcore-fuzz
4236 Zcore, @samp{+} if above the default level and @samp{-} if below the
4237 default level. If the difference between
4238 @code{gnus-summary-default-level} and the score is less than
4239 @code{gnus-summary-zcore-fuzz}, this spec will not be used.
4251 Number of articles in the current sub-thread. Using this spec will slow
4252 down summary buffer generation somewhat.
4254 A single character will be displayed if the article has any children.
4256 User defined specifier. The next character in the format string should
4257 be a letter. @sc{gnus} will call the function
4258 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
4259 following @samp{%u}. The function will be passed the current header as
4260 argument. The function should return a string, which will be inserted
4261 into the summary just like information from any other summary specifier.
4264 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
4265 have to be handled with care. For reasons of efficiency, Gnus will
4266 compute what column these characters will end up in, and "hard-code"
4267 that. This means that it is illegal to have these specs after a
4268 variable-length spec. Well, you might not be arrested, but your summary
4269 buffer will look strange, which is bad enough.
4271 The smart choice is to have these specs as far to the left as possible.
4272 (Isn't that the case with everything, though? But I digress.)
4274 This restriction may disappear in later versions of Gnus.
4276 @node Summary Buffer Mode Line
4277 @subsection Summary Buffer Mode Line
4279 @vindex gnus-summary-mode-line-format
4280 You can also change the format of the summary mode bar. Set
4281 @code{gnus-summary-mode-line-format} to whatever you like. Here are the
4282 elements you can play with:
4288 Unprefixed group name.
4290 Current article number.
4294 Number of unread articles in this group.
4296 Number of unselected articles in this group.
4298 A string with the number of unread and unselected articles represented
4299 either as @samp{<%U(+%u) more>} if there are both unread and unselected
4300 articles, and just as @samp{<%U more>} if there are just unread articles
4301 and no unselected ones.
4303 Shortish group name. For instance, @samp{rec.arts.anime} will be
4304 shortened to @samp{r.a.anime}.
4306 Subject of the current article.
4310 Name of the current score file.
4312 Number of dormant articles.
4314 Number of ticked articles.
4316 Number of articles that have been marked as read in this session.
4318 Number of articles expunged by the score files.
4322 @node Summary Maneuvering
4323 @section Summary Maneuvering
4324 @cindex summary movement
4326 All the straight movement commands understand the numeric prefix and
4327 behave pretty much as you'd expect.
4329 None of these commands select articles.
4334 @kindex M-n (Summary)
4335 @kindex G M-n (Summary)
4336 @findex gnus-summary-next-unread-subject
4337 Go to the next summary line of an unread article
4338 (@code{gnus-summary-next-unread-subject}).
4342 @kindex M-p (Summary)
4343 @kindex G M-p (Summary)
4344 @findex gnus-summary-prev-unread-subject
4345 Go to the previous summary line of an unread article
4346 (@code{gnus-summary-prev-unread-subject}).
4351 @kindex G g (Summary)
4352 @findex gnus-summary-goto-subject
4353 Ask for an article number and then go to this summary line
4354 (@code{gnus-summary-goto-subject}).
4357 If Gnus asks you to press a key to confirm going to the next group, you
4358 can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
4359 buffer, searching for the next group to read without actually returning
4360 to the group buffer.
4362 Variables related to summary movement:
4366 @vindex gnus-auto-select-next
4367 @item gnus-auto-select-next
4368 If you are at the end of the group and issue one of the movement
4369 commands, Gnus will offer to go to the next group. If this variable is
4370 @code{t} and the next group is empty, Gnus will exit summary mode and
4371 return to the group buffer. If this variable is neither @code{t} nor
4372 @code{nil}, Gnus will select the next group, no matter whether it has
4373 any unread articles or not. As a special case, if this variable is
4374 @code{quietly}, Gnus will select the next group without asking for
4375 confirmation. If this variable is @code{almost-quietly}, the same will
4376 happen only if you are located on the last article in the group. Also
4377 @xref{Group Levels}.
4379 @item gnus-auto-select-same
4380 @vindex gnus-auto-select-same
4381 If non-@code{nil}, all the movement commands will try to go to the next
4382 article with the same subject as the current. This variable is not
4383 particularly useful if you use a threaded display.
4385 @item gnus-summary-check-current
4386 @vindex gnus-summary-check-current
4387 If non-@code{nil}, all the "unread" movement commands will not proceed
4388 to the next (or previous) article if the current article is unread.
4389 Instead, they will choose the current article.
4391 @item gnus-auto-center-summary
4392 @vindex gnus-auto-center-summary
4393 If non-@code{nil}, Gnus will keep the point in the summary buffer
4394 centered at all times. This makes things quite tidy, but if you have a
4395 slow network connection, or simply do not like this un-Emacsism, you can
4396 set this variable to @code{nil} to get the normal Emacs scrolling
4397 action. This will also inhibit horizontal recentering of the summary
4398 buffer, which might make it more inconvenient to read extremely long
4404 @node Choosing Articles
4405 @section Choosing Articles
4406 @cindex selecting articles
4408 None of the following movement commands understand the numeric prefix,
4409 and they all select and display an article.
4413 @kindex SPACE (Summary)
4414 @findex gnus-summary-next-page
4415 Select the current article, or, if that one's read already, the next
4416 unread article (@code{gnus-summary-next-page}).
4421 @kindex G n (Summary)
4422 @findex gnus-summary-next-unread-article
4423 Go to next unread article (@code{gnus-summary-next-unread-article}).
4428 @findex gnus-summary-prev-unread-article
4429 Go to previous unread article (@code{gnus-summary-prev-unread-article}).
4434 @kindex G N (Summary)
4435 @findex gnus-summary-next-article
4436 Go to the next article (@code{gnus-summary-next-article}).
4441 @kindex G P (Summary)
4442 @findex gnus-summary-prev-article
4443 Go to the previous article (@code{gnus-summary-prev-article}).
4446 @kindex G C-n (Summary)
4447 @findex gnus-summary-next-same-subject
4448 Go to the next article with the same subject
4449 (@code{gnus-summary-next-same-subject}).
4452 @kindex G C-p (Summary)
4453 @findex gnus-summary-prev-same-subject
4454 Go to the previous article with the same subject
4455 (@code{gnus-summary-prev-same-subject}).
4459 @kindex G f (Summary)
4461 @findex gnus-summary-first-unread-article
4462 Go to the first unread article
4463 (@code{gnus-summary-first-unread-article}).
4467 @kindex G b (Summary)
4469 Go to the article with the highest score
4470 (@code{gnus-summary-best-unread-article}).
4475 @kindex G l (Summary)
4476 @findex gnus-summary-goto-last-article
4477 Go to the previous article read (@code{gnus-summary-goto-last-article}).
4480 @kindex G p (Summary)
4481 @findex gnus-summary-pop-article
4482 Pop an article off the summary history and go to this article
4483 (@code{gnus-summary-pop-article}). This command differs from the
4484 command above in that you can pop as many previous articles off the
4485 history as you like.
4488 Some variables that are relevant for moving and selecting articles:
4491 @item gnus-auto-extend-newsgroup
4492 @vindex gnus-auto-extend-newsgroup
4493 All the movement commands will try to go to the previous (or next)
4494 article, even if that article isn't displayed in the Summary buffer if
4495 this variable is non-@code{nil}. Gnus will then fetch the article from
4496 the server and display it in the article buffer.
4498 @item gnus-select-article-hook
4499 @vindex gnus-select-article-hook
4500 This hook is called whenever an article is selected. By default it
4501 exposes any threads hidden under the selected article.
4503 @item gnus-mark-article-hook
4504 @vindex gnus-mark-article-hook
4505 This hook is called whenever an article is selected. It is intended to
4506 be used for marking articles as read.
4508 @item gnus-visual-mark-article-hook
4509 @vindex gnus-visual-mark-article-hook
4510 This hook is run after selecting an article. It is meant to be used for
4511 highlighting the article in some way. It is not run if
4512 @code{gnus-visual} is @code{nil}.
4514 @item gnus-summary-update-hook
4515 @vindex gnus-summary-update-hook
4516 This hook is called when a summary line is changed. It is not run if
4517 @code{gnus-visual} is @code{nil}.
4519 @item gnus-summary-selected-face
4520 @vindex gnus-summary-selected-face
4521 This is the face (or @dfn{font} as some people call it) that is used to
4522 highlight the current article in the summary buffer.
4524 @item gnus-summary-highlight
4525 @vindex gnus-summary-highlight
4526 Summary lines are highlighted according to this variable, which is a
4527 list where the elements are on the format @code{(FORM . FACE)}. If you
4528 would, for instance, like ticked articles to be italic and high-scored
4529 articles to be bold, you could set this variable to something like
4531 (((eq mark gnus-ticked-mark) . italic)
4532 ((> score default) . bold))
4534 As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
4535 @var{FACE} will be applied to the line.
4538 @node Paging the Article
4539 @section Scrolling the Article
4540 @cindex article scrolling
4545 @kindex SPACE (Summary)
4546 @findex gnus-summary-next-page
4547 Pressing @kbd{SPACE} will scroll the current article forward one page,
4548 or, if you have come to the end of the current article, will choose the
4549 next article (@code{gnus-summary-next-page}).
4552 @kindex DEL (Summary)
4553 @findex gnus-summary-prev-page
4554 Scroll the current article back one page (@code{gnus-summary-prev-page}).
4557 @kindex RET (Summary)
4558 @findex gnus-summary-scroll-up
4559 Scroll the current article one line forward
4560 (@code{gnus-summary-scroll-up}).
4565 @kindex A < (Summary)
4566 @findex gnus-summary-beginning-of-article
4567 Scroll to the beginning of the article
4568 (@code{gnus-summary-beginning-of-article}).
4573 @kindex A > (Summary)
4574 @findex gnus-summary-end-of-article
4575 Scroll to the end of the article (@code{gnus-summary-end-of-article}).
4578 @kindex A s (Summary)
4579 @findex gnus-summary-isearch-article
4580 Perform an isearch in the article buffer
4581 (@code{gnus-summary-isearch-article}).
4585 @node Reply Followup and Post
4586 @section Reply, Followup and Post
4591 @kindex C-c C-c (Post)
4592 All the commands for posting and mailing will put you in a post or mail
4593 buffer where you can edit the article all you like, before you send the
4594 article by pressing @kbd{C-c C-c}. If you are in a foreign news group,
4595 and you wish to post the article using the foreign server, you can give
4596 a prefix to @kbd{C-c C-c} to make Gnus try to post using the foreign
4600 * Mail:: Mailing & replying.
4601 * Post:: Posting and following up.
4602 * Posting Server:: What server should you post via?
4603 * Mail & Post:: Mailing and posting at the same time.
4604 * Archived Messages:: Where Gnus stores the messages you've sent.
4605 * Posting Styles:: An easier way to configure some key elements.
4606 * Drafts:: Postponing messages and rejected messages.
4607 * Rejected Articles:: What happens if the server doesn't like your article?
4613 Commands for composing a mail message:
4619 @kindex S r (Summary)
4621 @findex gnus-summary-reply
4622 Mail a reply to the author of the current article
4623 (@code{gnus-summary-reply}).
4628 @kindex S R (Summary)
4629 @findex gnus-summary-reply-with-original
4630 Mail a reply to the author of the current article and include the
4631 original message (@code{gnus-summary-reply-with-original}). This
4632 command uses the process/prefix convention.
4635 @kindex S o m (Summary)
4636 @findex gnus-summary-mail-forward
4637 Forward the current article to some other person
4638 (@code{gnus-summary-mail-forward}).
4641 @kindex S o p (Summary)
4642 @findex gnus-summary-post-forward
4643 Forward the current article to a newsgroup
4644 (@code{gnus-summary-post-forward}).
4649 @kindex S m (Summary)
4650 @findex gnus-summary-mail-other-window
4651 Send a mail to some other person
4652 (@code{gnus-summary-mail-other-window}).
4655 @kindex S D b (Summary)
4656 @findex gnus-summary-resend-bounced-mail
4657 If you have sent a mail, but the mail was bounced back to you for some
4658 reason (wrong address, transient failure), you can use this command to
4659 resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
4660 will be popped into a mail buffer where you can edit the headers before
4661 sending the mail off again. The headers that match the regexp
4662 @code{gnus-bounced-headers-junk} (default @samp{^Received:}) are
4663 automatically deleted first. If you give a prefix to this command, and
4664 the bounced mail is a reply to some other mail, Gnus will try to fetch
4665 that mail and display it for easy perusal of its headers. This might
4666 very well fail, though.
4669 @kindex S D r (Summary)
4670 @findex gnus-summary-resend-message
4671 Not to be confused with the previous command,
4672 @code{gnus-summary-resend-message} will prompt you for an address to
4673 send the current message off to, and then send it to that place. The
4674 headers of the message won't be altered---but lots of headers that say
4675 @samp{Resent-To}, @samp{Resent-From} and so on will be added. This
4676 means that you actually send a mail to someone that has a @samp{To}
4677 header that (proabbly) points to yourself. This will confuse people.
4678 So, natcherly you'll only do that if you're really eVIl.
4680 This command is mainly used if you have several accounts and want to
4681 ship a mail to a different account of yours. (If you're both
4682 @samp{root} and @samp{postmaster} and get a mail for @samp{postmaster}
4683 to the @samp{root} account, you may want to resend it to
4684 @samp{postmaster}. Ordnung muss sein!
4687 @kindex S O m (Summary)
4688 @findex gnus-uu-digest-mail-forward
4689 Digest the current series and forward the result using mail
4690 (@code{gnus-uu-digest-mail-forward}). This command uses the
4691 process/prefix convention (@pxref{Process/Prefix}).
4694 @kindex S O p (Summary)
4695 @findex gnus-uu-digest-post-forward
4696 Digest the current series and forward the result to a newsgroup
4697 (@code{gnus-uu-digest-mail-forward}).
4700 Variables for customizing outgoing mail:
4703 @item gnus-reply-to-function
4704 @vindex gnus-reply-to-function
4705 Gnus uses the normal methods to determine where replies are to go, but
4706 you can change the behavior to suit your needs by fiddling with this
4709 If you want the replies to go to the @samp{Sender} instead of the
4710 @samp{From} in the group @samp{mail.stupid-list}, you could do something
4714 (setq gnus-reply-to-function
4716 (cond ((string= group "mail.stupid-list")
4717 (mail-fetch-field "sender"))
4722 This function will be called narrowed to the head of the article that is
4725 As you can see, this function should return a string if it has an
4726 opinion as to what the To header should be. If it does not, it should
4727 just return @code{nil}, and the normal methods for determining the To
4728 header will be used.
4730 This function can also return a list. In that case, each list element
4731 should be a cons, where the car should be the name of an header
4732 (eg. @samp{Cc}) and the cdr should be the header value
4733 (eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into
4734 the head of the outgoing mail.
4736 @item gnus-mail-send-method
4737 @vindex gnus-mail-send-method
4738 This variable says how a mail should be mailed. It uses the function in
4739 the @code{send-mail-function} variable as the default.
4741 @item gnus-uu-digest-headers
4742 @vindex gnus-uu-digest-headers
4743 List of regexps to match headers included in digested messages. The
4744 headers will be included in the sequence they are matched.
4746 @item gnus-mail-hook
4747 @vindex gnus-mail-hook
4748 Hook called as the last thing after setting up a mail buffer.
4750 @item gnus-required-mail-headers
4751 @vindex gnus-required-mail-headers
4752 Gnus will generate headers in all outgoing mail instead of letting
4753 @code{sendmail} do it for us. This makes it possible to do more neat
4754 stuff, like putting mail without sending it, do hairy @code{Fcc}
4755 handling, and much more. This variable controls what headers Gnus will
4756 generate, and is of the exact same form as @code{gnus-required-headers},
4757 which does the same for news articles (@pxref{Post}).
4759 The @code{Newsgroups} header is illegal in this list, while @code{To} is
4760 required, and @code{X-Mailer} can be added if you so should want.
4762 @findex gnus-forward-start-separator
4763 @item gnus-forward-start-separator
4764 Delimiter inserted before forwarded messages.
4766 @findex gnus-forward-end-separator
4767 @item gnus-forward-end-separator
4768 Delimiter inserted after forwarded messages.
4770 @vindex gnus-signature-before-forwarded-message
4771 @item gnus-signature-before-forwarded-message
4772 If this variable is @code{t}, which it is by default, your personal
4773 signature will be inserted before the forwarded message. If not, the
4774 forwarded message will be inserted first in the new mail.
4776 @item gnus-forward-included-headers
4777 @vindex gnus-forward-included-headers
4778 Regexp matching header lines to be included in forwarded messages. It
4779 usese the same regexp as @code{gnus-visible-headers} by default.
4783 @kindex C-c C-c (Mail)
4784 @kindex C-c C-p (Mail)
4785 @findex gnus-put-message
4786 You normally send a mail message by pressing @kbd{C-c C-c}. However,
4787 you may wish to just put the mail message you have just written in your
4788 own local mail group instead of sending it. Sounds quite unlikely, but
4789 I found that useful, so you can now also press @kbd{C-c C-p} to
4790 @dfn{put} the article in the current mail group, or, if there is no such
4791 thing, you will be prompted for a mail group, and then the article will
4792 be put there. This means that the article is @dfn{not} mailed.
4794 There are three "methods" for handling all mail. The default is
4795 @code{sendmail}. Some people like what @code{mh} does better, and some
4796 people prefer @code{vm}.
4798 Three variables for customizing what to use when:
4802 @vindex gnus-mail-reply-method
4803 @item gnus-mail-reply-method
4804 This function is used to compose replies. The three functions avaibale
4807 @findex gnus-mail-reply-using-vm
4808 @findex gnus-mail-reply-using-mhe
4809 @findex gnus-mail-reply-using-mail
4812 @code{gnus-mail-reply-using-mail} (sendmail)
4814 @code{gnus-mail-reply-using-mhe} (mh)
4816 @code{gnus-mail-reply-using-vm} (vm)
4819 @vindex gnus-mail-forward-method
4820 @item gnus-mail-forward-method
4821 This function is used to forward messages. The three functions avaibale
4824 @findex gnus-mail-forward-using-vm
4825 @findex gnus-mail-forward-using-mhe
4826 @findex gnus-mail-forward-using-mail
4829 @code{gnus-mail-forward-using-mail} (sendmail)
4831 @code{gnus-mail-forward-using-mhe} (mh)
4833 @code{gnus-mail-forward-using-vm} (vm)
4836 @vindex gnus-mail-other-window-method
4837 @item gnus-mail-other-window-method
4838 This function is used to send mails. The three functions avaibale are:
4840 @findex gnus-mail-other-window-using-vm
4841 @findex gnus-mail-other-window-using-mhe
4842 @findex gnus-mail-other-window-using-mail
4845 @code{gnus-mail-other-window-using-mail} (sendmail)
4847 @code{gnus-mail-other-window-using-mhe} (mh)
4849 @code{gnus-mail-other-window-using-vm} (vm)
4858 Commands for posting an article:
4864 @kindex S p (Summary)
4865 @findex gnus-summary-post-news
4866 Post an article to the current group
4867 (@code{gnus-summary-post-news}).
4872 @kindex S f (Summary)
4873 @findex gnus-summary-followup
4874 Post a followup to the current article (@code{gnus-summary-followup}).
4878 @kindex S F (Summary)
4880 @findex gnus-summary-followup-with-original
4881 Post a followup to the current article and include the original message
4882 (@code{gnus-summary-followup-with-original}). This command uses the
4883 process/prefix convention.
4886 @kindex S u (Summary)
4887 @findex gnus-uu-post-news
4888 Uuencode a file, split it into parts, and post it as a series
4889 (@code{gnus-uu-post-news}).
4890 @c (@pxref{Uuencoding & Posting}).
4893 @vindex gnus-required-headers
4894 @code{gnus-required-headers} a list of header symbols. These headers
4895 will either be automatically generated, or, if that's impossible, they
4896 will be prompted for. The following symbols are legal:
4901 This required header will be filled out with the result of the
4902 @code{gnus-inews-user-name} function, which depends on the
4903 @code{gnus-user-from-line}, @code{gnus-user-login-name},
4904 @code{gnus-local-domain} and @code{user-mail-address} variables.
4907 This required header will be prompted for if not present already.
4910 This required header says which newsgroups the article is to be posted
4911 to. If it isn't present already, it will be prompted for.
4914 @cindex organization
4915 @vindex gnus-local-organization
4916 @vindex gnus-organization-file
4917 This optional header will be filled out depending on the
4918 @code{gnus-local-organization} variable. @code{gnus-organization-file}
4919 will be used if that variable is nil.
4922 This optional header will be computed by Gnus.
4926 This required header will be generated by Gnus. A unique ID will be
4927 created based on date, time, user name and system name.
4930 @cindex X-Newsreader
4931 This optional header will be filled out with the Gnus version numbers.
4934 @vindex gnus-article-expires
4936 This extremely optional header will be inserted according to the
4937 @code{gnus-article-expires} variable. It is highly deprecated and
4938 shouldn't be used unless you know what you're doing.
4941 This optional header is filled out according to the
4942 @code{gnus-distribution-function} variable. It is a deprecated and much
4943 misunderstood header.
4946 In addition, you can enter conses into this list. The car of this cons
4947 should be a symbol. This symbol's name is the name of the header, and
4948 the cdr can either be a string to be entered verbatim as the value of
4949 this header, or it can be a function to be called. This function should
4950 return a string to be inserted. For instance, if you want to insert
4951 @samp{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
4952 into the list. If you want to insert a funny quote, you could enter
4953 something like @code{(X-Yow . yow)} into the list. The function
4954 @code{yow} will then be called without any arguments.
4956 The list contains a cons where the car of the cons is @code{optional},
4957 the cdr of this cons will only be inserted if it is non-@code{nil}.
4959 Other variables for customizing outgoing articles:
4962 @item nntp-news-default-headers
4963 @vindex nntp-news-default-headers
4964 If non-@code{nil}, this variable will override
4965 @code{mail-default-headers} when posting. This variable should then be
4966 a string. This string will be inserted, as is, in the head of all
4969 @item gnus-use-followup-to
4970 @vindex gnus-use-followup-to
4971 If @code{nil}, always ignore the Followup-To header. If it is @code{t},
4972 use its value, but ignore the special value @samp{poster}, which will
4973 send the followup as a reply mail to the person you are responding to.
4974 If it is the symbol @code{ask}, query the user before posting.
4975 If it is the symbol @code{use}, always use the value.
4977 @item gnus-followup-to-function
4978 @vindex gnus-followup-to-function
4979 This variable is most useful in mail groups, where "following up" really
4980 means sending a mail to a list address. Gnus uses the normal methods to
4981 determine where follow-ups are to go, but you can change the behavior
4982 to suit your needs by fiddling with this variable.
4984 If you want the followups to go to the @samp{Sender} instead of the
4985 @samp{From} in the group @samp{mail.stupid-list}, you could do something
4989 (setq gnus-followup-to-function
4991 (cond ((string= group "mail.stupid-list")
4992 (mail-fetch-field "sender"))
4997 This function will be called narrowed to header of the article that is
5000 @item gnus-removable-headers
5001 @vindex gnus-removable-headers
5002 Some headers that are generated are toxic to the @sc{nntp} server.
5003 These include the @code{NNTP-Posting-Host}, @code{Bcc} and @code{Xref},
5004 so these headers are deleted if they are present in this list of
5007 @item gnus-deletable-headers
5008 @vindex gnus-deletable-headers
5009 Headers in this list that were previously generated by Gnus will be
5010 deleted before posting. Let's say you post an article. Then you decide
5011 to post it again to some other group, you naughty boy, so you jump back
5012 to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
5013 ship it off again. By default, this variable makes sure that the old
5014 generated @code{Message-ID} is deleted, and a new one generated. If
5015 this isn't done, the entire empire would probably crumble, anarchy would
5016 prevail, and cats would start walking on two legs and rule the world.
5019 @item gnus-signature-function
5020 @vindex gnus-signature-function
5021 If non-@code{nil}, this variable should be a function that returns a
5022 signature file name. The function will be called with the name of the
5023 group being posted to. If the function returns a string that doesn't
5024 correspond to a file, the string itself is inserted. If the function
5025 returns @code{nil}, the @code{gnus-signature-file} variable will be used
5028 @item gnus-post-prepare-function
5029 @vindex gnus-post-prepare-function
5030 This function is called with the name of the current group after the
5031 post buffer has been initialized, and can be used for inserting a
5032 signature. Nice if you use different signatures in different groups.
5034 @item gnus-post-prepare-hook
5035 @vindex gnus-post-prepare-hook
5036 This hook is called after a post buffer has been prepared. If you want
5037 to insert a signature at this point, you could put
5038 @code{gnus-inews-insert-signature} into this hook.
5040 @item news-reply-header-hook
5041 @vindex news-reply-header-hook
5042 A related variable when following up and replying is this variable,
5043 which inserts the @dfn{quote line}. The default value is:
5046 (defvar news-reply-header-hook
5048 (insert "In article " news-reply-yank-message-id
5049 " " news-reply-yank-from " writes:\n\n")))
5052 This will create lines like:
5055 In article <zngay8jrql@@eyesore.no> Lars Mars <lars@@eyesore.no> writes:
5058 Having the @code{Message-ID} in this line is probably overkill, so I
5059 would suggest this hook instead:
5062 (setq news-reply-header-hook
5063 (lambda () (insert news-reply-yank-from " writes:\n\n")))
5066 @item gnus-prepare-article-hook
5067 @vindex gnus-prepare-article-hook
5068 This hook is called before the headers have been prepared.
5070 @item gnus-inews-article-function
5071 @vindex gnus-inews-article-function
5072 This function is used to do the actual article processing and header
5073 checking/generation.
5075 @item gnus-inews-article-hook
5076 @vindex gnus-inews-article-hook
5077 This hook is called right before the article is posted. By default it
5078 handles FCC processing (i.e., saving the article to a file.) You can
5079 also have this hook add a score to all followups to the article you've
5080 written (@pxref{Followups To Yourself}).
5082 @item gnus-inews-article-header-hook
5083 @vindex gnus-inews-article-header-hook
5084 This hook is called after inserting the required headers in an article
5085 to be posted. The hook is called from the @code{*post-news*} buffer,
5086 narrowed to the head, and is intended for people who would like to
5087 insert additional headers, or just change headers in some way or other.
5089 @item gnus-check-before-posting
5090 @vindex gnus-check-before-posting
5091 If non-@code{nil}, Gnus will attempt to check the legality of the
5092 headers, as well as some other stuff, before posting. You can control
5093 the granularity of the check by adding or removing elements from this
5094 list. Legal elements are:
5098 Check the subject for commands.
5100 Insert a new @code{Sender} header if the @code{From} header looks odd.
5101 @item multiple-headers
5102 Check for the existence of multiple equal headers.
5104 Check for the existence of version and sendsys commands.
5106 Check whether the @code{Message-ID} looks ok.
5108 Check whether the @code{From} header seems nice.
5110 Check for too long lines.
5112 Check for illegal characters.
5114 Check for excessive size.
5116 Check whether there is any new text in the messages.
5118 Check the length of the signature.
5120 Check whether the article has an @code{Approved} header, which is
5121 something only moderators should include.
5123 Check whether the article is empty.
5130 @node Posting Server
5131 @subsection Posting Server
5133 When you press those magical @kbd{C-c C-c} keys to ship off your latest
5134 (extremely intelligent, of course) article, where does it go?
5136 Thank you for asking. I hate you.
5138 @vindex gnus-post-method
5140 It can be quite complicated. Normally, Gnus will use the same native
5141 server. However. If your native server doesn't allow posting, just
5142 reading, you probably want to use some other server to post your
5143 (extremely intelligent and fabulously interesting) articles. You can
5144 then set the @code{gnus-post-method} to some other method:
5147 (setq gnus-post-method '(nnspool ""))
5150 Now, if you've done this, and then this server rejects your article, or
5151 this server is down, what do you do then? To override this variable you
5152 can use a non-zero prefix to the @kbd{C-c C-c} command to force using
5153 the "current" server for posting.
5155 If you give a zero prefix (i. e., @kbd{C-u 0 C-c C-c}) to that command,
5156 Gnus will prompt you for what method to use for posting.
5158 You can also set @code{gnus-post-method} to a list of select methods.
5159 If that's the case, Gnus will always prompt you for what method to use
5164 @subsection Mail & Post
5166 Commands for sending mail and post at the same time:
5170 @kindex S b (Summary)
5171 @findex gnus-summary-followup-and-reply
5172 Post a followup and send a reply to the current article
5173 (@code{gnus-summary-followup-and-reply}).
5176 @kindex S B (Summary)
5177 @findex gnus-summary-followup-and-reply-with-original
5178 Post a followup and send a reply to the current article and include the
5179 original message (@code{gnus-summary-followup-and-reply-with-original}).
5180 This command uses the process/prefix convention.
5183 Here's a list of variables that are relevant to both mailing and
5187 @item gnus-signature-file
5188 @itemx mail-signature
5189 @vindex mail-signature
5190 @vindex gnus-signature-file
5191 @cindex double signature
5193 If @code{gnus-signature-file} is non-@code{nil}, it should be the name
5194 of a file containing a signature (@samp{~/.signature} by default). This
5195 signature will be appended to all outgoing post. Most people find it
5196 more convenient to use @code{mail-signature}, which (sort of) does the
5197 same, but inserts the signature into the buffer before you start editing
5198 the post (or mail). So---if you have both of these variables set, you
5199 will get two signatures. Note that @code{mail-signature} does not work
5200 the same way as @code{gnus-signature-file}, which is a bit confusing.
5201 If @code{mail-signature} is @code{t}, it will insert
5202 @file{~/.signature}. If it is a string, this string will be inserted.
5204 Note that RFC1036 says that a signature should be preceded by the three
5205 characters @samp{-- } on a line by themselves. This is to make it
5206 easier for the recipient to automatically recognize and process the
5207 signature. So don't remove those characters, even though you might feel
5208 that they ruin you beautiful design, like, totally.
5210 Also note that no signature should be more than four lines long.
5211 Including ASCII graphics is an efficient way to get everybody to believe
5212 that you are silly and have nothing important to say.
5214 @item mail-yank-prefix
5215 @vindex mail-yank-prefix
5218 When you are replying to or following up an article, you normally want
5219 to quote the person you are answering. Inserting quoted text is done by
5220 @dfn{yanking}, and each quoted line you yank will have
5221 @code{mail-yank-prefix} prepended to it. This is @code{nil} by default,
5222 which isn't very pretty---the prefix will just be some spaces. Most
5223 everybody prefers that lines are prepended with @samp{> }, so
5224 @code{(setq mail-yank-prefix "> ")} in your @file{.emacs} file.
5226 @item mail-yank-ignored-headers
5227 @vindex mail-yank-ignored-headers
5228 When you yank a message, you do not want to quote any headers, so
5229 @code{(setq mail-yank-ignored-headers "^")}.
5231 @item user-mail-address
5232 @vindex user-mail-address
5233 If all of @code{gnus-user-login-name}, @code{gnus-use-generic-from} and
5234 @code{gnus-local-domain} are @code{nil}, Gnus will use
5235 @code{user-mail-address} as the address part of the @code{From} header.
5237 @item gnus-local-domain
5238 @vindex gnus-local-domain
5240 The local doman name excluding the host name. If your host is called
5241 @samp{"narfi.ifi.uio.no"}, then this variable should be
5242 @samp{"ifi.uio.no"}.
5244 @item gnus-local-domain
5245 @vindex gnus-local-domain
5247 The local doman name excluding the host name. If your host is called
5248 @samp{"narfi.ifi.uio.no"}, then this variable should be
5249 @samp{"ifi.uio.no"}.
5251 @item gnus-user-from-line
5252 @vindex gnus-user-from-line
5253 Your full, complete e-mail address with name. This variable overrides
5254 the other Gnus variables if it is non-@code{nil}.
5256 Here are two example values of this variable: @samp{"larsi@@ifi.uio.no
5257 (Lars Magne Ingebrigtsen)"} and @samp{"Lars Magne Ingebrigtsen
5258 <larsi@@ifi.uio.no>"}. The latter version is recommended in news (and is
5259 probably illegal in mail), but the name has to be quoted if it contains
5260 non-alpha-numerical characters---@samp{"\"Lars M. Ingebrigtsen\"
5261 <larsi@@ifi.uio.no>"}.
5263 @item mail-default-headers
5264 @vindex mail-default-headers
5265 This is a string that will be inserted into the header of all outgoing
5266 mail messages and news articles. Convenient to use to insert standard
5267 headers. If @code{nntp-news-default-headers} is non-@code{nil}, that
5268 variable will override this one when posting articles.
5270 @item gnus-auto-mail-to-author
5271 @vindex gnus-auto-mail-to-author
5272 If @code{ask}, you will be prompted for whether you want to send a mail
5273 copy to the author of the article you are following up. If
5274 non-@code{nil} and not @code{ask}, Gnus will send a mail with a copy of
5275 all follow-ups to the authors of the articles you follow up. It's nice
5276 in one way---you make sure that the person you are responding to gets
5277 your response. Other people loathe this method and will hate you dearly
5278 for it, because it means that they will first get a mail, and then have
5279 to read the same article later when they read the news. It is
5280 @code{nil} by default.
5282 @item gnus-mail-courtesy-message
5283 @vindex gnus-mail-courtesy-message
5284 This is a string that will be prepended to all mails that are the result
5285 of using the variable described above.
5287 @item gnus-mailing-list-groups
5288 @findex gnus-mailing-list-groups
5289 @cindex mailing lists
5291 If your newsserver offer groups that are really mailing lists that are
5292 gatewayed to the @sc{nntp} server, you can read those groups without
5293 problems, but you can't post/followup to them without some difficulty.
5294 One solution is to add a @code{to-address} to the group parameters
5295 (@pxref{Group Parameters}). An easier thing to do is set the
5296 @code{gnus-mailing-list-groups} to a regexp that match the groups that
5297 really are mailing lists. Then, at least, followups to the mailing
5298 lists will work most of the time. Posting to these groups (@kbd{a}) is
5299 still a pain, though.
5304 You may want to do spell-checking on messages that you send out. Or, if
5305 you don't want to spell-check by hand, you could add automatic
5306 spell-checking via the @code{ispell} package:
5308 @vindex news-inews-hook
5310 (add-hook 'news-inews-hook 'ispell-message) ;For news posts
5311 (add-hook 'mail-send-hook 'ispell-message) ;for mail posts via sendmail
5314 @findex gnus-inews-insert-mime-headers
5315 If you want to insert some @sc{mime} headers into the articles you post,
5316 without doing any actual encoding, you could add
5317 @code{gnus-inews-insert-mime-headers} to @code{gnus-inews-article-hook}.
5321 @node Archived Messages
5322 @subsection Archived Messages
5323 @cindex archived messages
5324 @cindex sent messages
5326 Gnus provides a few different methods for storing the mail you send.
5327 The default method is to use the @dfn{archive virtual server} to store
5330 @vindex gnus-message-archive-method
5331 @code{gnus-message-archive-method} says what virtual server Gnus is to
5332 use to store sent messages. It is @code{(nnfolder "archive"
5333 (nnfolder-directory "~/Mail/archive/"))} by default, but you can use any
5334 mail select method (@code{nnml}, @code{nnmbox}, etc.). However,
5335 @code{nnfolder} is a quite likable select method for doing this sort of
5336 thing. If you don't like the default directory chosen, you could say
5340 (setq gnus-message-archive-method
5341 '((nnfolder "archive"
5342 (nnfolder-inhibit-expiry t)
5343 (nnfolder-active-file "~/Mail/sent-mail/active")
5344 (nnfolder-directory "~/News/sent-mail/"))))
5347 @vindex gnus-message-archive-group
5348 Gnus will insert @code{Gcc} headers in all outgoing messages that point
5349 to one or more group(s) on that server. Which group to use is
5350 determined by the @code{gnus-message-archive-group} variable.
5352 This variable can be:
5356 Messages will be saved in that group.
5357 @item a list of strings
5358 Messages will be saved in all those groups.
5359 @item an alist of regexps, functions and forms
5360 When a key "matches", the result is used.
5365 Just saving to a single group called @samp{"MisK"}:
5367 (setq gnus-message-archive-group "MisK")
5370 Saving to two groups, @samp{"MisK"} and @samp{"safe"}:
5372 (setq gnus-message-archive-group '("MisK" "safe"))
5375 Save to different groups based on what group you are in:
5377 (setq gnus-message-archive-group
5378 '(("^alt" "sent-to-alt")
5379 ("mail" "sent-to-mail")
5380 (".*" "sent-to-misc")))
5385 (setq gnus-message-archive-group
5386 '((if (eq major-mode news-reply-mode) "misc-news" "misc-mail)))
5389 This last one is the default.
5391 Now, when you send a message off, it will be stored in the appropriate
5392 group. (If you want to disable storing for just one particular article,
5393 you can just remove the @code{Gcc} header that has been inserted.) The
5394 archive group will appear in the group buffer the next time you start
5395 Gnus, or the next time you press @key{F} in the group buffer. You can
5396 enter it and read the articles in it just like you'd read any other
5397 group. If the group gets really big and annoying, you can simply rename
5398 if (using @kbd{G r} in the group buffer) to something nice --
5399 @samp{"misc-mail-september-1995"}, or whatever. New messages will
5400 continue to be stored in the old (now empty) group.
5403 That's the default method of archiving sent mail. Gnus also offers two
5404 other variables for the people who don't like the default method. In
5405 that case you should set @code{gnus-message-archive-group} to
5406 @code{nil}; this will disable archiving.
5409 @item gnus-author-copy
5410 @vindex gnus-author-copy
5411 This is a file name, and all outgoing articles will be saved in that
5412 file. Initialized from the @code{AUTHORCOPY} environment variable.
5414 If this variable begins with the character @samp{"|"}, outgoing articles
5415 will be piped to the named program. It is possible to save an article in
5416 an MH folder as follows:
5419 (setq gnus-author-copy
5420 "|/usr/local/lib/mh/rcvstore +Article")
5423 If the first character is not a pipe, articles are saved using the
5424 function specified by the @code{gnus-author-copy-saver} variable.
5426 @item gnus-author-copy-saver
5427 @vindex gnus-author-copy-saver
5428 A function called to save outgoing articles. This function will be
5429 called with the same of the file to store the article in. The default
5430 function is @code{rmail-output} which saves in the Unix mailbox format.
5432 @item gnus-mail-self-blind
5433 @vindex gnus-mail-self-blind
5434 Non-@code{nil} means insert a BCC header in all outgoing articles
5435 pointing to yourself. This will result you receiving a copy of the
5436 article mailed to yourself. The BCC header is inserted when the post
5437 buffer is initialized, so you can remove or alter the BCC header to
5438 override the default.
5440 @item gnus-outgoing-message-group
5441 @vindex gnus-outgoing-message-group
5442 All outgoing messages will be put in this group. If you want to store
5443 all your outgoing mail and articles in the group @samp{nnml:archive},
5444 you set this variable to that value. This variable can also be a list of
5447 If you want to have greater control over what group to put each
5448 message in, you can set this variable to a function that checks the
5449 current newsgroup name and then returns a suitable group name (or list
5454 @node Posting Styles
5455 @subsection Posting Styles
5456 @cindex posting styles
5459 All them variables, they make my head swim.
5461 So what if you want a different @code{Organization} and signature based
5462 on what groups you post to? And you post both from your home machine
5463 and your work machine, and you want different @code{From} lines, and so
5466 @vindex gnus-posting-styles
5467 One way to do stuff like that is to write clever hooks that change the
5468 variables you need to have changed. That's a bit boring, so somebody
5469 came up with the bright idea of letting the user specify these things in
5470 a handy alist. Here's an example of a @code{gnus-posting-styles}
5474 ((".*" (signature . "Peace and happiness") (organization . "What me?"))
5475 ("^comp" (signature . "Death to everybody"))
5476 ("comp.emacs.i-love-it" (organization . "Emacs is it")))
5479 As you might surmise from this example, this alist consists of several
5480 @dfn{styles}. Each style will be applicable if the first element
5481 "matches", in some form or other. The entire alist will be iterated
5482 over, from the beginning towards the end, and each match will be
5483 applied, which means that attributes in later styles that match override
5484 the same attributes in earlier matching styles. So
5485 @samp{comp.programming.literate} will have the @samp{Death to everybody}
5486 signature and the @samp{What me?} @code{Organization} header.
5488 The first element in each style is called the @code{match}. If it's a
5489 string, then Gnus will try to regexp match it against the group name.
5490 If it's a function symbol, that function will be called with no
5491 arguments. If it's a variable symbol, then the variable will be
5492 referenced. If it's a list, then that list will be @code{eval}ed. In
5493 any case, if this returns a non-@code{nil} value, then the style is said
5496 Each style may contain a random amount of @dfn{attributes}. Each
5497 attribute consists of a @var{(name . value)} pair. The attribute name
5498 can be one of @code{signature}, @code{organization} or @code{from}.
5499 The attribute name can also be a string. In that case, this will be
5500 used as a header name, and the value will be inserted in the headers of
5503 The attribute value can be a string (used verbatim), a function (the
5504 return value will be used), a variable (its value will be used) or a
5505 list (it will be @code{eval}ed and the return value will be used).
5507 So here's a new example:
5510 (setq gnus-posting-styles
5512 (signature . "~/.signature")
5513 (from . "user@@foo (user)")
5514 ("X-Home-Page" . (getenv "WWW_HOME"))
5515 (organization . "People's Front Against MWM"))
5517 (signature . my-funny-signature-randomizer))
5518 ((equal (system-name) "gnarly")
5519 (signature . my-quote-randomizer))
5520 (posting-from-work-p
5521 (signature . "~/.work-signature")
5522 (from . "user@@bar.foo (user)")
5523 (organization . "Important Work, Inc"))
5525 (signature . "~/.mail-signature"))))
5534 If you are writing a message (mail or news) and suddenly remember that
5535 you have a steak in the oven (or some pesto in the food processor, you
5536 craazy vegetarians), you'll probably wish there was a method to save the
5537 message you are writing so that you can continue editing it some other
5538 day, and send it when you feel its finished.
5540 Well, don't worry about it. Whenever you start composing a message of
5541 some sort using the Gnus mail and post commands, the buffer you get will
5542 automatically associate to an article in a special @dfn{draft} group.
5543 If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the
5544 article will be saved there. (Auto-save files also go to the draft
5547 The draft group is a special group (which is implemented as an
5548 @code{nndraft} group, if you absolutely have to know) called
5549 @samp{nndraft:drafts}. The variable @code{gnus-draft-group-directory}
5550 controls both the name of the group and the location---the leaf element
5551 in the path will be used as the name of the group. What makes this
5552 group special is that you can't tick any articles in it or mark any
5553 articles as read---all articles in the group are permanently unread.
5555 If the group doesn't exist, it will be created and you'll be subscribed
5558 @findex gnus-dissociate-buffer-from-draft
5559 @kindex C-c M-d (Mail)
5560 @kindex C-c M-d (Post)
5561 @findex gnus-associate-buffer-with-draft
5562 @kindex C-c C-d (Mail)
5563 @kindex C-c C-d (Post)
5564 If you're writing some super-secret message that you later want to
5565 encode with PGP before sending, you may wish to turn the auto-saving
5566 (and association with the draft group) off. You never know who might be
5567 interested in reading all your extremely valuable and terribly horrible
5568 and interesting secrets. The @kbd{C-c M-d}
5569 (@code{gnus-dissociate-buffer-from-draft}) command does that for you.
5570 If you change your mind and want to turn the auto-saving back on again,
5571 @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that.
5573 @vindex gnus-use-draft
5574 To leave association with the draft group off by default, set
5575 @code{gnus-use-draft} to @code{nil}. It is @code{t} by default.
5577 @findex gnus-summary-send-draft
5578 @kindex S D c (Summary)
5579 When you want to continue editing the article, you simply enter the
5580 draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
5581 that. You will be placed in a buffer where you left off.
5583 Rejected articles will also be put in this draft group (@pxref{Rejected
5586 @findex gnus-summary-send-all-drafts
5587 If you have lots of rejected messages you want to post (or mail) without
5588 doing further editing, you can use the @kbd{S D a} command
5589 (@code{gnus-summary-send-all-drafts}). This command understands the
5590 process/prefix convention (@pxref{Process/Prefix}).
5593 @node Rejected Articles
5594 @subsection Rejected Articles
5595 @cindex rejected articles
5597 Sometimes a news server will reject an article. Perhaps the server
5598 doesn't like your face. Perhaps it just feels miserable. Perhaps
5599 @emph{there be demons}. Perhaps you have included too much cited text.
5600 Perhaps the disk is full. Perhaps the server is down.
5602 These situations are, of course, totally beyond the control of Gnus.
5603 (Gnus, of course, loves the way you look, always feels great, has angels
5604 fluttering around inside of it, doesn't care about how much cited text
5605 you include, never runs full and never goes down.) So Gnus saves these
5606 articles until some later time when the server feels better.
5608 The rejected articles will automatically be put in a special draft group
5609 (@pxref{Drafts}). When the server comes back up again, you'd then
5610 typically enter that group and send all the articles off.
5613 @node Canceling and Superseding
5614 @section Canceling Articles
5615 @cindex canceling articles
5616 @cindex superseding articles
5618 Have you ever written something, and then decided that you really,
5619 really, really wish you hadn't posted that?
5621 Well, you can't cancel mail, but you can cancel posts.
5623 @findex gnus-summary-cancel-article
5625 Find the article you wish to cancel (you can only cancel your own
5626 articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
5627 c} (@code{gnus-summary-cancel-article}). Your article will be
5628 canceled---machines all over the world will be deleting your article.
5630 Be aware, however, that not all sites honor cancels, so your article may
5631 live on here and there, while most sites will delete the article in
5634 If you discover that you have made some mistakes and want to do some
5635 corrections, you can post a @dfn{superseding} article that will replace
5636 your original article.
5638 @findex gnus-summary-supersede-article
5640 Go to the original article and press @kbd{S s}
5641 (@code{gnus-summary-supersede-article}). You will be put in a buffer
5642 where you can edit the article all you want before sending it off the
5645 @vindex gnus-delete-supersedes-headers
5646 You probably want to delete some of the old headers before sending the
5647 superseding article---@code{Path} and @code{Date} are probably
5648 incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
5649 match the lines you want removed. The default is
5650 @samp{"^Path:\\|^Date"}.
5652 The same goes for superseding as for canceling, only more so: Some
5653 sites do not honor superseding. On those sites, it will appear that you
5654 have posted almost the same article twice.
5656 If you have just posted the article, and change your mind right away,
5657 there is a trick you can use to cancel/supersede the article without
5658 waiting for the article to appear on your site first. You simply return
5659 to the post buffer (which is called @code{*post-buf*}). There you will
5660 find the article you just posted, with all the headers intact. Change
5661 the @samp{Message-ID} header to a @samp{Cancel} or @samp{Supersedes}
5662 header by substituting one of those words for @samp{Message-ID}. Then
5663 just press @kbd{C-c C-c} to send the article as you would do normally.
5664 The previous article will be canceled/superseded.
5666 Just remember, kids: There is no 'c' in 'supersede'.
5668 @node Marking Articles
5669 @section Marking Articles
5670 @cindex article marking
5671 @cindex article ticking
5674 There are several marks you can set on an article.
5676 You have marks that decide the @dfn{readed-ness} (whoo, neato-keano
5677 neologism ohoy!) of the article. Alphabetic marks generally mean
5678 @dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
5680 In addition, you also have marks that do not affect readedness.
5683 * Unread Articles:: Marks for unread articles.
5684 * Read Articles:: Marks for read articles.
5685 * Other Marks:: Marks that do not affect readedness.
5689 There's a plethora of commands for manipulating these marks:
5693 * Setting Marks:: How to set and remove marks.
5694 * Setting Process Marks:: How to mark articles for later processing.
5697 @node Unread Articles
5698 @subsection Unread Articles
5700 The following marks mark articles as unread, in one form or other.
5702 @vindex gnus-dormant-mark
5703 @vindex gnus-ticked-mark
5706 @dfn{Ticked articles} are articles that will remain visible always. If
5707 you see an article that you find interesting, or you want to put off
5708 reading it, or replying to it, until sometime later, you'd typically
5709 tick it. However, articles can be expired, so if you want to keep an
5710 article forever, you'll have to save it. Ticked articles have a
5711 @samp{!} (@code{gnus-ticked-mark}) in the first column.
5714 A @dfn{dormant} article is marked with a @samp{?}
5715 (@code{gnus-dormant-mark}), and will only appear in the summary buffer
5716 if there are followups to it.
5719 An @dfn{unread} article is marked with a @samp{SPC}
5720 (@code{gnus-unread-mark}). These are articles that haven't been read at
5725 @subsection Read Articles
5726 @cindex expirable mark
5728 All the following marks mark articles as read.
5733 Articles that are marked as read. They have a @samp{r}
5734 (@code{gnus-del-mark}) in the first column. These are articles that the
5735 user has marked as read more or less manually.
5738 Articles that are actually read are marked with @samp{R}
5739 (@code{gnus-read-mark}).
5742 Articles that were marked as read in previous sessions are now
5743 @dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
5746 Marked as killed (@code{gnus-killed-mark}).
5749 Marked as killed by kill files (@code{gnus-kill-file-mark}).
5752 Marked as read by having a too low score (@code{gnus-low-score-mark}).
5755 Marked as read by a catchup (@code{gnus-catchup-mark}).
5758 Canceled article (@code{gnus-cancelled-mark})
5761 All these marks just mean that the article is marked as read, really.
5762 They are interpreted differently by the adaptive scoring scheme,
5765 One more special mark, though:
5769 You can also mark articles as @dfn{expirable} (or have them marked as
5770 such automatically). That doesn't make much sense in normal groups,
5771 because a user does not control the expiring of news articles, but in
5772 mail groups, for instance, articles that are marked as @dfn{expirable}
5773 can be deleted by Gnus at any time. Expirable articles are marked with
5774 @samp{E} (@code{gnus-expirable-mark}).
5778 @subsection Other Marks
5779 @cindex process mark
5782 There are some marks that have nothing to do with whether the article is
5788 You can set a bookmark in the current article. Say you are reading a
5789 long thesis on cats' urinary tracts, and have to go home for dinner
5790 before you've finished reading the thesis. You can then set a bookmark
5791 in the article, and Gnus will jump to this bookmark the next time it
5792 encounters the article.
5795 All articles that you have replied to or made a followup to (i.e., have
5796 answered) will be marked with an @samp{A} in the second column
5797 (@code{gnus-replied-mark}).
5800 Articles that are stored in the article cache will be marked with an
5801 @samp{*} in the second column (@code{gnus-cached-mark}).
5804 Articles that are "saved" (in some manner or other; not necessarily
5805 religously) are marked with an @samp{S} in the second column
5806 (@code{gnus-saved-mark}.
5809 @vindex gnus-not-empty-thread-mark
5810 @vindex gnus-empty-thread-mark
5811 It the @samp{%e} spec is used, the presence of threads or not will be
5812 marked with @code{gnus-not-empty-thread-mark} and
5813 @code{gnus-empty-thread-mark} in the third column, respectively.
5816 @vindex gnus-process-mark
5817 Finally we have the @dfn{process mark} (@code{gnus-process-mark}. A
5818 variety of commands react to the presence of the process mark. For
5819 instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
5820 all articles that have been marked with the process mark. Articles
5821 marked with the process mark have a @samp{#} in the second column.
5825 You might have noticed that most of these "non-readedness" marks appear
5826 in the second column by default. So if you have a cached, saved,
5827 replied article that you have process-marked, what will that look like?
5829 Nothing much. The presedence rules go as follows: process -> cache ->
5830 replied -> saved. So if the article is in the cache and is replied,
5831 you'll only see the cache mark and not the replied mark.
5835 @subsection Setting Marks
5836 @cindex setting marks
5838 All the marking commands understand the numeric prefix.
5844 @kindex M t (Summary)
5845 @findex gnus-summary-tick-article-forward
5846 Tick the current article (@code{gnus-summary-tick-article-forward}).
5851 @kindex M ? (Summary)
5852 @findex gnus-summary-mark-as-dormant
5853 Mark the current article as dormant
5854 (@code{gnus-summary-mark-as-dormant}).
5858 @kindex M d (Summary)
5860 @findex gnus-summary-mark-as-read-forward
5861 Mark the current article as read
5862 (@code{gnus-summary-mark-as-read-forward}).
5867 @kindex M k (Summary)
5868 @findex gnus-summary-kill-same-subject-and-select
5869 Mark all articles that have the same subject as the current one as read,
5870 and then select the next unread article
5871 (@code{gnus-summary-kill-same-subject-and-select}).
5875 @kindex M K (Summary)
5876 @kindex C-k (Summary)
5877 @findex gnus-summary-kill-same-subject
5878 Mark all articles that have the same subject as the current one as read
5879 (@code{gnus-summary-kill-same-subject}).
5882 @kindex M C (Summary)
5883 @findex gnus-summary-catchup
5884 Mark all unread articles in the group as read
5885 (@code{gnus-summary-catchup}).
5888 @kindex M C-c (Summary)
5889 @findex gnus-summary-catchup-all
5890 Mark all articles in the group as read---even the ticked and dormant
5891 articles (@code{gnus-summary-catchup-all}).
5894 @kindex M H (Summary)
5895 @findex gnus-summary-catchup-to-here
5896 Catchup the current group to point
5897 (@code{gnus-summary-catchup-to-here}).
5900 @kindex C-w (Summary)
5901 @findex gnus-summary-mark-region-as-read
5902 Mark all articles between point and mark as read
5903 (@code{gnus-summary-mark-region-as-read}).
5906 @kindex M V k (Summary)
5907 @findex gnus-summary-kill-below
5908 Kill all articles with scores below the default score (or below the
5909 numeric prefix) (@code{gnus-summary-kill-below}).
5913 @kindex M c (Summary)
5914 @kindex M-u (Summary)
5915 @findex gnus-summary-clear-mark-forward
5916 Clear all readedness-marks from the current article
5917 (@code{gnus-summary-clear-mark-forward}).
5921 @kindex M e (Summary)
5923 @findex gnus-summary-mark-as-expirable
5924 Mark the current article as expirable
5925 (@code{gnus-summary-mark-as-expirable}).
5928 @kindex M b (Summary)
5929 @findex gnus-summary-set-bookmark
5930 Set a bookmark in the current article
5931 (@code{gnus-summary-set-bookmark}).
5934 @kindex M B (Summary)
5935 @findex gnus-summary-remove-bookmark
5936 Remove the bookmark from the current article
5937 (@code{gnus-summary-remove-bookmark}).
5940 @kindex M V c (Summary)
5941 @findex gnus-summary-clear-above
5942 Clear all marks from articles with scores over the default score (or
5943 over the numeric prefix) (@code{gnus-summary-clear-above}).
5946 @kindex M V u (Summary)
5947 @findex gnus-summary-tick-above
5948 Tick all articles with scores over the default score (or over the
5949 numeric prefix) (@code{gnus-summary-tick-above}).
5952 @kindex M V m (Summary)
5953 @findex gnus-summary-mark-above
5954 Prompt for a mark, and mark all articles with scores over the default
5955 score (or over the numeric prefix) with this mark
5956 (@code{gnus-summary-clear-above}).
5959 @code{gnus-summary-goto-unread} The @code{gnus-summary-goto-unread}
5960 variable controls what action should be taken after setting a mark. If
5961 non-@code{nil}, point will move to the next/previous unread article. If
5962 @code{nil}, point will just move one line up or down. As a special
5963 case, if this variable is @code{never}, all the marking commands as well
5964 as other commands (like @kbd{SPC}) will move to the next article,
5965 whether it is unread or not. The default is @code{t}.
5968 @node Setting Process Marks
5969 @subsection Setting Process Marks
5970 @cindex setting process marks
5977 @kindex M P p (Summary)
5978 @findex gnus-summary-mark-as-processable
5979 Mark the current article with the process mark
5980 (@code{gnus-summary-mark-as-processable}).
5981 @findex gnus-summary-unmark-as-processable
5985 @kindex M P u (Summary)
5986 @kindex M-# (Summary)
5987 Remove the process mark, if any, from the current article
5988 (@code{gnus-summary-unmark-as-processable}).
5991 @kindex M P U (Summary)
5992 @findex gnus-summary-unmark-all-processable
5993 Remove the process mark from all articles
5994 (@code{gnus-summary-unmark-all-processable}).
5997 @kindex M P R (Summary)
5998 @findex gnus-uu-mark-by-regexp
5999 Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
6002 @kindex M P r (Summary)
6003 @findex gnus-uu-mark-region
6004 Mark articles in region (@code{gnus-uu-mark-region}).
6007 @kindex M P t (Summary)
6008 @findex gnus-uu-mark-thread
6009 Mark all articles in the current (sub)thread
6010 (@code{gnus-uu-mark-thread}).
6013 @kindex M P T (Summary)
6014 @findex gnus-uu-unmark-thread
6015 Unmark all articles in the current (sub)thread
6016 (@code{gnus-uu-unmark-thread}).
6019 @kindex M P v (Summary)
6020 @findex gnus-uu-mark-over
6021 Mark all articles that have a score above the prefix argumnet
6022 (@code{gnus-uu-mark-over}).
6025 @kindex M P s (Summary)
6026 @findex gnus-uu-mark-series
6027 Mark all articles in the current series (@code{gnus-uu-mark-series}).
6030 @kindex M P S (Summary)
6031 @findex gnus-uu-mark-sparse
6032 Mark all series that have already had some articles marked
6033 (@code{gnus-uu-mark-sparse}).
6036 @kindex M P a (Summary)
6037 @findex gnus-uu-mark-all
6038 Mark all articles in series order (@code{gnus-uu-mark-series}).
6041 @kindex M P b (Summary)
6042 @findex gnus-uu-mark-buffer
6043 Mark all articles in the buffer in the order they appear
6044 (@code{gnus-uu-mark-buffer}).
6052 It can be convenient to limit the summary buffer to just show some
6053 subset of the articles currently in the group. The effect most limit
6054 commands have is to remove a few (or many) articles from the summary
6061 @kindex / / (Summary)
6062 @findex gnus-summary-limit-to-subject
6063 Limit the summary buffer to articles that match some subject
6064 (@code{gnus-summary-limit-to-subject}).
6067 @kindex / a (Summary)
6068 @findex gnus-summary-limit-to-author
6069 Limit the summary buffer to articles that match some author
6070 (@code{gnus-summary-limit-to-author}).
6074 @kindex / u (Summary)
6076 @findex gnus-summary-limit-to-unread
6077 Limit the summary buffer to articles that are not marked as read
6078 (@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
6079 buffer to articles that are strictly unread. This means that ticked and
6080 dormant articles will also be excluded.
6083 @kindex / m (Summary)
6084 @findex gnus-summary-limit-to-marks
6085 Ask for a mark and then limit to all articles that have not been marked
6086 with that mark (@code{gnus-summary-limit-to-marks}).
6089 @kindex / n (Summary)
6090 @findex gnus-summary-limit-to-articles
6091 Limit the summary buffer to the current article
6092 (@code{gnus-summary-limit-to-articles}). Uses the process/prefix
6093 convention (@pxref{Process/Prefix}).
6096 @kindex / w (Summary)
6097 @findex gnus-summary-pop-limit
6098 Pop the previous limit off the stack and restore it
6099 (@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
6103 @kindex / v (Summary)
6104 @findex gnus-summary-limit-to-score
6105 Limit the summary buffer to articles that have a score at or above some
6106 score (@code{gnus-summary-limit-to-score}).
6110 @kindex M S (Summary)
6111 @kindex / E (Summary)
6112 @findex gnus-summary-limit-include-expunged
6113 Display all expunged articles
6114 (@code{gnus-summary-limit-include-expunged}).
6117 @kindex / D (Summary)
6118 @findex gnus-summary-limit-include-dormant
6119 Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
6122 @kindex / d (Summary)
6123 @findex gnus-summary-limit-exclude-dormant
6124 Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
6127 @kindex / c (Summary)
6128 @findex gnus-summary-limit-exclude-childless-dormant
6129 Hide all dormant articles that have no children
6130 (@code{gnus-summary-limit-exclude-childless-dormant}).
6133 @kindex / C (Summary)
6134 @findex gnus-summary-limit-mark-excluded-as-read
6135 Mark all excluded unread articles as read
6136 (@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix,
6137 also mark exluded ticked and dormant articles as read.
6145 @cindex article threading
6147 Gnus threads articles by default. @dfn{To thread} is to put replies to
6148 articles directly after the articles they reply to---in a hierarchical
6152 * Customizing Threading:: Variables you can change to affect the threading.
6153 * Thread Commands:: Thread based commands in the summary buffer.
6156 @node Customizing Threading
6157 @subsection Customizing Threading
6158 @cindex customizing threading
6164 @item gnus-show-threads
6165 @vindex gnus-show-threads
6166 If this variable is @code{nil}, no threading will be done, and all of
6167 the rest of the variables here will have no effect. Turning threading
6168 off will speed group selection up a bit, but it is sure to make reading
6169 slower and more awkward.
6171 @item gnus-fetch-old-headers
6172 @vindex gnus-fetch-old-headers
6173 If non-@code{nil}, Gnus will attempt to build old threads by fetching
6174 more old headers---headers to articles that are marked as read. If you
6175 would like to display as few summary lines as possible, but still
6176 connect as many loose threads as possible, you should set this variable
6177 to @code{some} or a number. If you set it to a number, no more than
6178 that number of extra old headers will be fetched. In either case,
6179 fetching old headers only works if the backend you are using carries
6180 overview files---this would normally be @code{nntp}, @code{nnspool} and
6181 @code{nnml}. Also remember that if the root of the thread has been
6182 expired by the server, there's not much Gnus can do about that.
6184 @item gnus-build-sparse-threads
6185 @vindex gnus-build-sparse-threads
6186 Fetching old headers can be slow. A low-rent similar effect can be
6187 gotten by setting this variable to @code{some}. Gnus will then look at
6188 the complete @code{References} headers of all articles and try to string
6189 articles that belong in the same thread together. This will leave
6190 @dfn{gaps} in the threading display where Gnus guesses that an article
6191 is missing from the thread. (These gaps appear like normal summary
6192 lines. If you select a gap, Gnus will try to fetch the article in
6193 question.) If this variable is @code{t}, Gnus will display all these
6194 "gaps" without regard for whether they are useful for completing the
6195 thread or not. Finally, if this variable is @code{more}, Gnus won't cut
6196 off sparse leaf nodes that don't lead anywhere. This variable is
6197 @code{nil} by default.
6199 @item gnus-summary-gather-subject-limit
6200 @vindex gnus-summary-gather-subject-limit
6201 Loose threads are gathered by comparing subjects of articles. If this
6202 variable is @code{nil}, Gnus requires an exact match between the
6203 subjects of the loose threads before gathering them into one big
6204 super-thread. This might be too strict a requirement, what with the
6205 presence of stupid newsreaders that chop off long subjects lines. If
6206 you think so, set this variable to, say, 20 to require that only the
6207 first 20 characters of the subjects have to match. If you set this
6208 variable to a really low number, you'll find that Gnus will gather
6209 everything in sight into one thread, which isn't very helpful.
6211 @cindex fuzzy article gathering
6212 If you set this variable to the special value @code{fuzzy}, Gnus will
6213 use a fuzzy string comparison algorithm on the subjects.
6215 @item gnus-simplify-ignored-prefixes
6216 @vindex gnus-simplify-ignored-prefixes
6217 If you set @code{gnus-summary-gather-subject-limit} to something as low
6218 as 10, you might consider setting this variable to something sensible:
6220 @c Written by Michael Ernst <mernst@cs.rice.edu>
6222 (setq gnus-simplify-ignored-prefixes
6225 (mapconcat 'identity
6227 "wanted" "followup" "summary\\( of\\)?"
6228 "help" "query" "problem" "question"
6229 "answer" "reference" "announce"
6230 "How can I" "How to" "Comparison of"
6235 (mapconcat 'identity
6236 '("for" "for reference" "with" "about")
6238 "\\)?\\]?:?[ \t]*"))
6241 @item gnus-summary-gather-exclude-subject
6242 @vindex gnus-summary-gather-exclude-subject
6243 Since loose thread gathering is done on subjects only, that might lead
6244 to many false hits, especially with certain common subjects like
6245 @samp{""} and @samp{"(none)"}. To make the situation slightly better,
6246 you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
6247 what subjects should be excluded from the gathering process. The
6248 default is @samp{"^ *$\\|^(none)$"}.
6250 @item gnus-summary-thread-gathering-function
6251 @vindex gnus-summary-thread-gathering-function
6252 Gnus gathers threads by looking at @code{Subject} headers. This means
6253 that totally unrelated articles may end up in the same "thread", which
6254 is confusing. An alternate approach is to look at all the
6255 @code{Message-ID}s in all the @code{References} headers to find
6256 matches. This will ensure that no gathered threads ever includes
6257 unrelated articles, but it's also means that people who have posted with
6258 broken newsreaders won't be gathered properly. The choice is
6259 yours---plague or cholera:
6262 @item gnus-summary-gather-threads-by-subject
6263 @findex gnus-summary-gather-threads-by-subject
6264 This function is the default gathering function and looks at
6265 @code{Subject}s exclusively.
6267 @item gnus-summary-gather-threads-by-references
6268 @findex gnus-summary-gather-threads-by-references
6269 This function looks at @code{References} headers exclusively.
6272 If you want to test gathering by @code{References}, you could say
6276 (setq gnus-summary-thread-gathering-function
6277 'gnus-summary-gather-threads-by-references)
6280 @item gnus-summary-make-false-root
6281 @vindex gnus-summary-make-false-root
6282 If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
6283 and create a dummy root at the top. (Wait a minute. Root at the top?
6284 Yup.) Loose subtrees occur when the real root has expired, or you've
6285 read or killed the root in a previous session.
6287 When there is no real root of a thread, Gnus will have to fudge
6288 something. This variable says what fudging method Gnus should use.
6289 There are four possible values:
6291 @cindex adopting articles
6296 Gnus will make the first of the orphaned articles the parent. This
6297 parent will adopt all the other articles. The adopted articles will be
6298 marked as such by pointy brackets (@samp{<>}) instead of the standard
6299 square brackets (@samp{[]}). This is the default method.
6302 Gnus will create a dummy summary line that will pretend to be the
6303 parent. This dummy line does not correspond to any real article, so
6304 selecting it will just select the first real article after the dummy
6308 Gnus won't actually make any article the parent, but simply leave the
6309 subject field of all orphans except the first empty. (Actually, it will
6310 use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
6314 Don't make any article parent at all. Just gather the threads and
6315 display them after one another.
6318 Don't gather loose threads.
6321 @item gnus-thread-hide-subtree
6322 @vindex gnus-thread-hide-subtree
6323 If non-@code{nil}, all threads will be hidden when the summary buffer is
6326 @item gnus-thread-hide-killed
6327 @vindex gnus-thread-hide-killed
6328 if you kill a thread and this variable is non-@code{nil}, the subtree
6331 @item gnus-thread-ignore-subject
6332 @vindex gnus-thread-ignore-subject
6333 Sometimes somebody changes the subject in the middle of a thread. If
6334 this variable is non-@code{nil}, the subject change is ignored. If it
6335 is @code{nil}, which is the default, a change in the subject will result
6338 @item gnus-thread-indent-level
6339 @vindex gnus-thread-indent-level
6340 This is a number that says how much each sub-thread should be indented.
6341 The default is @samp{4}.
6344 @node Thread Commands
6345 @subsection Thread Commands
6346 @cindex thread commands
6352 @kindex T k (Summary)
6353 @kindex M-C-k (Summary)
6354 @findex gnus-summary-kill-thread
6355 Mark all articles in the current sub-thread as read
6356 (@code{gnus-summary-kill-thread}). If the prefix argument is positive,
6357 remove all marks instead. If the prefix argument is negative, tick
6362 @kindex T l (Summary)
6363 @kindex M-C-l (Summary)
6364 @findex gnus-summary-lower-thread
6365 Lower the score of the current thread
6366 (@code{gnus-summary-lower-thread}).
6369 @kindex T i (Summary)
6370 @findex gnus-summary-raise-thread
6371 Increase the score of the current thread
6372 (@code{gnus-summary-raise-thread}).
6375 @kindex T # (Summary)
6376 @findex gnus-uu-mark-thread
6377 Set the process mark on the current thread
6378 (@code{gnus-uu-mark-thread}).
6381 @kindex T M-# (Summary)
6382 @findex gnus-uu-unmark-thread
6383 Remove the process mark from the current thread
6384 (@code{gnus-uu-unmark-thread}).
6387 @kindex T T (Summary)
6388 @findex gnus-summary-toggle-threads
6389 Toggle threading (@code{gnus-summary-toggle-threads}).
6392 @kindex T s (Summary)
6393 @findex gnus-summary-show-thread
6394 Expose the thread hidden under the current article, if any
6395 (@code{gnus-summary-show-thread}).
6398 @kindex T h (Summary)
6399 @findex gnus-summary-hide-thread
6400 Hide the current (sub)thread (@code{gnus-summary-hide-thread}).
6403 @kindex T S (Summary)
6404 @findex gnus-summary-show-all-threads
6405 Expose all hidden threads (@code{gnus-summary-show-all-threads}).
6408 @kindex T H (Summary)
6409 @findex gnus-summary-hide-all-threads
6410 Hide all threads (@code{gnus-summary-hide-all-threads}).
6413 @kindex T t (Summary)
6414 @findex gnus-summary-rethread-current
6415 Re-thread the thread the current article is part of
6416 (@code{gnus-summary-rethread-current}). This works even when the
6417 summary buffer is otherwise unthreaded.
6420 @kindex T ^ (Summary)
6421 @findex gnus-summary-reparent-thread
6422 Make the current article the child of the marked (or previous) article
6423 (@code{gnus-summary-reparent-thread}.
6427 The following commands are thread movement commands. They all
6428 understand the numeric prefix.
6433 @kindex T n (Summary)
6434 @findex gnus-summary-next-thread
6435 Go to the next thread (@code{gnus-summary-next-thread}).
6438 @kindex T p (Summary)
6439 @findex gnus-summary-prev-thread
6440 Go to the previous thread (@code{gnus-summary-prev-thread}).
6443 @kindex T d (Summary)
6444 @findex gnus-summary-down-thread
6445 Descend the thread (@code{gnus-summary-down-thread}).
6448 @kindex T u (Summary)
6449 @findex gnus-summary-up-thread
6450 Ascend the thread (@code{gnus-summary-up-thread}).
6453 @kindex T o (Summary)
6454 @findex gnus-summary-top-thread
6455 Go to the top of the thread (@code{gnus-summary-top-thread}).
6458 @vindex gnus-thread-operation-ignore-subject
6459 If you ignore subject while threading, you'll naturally end up with
6460 threads that have several different subjects in them. If you then issue
6461 a command like `T k' (@code{gnus-summary-kill-thread}) you might not
6462 wish to kill the entire thread, but just those parts of the thread that
6463 have the same subject as the current article. If you like this idea,
6464 you can fiddle with @code{gnus-thread-operation-ignore-subject}. If is
6465 is non-@code{nil} (which it is by default), subjects will be ignored
6466 when doing thread commands. If this variable is @code{nil}, articles in
6467 the same thread with different subjects will not be included in the
6468 operation in question. If this variable is @code{fuzzy}, only articles
6469 that have subjects that are fuzzily equal will be included.
6472 @node Asynchronous Fetching
6473 @section Asynchronous Article Fetching
6474 @cindex asynchronous article fetching
6476 If you read your news from an @sc{nntp} server that's far away, the
6477 network latencies may make reading articles a chore. You have to wait
6478 for a while after pressing @kbd{n} to go to the next article before the
6479 article appears. Why can't Gnus just go ahead and fetch the article
6480 while you are reading the previous one? Why not, indeed.
6482 First, some caveats. There are some pitfalls to using asynchronous
6483 article fetching, especially the way Gnus does it.
6485 Let's say you are reading article 1, which is short, and article 2 is
6486 quite long, and you are not interested in reading that. Gnus does not
6487 know this, so it goes ahead and fetches article 2. You decide to read
6488 article 3, but since Gnus is in the process of fetching article 2, the
6489 connection is blocked.
6491 To avoid these situations, Gnus will open two (count 'em two)
6492 connections to the server. Some people may think this isn't a very nice
6493 thing to do, but I don't see any real alternatives. Setting up that
6494 extra connection takes some time, so Gnus startup will be slower.
6496 Gnus will fetch more articles than you will read. This will mean that
6497 the link between your machine and the @sc{nntp} server will become more
6498 loaded than if you didn't use article pre-fetch. The server itself will
6499 also become more loaded---both with the extra article requests, and the
6502 Ok, so now you know that you shouldn't really use this thing... unless
6505 @vindex gnus-asynchronous
6506 Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
6507 happen automatically.
6509 @vindex nntp-async-number
6510 You can control how many articles that are to be pre-fetched by setting
6511 @code{nntp-async-number}. This is five by default, which means that when
6512 you read an article in the group, @code{nntp} will pre-fetch the next
6513 five articles. If this variable is @code{t}, @code{nntp} will pre-fetch
6514 all the articles that it can without bound. If it is @code{nil}, no
6515 pre-fetching will be made.
6517 @vindex gnus-asynchronous-article-function
6518 You may wish to create some sort of scheme for choosing which articles
6519 that @code{nntp} should consider as candidates for pre-fetching. For
6520 instance, you may wish to pre-fetch all articles with high scores, and
6521 not pre-fetch low-scored articles. You can do that by setting the
6522 @code{gnus-asynchronous-article-function}, which will be called with an
6523 alist where the keys are the article numbers. Your function should
6524 return an alist where the articles you are not interested in have been
6525 removed. You could also do sorting on article score and the like.
6527 @node Article Caching
6528 @section Article Caching
6529 @cindex article caching
6532 If you have an @emph{extremely} slow @sc{nntp} connection, you may
6533 consider turning article caching on. Each article will then be stored
6534 locally under your home directory. As you may surmise, this could
6535 potentially use @emph{huge} amounts of disk space, as well as eat up all
6536 your inodes so fast it will make your head swim. In vodka.
6538 Used carefully, though, it could be just an easier way to save articles.
6540 @vindex gnus-use-long-file-name
6541 @vindex gnus-cache-directory
6542 @vindex gnus-use-cache
6543 To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
6544 all articles that are ticked or marked as dormant will then be copied
6545 over to your local cache (@code{gnus-cache-directory}). Whether this
6546 cache is flat or hierarchal is controlled by the
6547 @code{gnus-use-long-file-name} variable, as usual.
6549 When re-select a ticked or dormant article, it will be fetched from the
6550 cache instead of from the server. As articles in your cache will never
6551 expire, this might serve as a method of saving articles while still
6552 keeping them where they belong. Just mark all articles you want to save
6553 as dormant, and don't worry.
6555 When an article is marked as read, is it removed from the cache.
6557 @vindex gnus-cache-remove-articles
6558 @vindex gnus-cache-enter-articles
6559 The entering/removal of articles from the cache is controlled by the
6560 @code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
6561 variables. Both are lists of symbols. The first is @code{(ticked
6562 dormant)} by default, meaning that ticked and dormant articles will be
6563 put in the cache. The latter is @code{(read)} by default, meaning that
6564 articles that are marked as read are removed from the cache. Possibly
6565 symbols in these two lists are @code{ticked}, @code{dormant},
6566 @code{unread} and @code{read}.
6568 @findex gnus-jog-cache
6569 So where does the massive article-fetching and storing come into the
6570 picture? The @code{gnus-jog-cache} command will go through all
6571 subscribed newsgroups, request all unread articles, and store them in
6572 the cache. You should only ever, ever ever ever, use this command if 1)
6573 your connection to the @sc{nntp} server is really, really, really slow
6574 and 2) you have a really, really, really huge disk. Seriously.
6576 @vindex gnus-uncacheable-groups
6577 It is likely that you do not want caching on some groups. For instance,
6578 if your @code{nnml} mail is located under your home directory, it makes no
6579 sense to cache it somewhere else under your home directory. Unless you
6580 feel that it's neat to use twice as much space. To limit the caching,
6581 you could set the @code{gnus-uncacheable-groups} regexp to
6582 @samp{"^nnml"}, for instance. This variable is @code{nil} by
6585 @findex gnus-cache-generate-nov-databases
6586 @findex gnus-cache-generate-active
6587 If your cache becomes all messed up for some reason or other, Gnus
6588 offers two functions that will try to set things right. @kbd{M-x
6589 gnus-cache-generate-nov-databases} will (re)build all the @sc{nov}
6590 files, and @kbd{gnus-cache-generate-active} will (re)generate the active
6594 @node Persistent Articles
6595 @section Persistent Articles
6596 @cindex persistent articles
6598 Closely related to article caching, we have @dfn{persistent articles}.
6599 In fact, it's just a different way of looking at caching, and much more
6600 useful in my opinion.
6602 Say you're reading a newsgroup, and you happen on to some valuable gem
6603 that you want to keep and treasure forever. You'd normally just save it
6604 (using one of the many saving commands) in some file. The problem with
6605 that is that it's just, well, yucky. Ideally you'd prefer just having
6606 the article remain in the group where you found it forever; untouched by
6607 the expiry going on at the news server.
6609 This is what a @dfn{persistent article} is---an article that just won't
6610 be deleted. It's implemented using the normal cache functions, but
6611 you use two explicit commands for managing persistent articles:
6617 @findex gnus-cache-enter-article
6618 Make the current article persistent (@code{gnus-cache-enter-article}).
6621 @kindex M-* (Summary)
6622 @findex gnus-cache-remove-article
6623 Remove the current article from the persistent articles
6624 (@code{gnus-cache-remove-article}). This will normally delete the
6628 Both these commands understand the process/prefix convention.
6630 To avoid having all ticked articles (and stuff) entered into the cache,
6631 you should set @code{gnus-use-cache} to @code{passive} if you're just
6632 interested in persistent articles:
6635 (setq gnus-use-cache 'passive)
6639 @node Article Backlog
6640 @section Article Backlog
6642 @cindex article backlog
6644 If you have a slow connection, but the idea of using caching seems
6645 unappealing to you (and it is, really), you can help the situation some
6646 by switching on the @dfn{backlog}. This is where Gnus will buffer
6647 already read articles so that it doesn't have to re-fetch articles
6648 you've already read. This only helps if you are in the habit of
6649 re-selecting articles you've recently read, of course. If you never do
6650 that, turning the backlog on will slow Gnus down a little bit, and
6651 increase memory usage some.
6653 @vindex gnus-keep-backlog
6654 If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store
6655 at most @var{n} old articles in a buffer for later re-fetching. If this
6656 variable is non-@code{nil} and is not a number, Gnus will store
6657 @emph{all} read articles, which means that your Emacs will group without
6658 bound before exploding and taking your machine down with you. I put
6659 that in there just to keep y'all on your toes.
6661 This variable is @code{nil} by default.
6664 @node Exiting the Summary Buffer
6665 @section Exiting the Summary Buffer
6666 @cindex summary exit
6668 Exiting from the summary buffer will normally update all info on the
6669 group and return you to the group buffer.
6675 @kindex Z Z (Summary)
6677 @findex gnus-summary-exit
6678 @vindex gnus-summary-exit-hook
6679 @vindex gnus-summary-prepare-exit-hook
6680 Exit the current group and update all information on the group
6681 (@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
6682 called before doing much of the exiting, and calls
6683 @code{gnus-summary-expire-articles} by default.
6684 @code{gnus-summary-exit-hook} is called after finishing the exiting
6689 @kindex Z E (Summary)
6691 @findex gnus-summary-exit-no-update
6692 Exit the current group without updating any information on the group
6693 (@code{gnus-summary-exit-no-update}).
6697 @kindex Z c (Summary)
6699 @findex gnus-summary-catchup-and-exit
6700 Mark all unticked articles in the group as read and then exit
6701 (@code{gnus-summary-catchup-and-exit}).
6704 @kindex Z C (Summary)
6705 @findex gnus-summary-catchup-all-and-exit
6706 Mark all articles, even the ticked ones, as read and then exit
6707 (@code{gnus-summary-catchup-all-and-exit}).
6710 @kindex Z n (Summary)
6711 @findex gnus-summary-catchup-and-goto-next-group
6712 Mark all articles as read and go to the next group
6713 (@code{gnus-summary-catchup-and-goto-next-group}).
6716 @kindex Z R (Summary)
6717 @findex gnus-summary-reselect-current-group
6718 Exit this group, and then enter it again
6719 (@code{gnus-summary-reselect-current-group}). If given a prefix, select
6720 all articles, both read and unread.
6724 @kindex Z G (Summary)
6725 @kindex M-g (Summary)
6726 @findex gnus-summary-rescan-group
6727 Exit the group, check for new articles in the group, and select the
6728 group (@code{gnus-summary-rescan-group}). If given a prefix, select all
6729 articles, both read and unread.
6732 @kindex Z N (Summary)
6733 @findex gnus-summary-next-group
6734 Exit the group and go to the next group
6735 (@code{gnus-summary-next-group}).
6738 @kindex Z P (Summary)
6739 @findex gnus-summary-prev-group
6740 Exit the group and go to the previous group
6741 (@code{gnus-summary-prev-group}).
6744 @vindex gnus-exit-group-hook
6745 @code{gnus-exit-group-hook} is called when you exit the current
6748 @findex gnus-summary-wake-up-the-dead
6749 @findex gnus-dead-summary-mode
6750 @vindex gnus-kill-summary-on-exit
6751 If you're in the habit of exiting groups, and then changing your mind
6752 about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}.
6753 If you do that, Gnus won't kill the summary buffer when you exit it.
6754 (Quelle surprise!) Instead it will change the name of the buffer to
6755 something like @samp{"*Dead Summary ... *"} and install a minor mode
6756 called @code{gnus-dead-summary-mode}. Now, if you switch back to this
6757 buffer, you'll find that all keys are mapped to a function called
6758 @code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead
6759 summary buffer will result in a live, normal summary buffer.
6761 There will never be more than one dead summary buffer at any one time.
6763 @vindex gnus-use-cross-reference
6764 The data on the current group will be updated (which articles you have
6765 read, which articles you have replied to, etc.) when you exit the
6766 summary buffer. If the @code{gnus-use-cross-reference} variable is
6767 @code{t} (which is the default), articles that are cross-referenced to
6768 this group and are marked as read, will also be marked as read in the
6769 other subscribed groups they were cross-posted to. If this variable is
6770 neither @code{nil} nor @code{t}, the article will be marked as read in
6771 both subscribed and unsubscribed groups.
6773 Marking cross-posted articles as read ensures that you'll never have to
6774 read the same article more than once. Unless, of course, somebody has
6775 posted it to several groups separately. Posting the same article to
6776 several groups (not cross-posting) is called @dfn{spamming}, and you are
6777 by law required to send nasty-grams to anyone who perpetrates such a
6780 Remember: Cross-posting is kinda ok, but posting the same article
6781 separately to several groups is not.
6783 One thing that may cause Gnus to not do the cross-posting thing
6784 correctly is if you use an @sc{nntp} server that supports @sc{xover}
6785 (which is very nice, because it speeds things up considerably) which
6786 does not include the @code{Xref} header in its @sc{nov} lines. This is
6787 Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
6788 even with @sc{xover} by registering the @code{Xref} lines of all
6789 articles you actually read, but if you kill the articles, or just mark
6790 them as read without reading them, Gnus will not get a chance to snoop
6791 the @code{Xref} lines out of these articles, and will be unable to use
6792 the cross reference mechanism.
6794 @vindex gnus-nov-is-evil
6795 If you want Gnus to get the @code{Xref}s right all the time, you have to
6796 set @code{gnus-nov-is-evil} to @code{t}, which slows things down
6802 @node Process/Prefix
6803 @section Process/Prefix
6804 @cindex process/prefix convention
6806 Many functions, among them functions for moving, decoding and saving
6807 articles, use what is known as the @dfn{Process/Prefix convention}.
6809 This is a method for figuring out what articles that the user wants the
6810 command to be performed on.
6814 If the numeric prefix is N, perform the operation on the next N
6815 articles, starting with the current one. If the numeric prefix is
6816 negative, perform the operation on the previous N articles, starting
6817 with the current one.
6819 If @code{transient-mark-mode} in non-@code{nil} and the region is
6820 active, all articles in the region will be worked upon.
6822 If there is no numeric prefix, but some articles are marked with the
6823 process mark, perform the operation on the articles that are marked with
6826 If there is neither a numeric prefix nor any articles marked with the
6827 process mark, just perform the operation on the current article.
6829 Quite simple, really, but it needs to be made clear so that surprises
6832 @vindex gnus-summary-goto-unread
6833 One thing that seems to shock & horrify lots of people is that, for
6834 instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}.
6835 Since each @kbd{d} (which marks the current article as read) by default
6836 goes to the next unread article after marking, this means that @kbd{3 d}
6837 will mark the next three unread articles as read, no matter what the
6838 summary buffer looks like. Set @code{gnus-summary-goto-unread} to
6839 @code{nil} for a more straightforward action.
6842 @node Saving Articles
6843 @section Saving Articles
6844 @cindex saving articles
6846 Gnus can save articles in a number of ways. Below is the documentation
6847 for saving articles in a fairly straight-forward fashion (i.e., little
6848 processing of the article is done before it is saved). For a different
6849 approach (uudecoding, unsharing) you should use @code{gnus-uu}
6850 (@pxref{Decoding Articles}).
6852 @vindex gnus-save-all-headers
6853 If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
6854 unwanted headers before saving the article.
6856 @vindex gnus-saved-headers
6857 If the preceeding variable is @code{nil}, all headers that match the
6858 @code{gnus-saved-headers} regexp will be kept, while the rest will be
6859 deleted before saving.
6865 @kindex O o (Summary)
6867 @findex gnus-summary-save-article
6868 Save the current article using the default article saver
6869 (@code{gnus-summary-save-article}).
6872 @kindex O m (Summary)
6873 @findex gnus-summary-save-article-mail
6874 Save the current article in mail format
6875 (@code{gnus-summary-save-article-mail}).
6878 @kindex O r (Summary)
6879 @findex gnus-summary-save-article-mail
6880 Save the current article in rmail format
6881 (@code{gnus-summary-save-article-rmail}).
6884 @kindex O f (Summary)
6885 @findex gnus-summary-save-article-file
6886 Save the current article in plain file format
6887 (@code{gnus-summary-save-article-file}).
6890 @kindex O b (Summary)
6891 @findex gnus-summary-save-article-body-file
6892 Save the current article body in plain file format
6893 (@code{gnus-summary-save-article-body-file}).
6896 @kindex O h (Summary)
6897 @findex gnus-summary-save-article-folder
6898 Save the current article in mh folder format
6899 (@code{gnus-summary-save-article-folder}).
6902 @kindex O p (Summary)
6903 @findex gnus-summary-pipe-output
6904 Save the current article in a pipe. Uhm, like, what I mean is---Pipe
6905 the current article to a process (@code{gnus-summary-pipe-output}).
6908 @vindex gnus-prompt-before-saving
6909 All these commands use the process/prefix convention
6910 (@pxref{Process/Prefix}). If you save bunches of articles using these
6911 functions, you might get tired of being prompted for files to save each
6912 and every article in. The prompting action is controlled by
6913 the @code{gnus-prompt-before-saving} variable, which is @code{always} by
6914 default, giving you that excessive prompting action you know and
6915 loathe. If you set this variable to @code{t} instead, you'll be promted
6916 just once for each series of articles you save. If you like to really
6917 have Gnus do all your thinking for you, you can even set this variable
6918 to @code{nil}, which means that you will never be prompted for files to
6919 save articles in. Gnus will simply save all the articles in the default
6923 @vindex gnus-default-article-saver
6924 You can customize the @code{gnus-default-article-saver} variable to make
6925 Gnus do what you want it to. You can use any of the four ready-made
6926 functions below, or you can create your own.
6930 @item gnus-summary-save-in-rmail
6931 @findex gnus-summary-save-in-rmail
6932 This is the default format, @dfn{babyl}. Uses the function in the
6933 @code{gnus-rmail-save-name} variable to get a file name to save the
6934 article in. The default is @code{gnus-plain-save-name}.
6936 @item gnus-summary-save-in-mail
6937 @findex gnus-summary-save-in-mail
6938 Save in a Unix mail (mbox) file. Uses the function in the
6939 @code{gnus-mail-save-name} variable to get a file name to save the
6940 article in. The default is @code{gnus-plain-save-name}.
6942 @item gnus-summary-save-in-file
6943 @findex gnus-summary-save-in-file
6944 Append the article straight to an ordinary file. Uses the function in
6945 the @code{gnus-file-save-name} variable to get a file name to save the
6946 article in. The default is @code{gnus-numeric-save-name}.
6948 @item gnus-summary-save-body-in-file
6949 @findex gnus-summary-save-body-in-file
6950 Append the article body to an ordinary file. Uses the function in the
6951 @code{gnus-file-save-name} variable to get a file name to save the
6952 article in. The default is @code{gnus-numeric-save-name}.
6954 @item gnus-summary-save-in-folder
6955 @findex gnus-summary-save-in-folder
6956 Save the article to an MH folder using @code{rcvstore} from the MH
6959 @item gnus-summary-save-in-vm
6960 @findex gnus-summary-save-in-vm
6961 Save the article in a VM folder. You have to have the VM mail
6962 reader to use this setting.
6965 All of these functions, except for the last one, will save the article
6966 in the @code{gnus-article-save-directory}, which is initialized from the
6967 @samp{SAVEDIR} environment variable. This is @file{~/News/} by
6970 As you can see above, the functions use different functions to find a
6971 suitable name of a file to save the article in. Below is a list of
6972 available functions that generate names:
6976 @item gnus-Numeric-save-name
6977 @findex gnus-Numeric-save-name
6978 Generates file names that look like @samp{~/News/Alt.andrea-dworkin/45}.
6980 @item gnus-numeric-save-name
6981 @findex gnus-numeric-save-name
6982 Generates file names that look like @samp{~/News/alt.andrea-dworkin/45}.
6984 @item gnus-Plain-save-name
6985 @findex gnus-Plain-save-name
6986 Generates file names that look like @samp{~/News/Alt.andrea-dworkin}.
6988 @item gnus-plain-save-name
6989 @findex gnus-plain-save-name
6990 Generates file names that look like @samp{~/News/alt.andrea-dworkin}.
6993 @vindex gnus-split-methods
6994 You can have Gnus suggest where to save articles by plonking regexp into
6995 the @code{gnus-split-methods} alist. For instance, if you would like to
6996 save articles related to Gnus in the file @file{gnus-stuff}, and articles
6997 related to VM in @code{vm-stuff}, you could set this variable to something
7001 (("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
7002 ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff")
7003 (my-choosing-function "../other-dir/my-stuff")
7004 ((equal gnus-newsgroup-name "mail.misc") "mail-stuff"))
7007 We see that this is a list where each element is a list that has two
7008 elements---the @dfn{match} and the @dfn{file}. The match can either be
7009 a string (in which case it is used as a regexp to match on the article
7010 head); it can be a symbol (which will be called as a function); or it
7011 can be a list (which will be @code{eval}ed). If any of these actions
7012 have a non-@code{nil} result, the @dfn{file} will be used as a default
7013 prompt. In addition, the result of the operation itself will be used if
7014 the function or form called returns a string or a list of strings.
7016 You basically end up with a list of file names that might be used when
7017 saving the current article. (All "matches" will be used.) You will
7018 then be prompted for what you really want to use as a name, with file
7019 name completion over the results from applying this variable.
7021 This variable is @code{((gnus-article-archive-name))} by default, which
7022 means that Gnus will look at the articles it saves for an
7023 @samp{Archive-name} line and use that as a suggestion for the file
7026 @vindex gnus-use-long-file-name
7027 Finally, you have the @code{gnus-use-long-file-name} variable. If it is
7028 @code{nil}, all the preceding functions will replace all periods
7029 (@samp{.}) in the group names with slashes (@samp{/})---which means that
7030 the functions will generate hierarchies of directories instead of having
7031 all the files in the toplevel directory
7032 (@samp{~/News/alt/andrea-dworkin} instead of
7033 @samp{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default
7034 on most systems. However, for historical reasons, this is @code{nil} on
7035 Xenix and usg-unix-v machines by default.
7037 This function also affects kill and score file names. If this variable
7038 is a list, and the list contains the element @code{not-score}, long file
7039 names will not be used for score files, if it contains the element
7040 @code{not-save}, long file names will not be used for saving, and if it
7041 contains the element @code{not-kill}, long file names will not be used
7044 If you'd like to save articles in a hierarchy that looks something like
7048 (setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
7049 (setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
7052 Then just save with @kbd{o}. You'd then read this hierarchy with
7053 ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
7054 the toplevel directory as the argument (@file{~/News/}). Then just walk
7055 around to the groups/directories with @code{nneething}.
7058 @node Decoding Articles
7059 @section Decoding Articles
7060 @cindex decoding articles
7062 Sometime users post articles (or series of articles) that have been
7063 encoded in some way or other. Gnus can decode them for you.
7066 * Uuencoded Articles:: Uudecode articles.
7067 * Shared Articles:: Unshar articles.
7068 * PostScript Files:: Split PostScript.
7069 * Decoding Variables:: Variables for a happy decoding.
7070 * Viewing Files:: You want to look at the result of the decoding?
7073 All these functions use the process/prefix convention
7074 (@pxref{Process/Prefix}) for finding out what articles to work on, with
7075 the extension that a "single article" means "a single series". Gnus can
7076 find out by itself what articles belong to a series, decode all the
7077 articles and unpack/view/save the resulting file(s).
7079 Gnus guesses what articles are in the series according to the following
7080 simplish rule: The subjects must be (nearly) identical, except for the
7081 last two numbers of the line. (Spaces are largely ignored, however.)
7083 For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus
7084 will find all the articles that match the regexp @samp{^cat.gif
7085 ([0-9]+/[0-9]+).*$}.
7087 Subjects that are nonstandard, like @samp{cat.gif (2/3) Part 6 of a
7088 series}, will not be properly recognized by any of the automatic viewing
7089 commands, and you have to mark the articles manually with @key{#}.
7091 @node Uuencoded Articles
7092 @subsection Uuencoded Articles
7094 @cindex uuencoded articles
7099 @kindex X u (Summary)
7100 @findex gnus-uu-decode-uu
7101 Uudecodes the current series (@code{gnus-uu-decode-uu}).
7104 @kindex X U (Summary)
7105 @findex gnus-uu-decode-uu-and-save
7106 Uudecodes and saves the current series
7107 (@code{gnus-uu-decode-uu-and-save}).
7110 @kindex X v u (Summary)
7111 @findex gnus-uu-decode-uu-view
7112 Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
7115 @kindex X v U (Summary)
7116 @findex gnus-uu-decode-uu-and-save-view
7117 Uudecodes, views and saves the current series
7118 (@code{gnus-uu-decode-uu-and-save-view}).
7121 Remember that these all react to the presence of articles marked with
7122 the process mark. If, for instance, you'd like to uncode and save an
7123 entire newsgroup, you'd typically do @kbd{M P a}
7124 (@code{gnus-uu-mark-all}) and then @kbd{X U}
7125 (@code{gnus-uu-decode-uu-and-save}).
7127 All this is very much different from how @code{gnus-uu} worked with
7128 @sc{gnus 4.1}, where you had explicit keystrokes for everything under
7129 the sun. This version of @code{gnus-uu} generally assumes that you mark
7130 articles in some way (@pxref{Setting Process Marks}) and then press
7133 Note: When trying to decode articles that have names matching
7134 @code{gnus-uu-notify-files}, which is hard-coded to
7135 @samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
7136 automatically post an article on @samp{comp.unix.wizards} saying that
7137 you have just viewed the file in question. This feature can't be turned
7140 @node Shared Articles
7141 @subsection Shared Articles
7143 @cindex shared articles
7148 @kindex X s (Summary)
7149 @findex gnus-uu-decode-unshar
7150 Unshars the current series (@code{gnus-uu-decode-unshar}).
7153 @kindex X S (Summary)
7154 @findex gnus-uu-decode-unshar-and-save
7155 Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
7158 @kindex X v s (Summary)
7159 @findex gnus-uu-decode-unshar-view
7160 Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
7163 @kindex X v S (Summary)
7164 @findex gnus-uu-decode-unshar-and-save-view
7165 Unshars, views and saves the current series
7166 (@code{gnus-uu-decode-unshar-and-save-view}).
7169 @node PostScript Files
7170 @subsection PostScript Files
7176 @kindex X p (Summary)
7177 @findex gnus-uu-decode-postscript
7178 Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
7181 @kindex X P (Summary)
7182 @findex gnus-uu-decode-postscript-and-save
7183 Unpack and save the current PostScript series
7184 (@code{gnus-uu-decode-postscript-and-save}).
7187 @kindex X v p (Summary)
7188 @findex gnus-uu-decode-postscript-view
7189 View the current PostScript series
7190 (@code{gnus-uu-decode-postscript-view}).
7193 @kindex X v P (Summary)
7194 @findex gnus-uu-decode-postscript-and-save-view
7195 View and save the current PostScript series
7196 (@code{gnus-uu-decode-postscript-and-save-view}).
7199 @node Decoding Variables
7200 @subsection Decoding Variables
7202 Adjective, not verb.
7205 * Rule Variables:: Variables that say how a file is to be viewed.
7206 * Other Decode Variables:: Other decode variables.
7207 * Uuencoding & Posting:: Variables for customizing uuencoding.
7210 @node Rule Variables
7211 @subsubsection Rule Variables
7212 @cindex rule variables
7214 Gnus uses @dfn{rule variables} to decide how to view a file. All these
7215 variables are on the form
7218 (list '(regexp1 command2)
7225 @item gnus-uu-user-view-rules
7226 @vindex gnus-uu-user-view-rules
7227 This variable is consulted first when viewing files. If you wish to use,
7228 for instance, @code{sox} to convert an @samp{.au} sound file, you could
7231 (setq gnus-uu-user-view-rules
7232 (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
7235 @item gnus-uu-user-view-rules-end
7236 @vindex gnus-uu-user-view-rules-end
7237 This variable is consulted if Gnus couldn't make any matches from the
7238 user and default view rules.
7240 @item gnus-uu-user-archive-rules
7241 @vindex gnus-uu-user-archive-rules
7242 This variable can be used to say what commands should be used to unpack
7247 @node Other Decode Variables
7248 @subsubsection Other Decode Variables
7251 @vindex gnus-uu-grabbed-file-functions
7253 @item gnus-uu-grabbed-file-functions
7254 All functions in this list will be called right each file has been
7255 successfully decoded---so that you can move or view files right away,
7256 and don't have to wait for all files to be decoded before you can do
7257 anything. Ready-made functions you can put in this list are:
7261 @item gnus-uu-grab-view
7262 @findex gnus-uu-grab-view
7265 @item gnus-uu-grab-move
7266 @findex gnus-uu-grab-move
7267 Move the file (if you're using a saving function.)
7270 @item gnus-uu-ignore-files-by-name
7271 @vindex gnus-uu-ignore-files-by-name
7272 Files with name matching this regular expression won't be viewed.
7274 @item gnus-uu-ignore-files-by-type
7275 @vindex gnus-uu-ignore-files-by-type
7276 Files with a @sc{mime} type matching this variable won't be viewed.
7277 Note that Gnus tries to guess what type the file is based on the name.
7278 @code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
7281 @item gnus-uu-tmp-dir
7282 @vindex gnus-uu-tmp-dir
7283 Where @code{gnus-uu} does its work.
7285 @item gnus-uu-do-not-unpack-archives
7286 @vindex gnus-uu-do-not-unpack-archives
7287 Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
7288 looking for files to display.
7290 @item gnus-uu-view-and-save
7291 @vindex gnus-uu-view-and-save
7292 Non-@code{nil} means that the user will always be asked to save a file
7295 @item gnus-uu-ignore-default-view-rules
7296 @vindex gnus-uu-ignore-default-view-rules
7297 Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
7300 @item gnus-uu-ignore-default-archive-rules
7301 @vindex gnus-uu-ignore-default-archive-rules
7302 Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
7305 @item gnus-uu-kill-carriage-return
7306 @vindex gnus-uu-kill-carriage-return
7307 Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
7310 @item gnus-uu-unmark-articles-not-decoded
7311 @vindex gnus-uu-unmark-articles-not-decoded
7312 Non-@code{nil} means that @code{gnus-uu} will mark articles that were
7313 unsuccessfully decoded as unread.
7315 @item gnus-uu-correct-stripped-uucode
7316 @vindex gnus-uu-correct-stripped-uucode
7317 Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
7318 uuencoded files that have had trailing spaces deleted.
7320 @item gnus-uu-view-with-metamail
7321 @vindex gnus-uu-view-with-metamail
7322 Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
7323 commands defined by the rule variables and just fudge a @sc{mime}
7324 content type based on the file name. The result will be fed to
7325 @code{metamail} for viewing.
7327 @item gnus-uu-save-in-digest
7328 @vindex gnus-uu-save-in-digest
7329 Non-@code{nil} means that @code{gnus-uu}, when asked to save without
7330 decoding, will save in digests. If this variable is @code{nil},
7331 @code{gnus-uu} will just save everything in a file without any
7332 embellishments. The digesting almost conforms to RFC1153---no easy way
7333 to specify any meaningful volume and issue numbers were found, so I
7334 simply dropped them.
7338 @node Uuencoding & Posting
7339 @subsubsection Uuencoding & Posting
7343 @item gnus-uu-post-include-before-composing
7344 @vindex gnus-uu-post-include-before-composing
7345 Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
7346 before you compose the article. If this variable is @code{t}, you can
7347 either include an encoded file with @key{C-c C-i} or have one included
7348 for you when you post the article.
7350 @item gnus-uu-post-length
7351 @vindex gnus-uu-post-length
7352 Maximum length of an article. The encoded file will be split into how
7353 many articles it takes to post the entire file.
7355 @item gnus-uu-post-threaded
7356 @vindex gnus-uu-post-threaded
7357 Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
7358 thread. This may not be smart, as no other decoder I have seen are able
7359 to follow threads when collecting uuencoded articles. (Well, I have
7360 seen one package that does that---@code{gnus-uu}, but somehow, I don't
7361 think that counts...) Default is @code{nil}.
7363 @item gnus-uu-post-separate-description
7364 @vindex gnus-uu-post-separate-description
7365 Non-@code{nil} means that the description will be posted in a separate
7366 article. The first article will typically be numbered (0/x). If this
7367 variable is @code{nil}, the description the user enters will be included
7368 at the beginning of the first article, which will be numbered (1/x).
7369 Default is @code{t}.
7374 @subsection Viewing Files
7375 @cindex viewing files
7376 @cindex pseudo-articles
7378 After decoding, if the file is some sort of archive, Gnus will attempt
7379 to unpack the archive and see if any of the files in the archive can be
7380 viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
7381 containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
7382 uncompress and detar the main file, and then view the two pictures.
7383 This unpacking process is recursive, so if the archive contains archives
7384 of archives, it'll all be unpacked.
7386 Finally, Gnus will normally insert a @dfn{pseudo-article} for each
7387 extracted file into the summary buffer. If you go to these "articles",
7388 you will be prompted for a command to run (usually Gnus will make a
7389 suggestion), and then the command will be run.
7391 @vindex gnus-view-pseudo-asynchronously
7392 If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
7393 until the viewing is done before proceeding.
7395 @vindex gnus-view-pseudos
7396 If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
7397 the pseudo-articles into the summary buffer, but view them
7398 immediately. If this variable is @code{not-confirm}, the user won't even
7399 be asked for a confirmation before viewing is done.
7401 @vindex gnus-view-pseudos-separately
7402 If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
7403 pseudo-article will be created for each file to be viewed. If
7404 @code{nil}, all files that use the same viewing command will be given as
7405 a list of parameters to that command.
7407 If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert
7408 pseudo-articles when decoding. It is @code{t} by default.
7410 So; there you are, reading your @emph{pseudo-articles} in your
7411 @emph{virtual newsgroup} from the @emph{virtual server}; and you think:
7412 Why isn't anything real anymore? How did we get here?
7415 @node Article Treatment
7416 @section Article Treatment
7418 Reading through this huge manual, you may have quite forgotten that the
7419 object of newsreaders are to actually, like, read what people have
7420 written. Reading articles. Unfortunately, people are quite bad at
7421 writing, so there are tons of functions and variables to make reading
7422 these articles easier.
7425 * Article Highlighting:: You want to make the article look like fruit salad.
7426 * Article Hiding:: You also want to make certain info go away.
7427 * Article Washing:: Lots of way-neat functions to make life better.
7428 * Article Buttons:: Clcik on URLs, Message-IDs, addresses and the like.
7429 * Article Date:: Grumble, UT!
7433 @node Article Highlighting
7434 @subsection Article Highlighting
7437 Not only do you want your article buffer to look like fruit salad, but
7438 you want it to look like technicolor fruit salad.
7443 @kindex W H a (Summary)
7444 @findex gnus-article-highlight
7445 Highlight the current article (@code{gnus-article-highlight}).
7448 @kindex W H h (Summary)
7449 @findex gnus-article-highlight-headers
7450 @vindex gnus-header-face-alist
7451 Highlight the headers (@code{gnus-article-highlight-headers}). The
7452 highlighting will be done according to the @code{gnus-header-face-alist}
7453 variable, which is a list where each element has the form @var{(regexp
7454 name content)}. @var{regexp} is a regular expression for matching the
7455 header, @var{name} is the face used for highling the header name and
7456 @var{content} is the face for highlighting the header value. The first
7457 match made will be used.
7460 @kindex W H c (Summary)
7461 @findex gnus-article-highlight-citation
7462 Highlight cited text (@code{gnus-article-highlight-citation}).
7464 Some variables to customize the citation highlights:
7467 @vindex gnus-cite-parse-max-size
7469 @item gnus-cite-parse-max-size
7470 If the article size if bigger than this variable (which is 25000 by
7471 default), no citation highlighting will be performed.
7473 @item gnus-cite-prefix-regexp
7474 @vindex gnus-cite-prefix-regexp
7475 Regexp mathcing the longest possible citation prefix on a line.
7477 @item gnus-cite-max-prefix
7478 @vindex gnus-cite-max-prefix
7479 Maximum possible length for a citation prefix (default 20).
7481 @item gnus-supercite-regexp
7482 @vindex gnus-supercite-regexp
7483 Regexp matching normal SuperCite attribution lines.
7485 @item gnus-supercite-secondary-regexp
7486 @vindex gnus-supercite-secondary-regexp
7487 Regexp matching mangled SuperCite attribution lines.
7489 @item gnus-cite-minimum-match-count
7490 @vindex gnus-cite-minimum-match-count
7491 Minimum number of identical prefixes we have to see before we believe
7492 that it's a citation.
7494 @item gnus-cite-attribution-prefix
7495 @vindex gnus-cite-attribution-prefix
7496 Regexp matching the beginning of an attribution line.
7498 @item gnus-cite-addtribution-suffix
7499 @vindex gnus-cite-addtribution-suffix
7500 Regexp matching the end of an attribution line.
7502 @item gnus-cite-attribution-face
7503 @vindex gnus-cite-attribution-face
7504 Face used for attribution lines. It is merged with the face for the
7505 cited text belonging to the attribution.
7511 @kindex W H s (Summary)
7512 @vindex gnus-signature-separator
7513 @findex gnus-article-highlight-signature
7514 Highlight the signature (@code{gnus-article-highlight-signature}).
7515 Everything after @code{gnus-signature-separator} in an article will be
7516 considered a signature.
7521 @node Article Hiding
7522 @subsection Article Hiding
7523 @cindex article hiding
7525 Or rather, hiding certain things in each article. There usually is much
7526 too much gruft in most articles.
7531 @kindex W W a (Summary)
7532 @findex gnus-article-hide
7533 Do maximum hiding on the summary buffer (@kbd{gnus-article-hide}).
7536 @kindex W W h (Summary)
7537 @findex gnus-article-hide-headers
7538 Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
7542 @kindex W W b (Summary)
7543 @findex gnus-article-hide-boring-headers
7544 Hide headers that aren't particularly interesting
7545 (@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}.
7548 @kindex W W s (Summary)
7549 @findex gnus-article-hide-signature
7550 Hide signature (@code{gnus-article-hide-signature}).
7553 @kindex W W p (Summary)
7554 @findex gnus-article-hide-pgp
7555 Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}).
7558 @kindex W W c (Summary)
7559 @findex gnus-article-hide-citation
7560 Hide citation (@code{gnus-article-hide-citation}). Some variables for
7561 customizing the hiding:
7565 @item gnus-cite-hide-percentage
7566 @vindex gnus-cite-hide-percentage
7567 If the cited text is of a bigger percentage than this variable (default
7568 50), hide the cited text.
7570 @item gnus-cite-hide-absolute
7571 @vindex gnus-cite-hide-absolute
7572 The cited text must be have at least this length (default 10) before it
7575 @item gnus-cited-text-button-line-format
7576 @vindex gnus-cited-text-button-line-format
7577 Gnus adds buttons show where the cited text has been hidden, and to
7578 allow toggle hiding the text. The format of the variable is specified
7579 by this format-like variable. These specs are legal:
7583 Start point of the hidden text.
7585 End point of the hidden text.
7587 Length of the hidden text.
7590 @item gnus-cited-lines-visible
7591 @vindex gnus-cited-lines-visible
7592 The number of lines at the beginning of the cited text to leave shown.
7597 @kindex W W C (Summary)
7598 @findex gnus-article-hide-citation-in-followups
7599 Hide cited text in articles that aren't roots
7600 (@code{gnus-article-hide-citation-in-followups}). This isn't very
7601 useful as an interactive command, but might be a handy function to stick
7602 in @code{gnus-article-display-hook} (@pxref{Customizing Articles}).
7606 All these "hiding" commands are toggles, but if you give a negative
7607 prefix to these commands, they will show what they have previously
7608 hidden. If you give a positive prefix, they will always hide.
7610 Also see @xref{Article Highlighting} for further variables for
7611 citation customization.
7613 @vindex gnus-signature-limit
7614 @code{gnus-signature-limit} provides a limit to what is considered a
7615 signature. If it is a number, no signature may not be longer (in
7616 characters) than that number. If it is a function, the function will be
7617 called without any parameters, and if it returns @code{nil}, there is no
7618 signature in the buffer. If it is a string, it will be used as a
7619 regexp. If it matches, the text in question is not a signature.
7622 @node Article Washing
7623 @subsection Article Washing
7625 @cindex article washing
7627 We call this "article washing" for a really good reason. Namely, the
7628 @kbd{A} key was taken, so we had to use the @kbd{W} key instead.
7630 @dfn{Washing} is defined by us as "changing something from something to
7631 something else", but normally results in something looking better.
7637 @kindex W l (Summary)
7638 @findex gnus-summary-stop-page-breaking
7639 Remove page breaks from the current article
7640 (@code{gnus-summary-stop-page-breaking}).
7643 @kindex W r (Summary)
7644 @findex gnus-summary-caesar-message
7645 Do a Caesar rotate (rot13) on the article buffer
7646 (@code{gnus-summary-caesar-message}).
7649 @kindex A g (Summary)
7650 @findex gnus-summary-show-article
7651 (Re)fetch the current article (@code{gnus-summary-show-article}). If
7652 given a prefix, fetch the current article, but don't run any of the
7653 article treatment functions. This will give you a "raw" article, just
7654 the way it came from the server.
7657 @kindex W t (Summary)
7658 @findex gnus-summary-toggle-header
7659 Toggle whether to display all headers in the article buffer
7660 (@code{gnus-summary-toggle-header}).
7663 @kindex W m (Summary)
7664 @findex gnus-summary-toggle-mime
7665 Toggle whether to run the article through @sc{mime} before displaying
7666 (@code{gnus-summary-toggle-mime}).
7669 @kindex W o (Summary)
7670 @findex gnus-article-treat-overstrike
7671 Treat overstrike (@code{gnus-article-treat-overstrike}).
7674 @kindex W w (Summary)
7675 @findex gnus-article-word-wrap
7676 Do word wrap (@code{gnus-article-word-wrap}).
7679 @kindex W c (Summary)
7680 @findex gnus-article-remove-cr
7681 Remove CR (@code{gnus-article-remove-cr}).
7684 @kindex W L (Summary)
7685 @findex gnus-article-remove-trailing-blank-lines
7686 Remove all blank lines at the end of the article
7687 (@code{gnus-article-remove-trailing-blank-lines}).
7690 @kindex W q (Summary)
7691 @findex gnus-article-de-quoted-unreadable
7692 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
7695 @kindex W f (Summary)
7697 @findex gnus-article-display-x-face
7698 @findex gnus-article-x-face-command
7699 @vindex gnus-article-x-face-command
7700 @vindex gnus-article-x-face-too-ugly
7701 Look for and display any X-Face headers
7702 (@code{gnus-article-display-x-face}). The command executed by this
7703 function is given by the @code{gnus-article-x-face-command} variable. If
7704 this variable is a string, this string will be executed in a sub-shell.
7705 If it is a function, this function will be called with the face as the
7706 argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
7707 matches the @code{From} header, the face will not be shown.
7710 @kindex W b (Summary)
7711 @findex gnus-article-add-buttons
7712 Add clickable buttons to the article (@code{gnus-article-add-buttons}).
7715 @kindex W B (Summary)
7716 @findex gnus-article-add-buttons-to-head
7717 Add clickable buttons to the article headers
7718 (@code{gnus-article-add-buttons-to-head}).
7723 @node Article Buttons
7724 @subsection Article Buttons
7727 People often include references to other stuff in articles, and it would
7728 be nice if Gnus could just fetch whatever it is that people talk about
7729 with the minimum of fuzz.
7731 Gnus adds @dfn{buttons} to certain standard references by default:
7732 Well-formed URLs, mail addresses and Message-IDs. This is controlled by
7733 two variables, one that handles article bodies and one that handles
7738 @item gnus-button-alist
7739 @vindex gnus-header-button-alist
7740 This is an alist where each entry has this form:
7743 (REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
7749 All text that match this regular expression will be considered an
7750 external reference. Here's a typical regexp that match embedded URLs:
7751 @samp{"<URL:\\([^\n\r>]*\\)>"}.
7754 Gnus has to know which parts of the match is to be highlighted. This is
7755 a number that says what sub-expression of the regexp that is to be
7756 highlighted. If you want it all highlighted, you use @samp{0} here.
7759 This form will be @code{eval}ed, and if the result is non-@code{nil},
7760 this is considered a match. This is useful if you want extra sifting to
7761 avoid false matches.
7764 This function will be called when you click on this button.
7767 As with @var{button-par}, this is a sub-expression number, but this one
7768 says which part of the match is to be sent as data to @var{function}.
7772 So the full entry for buttonizing URLs is then
7775 ("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
7778 @item gnus-header-button-alist
7779 @vindex gnus-header-button-alist
7780 This is just like the other alist, except that it is applied to the
7781 article head only, and that each entry has an additional element that is
7782 used to say what headers to apply the buttonize coding to:
7785 (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
7788 @var{header} is a regular expression.
7792 @vindex gnus-article-button-face
7793 @vindex gnus-article-mouse-face
7794 Buttons are highlighted with @code{gnus-article-button-face}, while
7795 @code{gnus-article-mouse-face} is used when the mouse cursor is over the
7800 @subsection Article Date
7802 The date is most likely generated in some obscure timezone you've never
7803 heard of, so it's quite nice to be able to find out what the time was
7804 when the article was sent.
7809 @kindex W T u (Summary)
7810 @findex gnus-article-date-ut
7811 Display the date in UT (aka. GMT, aka ZULU)
7812 (@code{gnus-article-date-ut}).
7815 @kindex W T l (Summary)
7816 @findex gnus-article-date-local
7817 Display the date in the local timezone (@code{gnus-article-date-local}).
7820 @kindex W T e (Summary)
7821 @findex gnus-article-date-lapsed
7822 Say how much time has (e)lapsed between the article was posted and now
7823 (@code{gnus-article-date-lapsed}).
7826 @kindex W T o (Summary)
7827 @findex gnus-article-date-original
7828 Display the original date (@code{gnus-article-date-original}). This can
7829 be useful if you normally use some other conversion function and is
7830 worried that it might be doing something totally wrong. Say, claiming
7831 that the article was posted in 1854. Although something like that is
7832 @emph{totally} impossible. Don't you trust me? *titter*
7837 @node Summary Sorting
7838 @section Summary Sorting
7839 @cindex summary sorting
7841 You can have the summary buffer sorted in various ways, even though I
7842 can't really see why you'd want that.
7847 @kindex C-c C-s C-n (Summary)
7848 @findex gnus-summary-sort-by-number
7849 Sort by article number (@code{gnus-summary-sort-by-number}).
7852 @kindex C-c C-s C-a (Summary)
7853 @findex gnus-summary-sort-by-author
7854 Sort by author (@code{gnus-summary-sort-by-author}).
7857 @kindex C-c C-s C-s (Summary)
7858 @findex gnus-summary-sort-by-subject
7859 Sort by subject (@code{gnus-summary-sort-by-subject}).
7862 @kindex C-c C-s C-d (Summary)
7863 @findex gnus-summary-sort-by-date
7864 Sort by date (@code{gnus-summary-sort-by-date}).
7867 @kindex C-c C-s C-i (Summary)
7868 @findex gnus-summary-sort-by-score
7869 Sort by score (@code{gnus-summary-sort-by-score}).
7872 These functions will work both when you use threading and when you don't
7873 use threading. In the latter case, all summary lines will be sorted,
7874 line by line. In the former case, sorting will be done on a
7875 root-by-root basis, which might not be what you were looking for. To
7876 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
7880 @node Finding the Parent
7881 @section Finding the Parent
7882 @cindex parent articles
7883 @cindex referring articles
7885 @findex gnus-summary-refer-parent-article
7887 If you'd like to read the parent of the current article, and it is not
7888 displayed in the article buffer, you might still be able to. That is,
7889 if the current group is fetched by @sc{nntp}, the parent hasn't expired
7890 and the @code{References} in the current article are not mangled, you
7891 can just press @kbd{^} or @kbd{A r}
7892 (@code{gnus-summary-refer-parent-article}). If everything goes well,
7893 you'll get the parent. If the parent is already displayed in the
7894 summary buffer, point will just move to this article.
7896 @findex gnus-summary-refer-references
7897 @kindex A R (Summary)
7898 You can have Gnus fetch all articles mentioned in the @code{References}
7899 header of the article by pushing @kbd{A R}
7900 (@code{gnus-summary-refer-references}).
7902 @findex gnus-summary-refer-article
7903 @kindex M-^ (Summary)
7904 You can also ask the @sc{nntp} server for an arbitrary article, no
7905 matter what group it belongs to. @kbd{M-^}
7906 (@code{gnus-summary-refer-article}) will ask you for a
7907 @code{Message-ID}, which is one of those long thingies that look
7908 something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
7909 it all exactly right. No fuzzy searches, I'm afraid.
7911 @vindex gnus-refer-article-method
7912 If the group you are reading is located on a backend that does not
7913 support fetching by @code{Message-ID} very well (like @code{nnspool}),
7914 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
7915 would, perhaps, be best if the @sc{nntp} server you consult is the same
7916 as the one that keeps the spool you are reading from updated, but that's
7917 not really necessary.
7919 Most of the mail backends support fetching by @code{Message-ID}, but do
7920 not do a particularly excellent job of it. That is, @code{nnmbox} and
7921 @code{nnbabyl} are able to locate articles from any groups, while
7922 @code{nnml} and @code{nnfolder} are only able to locate articles that
7923 have been posted to the current group. (Anything else would be too time
7924 consuming.) @code{nnmh} does not support this at all.
7927 @node Alternative Approaches
7928 @section Alternative Approaches
7930 Different people like to read news using different methods. This being
7931 Gnus, we offer a small selection of minor modes for the summary buffers.
7934 * Pick and Read:: First mark articles and then read them.
7935 * Binary Groups:: Auto-decode all articles.
7940 @subsection Pick and Read
7941 @cindex pick and read
7943 Some newsreaders (like @code{nn} and, uhm, @code{nn}) use a two-phased
7944 reading interface. The user first marks the articles she wants to read
7945 from a summary buffer. Then she starts reading the articles with just
7946 an article buffer displayed.
7948 @findex gnus-pick-mode
7949 @kindex M-x gnus-pick-mode
7950 Gnus provides a summary buffer minor mode that allows
7951 this---@code{gnus-pick-mode}. This basically means that a few process
7952 mark commands becode one-keystroke commands to allow easy marking, and
7953 it makes one additional command for switching to the summary buffer
7956 Here are the available keystrokes when using pick mode:
7960 Pick the article (@code{gnus-summary-mark-as-processable}).
7963 Unpick the article (@code{gnus-summary-unmark-as-processable}).
7966 Unpick all articles (@code{gnus-summary-unmark-all-processable}).
7969 Pick the thread (@code{gnus-uu-mark-thread}).
7972 Unpick the thread (@code{gnus-uu-unmark-thread}).
7975 Pick the region (@code{gnus-uu-mark-region}).
7978 Unpick the region (@code{gnus-uu-unmark-region}).
7981 Pick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
7984 Unpick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
7987 Pick the buffer (@code{gnus-uu-mark-buffer}).
7990 Unpick the buffer (@code{gnus-uu-unmark-buffer}).
7993 @vindex gnus-pick-display-summary
7994 Start reading the picked articles (@code{gnus-pick-start-reading}). If
7995 given a prefix, mark all unpicked articles as read first. If
7996 @code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer
7997 will still be visible when you are reading.
8001 If this sounds like a good idea to you, you could say:
8004 (add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)
8009 @subsection Binary Groups
8010 @cindex binary groups
8012 @findex gnus-binary-mode
8013 @kindex M-x gnus-binary-mode
8014 If you spend much time in binary groups, you may grow tired of hitting
8015 @kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode}
8016 is a minor mode for summary buffers that makes all ordinary Gnus article
8017 selection functions uudecode series of articles and display the result
8018 instead of just displaying the articles the normal way.
8021 @findex gnus-binary-show-article
8022 In fact, the only way to see the actual articles if you have turned this
8023 mode on is the @kbd{g} command (@code{gnus-binary-show-article}).
8027 @section Tree Display
8030 @vindex gnus-use-trees
8031 If you don't like the normal Gnus summary display, you might try setting
8032 @code{gnus-use-trees} to @code{t}. This will create (by default) an
8033 additional @dfn{tree buffer}. You can execute all summary mode commands
8036 There are a few variables to customize the tree display, of course:
8039 @item gnus-tree-mode-hook
8040 @vindex gnus-tree-mode-hook
8041 A hook called in all tree mode buffers.
8043 @item gnus-tree-mode-line-format
8044 @vindex gnus-tree-mode-line-format
8045 A format string for the mode bar in the tree mode buffers. The default
8046 is @samp{"Gnus: %%b [%A] %Z"}. For a list of legal specs, @xref{Summary
8049 @item gnus-selected-tree-face
8050 @vindex gnus-selected-tree-face
8051 Face used for highlighting the selected article in the tree buffer. The
8052 default is @code{modeline}.
8054 @item gnus-tree-line-format
8055 @vindex gnus-tree-line-format
8056 A format string for the tree nodes. The name is a bit of a misnomer,
8057 though---it doesn't define a line, but just the node. The default value
8058 is @samp{"%(%[%3,3n%]%)"}, which displays the first three characters of
8059 the name of the poster. It is vital that all nodes are of the same
8060 length, so you @emph{must} use @samp{%4,4n}-like specifiers.
8066 The name of the poster.
8068 The @code{From} header.
8070 The number of the article.
8072 The opening bracket.
8074 The closing bracket.
8079 @xref{Formatting Variables}.
8081 Variables related to the display are:
8084 @item gnus-tree-brackets
8085 @vindex gnus-tree-brackets
8086 This is used for differentiating between "real" articles and "sparse"
8087 articles. The format is @var{((real-open . real-close) (sparse-open
8088 . sparse-close) (dummy-open . dummy-close))}, and the default is
8089 @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}))}.
8091 @item gnus-tree-parent-child-edges
8092 @vindex gnus-tree-parent-child-edges
8093 This is a list that contains the characters used for connecting parent
8094 nodes to their children. The default is @code{(?- ?\\ ?|)}.
8098 @item gnus-tree-minimize-window
8099 @vindex gnus-tree-minimize-window
8100 If this variable is non-@code{nil}, Gnus will try to keep the tree
8101 buffer as small as possible to allow more room for the other Gnus
8102 windows. If this variable is a number, the tree buffer will never be
8103 higher than that number. The default is @code{t}.
8105 @item gnus-generate-tree-function
8106 @vindex gnus-generate-tree-function
8107 @findex gnus-generate-horizontal-tree
8108 @findex gnus-generate-vertical-tree
8109 The function that actually generates the thread tree. Two predefined
8110 functions are available: @code{gnus-generate-horizontal-tree} and
8111 @code{gnus-generate-vertical-tree} (which is the default).
8115 Here's and example from a horizontal tree buffer:
8118 @{***@}-(***)-[odd]-[Gun]
8128 Here's the same thread displayed in a vertical tree buffer:
8132 |--------------------------\-----\-----\
8133 (***) [Bjo] [Gun] [Gun]
8135 [odd] [Jan] [odd] (***) [Jor]
8137 [Gun] [Eri] [Eri] [odd]
8143 @node Mail Group Commands
8144 @section Mail Group Commands
8145 @cindex mail group commands
8147 Some commands only make sense in mail groups. If these commands are
8148 illegal in the current group, they will raise a hell and let you know.
8150 All these commands (except the expiry and edit commands) use the
8151 process/prefix convention (@pxref{Process/Prefix}).
8156 @kindex B e (Summary)
8157 @findex gnus-summary-expire-articles
8158 Expire all expirable articles in the group
8159 (@code{gnus-summary-expire-articles}).
8162 @kindex B M-C-e (Summary)
8163 @findex gnus-summary-expire-articles-now
8164 Expunge all the expirable articles in the group
8165 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
8166 articles that are eligeble for expiry in the current group will
8167 disappear forever into that big @file{/dev/null} in the sky.
8170 @kindex B DEL (Summary)
8171 @findex gnus-summary-delete-articles
8172 Delete the mail article. This is "delete" as in "delete it from your
8173 disk forever and ever, never to return again." Use with caution.
8174 (@code{gnus-summary-delete-article}).
8177 @kindex B m (Summary)
8179 @findex gnus-summary-move-article
8180 Move the article from one mail group to another
8181 (@code{gnus-summary-move-article}).
8184 @kindex B c (Summary)
8186 @findex gnus-summary-copy-article
8187 Copy the article from one group (mail group or not) to a mail group
8188 (@code{gnus-summary-copy-article}).
8191 @kindex B C (Summary)
8192 @cindex crosspost mail
8193 @findex gnus-summary-crosspost-article
8194 Crosspost the current article to some other group
8195 (@code{gnus-summary-crosspost-article}). This will create a new copy of
8196 the article in the other group, and the Xref headers of the article will
8197 be properly updated.
8200 @kindex B i (Summary)
8201 @findex gnus-summary-import-article
8202 Import a random file into the current mail newsgroup
8203 (@code{gnus-summary-import-article}). You will be prompted for a file
8204 name, a @code{From} header and a @code{Subject} header.
8206 Something similar can be done by just starting to compose a mail
8207 message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
8208 @kbd{C-c C-p} instead. This will put the message you have just created
8209 into the current mail group.
8212 @kindex B r (Summary)
8213 @findex gnus-summary-respool-article
8214 Respool the mail article (@code{gnus-summary-move-article}).
8218 @kindex B w (Summary)
8220 @findex gnus-summary-edit-article
8221 @kindex C-c C-c (Article)
8222 Edit the current article (@code{gnus-summary-edit-article}). To finish
8223 editing and make the changes permanent, type @kbd{C-c C-c}
8224 (@kbd{gnus-summary-edit-article-done}).
8227 @kindex B q (Summary)
8228 @findex gnus-summary-respool-query
8229 If you want to respool an article, you might be curious as to what group
8230 the article will end up in before you do the respooling. This command
8231 will tell you (@code{gnus-summary-fancy-query}).
8234 If you move (or copy) articles regularly, you might wish to have Gnus
8235 suggest where to put the articles. @code{gnus-move-split-methods} is a
8236 variable that uses the same syntax as @code{gnus-split-methods}
8237 (@pxref{Saving Articles}). You may customize that variable to create
8238 suggestions you find reasonable.
8241 @node Various Summary Stuff
8242 @section Various Summary Stuff
8245 * Group Information:: Information oriented commands.
8246 * Searching for Articles:: Multiple article commands.
8247 * Really Various Summary Commands:: Those pesky non-conformant commands.
8250 @vindex gnus-summary-generate-hook
8251 @code{gnus-summary-generate-hook} is called as the last thing before
8252 doing the threading and the generation of the summary buffer. It's
8253 quite convenient for customizing the threading variables based on what
8254 data the newsgroup has. This hook is called from the summary buffer
8255 after most summary buffer variables has been set.
8257 @vindex gnus-summary-prepare-hook
8258 @code{gnus-summary-prepare-hook} is called after the summary buffer has
8259 been generated. You might use it to, for instance, highlight lines or
8260 modify the look of the buffer in some other ungodly manner. I don't
8263 @node Group Information
8264 @subsection Group Information
8269 @kindex H f (Summary)
8270 @findex gnus-summary-fetch-faq
8271 @vindex gnus-group-faq-directory
8272 Try to fetch the FAQ (list of frequently asked questions) for the
8273 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
8274 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
8275 on a remote machine. This variable can also be a list of directories.
8276 In that case, giving a prefix to this command will allow you to choose
8277 between the various sites. @code{ange-ftp} probably will be used for
8281 @kindex H d (Summary)
8282 @findex gnus-summary-describe-group
8283 Give a brief description of the current group
8284 (@code{gnus-summary-describe-group}). If given a prefix, force
8285 rereading the description from the server.
8288 @kindex H h (Summary)
8289 @findex gnus-summary-describe-briefly
8290 Give a very brief description of the most important summary keystrokes
8291 (@code{gnus-summary-describe-briefly}).
8294 @kindex H i (Summary)
8295 @findex gnus-info-find-node
8296 Go to the Gnus info node (@code{gnus-info-find-node}).
8299 @node Searching for Articles
8300 @subsection Searching for Articles
8305 @kindex M-s (Summary)
8306 @findex gnus-summary-search-article-forward
8307 Search through all subsequent articles for a regexp
8308 (@code{gnus-summary-search-article-forward}).
8311 @kindex M-r (Summary)
8312 @findex gnus-summary-search-article-backward
8313 Search through all previous articles for a regexp
8314 (@code{gnus-summary-search-article-backward}).
8318 @findex gnus-summary-execute-command
8319 This command will prompt you for a header field, a regular expression to
8320 match on this field, and a command to be executed if the match is made
8321 (@code{gnus-summary-execute-command}).
8324 @kindex M-& (Summary)
8325 @findex gnus-summary-universal-argument
8326 Perform any operation on all articles that have been marked with
8327 the process mark (@code{gnus-summary-universal-argument}).
8330 @node Really Various Summary Commands
8331 @subsection Really Various Summary Commands
8336 @kindex A D (Summary)
8337 @findex gnus-summary-enter-digest-group
8338 If the current article is a collection of other articles (for instance,
8339 a digest), you might use this command to enter a group based on the that
8340 article (@code{gnus-summary-enter-digest-group}). Gnus will try to
8341 guess what article type is currently displayed unless you give a prefix
8342 to this command, which forces a "digest" interpretation. Basically,
8343 whenever you see a message that is a collection of other messages on
8344 some format, you @kbd{A D} and read these messages in a more convenient
8348 @kindex C-t (Summary)
8349 @findex gnus-summary-toggle-truncation
8350 Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
8354 @findex gnus-summary-expand-window
8355 Expand the summary buffer window (@code{gnus-summary-expand-window}).
8356 If given a prefix, force an @code{article} window configuration.
8360 @node The Article Buffer
8361 @chapter The Article Buffer
8362 @cindex article buffer
8364 The articles are displayed in the article buffer, of which there is only
8365 one. All the summary buffers share the same article buffer unless you
8366 tell Gnus otherwise.
8369 * Hiding Headers:: Deciding what headers should be displayed.
8370 * Using MIME:: Pushing articles through @sc{mime} before reading them.
8371 * Customizing Articles:: Tailoring the look of the articles.
8372 * Article Keymap:: Keystrokes available in the article buffer
8373 * Misc Article:: Other stuff.
8377 @node Hiding Headers
8378 @section Hiding Headers
8379 @cindex hiding headers
8380 @cindex deleting headers
8382 The top section of each article is the @dfn{head}. (The rest is the
8383 @dfn{body}, but you may have guessed that already.)
8385 @vindex gnus-show-all-headers
8386 There is a lot of useful information in the head: the name of the person
8387 who wrote the article, the date it was written and the subject of the
8388 article. That's well and nice, but there's also lots of information
8389 most people do not want to see---what systems the article has passed
8390 through before reaching you, the @code{Message-ID}, the
8391 @code{References}, etc. ad nauseum---and you'll probably want to get rid
8392 of some of those lines. If you want to keep all those lines in the
8393 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
8395 Gnus provides you with two variables for sifting headers:
8399 @item gnus-visible-headers
8400 @vindex gnus-visible-headers
8401 If this variable is non-@code{nil}, it should be a regular expression
8402 that says what headers you wish to keep in the article buffer. All
8403 headers that do not match this variable will be hidden.
8405 For instance, if you only want to see the name of the person who wrote
8406 the article and the subject, you'd say:
8409 (setq gnus-visible-headers "^From:\\|^Subject:")
8412 This variable can also be a list of regexps to match headers that are to
8415 @item gnus-ignored-headers
8416 @vindex gnus-ignored-headers
8417 This variable is the reverse of @code{gnus-visible-headers}. If this
8418 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
8419 should be a regular expression that matches all lines that you want to
8420 hide. All lines that do not match this variable will remain visible.
8422 For instance, if you just want to get rid of the @code{References} line
8423 and the @code{Xref} line, you might say:
8426 (setq gnus-ignored-headers "^References:\\|^Xref:")
8429 This variable can also be a list of regexps to match headers that are to
8432 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
8433 variable will have no effect.
8437 @vindex gnus-sorted-header-list
8438 Gnus can also sort the headers for you. (It does this by default.) You
8439 can control the sorting by setting the @code{gnus-sorted-header-list}
8440 variable. It is a list of regular expressions that says in what order
8441 the headers are to be displayed.
8443 For instance, if you want the name of the author of the article first,
8444 and then the subject, you might say something like:
8447 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
8450 Any headers that are to remain visible, but are not listed in this
8451 variable, will be displayed in random order after all the headers that
8452 are listed in this variable.
8454 @findex gnus-article-hide-boring-headers
8455 @vindex gnus-article-display-hook
8456 @vindex gnus-boring-article-headers
8457 You can hide further boring headers by entering
8458 @code{gnus-article-hide-boring-headers} into
8459 @code{gnus-article-display-hook}. What this function does depends on
8460 the @code{gnus-boring-article-headers} variable. It's a list, but this
8461 list doesn't actually contain header names. Instead is lists various
8462 @dfn{boring conditions} that Gnus can check and remove from sight.
8464 These conditions are:
8467 Remove all empty headers.
8469 Remove the @code{Newsgroups} header if it only contains the current group
8472 Remove the @code{Followup-To} header if it is identical to the
8473 @code{Newsgroups} header.
8475 Remove the @code{Reply-To} header if it lists the same address as the
8478 Remove the @code{Date} header if the article is less than three days
8482 To include the four first elements, you could say something like;
8485 (setq gnus-boring-article-headers
8486 '(empty newsgroups followup-to reply-to))
8489 This is also the default value for this variable.
8493 @section Using @sc{mime}
8496 Mime is a standard for waving your hands through the air, aimlessly,
8497 while people stand around yawning.
8499 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
8500 while all newsreaders die of fear.
8502 @sc{mime} may specify what character set the article uses, the encoding
8503 of the characters, and it also makes it possible to embed pictures and
8504 other naughty stuff in innocent-looking articles.
8506 @vindex gnus-show-mime
8507 @vindex gnus-show-mime-method
8508 @vindex gnus-strict-mime
8509 Gnus handles @sc{mime} by shoving the articles through
8510 @code{gnus-show-mime-method}, which is @code{metamail-buffer} by
8511 default. Set @code{gnus-show-mime} to @code{t} if you want to use
8512 @sc{mime} all the time. However, if @code{gnus-strict-mime} is
8513 non-@code{nil}, the @sc{mime} method will only be used if there are
8514 @sc{mime} headers in the article.
8516 It might be best to just use the toggling functions from the summary
8517 buffer to avoid getting nasty surprises. (For instance, you enter the
8518 group @samp{alt.sing-a-long} and, before you know it, @sc{mime} has
8519 decoded the sound file in the article and some horrible sing-a-long song
8520 comes streaming out out your speakers, and you can't find the volume
8521 button, because there isn't one, and people are starting to look at you,
8522 and you try to stop the program, but you can't, and you can't find the
8523 program to control the volume, and everybody else in the room suddenly
8524 decides to look at you disdainfully, and you'll feel rather stupid.)
8526 Any similarity to real events and people is purely coincidental. Ahem.
8529 @node Customizing Articles
8530 @section Customizing Articles
8531 @cindex article customization
8533 @vindex gnus-article-display-hook
8534 The @code{gnus-article-display-hook} is called after the article has
8535 been inserted into the article buffer. It is meant to handle all
8536 treatment of the article before it is displayed.
8538 By default it contains @code{gnus-article-hide-headers},
8539 @code{gnus-article-treat-overstrike}, and
8540 @code{gnus-article-maybe-highlight}, but there are thousands, nay
8541 millions, of functions you can put in this hook. For an overview of
8542 functions @xref{Article Highlighting}, @xref{Article Hiding},
8543 @xref{Article Washing}, @xref{Article Buttons} and @xref{Article Date}.
8545 You can, of course, write your own functions. The functions are called
8546 from the article buffer, and you can do anything you like, pretty much.
8547 There is no information that you have to keep in the buffer---you can
8548 change everything. However, you shouldn't delete any headers. Instead
8549 make them invisible if you want to make them go away.
8552 @node Article Keymap
8553 @section Article Keymap
8555 Most of the keystrokes in the summary buffer can also be used in the
8556 article buffer. They should behave as if you typed them in the summary
8557 buffer, which means that you don't actually have to have a summary
8558 buffer displayed while reading. You can do it all from the article
8561 A few additional keystrokes are available:
8566 @kindex SPACE (Article)
8567 @findex gnus-article-next-page
8568 Scroll forwards one page (@code{gnus-article-next-page}).
8571 @kindex DEL (Article)
8572 @findex gnus-article-prev-page
8573 Scroll backwards one page (@code{gnus-article-prev-page}).
8576 @kindex C-c ^ (Article)
8577 @findex gnus-article-refer-article
8578 If point is in the neighborhood of a @code{Message-ID} and you press
8579 @kbd{r}, Gnus will try to get that article from the server
8580 (@code{gnus-article-refer-article}).
8583 @kindex C-c C-m (Article)
8584 @findex gnus-article-mail
8585 Send a reply to the address near point (@code{gnus-article-mail}). If
8586 given a prefix, include the mail.
8590 @findex gnus-article-show-summary
8591 Reconfigure the buffers so that the summary buffer becomes visible
8592 (@code{gnus-article-show-summary}).
8596 @findex gnus-article-describe-briefly
8597 Give a very brief description of the available keystrokes
8598 (@code{gnus-article-describe-briefly}).
8601 @kindex TAB (Article)
8602 @findex gnus-article-next-button
8603 Go to the next button, if any (@code{gnus-article-next-button}. This
8604 only makes sense if you have buttonizing turned on.
8607 @kindex M-TAB (Article)
8608 @findex gnus-article-prev-button
8609 Go to the previous button, if any (@code{gnus-article-prev-button}.
8615 @section Misc Article
8619 @item gnus-single-article-buffer
8620 @vindex gnus-single-article-buffer
8621 If non-@code{nil}, use the same article buffer for all the groups.
8622 (This is the default.) If @code{nil}, each group will have its own
8625 @vindex gnus-article-prepare-hook
8627 @item gnus-article-prepare-hook
8628 This hook is called right after the article has been inserted into the
8629 article buffer. It is mainly intended for functions that do something
8630 depending on the contents; it should probably not be used for changing
8631 the contents of the article buffer.
8632 @vindex gnus-article-display-hook
8634 @item gnus-article-display-hook
8635 This hook is called as the last thing when displaying an article, and is
8636 intended for modifying the contents of the buffer, doing highlights,
8637 hiding headers, and the like.
8638 @vindex gnus-article-mode-line-format
8640 @item gnus-article-mode-line-format
8641 This variable is a format string along the same lines as
8642 @code{gnus-summary-mode-line-format}. It accepts exactly the same
8643 format specifications as that variable.
8644 @vindex gnus-break-pages
8646 @item gnus-break-pages
8647 Controls whether @dfn{page breaking} is to take place. If this variable
8648 is non-@code{nil}, the articles will be divided into pages whenever a
8649 page delimiter appears in the article. If this variable is @code{nil},
8650 paging will not be done.
8652 @item gnus-page-delimiter
8653 @vindex gnus-page-delimiter
8654 This is the delimiter mentioned above. By default, it is @samp{^L}
8658 @node The Server Buffer
8659 @chapter The Server Buffer
8661 Traditionally, a @dfn{server} is a machine or a piece of software that
8662 one connects to, and then requests information from. Gnus does not
8663 connect directly to any real servers, but does all transactions through
8664 one backend or other. But that's just putting one layer more between
8665 the actual media and Gnus, so we might just as well say that each
8666 backend represents a virtual server.
8668 For instance, the @code{nntp} backend may be used to connect to several
8669 different actual @sc{nntp} servers, or, perhaps, to many different ports
8670 on the same actual @sc{nntp} server. You tell Gnus which backend to
8671 use, and what parameters to set by specifying a @dfn{select method}.
8673 These select methods specifications can sometimes become quite
8674 complicated---say, for instance, that you want to read from the
8675 @sc{nntp} server @samp{news.funet.fi} on port number @samp{13}, which
8676 hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
8677 Anyways, if you had to specify that for each group that used this
8678 server, that would be too much work, so Gnus offers a way of putting
8679 names to methods, which is what you do in the server buffer.
8681 To enter the server buffer, user the @kbd{^}
8682 (@code{gnus-group-enter-server-mode}) command in the group buffer.
8685 * Server Buffer Format:: You can customize the look of this buffer.
8686 * Server Commands:: Commands to manipulate servers.
8687 * Example Methods:: Examples server specifications.
8688 * Servers & Methods:: You can use server names as select methods.
8689 * Unavailable Servers:: Some servers you try to contact may be down.
8692 @node Server Buffer Format
8693 @section Server Buffer Format
8694 @cindex server buffer format
8696 @vindex gnus-server-line-format
8697 You can change the look of the server buffer lines by changing the
8698 @code{gnus-server-line-format} variable. This is a @code{format}-like
8699 variable, with some simple extensions:
8704 How the news is fetched---the backend name.
8707 The name of this server.
8710 Where the news is to be fetched from---the address.
8713 @node Server Commands
8714 @section Server Commands
8715 @cindex server commands
8720 Browse the current server (@code{gnus-server-read-server}).
8723 Return to the group buffer (@code{gnus-server-exit}).
8726 List all servers (@code{gnus-server-list-servers}).
8729 Kill the current server (@code{gnus-server-kill-server}).
8732 Yank the previously killed server (@code{gnus-server-yank-server}).
8735 Copy the current server (@code{gnus-server-copy-server}).
8738 Add a new server (@code{gnus-server-add-server}).
8741 Edit a server (@code{gnus-server-edit-server}).
8744 @node Example Methods
8745 @section Example Methods
8747 Most select methods are pretty simple and self-explanatory:
8750 (nntp "news.funet.fi")
8753 Reading directly from the spool is even simpler:
8759 As you can see, the first element in a select method is the name of the
8760 backend, and the second is the @dfn{address}, or @dfn{name}, if you
8763 After these two elements, there may be a random number of @var{(variable
8766 To go back to the first example---imagine that you want to read from
8767 port @code{15} from that machine. This is what the select method should
8771 (nntp "news.funet.fi" (nntp-port-number 15))
8774 You should read the documentation to each backend to find out what
8775 variables are relevant, but here's an @code{nnmh} example.
8777 @code{nnmh} is a mail backend that reads a spool-like structure. Say
8778 you have two structures that you wish to access: One is your private
8779 mail spool, and the other is a public one. Here's the possible spec for
8783 (nnmh "private" (nnmh-directory "~/private/mail/"))
8786 (This server is then called @samp{private}, but you may have guessed
8789 Here's the method for the public spool:
8793 (nnmh-directory "/usr/information/spool/")
8794 (nnmh-get-new-mail nil))
8797 @node Servers & Methods
8798 @section Servers & Methods
8800 Wherever you would normally use a select method
8801 (eg. @code{gnus-secondary-select-method}, in the group select method,
8802 when browsing a foreign server) you can use a virtual server name
8803 instead. This could potentially save lots of typing. And it's nice all
8807 @node Unavailable Servers
8808 @section Unavailable Servers
8810 If a server seems to be unreachable, Gnus will mark that server as
8811 @code{denied}. That means that any subsequent attempt to make contact
8812 with that server will just be ignored. "It can't be opened," Gnus will
8813 tell you, without making the least effort to see whether that is
8814 actually the case or not.
8816 That might seem quite naughty, but it does make sense most of the time.
8817 Let's say you have 10 groups subscribed to the server
8818 @samp{nepholococcygia.com}. This server is located somewhere quite far
8819 away from you, the machine is quite, so it takes 1 minute just to find
8820 out that it refuses connection from you today. If Gnus were to attempt
8821 to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
8822 that. Once it has gotten a single "connection refused", it will regard
8823 that server as "down".
8825 So, what happens if the machine was only feeling unwell temporarily?
8826 How do you test to see whether the machine has come up again?
8828 You jump to the server buffer (@pxref{The Server Buffer}) and poke ut
8829 with the following commands:
8835 @findex gnus-server-open-server
8836 Try to establish connection to the server on the current line
8837 (@code{gnus-server-open-server}).
8841 @findex gnus-server-close-server
8842 Close the connection (if any) to the server
8843 (@code{gnus-server-close-server}).
8847 @findex gnus-server-deny-server
8848 Mark the current server as unreachable
8849 (@code{gnus-server-deny-server}).
8853 @findex gnus-server-remove-denials
8854 Remove all marks to whether Gnus was denied connection from all servers
8855 (@code{gnus-server-remove-denials}).
8864 Other people use @dfn{kill files}, but we here at Gnus Towers like
8865 scoring better than killing, so we'd rather switch than fight. They do
8866 something completely different as well, so sit up straight and pay
8869 @vindex gnus-summary-mark-below
8870 All articles have a default score (@code{gnus-summary-default-score}),
8871 which is 0 by default. This score may be raised or lowered either
8872 interactively or by score files. Articles that have a score lower than
8873 @code{gnus-summary-mark-below} are marked as read.
8875 Gnus will read any @dfn{score files} that apply to the current group
8876 before generating the summary buffer.
8878 There are several commands in the summary buffer that insert score
8879 entries based on the current article. You can, for instance, ask Gnus to
8880 lower or increase the score of all articles with a certain subject.
8882 There are two sorts of scoring entries: Permanent and temporary.
8883 Temporary score entries are self-expiring entries. Any entries that are
8884 temporary and have not been used for, say, a week, will be removed
8885 silently to help keep the sizes of the score files down.
8888 * Summary Score Commands:: Adding score entries for the current group.
8889 * Group Score Commands:: General score commands.
8890 * Score Variables:: Customize your scoring. (My, what terminology).
8891 * Score File Format:: What a score file may contain.
8892 * Score File Editing:: You can edit score files by hand as well.
8893 * Adaptive Scoring:: Big Sister Gnus *knows* what you read.
8894 * Followups To Yourself:: Having Gnus notice when people answer you.
8895 * Scoring Tips:: How to score effectively.
8896 * Reverse Scoring:: That problem child of old is not problem.
8897 * Global Score Files:: Earth-spanning, ear-splitting score files.
8898 * Kill Files:: They are still here, but they can be ignored.
8901 @node Summary Score Commands
8902 @section Summary Score Commands
8903 @cindex score commands
8905 The score commands that alter score entries do not actually modify real
8906 score files. That would be too inefficient. Gnus maintains a cache of
8907 previously loaded score files, one of which is considered the
8908 @dfn{current score file alist}. The score commands simply insert
8909 entries into this list, and upon group exit, this list is saved.
8911 The current score file is by default the group's local score file, even
8912 if no such score file actually exists. To insert score commands into
8913 some other score file (eg. @file{all.SCORE}), you must first make this
8914 score file the current one.
8916 General score commands that don't actually change the score file:
8921 @kindex V s (Summary)
8922 @findex gnus-summary-set-score
8923 Set the score of the current article (@code{gnus-summary-set-score}).
8926 @kindex V S (Summary)
8927 @findex gnus-summary-current-score
8928 Display the score of the current article
8929 (@code{gnus-summary-current-score}).
8932 @kindex V t (Summary)
8933 @findex gnus-score-find-trace
8934 Display all score rules that have been used on the current article
8935 (@code{gnus-score-find-trace}).
8939 @findex gnus-summary-rescore
8940 Run the current summary through the scoring process
8941 (@code{gnus-summary-rescore}). This might be useful if you're playing
8942 around with your score files behind Gnus' back and want to see the
8943 effect you're having.
8946 @kindex V a (Summary)
8947 @findex gnus-summary-score-entry
8948 Add a new score entry, and allow specifying all elements
8949 (@code{gnus-summary-score-entry}).
8952 @kindex V c (Summary)
8953 @findex gnus-score-change-score-file
8954 Make a different score file the current
8955 (@code{gnus-score-change-score-file}).
8958 @kindex V e (Summary)
8959 @findex gnus-score-edit-alist
8960 Edit the current score file (@code{gnus-score-edit-alist}). You will be
8961 popped into a @code{gnus-score-mode} buffer (@pxref{Score File
8965 @kindex V f (Summary)
8966 @findex gnus-score-edit-file
8967 Edit a score file and make this score file the current one
8968 (@code{gnus-score-edit-file}).
8971 @kindex V C (Summary)
8972 @findex gnus-score-customize
8973 Customize a score file in a visually pleasing manner
8974 (@code{gnus-score-customize}).
8977 @kindex I C-i (Summary)
8978 @findex gnus-summary-raise-score
8979 Increase the score of the current article
8980 (@code{gnus-summary-raise-score}).
8983 @kindex L C-l (Summary)
8984 @findex gnus-summary-lower-score
8985 Lower the score of the current article
8986 (@code{gnus-summary-lower-score}).
8989 The rest of these commands modify the local score file.
8994 @kindex V m (Summary)
8995 @findex gnus-score-set-mark-below
8996 Prompt for a score, and mark all articles with a score below this as
8997 read (@code{gnus-score-set-mark-below}).
9000 @kindex V E (Summary)
9001 @findex gnus-score-set-expunge-below
9002 Expunge all articles with a score below the default score (or the
9003 numeric prefix) (@code{gnus-score-set-expunge-below}).
9006 The keystrokes for actually making score entries follow a very regular
9007 pattern, so there's no need to list all the commands. (Hundreds of
9012 The first key is either @kbd{I} (upper case i) for increasing the score
9013 or @kbd{L} for lowering the score.
9015 The second key says what header you want to score on. The following
9020 Score on the author name.
9023 Score on the subject line.
9026 Score on the Xref line---i.e., the cross-posting line.
9029 Score on thread---the References line.
9035 Score on the number of lines.
9038 Score on the Message-ID.
9051 The third key is the match type. Which match types are legal depends on
9052 what headers you are scoring on.
9096 Greater than number.
9101 The fourth and final key says whether this is a temporary (i.e., expiring)
9102 score entry, or a permanent (i.e., non-expiring) score entry, or whether
9103 it is to be done immediately, without adding to the score file.
9107 Temporary score entry.
9110 Permanent score entry.
9113 Immediately scoring.
9118 So, let's say you want to increase the score on the current author with
9119 exact matching permanently: @kbd{I a e p}. If you want to lower the
9120 score based on the subject line, using substring matching, and make a
9121 temporary score entry: @kbd{L s s t}. Pretty easy.
9123 To make things a bit more complicated, there are shortcuts. If you use
9124 a capital letter on either the second or third keys, Gnus will use
9125 defaults for the remaining one or two keystrokes. The defaults are
9126 "substring" and "temporary". So @kbd{I A} is the same as @kbd{I a s t},
9127 and @kbd{I a R} is the same as @kbd{I a r t}.
9129 @vindex gnus-score-mimic-keymap
9130 The @code{gnus-score-mimic-keymap} says whether these commands will
9131 pretend they are keymaps or not.
9134 @node Group Score Commands
9135 @section Group Score Commands
9136 @cindex group score commands
9138 There aren't many of these as yet, I'm afraid.
9144 @findex gnus-score-flush-cache
9145 Gnus maintains a cache of score alists to avoid having to reload them
9146 all the time. This command will flush the cache
9147 (@code{gnus-score-flush-cache}).
9152 @node Score Variables
9153 @section Score Variables
9154 @cindex score variables
9158 @item gnus-use-scoring
9159 @vindex gnus-use-scoring
9160 If @code{nil}, Gnus will not check for score files, and will not, in
9161 general, do any score-related work. This is @code{t} by default.
9163 @item gnus-kill-killed
9164 @vindex gnus-kill-killed
9165 If this variable is @code{nil}, Gnus will never apply score files to
9166 articles that have already been through the kill process. While this
9167 may save you lots of time, it also means that if you apply a kill file
9168 to a group, and then change the kill file and want to run it over you
9169 group again to kill more articles, it won't work. You have to set this
9170 variable to @code{t} to do that. (It is @code{t} by default.)
9172 @item gnus-kill-files-directory
9173 @vindex gnus-kill-files-directory
9174 All kill and score files will be stored in this directory, which is
9175 initialized from the @samp{SAVEDIR} environment variable by default.
9176 This is @file{~/News/} by default.
9178 @item gnus-score-file-suffix
9179 @vindex gnus-score-file-suffix
9180 Suffix to add to the group name to arrive at the score file name
9181 (@samp{SCORE} by default.)
9183 @item gnus-score-uncacheable-files
9184 @vindex gnus-score-uncacheable-files
9186 All score files are normally cached to avoid excessive re-loading of
9187 score files. However, if this might make you Emacs grow big and
9188 bloated, so this regexp can be used to weed out score files that are
9189 unlikely to be needed again. It would be a bad idea to deny caching of
9190 @file{all.SCORE}, while it might be a good idea to not cache
9191 @file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
9192 variable is @samp{"ADAPT$"} by default, so no adaptive score files will
9195 @item gnus-save-score
9196 @vindex gnus-save-score
9197 If you have really complicated score files, and do lots of batch
9198 scoring, then you might set this variable to @code{t}. This will make
9199 Gnus save the scores into the @file{.newsrc.eld} file.
9201 @item gnus-save-score
9202 @vindex gnus-save-score
9203 If you have really complicated score files, and do lots of batch
9204 scoring, then you might set this variable to @code{t}. This will make
9205 Gnus save the scores into the @file{.newsrc.eld} file.
9207 @item gnus-score-interactive-default-score
9208 @vindex gnus-score-interactive-default-score
9209 Score used by all the interactive raise/lower commands to raise/lower
9210 score with. Default is 1000, which may seem excessive, but this is to
9211 ensure that the adaptive scoring scheme gets enough room to play with.
9212 We don't want the small changes from the adaptive scoring to overwrite
9213 manually entered data.
9215 @item gnus-summary-default-score
9216 @vindex gnus-summary-default-score
9217 Default score of an article, which is 0 by default.
9219 @item gnus-score-over-mark
9220 @vindex gnus-score-over-mark
9221 Mark (in the third column) used for articles with a score over the
9222 default. Default is @samp{+}.
9224 @item gnus-score-below-mark
9225 @vindex gnus-score-below-mark
9226 Mark (in the third column) used for articles with a score below the
9227 default. Default is @samp{-}.
9229 @item gnus-score-find-score-files-function
9230 @vindex gnus-score-find-score-files-function
9231 Function used to find score files for the current group. This function
9232 is called with the name of the group as the argument.
9234 Predefined functions available are:
9237 @item gnus-score-find-single
9238 @findex gnus-score-find-single
9239 Only apply the group's own score file.
9241 @item gnus-score-find-bnews
9242 @findex gnus-score-find-bnews
9243 Apply all score files that match, using bnews syntax. This is the
9244 default. For instance, if the current group is @samp{gnu.emacs.gnus},
9245 @samp{all.emacs.all.SCORE}, @samp{not.alt.all.SCORE} and
9246 @samp{gnu.all.SCORE} would all apply. In short, the instances of
9247 @samp{all} in the score file names are translated into @samp{.*}, and
9248 then a regexp match is done.
9250 This means that if you have some score entries that you want to apply to
9251 all groups, then you put those entries in the @file{all.SCORE} file.
9253 If @code{gnus-use-long-file-name} is non-@code{nil}, this won't work
9254 very will. It will find stuff like @file{gnu/all/SCORE}, but will not
9255 find files like @file{not/gnu/all/SCORE}.
9257 @item gnus-score-find-hierarchical
9258 @findex gnus-score-find-hierarchical
9259 Apply all score files from all the parent groups. This means that you
9260 can't have score files like @file{all.SCORE} or @file{all.emacs.SCORE},
9261 but you can have @file{SCORE}, @file{comp.SCORE} and
9262 @file{comp.emacs.SCORE}.
9265 This variable can also be a list of functions. In that case, all these
9266 functions will be called, and all the returned lists of score files will
9267 be applied. These functions can also return lists of score alists
9268 directly. In that case, the functions that return these non-file score
9269 alists should probably be placed before the "real" score file functions,
9270 to ensure that the last score file returned is the local score file.
9273 @item gnus-score-expiry-days
9274 @vindex gnus-score-expiry-days
9275 This variable says how many days should pass before an unused score file
9276 entry is expired. If this variable is @code{nil}, no score file entries
9277 are expired. It's 7 by default.
9279 @item gnus-update-score-entry-dates
9280 @vindex gnus-update-score-entry-dates
9281 If this variable is non-@code{nil}, matching score entries will have
9282 their dates updated. (This is how Gnus controls expiry---all
9283 non-matching entries will become too old while matching entries will
9284 stay fresh and young.) However, if you set this variable to @code{nil},
9285 even matching entries will grow old and will have to face that oh-so
9291 @node Score File Format
9292 @section Score File Format
9293 @cindex score file format
9295 A score file is an @code{emacs-lisp} file that normally contains just a
9296 single form. Casual users are not expected to edit these files;
9297 everything can be changed from the summary buffer.
9299 Anyway, if you'd like to dig into it yourself, here's an example:
9303 ("Lars Ingebrigtsen" -10000)
9305 ("larsi\\|lmi" -50000 nil R))
9307 ("Ding is Badd" nil 728373))
9309 ("alt.politics" -1000 728372 s))
9314 (mark-and-expunge -10)
9318 (files "/hom/larsi/News/gnu.SCORE")
9319 (exclude-files "all.SCORE")
9320 (local (gnus-newsgroup-auto-expire t)
9321 (gnus-summary-make-false-root 'empty))
9325 This example demonstrates absolutely everything about a score file.
9327 Even though this looks much like lisp code, nothing here is actually
9328 @code{eval}ed. The lisp reader is used to read this form, though, so it
9329 has to be legal syntactically, if not semantically.
9331 Six keys are supported by this alist:
9336 If the key is a string, it is the name of the header to perform the
9337 match on. Scoring can only be performed on these eight headers:
9338 @samp{From}, @samp{Subject}, @samp{References}, @samp{Message-ID},
9339 @samp{Xref}, @samp{Lines}, @samp{Chars} and @samp{Date}. In addition to
9340 these headers, there are three strings to tell Gnus to fetch the entire
9341 article and do the match on larger parts of the article: @samp{Body}
9342 will perform the match on the body of the article, @samp{Head} will
9343 perform the match on the head of the article, and @samp{All} will
9344 perform the match on the entire article. Note that using any of these
9345 last three keys will slow down group entry @emph{considerably}. The
9346 final "header" you can score on is @samp{Followup}. These score entries
9347 will result in new score entries being added for all follow-ups to
9348 articles that matches these score entries.
9350 Following this key is a random number of score entries, where each score
9351 entry has one to four elements.
9355 The first element is the @dfn{match element}. On most headers this will
9356 be a string, but on the Lines and Chars headers, this must be an
9360 If the second element is present, it should be a number---the @dfn{score
9361 element}. This number should be an integer in the neginf to posinf
9362 interval. This number is added to the score of the article if the match
9363 is successful. If this element is not present, the
9364 @code{gnus-score-interactive-default-score} number will be used
9365 instead. This is 1000 by default.
9368 If the third element is present, it should be a number---the @dfn{date
9369 element}. This date says when the last time this score entry matched,
9370 which provides a mechanism for expiring the score entries. It this
9371 element is not present, the score entry is permanent. The date is
9372 represented by the number of days since December 31, 1 ce.
9375 If the fourth element is present, it should be a symbol---the @dfn{type
9376 element}. This element specifies what function should be used to see
9377 whether this score entry matches the article. What match types that can
9378 be used depends on what header you wish to perform the match on.
9381 @item From, Subject, References, Xref, Message-ID
9382 For most header types, there are the @code{r} and @code{R} (regexp) as
9383 well as @code{s} and @code{S} (substring) types and @code{e} and
9384 @code{E} (exact match) types. If this element is not present, Gnus will
9385 assume that substring matching should be used. @code{R} and @code{S}
9386 differ from the other two in that the matches will be done in a
9387 case-sensitive manner. All these one-letter types are really just
9388 abbreviations for the @code{regexp}, @code{string} and @code{exact}
9389 types, which you can use instead, if you feel like.
9392 These two headers use different match types: @code{<}, @code{>},
9393 @code{=}, @code{>=} and @code{<=}.
9396 For the Date header we have three match types: @code{before}, @code{at}
9397 and @code{after}. I can't really imagine this ever being useful, but,
9398 like, it would feel kinda silly not to provide this function. Just in
9399 case. You never know. Better safe than sorry. Once burnt, twice shy.
9400 Don't judge a book by its cover. Never not have sex on a first date.
9402 @item Head, Body, All
9403 These three match keys use the same match types as the @code{From} (etc)
9407 This match key will add a score entry on all articles that followup to
9408 some author. Uses the same match types as the @code{From} header uses.
9411 This match key will add a ascore entry on all articles that are part of
9412 a thread. Uses the same match types as the @code{References} header
9418 The value of this entry should be a number. Any articles with a score
9419 lower than this number will be marked as read.
9422 The value of this entry should be a number. Any articles with a score
9423 lower than this number will be removed from the summary buffer.
9425 @item mark-and-expunge
9426 The value of this entry should be a number. Any articles with a score
9427 lower than this number will be marked as read and removed from the
9430 @item thread-mark-and-expunge
9431 The value of this entry should be a number. All articles that belong to
9432 a thread that has a total score below this number will be marked as read
9433 and removed from the summary buffer. @code{gnus-thread-score-function}
9434 says how to compute the total score for a thread.
9437 The value of this entry should be any number of file names. These files
9438 are assumed to be score files as well, and will be loaded the same way
9442 The clue of this entry should be any number of files. This files will
9443 not be loaded, even though they would normally be so, for some reason or
9447 The value of this entry will be @code{eval}el. This element will be
9448 ignored when handling global score files.
9451 Read-only score files will not be updated or saved. Global score files
9452 should feature this atom (@pxref{Global Score Files}).
9455 The value of this entry should be a number. Articles that do not have
9456 parents will get this number added to their scores.
9459 This entry controls the adaptive scoring. If it is @code{t}, the
9460 default adaptive scoring rules will be used. If it is @code{ignore}, no
9461 adaptive scoring will be performed on this group. If it is a list, this
9462 list will be used as the adaptive scoring rules. If it isn't present,
9463 or is something other than @code{t} or @code{ignore}, the default
9464 adaptive scoring rules will be used. If you want to use adaptive
9465 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
9466 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
9467 not want adaptive scoring. If you only want adaptive scoring in a few
9468 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
9469 insert @code{(adapt t)} in the score files of the groups where you want
9473 All adaptive score entries will go to the file named by this entry. It
9474 will also be applied when entering the group. This atom might be handy
9475 if you want to adapt on several groups at once, using the same adaptive
9476 file for a number of groups.
9479 @cindex local variables
9480 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
9481 Each @var{var} will be made buffer-local to the current summary buffer,
9482 and set to the value specified. This is a convenient, if somewhat
9483 strange, way of setting variables in some groups if you don't like hooks
9487 @node Score File Editing
9488 @section Score File Editing
9490 You normally enter all scoring commands from the summary buffer, but you
9491 might feel the urge to edit them by hand as well, so we've supplied you
9492 with a mode for that.
9494 It's simply a slightly customized @code{emacs-lisp} mode, with these
9495 additional commands:
9500 @kindex C-c C-c (Score)
9501 @findex gnus-score-edit-done
9502 Save the changes you have made and return to the summary buffer
9503 (@code{gnus-score-edit-done}).
9506 @kindex C-c C-d (Score)
9507 @findex gnus-score-edit-insert-date
9508 Insert the current date in numerical format
9509 (@code{gnus-score-edit-insert-date}). This is really the day number, if
9513 @kindex C-c C-p (Score)
9514 @findex gnus-score-pretty-print
9515 The adaptive score files are saved in an unformatted fashion. If you
9516 intend to read one of these files, you want to @dfn{pretty print} it
9517 first. This command (@code{gnus-score-pretty-print}) does that for
9522 @node Adaptive Scoring
9523 @section Adaptive Scoring
9524 @cindex adaptive scoring
9526 If all this scoring is getting you down, Gnus has a way of making it all
9527 happen automatically---as if by magic. Or rather, as if by artificial
9528 stupidity, to be precise.
9530 @vindex gnus-use-adaptive-scoring
9531 When you read an article, or mark an article as read, or kill an
9532 article, you leave marks behind. On exit from the group, Gnus can sniff
9533 these marks and add score elements depending on what marks it finds.
9534 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
9537 @vindex gnus-default-adaptive-score-alist
9538 To give you complete control over the scoring process, you can customize
9539 the @code{gnus-default-adaptive-score-alist} variable. By default, it
9540 looks something like this:
9543 (defvar gnus-default-adaptive-score-alist
9544 '((gnus-unread-mark)
9545 (gnus-ticked-mark (from 4))
9546 (gnus-dormant-mark (from 5))
9547 (gnus-del-mark (from -4) (subject -1))
9548 (gnus-read-mark (from 4) (subject 2))
9549 (gnus-expirable-mark (from -1) (subject -1))
9550 (gnus-killed-mark (from -1) (subject -3))
9551 (gnus-kill-file-mark)
9552 (gnus-catchup-mark (from -1) (subject -1))))
9555 As you see, each element in this alist has a mark as a key (either a
9556 variable name or a "real" mark---a character). Following this key is a
9557 random number of header/score pairs.
9559 To take @code{gnus-del-mark} as an example---this alist says that all
9560 articles that have that mark (i.e., are marked with @samp{D}) will have a
9561 score entry added to lower based on the @code{From} header by -4, and
9562 lowered by @code{Subject} by -1. Change this to fit your prejudices.
9564 The headers you can score on are @code{from}, @code{subject},
9565 @code{message-id}, @code{references}, @code{xref}, @code{lines},
9566 @code{chars} and @code{date}. In addition, you can score on
9567 @code{followup}, which will create an adaptive score entry that matches
9568 on the @code{References} header using the @code{Message-ID} of the
9569 current article, thereby matching the following thread.
9571 You can also score on @code{thread}, which will try to score all
9572 articles that appear in a thread. @code{thread} matches uses a
9573 @code{Message-ID} to match on the @code{References} header of the
9574 article. If the match is made, the @code{Message-ID} of the article is
9575 added to the @code{thread} rule. (Think about it. I'd recommend two
9576 aspirins afterwards.)
9578 If you use this scheme, you should set @code{mark-below} to something
9579 small---like -300, perhaps, to avoid having small random changes result
9580 in articles getting marked as read.
9582 After using adaptive scoring for a week or so, Gnus should start to
9583 become properly trained and enhance the authors you like best, and kill
9584 the authors you like least, without you having to say so explicitly.
9586 You can control what groups the adaptive scoring is to be performed on
9587 by using the score files (@pxref{Score File Format}). This will also
9588 let you use different rules in different groups.
9590 @vindex gnus-adaptive-file-suffix
9591 The adaptive score entries will be put into a file where the name is the
9592 group name with @code{gnus-adaptive-file-suffix} appended. The default
9595 @vindex gnus-score-exact-adapt-limit
9596 When doing adaptive scoring, substring or fuzzy matching would probably
9597 give you the best results in most cases. However, if the header one
9598 matches is short, the possibility for false positives is great, so if
9599 the length of the match is less than
9600 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
9601 this variable is @code{nil}, exact matching will always be used to avoid
9605 @node Followups To Yourself
9606 @section Followups To Yourself
9608 Gnus offers two commands for picking out the @code{Message-ID} header in
9609 the current buffer. Gnus will then add a score rule that scores using
9610 this @code{Message-ID} on the @code{References} header of other
9611 articles. This will, in effect, increase the score of all articles that
9612 respond to the article in the current buffer. Quite useful if you want
9613 to easily note when people answer what you've said.
9617 @item gnus-score-followup-article
9618 @findex gnus-score-followup-article
9619 This will add a score to articles that directly follow up your own
9622 @item gnus-score-followup-thread
9623 @findex gnus-score-followup-thread
9624 This will add a score to all articles that appear in a thread "below"
9628 @vindex gnus-inews-article-hook
9629 These two functions are both primarily meant to be used in hooks like
9630 @code{gnus-inews-article-hook}.
9634 @section Scoring Tips
9635 @cindex scoring tips
9640 If you want to lower the score of crossposts, the line to match on is
9641 the @code{Xref} header.
9643 ("xref" (" talk.politics.misc:" -1000))
9646 @item Multiple crossposts
9647 If you want to lower the score of articles that have been crossposted to
9648 more than, say, 3 groups:
9650 ("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
9653 @item Matching on the body
9654 This is generally not a very good idea---it takes a very long time.
9655 Gnus actually has to fetch each individual article from the server. But
9656 you might want to anyway, I guess. Even though there are three match
9657 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
9658 and stick with it in each score file. If you use any two, each article
9659 will be fetched @emph{twice}. If you want to match a bit on the
9660 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
9663 @item Marking as read
9664 You will probably want to mark articles that has a score below a certain
9665 number as read. This is most easily achieved by putting the following
9666 in your @file{all.SCORE} file:
9670 You may also consider doing something similar with @code{expunge}.
9672 @item Negated charater classes
9673 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
9674 That will match newlines, which might lead to, well, The Unknown. Say
9675 @code{[^abcd\n]*} instead.
9678 @node Reverse Scoring
9679 @section Reverse Scoring
9680 @cindex reverse scoring
9682 If you want to keep just articles that have @samp{Sex with Emacs} in the
9683 subject header, and expunge all other articles, you could put something
9684 like this in your score file:
9688 ("Sex with Emacs" 2))
9693 So, you raise all articles that match @samp{Sex with Emacs} and mark the
9694 rest as read, and expunge them to boot.
9696 @node Global Score Files
9697 @section Global Score Files
9698 @cindex global score files
9700 Sure, other newsreaders have "global kill files". These are usually
9701 nothing more than a single kill file that applies to all groups, stored
9702 in the user's home directory. Bah! Puny, weak newsreaders!
9704 What I'm talking about here are Global Score Files. Score files from
9705 all over the world, from users everywhere, uniting all nations in one
9706 big, happy score file union! Ange-score! New and untested!
9708 @vindex gnus-global-score-files
9709 All you have to do to use other people's score files is to set the
9710 @code{gnus-global-score-files} variable. One entry for each score file,
9711 or each score file directory. Gnus will decide by itself what score
9712 files are applicable to which group.
9714 Say you want to use all score files in the
9715 @file{/ftp@@ftp.some-where:/pub/score} directory and the single score
9716 file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
9719 (setq gnus-global-score-files
9720 '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
9721 "/ftp@@ftp.some-where:/pub/score/"))
9724 @findex gnus-score-search-global-directories
9725 Simple, eh? Directory names must end with a @samp{/}. These
9726 directories are typically scanned only once during each Gnus session.
9727 If you feel the need to manually re-scan the remote directories, you can
9728 use the @code{gnus-score-search-global-directories} command.
9730 Note that, at present, using this option will slow down group entry
9731 somewhat. (That is---a lot.)
9733 If you want to start maintaining score files for other people to use,
9734 just put your score file up for anonymous ftp and announce it to the
9735 world. Become a retro-moderator! Participate in the retro-moderator
9736 wars sure to ensue, where retro-moderators battle it out for the
9737 sympathy of the people, luring them to use their score files on false
9738 premises! Yay! The net is saved!
9740 Here are some tips for the would-be retro-moderator, off the top of my
9746 Articles that are heavily crossposted are probably junk.
9748 To lower a single inappropriate article, lower by @code{Message-ID}.
9750 Particularly brilliant authors can be raised on a permanent basis.
9752 Authors that repeatedly post off-charter for the group can safely be
9753 lowered out of existence.
9755 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
9756 articles completely.
9759 Use expiring score entries to keep the size of the file down. You
9760 should probably have a long expiry period, though, as some sites keep
9761 old articles for a long time.
9764 ... I wonder whether other newsreaders will support global score files
9765 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
9766 Wave, xrn and 1stReader are bound to implement scoring. Should we start
9767 holding our breath yet?
9774 Gnus still supports those pesky old kill files. In fact, the kill file
9775 entries can now be expiring, which is something I wrote before Daniel
9776 Quinlan thought of doing score files, so I've left the code in there.
9778 In short, kill processing is a lot slower (and I do mean @emph{a lot})
9779 than score processing, so it might be a good idea to rewrite your kill
9780 files into score files.
9782 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
9783 forms into this file, which means that you can use kill files as some
9784 sort of primitive hook function to be run on group entry, even though
9785 that isn't a very good idea.
9787 XCNormal kill files look like this:
9790 (gnus-kill "From" "Lars Ingebrigtsen")
9791 (gnus-kill "Subject" "ding")
9795 This will mark every article written by me as read, and remove them from
9796 the summary buffer. Very useful, you'll agree.
9798 Other programs use a totally different kill file syntax. If Gnus
9799 encounters what looks like a @code{rn} kill file, it will take a stab at
9802 Two functions for editing a GNUS kill file:
9807 @kindex M-k (Summary)
9808 @findex gnus-summary-edit-local-kill
9809 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
9812 @kindex M-K (Summary)
9813 @findex gnus-summary-edit-global-kill
9814 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
9817 @vindex gnus-kill-file-name
9818 A kill file for the group @samp{soc.motss} is normally called
9819 @file{soc.motss.KILL}. The suffix appended to the group name to get
9820 this file name is detailed by the @code{gnus-kill-file-name} variable.
9821 The "global" kill file (not in the score file sense of "global", of
9822 course) is called just @file{KILL}.
9824 @vindex gnus-kill-save-kill-file
9825 If @code{gnus-kill-save-kill-file} is non-@code{nil}, Gnus will save the
9826 kill file after processing, which is necessary if you use expiring
9836 * Interactive:: Making Gnus ask you many questions.
9837 * Formatting Variables:: How to control the look of the buffers.
9838 * Windows Configuration:: Configuring the Gnus buffer windows.
9839 * Buttons:: Get tendonitis in ten easy steps!
9840 * Compilation & Init File:: How to speed Gnus up.
9841 * Daemons:: Gnus can do things behind your back.
9842 * NoCeM:: How to avoid spam and other fatty foods.
9843 * Various Various:: Things that are really various.
9847 @section Interactive
9852 @item gnus-novice-user
9853 @vindex gnus-novice-user
9854 If this variable is non-@code{nil}, you are either a newcomer to the
9855 World of Usenet, or you are very cautious, which is a nice thing to be,
9856 really. You will be given questions of the type "Are you sure you want
9857 to do this?" before doing anything dangerous. This is @code{t} by
9860 @item gnus-expert-user
9861 @vindex gnus-expert-user
9862 If this variable is non-@code{nil}, you will never ever be asked any
9863 questions by Gnus. It will simply assume you know what you're doing, no
9866 @item gnus-interactive-catchup
9867 @vindex gnus-interactive-catchup
9868 Require confirmation before catching up a group if non-@code{nil}. It
9869 is @code{t} by default.
9871 @item gnus-interactive-post
9872 @vindex gnus-interactive-post
9873 If non-@code{nil}, the user will be prompted for a group name when
9874 posting an article. It is @code{t} by default.
9876 @item gnus-interactive-exit
9877 @vindex gnus-interactive-exit
9878 Require confirmation before exiting Gnus. This variable is @code{t} by
9883 @node Formatting Variables
9884 @section Formatting Variables
9885 @cindex formatting variables
9887 Throughout this manual you've probably noticed lots of variables that
9888 are called things like @code{gnus-group-line-format} and
9889 @code{gnus-summary-mode-line-format}. These control how Gnus is to
9890 output lines in the various buffers. There's quite a lot of them.
9891 Fortunately, they all use the same syntax, so there's not that much to
9894 Here's an example format spec (from the group buffer): @samp{"%M%S%5y:
9895 %(%g%)\n"}. We see that it is indeed extremely ugly, and that there are
9896 lots of percentages everywhere.
9898 Each @samp{%} element will be replaced by some string or other when the
9899 buffer in question is generated. @samp{%5y} means "insert the @samp{y}
9900 spec, and pad with spaces to get a 5-character field". Just like a
9901 normal format spec, almost.
9903 You can also say @samp{%6,4y}, which means that the field will never be
9904 more than 6 characters wide and never less than 4 characters wide.
9906 There are also specs for highlighting, and these are shared by all the
9907 format variables. Text inside the @samp{%(} and @samp{%)} specifiers
9908 will get the special @code{mouse-face} property set, which means that it
9909 will be highlighted (with @code{gnus-mouse-face}) when you put the mouse
9912 Text inside the @samp{%@{} and @samp{%@}} specifiers will have their
9913 normal faces set using @code{gnus-face-0}, which is @code{bold} by
9914 default. If you say @samp{%1@{} instead, you'll get @code{gnus-face-1}
9915 instead, and so on. Create as many faces as you wish. The same goes
9916 for the @code{mouse-face} specs---you can say @samp{%3(hello%)} to have
9917 @samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
9919 Here's an alternative recipe for the group buffer:
9922 ;; Create three face types.
9923 (setq gnus-face-1 'bold)
9924 (setq gnus-face-3 'italic)
9926 ;; We want the article count to be in
9927 ;; a bold and green face. So we create
9928 ;; a new face called `my-green-bold'.
9929 (copy-face 'bold 'my-green-bold)
9931 (set-face-foreground 'my-green-bold "ForestGreen")
9932 (setq gnus-face-2 'my-green-bold)
9934 ;; Set the new & fancy format.
9935 (setq gnus-group-line-format
9936 "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
9939 I'm sure you'll be able to use this scheme to create totally unreadable
9940 and extremely vulgar displays. Have fun!
9942 Currently Gnus uses the following formatting variables:
9943 @code{gnus-group-line-format}, @code{gnus-summary-line-format},
9944 @code{gnus-server-line-format}, @code{gnus-topic-line-format},
9945 @code{gnus-group-mode-line-format},
9946 @code{gnus-summary-mode-line-format},
9947 @code{gnus-article-mode-line-format},
9948 @code{gnus-server-mode-line-format}.
9950 Note that the @samp{%(} specs (and friends) do not make any sense on the
9951 mode-line variables.
9953 All these format variables can also be random elisp forms. In that
9954 case, they will be @code{eval}ed to insert the required lines.
9956 @kindex M-x gnus-update-format
9957 @findex gnus-update-format
9958 Gnus includes a command to help you while creating your own format
9959 specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
9960 update the spec in question and pop you to a buffer where you can
9961 examine the resulting lisp code to be run to generate the line.
9964 @node Windows Configuration
9965 @section Windows Configuration
9966 @cindex windows configuration
9968 No, there's nothing here about X, so be quiet.
9970 @vindex gnus-use-full-window
9971 If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all
9972 other windows and occupy the entire Emacs screen by itself. It is
9973 @code{t} by default.
9975 @code{gnus-buffer-configuration} describes how much space each Gnus
9976 buffer should be given. Here's an excerpt of this variable:
9979 ((group (vertical 1.0 (group 1.0 point)
9980 (if gnus-carpal (group-carpal 4))))
9981 (article (vertical 1.0 (summary 0.25 point)
9985 This is an alist. The @dfn{key} is a symbol that names some action or
9986 other. For instance, when displaying the group buffer, the window
9987 configuration function will use @code{group} as the key. A full list of
9988 possible names is listed below.
9990 The @dfn{value} (i. e., the @dfn{split}) says how much space each buffer
9991 should occupy. To take the @code{article} split as an example -
9994 (article (vertical 1.0 (summary 0.25 point)
9998 This @dfn{split} says that the summary buffer should occupy 25% of upper
9999 half of the screen, and that it is placed over the article buffer. As
10000 you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all
10001 reaching for that calculator there). However, the special number
10002 @code{1.0} is used to signal that this buffer should soak up all the
10003 rest of the space avaiable after the rest of the buffers have taken
10004 whatever they need. There should be only one buffer with the @code{1.0}
10005 size spec per split.
10007 Point will be put in the buffer that has the optional third element
10010 Here's a more complicated example:
10013 (article (vertical 1.0 (group 4)
10014 (summary 0.25 point)
10015 (if gnus-carpal (summary-carpal 4))
10019 If the size spec is an integer instead of a floating point number,
10020 then that number will be used to say how many lines a buffer should
10021 occupy, not a percentage.
10023 If the @dfn{split} looks like something that can be @code{eval}ed (to be
10024 precise---if the @code{car} of the split is a function or a subr), this
10025 split will be @code{eval}ed. If the result is non-@code{nil}, it will
10026 be used as a split. This means that there will be three buffers if
10027 @code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal}
10030 Not complicated enough for you? Well, try this on for size:
10033 (article (horizontal 1.0
10038 (summary 0.25 point)
10043 Whoops. Two buffers with the mystery 100% tag. And what's that
10044 @code{horizontal} thingie?
10046 If the first element in one of the split is @code{horizontal}, Gnus will
10047 split the window horizontally, giving you two windows side-by-side.
10048 Inside each of these strips you may carry on all you like in the normal
10049 fashion. The number following @code{horizontal} says what percentage of
10050 the screen is to be given to this strip.
10052 For each split, there @emph{must} be one element that has the 100% tag.
10053 The splitting is never accurate, and this buffer will eat any leftover
10054 lines from the splits.
10056 To be slightly more formal, here's a definition of what a legal split
10060 split = frame | horizontal | vertical | buffer | form
10061 frame = "(frame " size *split ")"
10062 horizontal = "(horizontal " size *split ")"
10063 vertical = "(vertical " size *split ")"
10064 buffer = "(" buffer-name " " size *[ "point" ] ")"
10065 size = number | frame-params
10066 buffer-name = group | article | summary ...
10069 The limitations are that the @samp{frame} split can only appear as the
10070 top-level split. @samp{form} should be an Emacs Lisp form that should
10071 return a valid split. We see that each split is fully recursive, and
10072 may contain any number of @samp{vertical} and @samp{horizontal} splits.
10074 @vindex gnus-window-min-width
10075 @vindex gnus-window-min-height
10076 @cindex window height
10077 @cindex window width
10078 Finding the right sizes can be a bit complicated. No window may be less
10079 than @code{gnus-window-min-height} (default 2) characters high, and all
10080 windows must be at least @code{gnus-window-min-wide} (default 1)
10081 characters wide. Gnus will try to enforce this before applying the
10082 splits. If you want to use the normal Emacs window width/height limit,
10083 you can just set these two variables to @code{nil}.
10085 If you're not familiar with Emacs terminology, @samp{horizontal} and
10086 @samp{vertical} splits may work the opposite way of what you'd expect.
10087 Windows inside a @samp{horizontal} split are shown side-by-side, and
10088 windows within a @samp{vertical} split are shown above each other.
10090 @findex gnus-configure-frame
10091 If you want to experiment with window placement, a good tip is to call
10092 @code{gnus-configure-frame} directly with a split. This is the function
10093 that does all the real work when splitting buffers. Below is a pretty
10094 nonsensical configuration with 5 windows; two for the group buffer and
10095 three for the article buffer. (I said it was nonsensical.) If you
10096 @code{eval} the statement below, you can get an idea of how that would
10097 look straight away, without going through the normal Gnus channels.
10098 Play with it until you're satisfied, and then use
10099 @code{gnus-add-configuration} to add your new creation to the buffer
10100 configuration list.
10103 (gnus-configure-frame
10107 (article 0.3 point))
10115 You might want to have several frames as well. No prob---just use the
10116 @code{frame} split:
10119 (gnus-configure-frame
10122 (summary 0.25 point)
10124 (vertical ((height . 5) (width . 15)
10125 (user-position . t)
10126 (left . -1) (top . 1))
10131 This split will result in the familiar summary/article window
10132 configuration in the first (or "main") frame, while a small additional
10133 frame will be created where picons will be shown. As you can see,
10134 instead of the normal @samp{1.0} top-level spec, each additional split
10135 should have a frame parameter alist as the size spec.
10136 @xref{(elisp)Frame Parameters}.
10138 Here's a list of all possible keys for
10139 @code{gnus-buffer-configuaration}:
10141 @code{group}, @code{summary}, @code{article}, @code{server},
10142 @code{browse}, @code{group-mail}, @code{summary-mail},
10143 @code{summary-reply}, @code{info}, @code{summary-faq},
10144 @code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
10145 @code{followup}, @code{followup-yank}, @code{edit-score}.
10147 @findex gnus-add-configuration
10148 Since the @code{gnus-buffer-configuration} variable is so long and
10149 complicated, there's a function you can use to ease changing the config
10150 of a single setting: @code{gnus-add-configuration}. If, for instance,
10151 you want to change the @code{article} setting, you could say:
10154 (gnus-add-configuration
10155 '(article (vertical 1.0
10157 (summary .25 point)
10161 You'd typically stick these @code{gnus-add-configuration} calls in your
10162 @file{.gnus} file or in some startup hook -- they should be run after
10163 Gnus has been loaded.
10172 Those new-fangled @dfn{mouse} contraptions is very popular with the
10173 young, hep kids who don't want to learn the proper way to do things
10174 these days. Why, I remember way back in the summer of '89, when I was
10175 using Emacs on a Tops 20 system. Three hundred users on one single
10176 machine, and every user was running Simula compilers. Bah!
10180 @vindex gnus-carpal
10181 Well, you can make Gnus display bufferfuls of buttons you can click to
10182 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
10183 really. Tell the chiropractor I sent you.
10188 @item gnus-carpal-mode-hook
10189 @vindex gnus-carpal-mode-hook
10190 Hook run in all carpal mode buffers.
10192 @item gnus-carpal-button-face
10193 @vindex gnus-carpal-button-face
10194 Face used on buttons.
10196 @item gnus-carpal-group-buffer-buttons
10197 @vindex gnus-carpal-group-buffer-buttons
10198 Buttons in the group buffer.
10200 @item gnus-carpal-summary-buffer-buttons
10201 @vindex gnus-carpal-summary-buffer-buttons
10202 Buttons in the summary buffer.
10204 @item gnus-carpal-server-buffer-buttons
10205 @vindex gnus-carpal-server-buffer-buttons
10206 Buttons in the server buffer.
10208 @item gnus-carpal-browse-buffer-buttons
10209 @vindex gnus-carpal-browse-buffer-buttons
10210 Buttons in the browse buffer.
10213 All the @code{buttons} variables are lists. The elements in these list
10214 is either a cons cell where the car contains a text to be displayed and
10215 the cdr contains a function symbol, or a simple string.
10218 @node Compilation & Init File
10219 @section Compilation & Init File
10220 @cindex compilation
10222 @cindex byte-compilation
10224 @vindex gnus-init-file
10225 @findex gnus-compile
10226 When Gnus starts up, it will read the Gnus init file
10227 @code{gnus-init-file}, which is @file{.gnus} by default. It is
10228 recommended that you keep any Gnus-related functions that you have
10229 written in that file. If you want to byte-compile the file, Gnus offers
10230 the handy @kbd{M-x gnus-compile} function that will do that for you.
10232 That's not really why that function was written, though.
10234 Remember all those line format specification variables?
10235 @code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
10236 on. Now, Gnus will of course heed whatever these variables are, but,
10237 unfortunately, changing them will mean a quite significant slow-down.
10238 (The default values of these variables have byte-compiled functions
10239 associated with them, while the user-generated versions do not, of
10242 To help with this, you can run @code{gnus-compile} after you've fiddled
10243 around with the variables and feel that you're (kind of) satisfied.
10244 This will result in the new specs being byte-compiled, and you'll get
10247 The result of these byte-compilations will be written to
10248 @file{.gnus.elc} by default.
10250 Note that Gnus will read @file{.gnus.elc} instead of @file{.gnus} if
10251 @file{.gnus.elc} exists, so if you change @file{.gnus}, you should
10252 remove @file{.gnus.elc}.
10260 Gnus, being larger than any program ever written (allegedly), does lots
10261 of strange stuff that you may wish to have done while you're not
10262 present. For instance, you may want it to check for new mail once in a
10263 while. Or you may want it to close down all connections to all servers
10264 when you leave Emacs idle. And stuff like that.
10266 Gnus will let you do stuff like that by defining various
10267 @dfn{handlers}. Each handler consists of three elements: A
10268 @var{function}, a @var{time}, and an @var{idle} parameter.
10270 Here's an example of a handler that closes connections when Emacs has
10271 been idle for thirty minutes:
10274 (gnus-demon-close-connections nil 30)
10277 Here's a handler that scans for PGP headers every hour when Emacs is
10281 (gnus-demon-scan-pgp 60 t)
10284 This @var{time} parameter and than @var{idle} parameter works together
10285 in a strange, but wonderful fashion. Basically, if @var{idle} is
10286 @code{nil}, then the function will be called every @var{time} minutes.
10288 If @var{idle} is @code{t}, then the function will be called after
10289 @var{time} minutes only if Emacs is idle. So if Emacs is never idle,
10290 the function will never be called. But once Emacs goes idle, the
10291 function will be called every @var{time} minutes.
10293 If @var{idle} is a number and @var{time} is a number, the function will
10294 be called every @var{time} minutes only when Emacs has been idle for
10295 @var{idle} minutes.
10297 If @var{idle} is a number and @var{time} is @code{nil}, the function
10298 will be called once every time Emacs has been idle for @var{idle}
10301 And if @var{time} is a string, it should look like @samp{"07:31"}, and
10302 the function will then be called once every day somewhere near that
10303 time. Modified by the @var{idle} parameter, of course.
10305 @vindex gnus-demon-timestep
10306 (When I say "minute" here, I really mean @code{gnus-demon-timestep}
10307 seconds. This is @samp{60} by default. If you change that variable,
10308 all the timings in the handlers will be affected.)
10310 @vindex gnus-use-demon
10311 To set the whole thing in motion, though, you have to set
10312 @code{gnus-use-demon} to @code{t}.
10314 @vindex gnus-use-demon
10315 To set the whole thing in motion, though, you have to set
10316 @code{gnus-use-demon} to @code{t}.
10318 So, if you want to add a handler, you could put something like this in
10319 your @file{.gnus} file:
10321 @findex gnus-demon-add-handler
10323 (gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
10326 @findex gnus-demon-add-nocem
10327 @findex gnus-demon-add-scanmail
10328 @findex gnus-demon-add-disconnection
10329 Some ready-made functions to do this has been created:
10330 @code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, and
10331 @code{gnus-demon-add-scanmail}. Just put those functions in your
10332 @file{.gnus} if you want those abilities.
10334 @findex gnus-demon-init
10335 @findex gnus-demon-cancel
10336 @vindex gnus-demon-handlers
10337 If you add handlers to @code{gnus-demon-handlers} directly, you should
10338 run @code{gnus-demon-init} to make the changes take hold. To cancel all
10339 daemons, you can use the @code{gnus-demon-cancel} function.
10341 Note that adding daemons can be pretty naughty if you overdo it. Adding
10342 functions that scan all news and mail from all servers every two seconds
10343 is a sure-fire way of getting booted off any respectable system. So
10354 @node Various Various
10355 @section Various Various
10362 @vindex gnus-verbose
10363 This variable is an integer between zero and ten. The higher the value,
10364 the more messages will be displayed. If this variable is zero, Gnus
10365 will never flash any messages, if it is seven (which is the default),
10366 most important messages will be shown, and if it is ten, Gnus won't ever
10367 shut up, but will flash so many messages it will make your head swim.
10369 @item gnus-verbose-backends
10370 @vindex gnus-verbose-backends
10371 This variable works the same way as @code{gnus-verbose}, but it applies
10372 to the Gnus backends instead of Gnus proper.
10374 @item gnus-updated-mode-lines
10375 @vindex gnus-updated-mode-lines
10376 This is a list of buffers that should keep their mode lines updated.
10377 The list may contain the symbols @code{group}, @code{article} and
10378 @code{summary}. If the corresponding symbol is present, Gnus will keep
10379 that mode line updated with information that may be pertinent. If this
10380 variable is @code{nil}, screen refresh may be quicker.
10382 @cindex display-time
10384 @item gnus-mode-non-string-length
10385 @vindex gnus-mode-non-string-length
10386 By default, Gnus displays information on the current article in the mode
10387 lines of the summary and article buffers. The information Gnus wishes
10388 to display (eg. the subject of the article) is often longer than the
10389 mode lines, and therefore have to be cut off at some point. This
10390 variable says how long the other elements on the line is (i.e., the
10391 non-info part). If you put additional elements on the mode line (eg. a
10392 clock), you should modify this variable:
10394 @c Hook written by Francesco Potorti` <pot@cnuce.cnr.it>
10396 (add-hook 'display-time-hook
10397 (lambda () (setq gnus-mode-non-string-length
10399 (if line-number-mode 5 0)
10400 (if column-number-mode 4 0)
10401 (length display-time-string)))))
10404 If this variable is @code{nil} (which is the default), the mode line
10405 strings won't be chopped off, and they won't be padded either.
10408 @vindex gnus-visual
10410 @cindex highlighting
10413 If @code{nil}, Gnus won't attempt to create menus or use fancy colors
10414 or fonts. This will also inhibit loading the @file{gnus-visual.el}
10417 This variable can also be a list of visual properties that are enabled.
10418 The following elements are legal, and are all set by default:
10422 @item summary-highlight
10423 Perform various highlighting in the summary buffer.
10425 @item article-highlight
10426 Perform various highlighting in the article buffer.
10429 Turn on highlighting in all buffers.
10432 Create menus in the group buffer.
10435 Create menus in the summary buffer.
10438 Create menus in the article buffer.
10441 Create menus in the browse buffer.
10444 Create menus in the server buffer.
10447 Create menus in all buffers.
10451 So if you only want highlighting in the article buffer and menus in all
10452 buffers, you couls say something like:
10455 (setq gnus-visual '(article-highlight menu))
10458 If you want only highlighting and no menus whatsoever, you'd say:
10461 (setq gnus-visual '(highlight))
10464 @item gnus-mouse-face
10465 @vindex gnus-mouse-face
10466 This is the face (i.e., font) used for mouse highlighting in Gnus. No
10467 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
10469 @item gnus-display-type
10470 @vindex gnus-display-type
10471 This variable is symbol indicating the display Emacs is running under.
10472 The symbol should be one of @code{color}, @code{grayscale} or
10473 @code{mono}. If Gnus guesses this display attribute wrongly, either set
10474 this variable in your @file{~/.emacs} or set the resource
10475 @code{Emacs.displayType} in your @file{~/.Xdefaults}.
10477 @item gnus-background-mode
10478 @vindex gnus-background-mode
10479 This is a symbol indicating the Emacs background brightness. The symbol
10480 should be one of @code{light} or @code{dark}. If Gnus guesses this
10481 frame attribute wrongly, either set this variable in your @file{~/.emacs} or
10482 set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
10483 `gnus-display-type'.
10485 @item nnheader-max-head-length
10486 @vindex nnheader-max-head-length
10487 When the backends read straight heads of articles, they all try to read
10488 as little as possible. This variable (default @code{4096}) specifies
10489 the absolute max length the backends will try to read before giving up
10490 on finding a separator line between the head and the body. If this
10491 variable is @code{nil}, there is no upper read bound. If it is
10492 @code{t}, the backends won't try to read the articles piece by piece,
10493 but read the entire articles. This makes sense with some versions of
10496 @item nnheader-file-name-translation-alist
10497 @vindex nnheader-file-name-translation-alist
10499 @cindex illegal characters in file names
10500 @cindex characters in file names
10501 This is an alist that says how to translate characters in file names.
10502 For instance, if @samp{:} is illegal as a file character in file names
10503 on your system (you OS/2 user you), you could say something like:
10506 (setq nnheader-file-name-translation-alist
10510 In fact, this is the default value for this variable on OS/2 and MS
10511 Windows (phooey) systems.
10515 @node Customization
10516 @chapter Customization
10517 @cindex general customization
10519 All variables are properly documented elsewhere in this manual. This
10520 section is designed to give general pointers on how to customize Gnus
10521 for some quite common situations.
10524 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
10525 * Slow Terminal Connection:: You run a remote Emacs.
10526 * Little Disk Space:: You feel that having large setup files is icky.
10527 * Slow Machine:: You feel like buying a faster machine.
10530 @node Slow/Expensive Connection
10531 @section Slow/Expensive @sc{nntp} Connection
10533 If you run Emacs on a machine locally, and get your news from a machine
10534 over some very thin strings, you want to cut down on the amount of data
10535 Gnus has to get from the @sc{nntp} server.
10539 @item gnus-read-active-file
10540 Set this to @code{nil}, which will inhibit Gnus from requesting the
10541 entire active file from the server. This file is often v. large. You
10542 also have to set @code{gnus-check-new-news} and
10543 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
10544 doesn't suddenly decide to fetch the active file anyway.
10546 @item gnus-nov-is-evil
10547 This one has to be @code{nil}. If not, grabbing article headers from
10548 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
10549 support @sc{xover}; Gnus will detect this by itself.
10552 @node Slow Terminal Connection
10553 @section Slow Terminal Connection
10555 Let's say you use your home computer for dialing up the system that
10556 runs Emacs and Gnus. If your modem is slow, you want to reduce the
10557 amount of data that is sent over the wires as much as possible.
10561 @item gnus-auto-center-summary
10562 Set this to @code{nil} to inhibit Gnus from recentering the summary
10563 buffer all the time.
10565 @item gnus-visible-headers
10566 Cut down on the headers that are included in the articles to the
10567 minimum. You can, in fact, make do without them altogether---most of the
10568 useful data is in the summary buffer, anyway. Set this variable to
10569 @samp{"^NEVVVVER"} or @samp{"From:"}, or whatever you feel you need.
10571 @item gnus-article-display-hook
10572 Set this hook to all the available hiding commands:
10574 (setq gnus-article-display-hook
10575 '(gnus-article-hide-headers gnus-article-hide-signature
10576 gnus-article-hide-citation))
10579 @item gnus-use-full-window
10580 By setting this to @code{nil}, you can make all the windows smaller.
10581 While this doesn't really cut down much generally, it means that you
10582 have to see smaller portions of articles before deciding that you didn't
10583 want to read them anyway.
10585 @item gnus-thread-hide-subtree
10586 If this is non-@code{nil}, all threads in the summary buffer will be
10589 @item gnus-updated-mode-lines
10590 If this is @code{nil}, Gnus will not put information in the buffer mode
10591 lines, which might save some time.
10594 @node Little Disk Space
10595 @section Little Disk Space
10597 The startup files can get rather large, so you may want to cut their
10598 sizes a bit if you are running out of space.
10602 @item gnus-save-newsrc-file
10603 If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
10604 only save @file{.newsrc.eld}. This means that you will not be able to
10605 use any other newsreaders than Gnus. This variable is @code{t} by
10608 @item gnus-save-killed-list
10609 If this is @code{nil}, Gnus will not save the list of dead groups. You
10610 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
10611 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
10612 variable to @code{nil}. This variable is @code{t} by default.
10618 @section Slow Machine
10620 If you have a slow machine, or are just really impatient, there are a
10621 few things you can do to make Gnus run faster.
10623 Set@code{gnus-check-new-newsgroups} and
10624 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
10626 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
10627 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
10628 summary buffer faster.
10630 Set @code{gnus-article-display-hook} to @code{nil} to make article
10631 processing a bit faster.
10634 @node Troubleshooting
10635 @chapter Troubleshooting
10636 @cindex troubleshooting
10638 Gnus works @emph{so} well straight out of the box---I can't imagine any
10646 Make sure your computer is switched on.
10649 Make sure that you really load the current Gnus version. If you have
10650 been running @sc{gnus}, you need to exit Emacs and start it up again before
10654 Try doing an @kbd{M-x gnus-version}. If you get something that looks
10655 like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
10656 on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
10657 flee}, you have some old @file{.el} files lying around. Delete these.
10660 Read the help group (@kbd{G h} in the group buffer) for a FAQ and a
10664 If all else fails, report the problem as a bug.
10667 @cindex reporting bugs
10669 @kindex M-x gnus-bug
10671 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
10672 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
10673 me the backtrace. I will fix bugs, but I can only fix them if you send
10674 me a precise description as to how to reproduce the bug.
10676 You really can never be too detailed in a bug report. Always use the
10677 @kbd{M-x gnus-bug} command when you make bug reports, even if it creates
10678 a 10Kb mail each time you use it, and even if you have sent me your
10679 environment 500 times before. I don't care. I want the full info each
10682 It is also important to remember that I have no memory whatsoever. If
10683 you send a bug report, and I send you a reply, and then you send back
10684 just "No, it's not! Moron!", I will have no idea what you are insulting
10685 me about. Always overexplain everything. It's much easier for all of
10686 us---if I don't have all the information I need, I will just mail you
10687 and ask for more info, and everything takes more time.
10689 If you just need help, you are better off asking on
10690 @samp{gnu.emacs.gnus}. I'm not very helpful.
10692 @cindex gnu.emacs.gnus
10693 @cindex ding mailing list
10694 You can also ask on the ding mailing list---@samp{ding@@ifi.uio.no}.
10695 Write to @samp{ding-request@@ifi.uio.no} to subscribe.
10701 Well, that's the manual---you can get on with your life now. Keep in
10702 touch. Say hello to your cats from me.
10704 My @strong{ghod}---I just can't stand goodbyes. Sniffle.
10706 Ol' Chuck Reznikoff said it pretty well, so I leave the floor to him:
10711 Not because of victories @*
10714 but for the common sunshine,@*
10716 the largess of the spring.
10719 but for the day's work done@*
10720 as well as I was able;@*
10721 not for a seat upon the dais@*
10722 but at the common table.@*
10726 @chapter Appendices
10729 * A Programmer@'s Guide to Gnus:: Rilly, rilly technical stuff.
10730 * Emacs for Heathens:: A short intruduction to Emacsian terms.
10731 * Frequently Asked Questions:: A question-and-answer session.
10735 @node A Programmer@'s Guide to Gnus
10736 @section A Programmer's Guide to Gnus
10738 It is my hope that other people will figure out smart stuff that Gnus
10739 can do, and that other people will write those smart things as well. To
10740 facilitate that I thought it would be a good idea to describe the inner
10741 workings of Gnus. And some of the not-so-inner workings, while I'm at
10744 You can never expect the internals of a program not to change, but I
10745 will be defining (in some details) the interface between Gnus and its
10746 backends (this is written in stone), the format of the score files
10747 (ditto), data structures (some are less likely to change than others)
10748 and general method of operations.
10751 * Backend Interface:: How Gnus communicates with the servers.
10752 * Score File Syntax:: A BNF definition of the score file standard.
10753 * Headers:: How Gnus stores headers internally.
10754 * Ranges:: A handy format for storing mucho numbers.
10755 * Group Info:: The group info format.
10756 * Various File Formats:: Formats of files that Gnus use.
10760 @node Backend Interface
10761 @subsection Backend Interface
10763 Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
10764 groups. It only knows how to talk to @dfn{virtual servers}. A virtual
10765 server is a @dfn{backend} and some @dfn{backend variables}. As examples
10766 of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
10767 examples of the latter we have @code{nntp-port-number} and
10768 @code{nnmbox-directory}.
10770 When Gnus asks for information from a backend---say @code{nntp}---on
10771 something, it will normally include a virtual server name in the
10772 function parameters. (If not, the backend should use the "current"
10773 virtual server.) For instance, @code{nntp-request-list} takes a virtual
10774 server as its only (optional) parameter. If this virtual server hasn't
10775 been opened, the function should fail.
10777 Note that a virtual server name has no relation to some physical server
10778 name. Take this example:
10782 (nntp-address "ifi.uio.no")
10783 (nntp-port-number 4324))
10786 Here the virtual server name is @samp{"odd-one"} while the name of
10787 the physical server is @samp{"ifi.uio.no"}.
10789 The backends should be able to switch between several virtual servers.
10790 The standard backends implement this by keeping an alist of virtual
10791 server environments that it pulls down/pushes up when needed.
10793 There are two groups of interface functions: @dfn{required functions},
10794 which must be present, and @dfn{optional functions}, which Gnus will
10795 always check whether are present before attempting to call.
10797 All these functions are expected to return data in the buffer
10798 @code{nntp-server-buffer} (@samp{" *nntpd*"}), which is somewhat
10799 unfortunately named, but we'll have to live with it. When I talk about
10800 "resulting data", I always refer to the data in that buffer. When I
10801 talk about "return value", I talk about the function value returned by
10804 Some backends could be said to be @dfn{server-forming} backends, and
10805 some might be said to not be. The latter are backends that generally
10806 only operate on one group at a time, and have no concept of "server" --
10807 they have a group, and they deliver info on that group and nothing more.
10809 In the examples and definitions I will refer to the imaginary backend
10812 @cindex @code{nnchoke}
10815 * Required Backend Functions:: Functions that must be implemented.
10816 * Optional Backend Functions:: Functions that need not be implemented.
10820 @node Required Backend Functions
10821 @subsubsection Required Backend Functions
10825 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
10827 @var{articles} is either a range of article numbers or a list of
10828 @code{Message-ID}s. Current backends do not fully support either---only
10829 sequences (lists) of article numbers, and most backends do not support
10830 retrieval of @code{Message-ID}s. But they should try for both.
10832 The result data should either be HEADs or NOV lines, and the result
10833 value should either be @code{headers} or @code{nov} to reflect this.
10834 This might later be expanded to @code{various}, which will be a mixture
10835 of HEADs and NOV lines, but this is currently not supported by Gnus.
10837 If @var{fetch-old} is non-@code{nil} it says to try to fetch "extra
10838 headers, in some meaning of the word. This is generally done by
10839 fetching (at most) @var{fetch-old} extra headers less than the smallest
10840 article number in @code{articles}, and fill in the gaps as well. The
10841 presence of this parameter can be ignored if the backend finds it
10842 cumbersome to follow the request. If this is non-@code{nil} and not a
10843 number, do maximum fetches.
10845 Here's an example HEAD:
10848 221 1056 Article retrieved.
10849 Path: ifi.uio.no!sturles
10850 From: sturles@@ifi.uio.no (Sturle Sunde)
10851 Newsgroups: ifi.discussion
10852 Subject: Re: Something very droll
10853 Date: 27 Oct 1994 14:02:57 +0100
10854 Organization: Dept. of Informatics, University of Oslo, Norway
10856 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
10857 References: <38jdmq$4qu@@visbur.ifi.uio.no>
10858 NNTP-Posting-Host: holmenkollen.ifi.uio.no
10862 So a @code{headers} return value would imply that there's a number of
10863 these in the data buffer.
10865 Here's a BNF definition of such a buffer:
10869 head = error / valid-head
10870 error-message = [ "4" / "5" ] 2number " " <error message> eol
10871 valid-head = valid-message *header "." eol
10872 valid-message = "221 " <number> " Article retrieved." eol
10873 header = <text> eol
10876 If the return value is @code{nov}, the data buffer should contain
10877 @dfn{network overview database} lines. These are basically fields
10881 nov-buffer = *nov-line
10882 nov-line = 8*9 [ field <TAB> ] eol
10883 field = <text except TAB>
10886 For a closer explanation what should be in those fields,
10890 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
10892 @var{server} is here the virtual server name. @var{definitions} is a
10893 list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
10895 If the server can't be opened, no error should be signaled. The backend
10896 may then choose to refuse further attempts at connecting to this
10897 server. In fact, it should do so.
10899 If the server is opened already, this function should return a
10900 non-@code{nil} value. There should be no data returned.
10903 @item (nnchoke-close-server &optional SERVER)
10905 Close connection to @var{server} and free all resources connected
10908 There should be no data returned.
10911 @item (nnchoke-request-close)
10913 Close connection to all servers and free all resources that the backend
10914 have reserved. All buffers that have been created by that backend
10915 should be killed. (Not the @code{nntp-server-buffer}, though.)
10917 There should be no data returned.
10920 @item (nnchoke-server-opened &optional SERVER)
10922 This function should return whether @var{server} is opened, and that the
10923 connection to it is still alive. This function should under no
10924 circumstances attempt to reconnect to a server that is has lost
10927 There should be no data returned.
10930 @item (nnchoke-status-message &optional SERVER)
10932 This function should return the last error message from @var{server}.
10934 There should be no data returned.
10937 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
10939 The result data from this function should be the article specified by
10940 @var{article}. This might either be a @code{Message-ID} or a number.
10941 It is optional whether to implement retrieval by @code{Message-ID}, but
10942 it would be nice if that were possible.
10944 If @var{to-buffer} is non-@code{nil}, the result data should be returned
10945 in this buffer instead of the normal data buffer. This is to make it
10946 possible to avoid copying large amounts of data from one buffer to
10947 another, and Gnus mainly request articles to be inserted directly into
10948 its article buffer.
10951 @item (nnchoke-open-group GROUP &optional SERVER)
10953 Make @var{group} the current group.
10955 There should be no data returned by this function.
10958 @item (nnchoke-request-group GROUP &optional SERVER)
10960 Get data on @var{group}. This function also has the side effect of
10961 making @var{group} the current group.
10963 Here's an example of some result data and a definition of the same:
10966 211 56 1000 1059 ifi.discussion
10969 The first number is the status, which should be @samp{211}. Next is the
10970 total number of articles in the group, the lowest article number, the
10971 highest article number, and finally the group name. Note that the total
10972 number of articles may be less than one might think while just
10973 considering the highest and lowest article numbers, but some articles
10974 may have been cancelled. Gnus just discards the total-number, so
10975 whether one should take the bother to generate it properly (if that is a
10976 problem) is left as an excercise to the reader.
10979 group-status = [ error / info ] eol
10980 error = [ "4" / "5" ] 2<number> " " <Error message>
10981 info = "211 " 3* [ <number> " " ] <string>
10985 @item (nnchoke-close-group GROUP &optional SERVER)
10987 Close @var{group} and free any resources connected to it. This will be
10988 a no-op on most backends.
10990 There should be no data returned.
10993 @item (nnchoke-request-list &optional SERVER)
10995 Return a list of all groups available on @var{server}. And that means
10998 Here's an example from a server that only carries two groups:
11001 ifi.test 0000002200 0000002000 y
11002 ifi.discussion 3324 3300 n
11005 On each line we have a group name, then the highest article number in
11006 that group, the lowest article number, and finally a flag.
11009 active-file = *active-line
11010 active-line = name " " <number> " " <number> " " flags eol
11012 flags = "n" / "y" / "m" / "x" / "j" / "=" name
11015 The flag says whether the group is read-only (@samp{n}), is moderated
11016 (@samp{m}), is dead (@samp{x}), is aliased to some other group
11017 (@samp{=other-group} or none of the above (@samp{y}).
11020 @item (nnchoke-request-post &optional SERVER)
11022 This function should post the current buffer. It might return whether
11023 the posting was successful or not, but that's not required. If, for
11024 instance, the posting is done asynchronously, it has generally not been
11025 completed by the time this function concludes. In that case, this
11026 function should set up some kind of sentinel to beep the user loud and
11027 clear if the posting could not be completed.
11029 There should be no result data from this function.
11032 @item (nnchoke-request-post-buffer POST GROUP SUBJECT HEADER ARTICLE-BUFFER INFO FOLLOW-TO RESPECT-POSTER)
11034 This function should return a buffer suitable for composing an article
11035 to be posted by @code{nnchoke-request-post}. If @var{post} is
11036 non-@code{nil}, this is not a followup, but a totally new article.
11037 @var{group} is the name of the group to be posted to. @var{subject} is
11038 the subject of the message. @var{article-buffer} is the buffer being
11039 followed up, if that is the case. @var{info} is the group info.
11040 @var{follow-to} is the group that one is supposed to re-direct the
11041 article ot. If @var{respect-poster} is non-@code{nil}, the special
11042 @samp{"poster"} value of a @code{Followup-To} header is to be respected.
11044 There should be no result data returned.
11048 @node Optional Backend Functions
11049 @subsubsection Optional Backend Functions
11053 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
11055 @var{groups} is a list of groups, and this function should request data
11056 on all those groups. How it does it is of no concern to Gnus, but it
11057 should attempt to do this in a speedy fashion.
11059 The return value of this function can be either @code{active} or
11060 @code{group}, which says what the format of the result data is. The
11061 former is in the same format as the data from
11062 @code{nnchoke-request-list}, while the latter is a buffer full of lines
11063 in the same format as @code{nnchoke-request-group} gives.
11066 group-buffer = *active-line / *group-status
11070 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
11072 A Gnus group info (@pxref{Group Info}) is handed to the backend for
11073 alterations. This comes in handy if the backend really carries all the
11074 information (as is the case with virtual an imap groups). This function
11075 may alter the info in any manner it sees fit, and should return the
11076 (altered) group info. This function may alter the group info
11077 destructively, so no copying is needed before boogeying.
11079 There should be no result data from this function.
11082 @item (nnchoke-request-type GROUP &optional ARTICLE)
11084 When the user issues commands for "sending news" (@kbd{F} in the summary
11085 buffer, for instance), Gnus has to know whether the article the user is
11086 following up is news or mail. This function should return @code{news}
11087 if @var{article} in @var{group} is news, @code{mail} if it is mail and
11088 @code{unknown} if the type can't be decided. (The @var{article}
11089 parameter is necessary in @code{nnvirtual} groups which might very well
11090 combine mail groups and news groups.)
11092 There should be no result data from this function.
11095 @item (nnchoke-request-update-mark GROUP ARTICLE MARK)
11097 If the user tries to set a mark that the backend doesn't like, this
11098 function may change the mark. Gnus will use whatever this function
11099 returns as the mark for @var{article} instead of the original
11100 @var{mark}. If the backend doesn't care, it must return the original
11101 @var{mark}, and not @code{nil} or any other type of garbage.
11103 The only use for this that I can see is what @code{nnvirtual} does with
11104 it---if a component group is auto-expirable, marking an article as read
11105 in the virtual group should result in the article being marked as
11108 There should be no result data from this function.
11111 @item (nnchoke-request-scan &optional GROUP SERVER)
11113 This function may be called at any time (by Gnus or anything else) to
11114 request that the backend check for incoming articles, in one way or
11115 another. A mail backend will typically read the spool file or query the
11116 POP server when this function is invoked. The @var{group} doesn't have
11117 to be heeded---if the backend decides that it is too much work just
11118 scanning for a single group, it may do a total scan of all groups. It
11119 would be nice, however, to keep things local if that's practical.
11121 There should be no result data from this function.
11124 @item (nnchoke-request-asynchronous GROUP &optional SERVER ARTICLES)
11126 This is a request to fetch articles asynchronously later.
11127 @var{articles} is an alist of @var{(article-number line-number)}. One
11128 would generally expect that if one later fetches article number 4, for
11129 instance, some sort of asynchronous fetching of the articles after 4
11130 (which might be 5, 6, 7 or 11, 3, 909 depending on the order in that
11131 alist) would be fetched asynchronouly, but that is left up to the
11132 backend. Gnus doesn't care.
11134 There should be no result data from this function.
11137 @item (nnchoke-request-group-description GROUP &optional SERVER)
11139 The result data from this function should be a description of
11143 description-line = name <TAB> description eol
11145 description = <text>
11148 @item (nnchoke-request-list-newsgroups &optional SERVER)
11150 The result data from this function should be the description of all
11151 groups available on the server.
11154 description-buffer = *description-line
11158 @item (nnchoke-request-newgroups DATE &optional SERVER)
11160 The result data from this function should be all groups that were
11161 created after @samp{date}, which is in normal human-readable date
11162 format. The data should be in the active buffer format.
11165 @item (nnchoke-request-create-groups GROUP &optional SERVER)
11167 This function should create an empty group with name @var{group}.
11169 There should be no return data.
11172 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
11174 This function should run the expiry process on all articles in the
11175 @var{articles} range (which is currently a simple list of article
11176 numbers.) It is left up to the backend to decide how old articles
11177 should be before they are removed by this function. If @var{force} is
11178 non-@code{nil}, all @var{articles} should be deleted, no matter how new
11181 This function should return a list of articles that it did not/was not
11184 There should be no result data returned.
11187 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
11190 This function should move @var{article} (which is a number) from
11191 @var{group} by calling @var{accept-form}.
11193 This function should ready the article in question for moving by
11194 removing any header lines it has added to the article, and generally
11195 should "tidy up" the article. Then it should @code{eval}
11196 @var{accept-form} in the buffer where the "tidy" article is. This will
11197 do the actual copying. If this @code{eval} returns a non-@code{nil}
11198 value, the article should be removed.
11200 If @var{last} is @code{nil}, that means that there is a high likelihood
11201 that there will be more requests issued shortly, so that allows some
11204 There should be no data returned.
11207 @item (nnchoke-request-accept-article GROUP &optional LAST)
11209 This function takes the current buffer and inserts it into @var{group}.
11210 If @var{last} in @code{nil}, that means that there will be more calls to
11211 this function in short order.
11213 There should be no data returned.
11216 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
11218 This function should remove @var{article} (which is a number) from
11219 @var{group} and insert @var{buffer} there instead.
11221 There should be no data returned.
11224 @item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
11226 This function should delete @var{group}. If @var{force}, it should
11227 really delete all the articles in the group, and then delete the group
11228 itself. (If there is such a thing as "the group itself".)
11230 There should be no data returned.
11233 @item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
11235 This function should rename @var{group} into @var{new-name}. All
11236 articles that are in @var{group} should move to @var{new-name}.
11238 There should be no data returned.
11244 @node Score File Syntax
11245 @subsection Score File Syntax
11247 Score files are meant to be easily parsable, but yet extremely
11248 mallable. It was decided that something that had the same read syntax
11249 as an Emacs Lisp list would fit that spec.
11251 Here's a typical score file:
11255 ("win95" -10000 nil s)
11262 BNF definition of a score file:
11265 score-file = "" / "(" *element ")"
11266 element = rule / atom
11267 rule = string-rule / number-rule / date-rule
11268 string-rule = "(" quote string-header quote space *string-match ")"
11269 number-rule = "(" quote number-header quote space *number-match ")"
11270 date-rule = "(" quote date-header quote space *date-match ")"
11272 string-header = "subject" / "from" / "references" / "message-id" /
11273 "xref" / "body" / "head" / "all" / "followup"
11274 number-header = "lines" / "chars"
11275 date-header = "date"
11276 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
11277 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
11278 score = "nil" / <integer>
11279 date = "nil" / <natural number>
11280 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
11281 "r" / "regex" / "R" / "Regex" /
11282 "e" / "exact" / "E" / "Exact" /
11283 "f" / "fuzzy" / "F" / "Fuzzy"
11284 number-match = "(" <integer> [ "" / [ space score [ "" /
11285 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
11286 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
11287 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
11288 space date [ "" / [ space date-match-t ] ] ] ] ")"
11289 date-match-t = "nil" / "at" / "before" / "after"
11290 atom = "(" [ required-atom / optional-atom ] ")"
11291 required-atom = mark / expunge / mark-and-expunge / files /
11292 exclude-files / read-only / touched
11293 optional-atom = adapt / local / eval
11294 mark = "mark" space nil-or-number
11295 nil-or-number = "nil" / <integer>
11296 expunge = "expunge" space nil-or-number
11297 mark-and-expunge = "mark-and-expunge" space nil-or-number
11298 files = "files" *[ space <string> ]
11299 exclude-files = "exclude-files" *[ space <string> ]
11300 read-only = "read-only" [ space "nil" / space "t" ]
11301 adapt = "adapt" [ space "nil" / space "t" / space adapt-rule ]
11302 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
11303 local = "local" *[ space "(" <string> space <form> ")" ]
11304 eval = "eval" space <form>
11305 space = *[ " " / <TAB> / <NEWLINE> ]
11308 Any unrecognized elements in a score file should be ignored, but not
11311 As you can see, white space is needed, but the type and amount of white
11312 space is irrelevant. This means that formatting of the score file is
11313 left up to the programmer---if it's simpler to just spew it all out on
11314 one looong line, then that's ok.
11316 The meaning of the various atoms are explained elsewhere in this
11321 @subsection Headers
11323 Gnus uses internally a format for storing article headers that
11324 corresponds to the @sc{nov} format in a mysterious fashion. One could
11325 almost suspect that the author looked at the @sc{nov} specification and
11326 just shamelessly @emph{stole} the entire thing, and one would be right.
11328 @dfn{Header} is a severly overloaded term. "Header" is used in RFC1036
11329 to talk about lines in the head of an article (eg., @code{From}). It is
11330 used by many people as a synonym for "head"---"the header and the
11331 body". (That should be avoided, in my opinion.) And Gnus uses a format
11332 interanally that it calls "header", which is what I'm talking about
11333 here. This is a 9-element vector, basically, with each header (ouch)
11336 These slots are, in order: @code{number}, @code{subject}, @code{from},
11337 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
11338 @code{xref}. There are macros for accessing and setting these slots --
11339 they all have predicatable names beginning with @code{mail-header-} and
11340 @code{mail-header-set-}, respectively.
11342 The @code{xref} slot is really a @code{misc} slot. Any extra info will
11349 @sc{gnus} introduced a concept that I found so useful that I've started
11350 using it a lot and have elaborated on it greatly.
11352 The question is simple: If you have a large amount of objects that are
11353 identified by numbers (say, articles, to take a @emph{wild} example)
11354 that you want to callify as being "included", a normal sequence isn't
11355 very useful. (A 200,000 length sequence is a bit long-winded.)
11357 The solution is as simple as the question: You just collapse the
11361 (1 2 3 4 5 6 10 11 12)
11364 is transformed into
11367 ((1 . 6) (10 . 12))
11370 To avoid having those nasty @samp{(13 . 13)} elements to denote a
11371 lonesome object, a @samp{13} is a valid element:
11374 ((1 . 6) 7 (10 . 12))
11377 This means that comparing two ranges to find out whether they are equal
11378 is slightly tricky:
11381 ((1 . 5) 7 8 (10 . 12))
11387 ((1 . 5) (7 . 8) (10 . 12))
11390 are equal. In fact, any non-descending list is a range:
11396 is a perfectly valid range, although a pretty longwinded one. This is
11403 and is equal to the previous range.
11405 Here's a BNF definition of ranges. Of course, one must remember the
11406 semantic requirement that the numbers are non-descending. (Any number
11407 of repetition of the same number is allowed, but apt to disappear in
11411 range = simple-range / normal-range
11412 simple-range = "(" number " . " number ")"
11413 normal-range = "(" start-contents ")"
11414 contents = "" / simple-range *[ " " contents ] /
11415 number *[ " " contents ]
11418 Gnus currently uses ranges to keep track of read articles and article
11419 marks. I plan on implementing a number of range operators in C if The
11420 Powers That Be are willing to let me. (I haven't asked yet, because I
11421 need to do some more thinking on what operators I need to make life
11422 totally range-based without ever having to convert back to normal
11427 @subsection Group Info
11429 Gnus stores all permanent info on groups in a @dfn{group info} list.
11430 This list is from three to six elements (or more) long and exhaustively
11431 describes the group.
11433 Here are two example group infos; one is a very simple group while the
11434 second is a more complex one:
11437 ("no.group" 5 (1 . 54324))
11439 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
11440 ((tick (15 . 19)) (replied 3 6 (19 . 3)))
11442 (auto-expire (to-address "ding@@ifi.uio.no")))
11445 The first element is the group name as Gnus knows the group; the second
11446 is the group level; the third is the read articles in range format; the
11447 fourth is a list of article marks lists; the fifth is the select method;
11448 and the sixth contains the group parameters.
11450 Here's a BNF definition of the group info format:
11453 info = "(" group space level space read
11454 [ "" / [ space marks-list [ "" / [ space method [ "" /
11455 space parameters ] ] ] ] ] ")"
11456 group = quote <string> quote
11457 level = <integer in the range of 1 to inf>
11459 marks-lists = nil / "(" *marks ")"
11460 marks = "(" <string> range ")"
11461 method = "(" <string> *elisp-forms ")"
11462 parameters = "(" *elisp-forms ")"
11465 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
11466 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
11470 @node Various File Formats
11471 @subsection Various File Formats
11474 * Active File Format:: Information on articles and groups available.
11475 * Newsgroups File Format:: Group descriptions.
11479 @node Active File Format
11480 @subsubsection Active File Format
11482 The active file lists all groups that are available on the server in
11483 question. It also lists the highest and lowest current article numbers
11486 Here's an exceprt from a typical active file:
11489 soc.motss 296030 293865 y
11490 alt.binaries.pictures.fractals 3922 3913 n
11491 comp.sources.unix 1605 1593 m
11492 comp.binaries.ibm.pc 5097 5089 y
11493 no.general 1000 900 y
11496 Here's a pseudo-BNF definition of this file:
11499 active = *group-line
11500 group-line = group space high-number space low-number space flag <NEWLINE>
11501 group = <non-white-space string>
11503 high-number = <non-negative integer>
11504 low-number = <positive integer>
11505 flag = "y" / "n" / "m" / "j" / "x" / "=" group
11509 @node Newsgroups File Format
11510 @subsubsection Newsgroups File Format
11512 The newsgroups file lists groups along with their descriptions. Not all
11513 groups on the server have to be listed, and not all groups in the file
11514 have to exist on the server. The file is meant purely as information to
11517 The format is quite simple; a group name, a tab, and the description.
11518 Here's the definition:
11522 line = group tab description <NEWLINE>
11523 group = <non-white-space string>
11525 description = <string>
11529 @node Emacs for Heathens
11530 @section Emacs for Heathens
11532 Believe it or not, but some people who use Gnus haven't really used
11533 Emacs much before they embarked on their journey on the Gnus Love Boat.
11534 If you are one of those unfortunates whom "@kbd{M-C-a}", "kill the
11535 region", and "set @code{gnus-flargblossen} to an alist where the key is
11536 a regexp that is used for matching on the group name" are magical
11537 phrases with little or no meaning, then this appendix is for you. If
11538 you are already familiar with Emacs, just ignore this and go fondle your
11542 * Keystrokes:: Entering text and executing commands.
11543 * Emacs Lisp:: The built-in Emacs programming language.
11548 @subsection Keystrokes
11552 Q: What is an experienced Emacs user?
11555 A: A person who wishes that the terminal had pedals.
11558 Yes, when you use Emacs, you are apt to use the control key, the shift
11559 key and the meta key a lot. This is very annoying to some people
11560 (notably @code{vi}le users), and the rest of us just love the hell out
11561 of it. Just give up and submit. Emacs really does stand for
11562 "Escape-Meta-Alt-Control-Shift", and not "Editin Macros", as you may
11563 have heard from other disreputable sources (like the Emacs author).
11565 The shift key is normally located near your pinky fingers, and are
11566 normally used to get capital letters and stuff. You probably use it all
11567 the time. The control key is normally marked "CTRL" or something like
11568 that. The meta key is, funnily enough, never marked as such on any
11569 keyboards. The one I'm curretly at has a key that's marked "Alt", which
11570 is the meta key on this keyboard. It's usually located somewhere to the
11571 left hand side of the keyboard, usually on the bottom row.
11573 Now, us Emacs people doesn't say "press the meta-control-m key", because
11574 that's just too inconvenient. We say "press the @kbd{M-C-m} key".
11575 @kbd{M-} is the prefix that means "meta" and "C-" is the prefix that
11576 means "control". So "press @kbd{C-k}" means "press down the control
11577 key, and hold it down while you press @kbd{k}". "Press @kbd{M-C-k}"
11578 means "press down and hold down the meta key and the control key and
11579 then press @kbd{k}". Simple, ay?
11581 This is somewhat complicated by the fact that not all keyboards have a
11582 meta key. In that case you can use the "escape" key. Then @kbd{M-k}
11583 means "press escape, release escape, press @kbd{k}". That's much more
11584 work than if you have a meta key, so if that's the case, I respectfully
11585 suggest you get a real keyboard with a meta key. You can't live without
11591 @subsection Emacs Lisp
11593 Emacs is the King of Editors because it's really a Lisp interpreter.
11594 Each and every key you tap runs some Emacs Lisp code snippet, and since
11595 Emacs Lisp is an interpreted language, that means that you can configure
11596 any key to run any random code. You just, like, do it.
11598 Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
11599 functions. (These are byte-compiled for speed, but it's still
11600 interpreted.) If you decide that you don't like the way Gnus does
11601 certain things, it's trivial to have it do something a different way.
11602 (Well, at least if you know how to write Lisp code.) However, that's
11603 beyond the scope of this manual, so we are simply going to talk about
11604 some common constructs that you normally use in your @file{.emacs} file
11607 If you want to set the variable @code{gnus-florgbnize} to four (4), you
11608 write the following:
11611 (setq gnus-florgbnize 4)
11614 This function (really "special form") @code{setq} is the one that can
11615 set a variable to some value. This is really all you need to know. Now
11616 you can go and fill your @code{.emacs} file with lots of these to change
11619 If you have put that thing in your @code{.emacs} file, it will be read
11620 and @code{eval}ed (which is lispese for "run") the next time you start
11621 Emacs. If you want to change the variable right away, simply say
11622 @kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
11623 previous "form", which here is a simple @code{setq} statement.
11625 Go ahead---just try it, if you're located at your Emacs. After you
11626 @kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
11627 is the return value of the form you @code{eval}ed.
11631 If the manual says "set @code{gnus-read-active-file} to @code{some}",
11635 (setq gnus-read-active-file 'some)
11638 On the other hand, if the manual says "set @code{gnus-nntp-server} to
11639 @samp{"nntp.ifi.uio.no"}", that means:
11642 (setq gnus-nntp-server "nntp.ifi.uio.no")
11645 So be careful not to mix up strings (the latter) with symbols (the
11646 former). The manual is unambiguous, but it can be confusing.
11649 @include gnus-faq.texi
11664 @c Local Variables:
11665 @c outline-regexp: "@chap\\|@\\(sub\\)*section\\|@appendix \\|@appendix\\(sub\\)*sec\\|\^L"