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 if 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.26 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 @code{trn}-like trees.
530 @code{nn}-like pick-and-read summary interface.
534 Automatic re-scan of incoming mail.
536 Buttonize more stuff in the article buffer.
538 A better and simpler method for specifying mail composing methods.
540 Marks for saved, forwarded, etc articles.
542 Gather thread by filling in missing Message-IDs.
546 Allow posting through mail-to-news gateways.
548 @code{jka-compr} isn't fully supported.
550 Do better word-wrap on cited text.
552 Better X-Face support with X-Face databases and stuff.
554 Really do unbinhexing.
558 Don't kill summary buffers upon exit from the groups.
560 Allow adaption on secondary marks.
563 And much, much, much more. There is more to come than has already been
564 implemented. (But that's always true, isn't it?)
566 @code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>} is where the actual
567 up-to-the-second todo list is located, so if you're really curious, you
568 could point your Web browser over that-a-way.
579 This is what you are supposed to use this thing for---reading news.
580 News is generally fetched from a nearby @sc{nntp} server, and is
581 generally publicly available to everybody. If you post news, the entire
582 world is likely to read just what you have written, and they'll all
583 snigger mischievously. Behind your back.
587 Everything that's delivered to you personally is mail. Some news/mail
588 readers (like Gnus) blur the distinction between mail and news, but
589 there is a difference. Mail is private. News is public. Mailing is
590 not posting, and replying is not following up.
593 Send a mail to the person who has written what you are reading.
596 Post an article to the current newsgroup responding to the article you
600 Gnus gets fed articles from a number of backends, both news and mail
601 backends. Gnus does not handle the underlying media, so to speak---this
602 is all done by the backends.
605 Gnus will always use one method (and backend) as the @dfn{native}, or
606 default, way of getting news.
609 You can also have any number of foreign groups at the same time. These
610 are groups that use different backends for getting news.
614 The top part of an article, where administration information (etc.) is
619 The rest of an article. Everything that is not in the head is in the
624 A line from the head of an article.
628 A collection of such lines, or a collection of heads. Or even a
629 collection of @sc{nov} lines.
633 When Gnus enters a group, it asks the backend for the headers for all
634 the unread articles in the group. Most servers support the News OverView
635 format, which is much smaller and much faster to read than the normal
640 Each group is subscribed at some @dfn{level} or other (1-9). The ones
641 that have a lower level are "more" subscribed than the groups with a
642 higher level. In fact, groups on levels 1-5 are considered
643 @dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
644 are @dfn{killed}. Commands for listing groups and scanning for new
645 articles will all use the numeric prefix as @dfn{working level}.
648 @cindex killed groups
649 No information on killed groups is stored or updated, which makes killed
650 groups much easier to handle than subscribed groups.
653 @cindex zombie groups
654 Just like killed groups, only slightly less dead.
658 The news server has to keep track of what articles it carries, and what
659 groups exist. All this information in stored in the active file, which
660 is rather large, as you might surmise.
664 A group that exists in the @file{.newsrc} file, but isn't known to the
665 server (i. e., it isn't in the active file), is a @emph{bogus group}.
666 This means that the group probably doesn't exist (any more).
670 @chapter Starting Gnus
674 If your system administrator has set things up properly, starting Gnus
675 and reading news is extremely easy---you just type @kbd{M-x gnus}.
677 If things do not go smoothly at startup, you have to twiddle some
681 * Finding the News:: Choosing a method for getting news.
682 * The First Time:: What does Gnus do the first time you start it?
683 * The Server is Down:: How can I read my mail then?
684 * Slave Gnusii:: You can have more than one Gnus active at a time.
685 * Fetching a Group:: Starting Gnus just to read a group.
686 * New Groups:: What is Gnus supposed to do with new groups?
687 * Startup Files:: Those pesky startup files---@file{.newsrc}.
688 * Auto Save:: Recovering from a crash.
689 * The Active File:: Reading the active file over a slow line Takes Time.
690 * Startup Variables:: Other variables you might change.
693 @node Finding the News
694 @section Finding the News
696 @vindex gnus-select-method
697 The @code{gnus-select-method} variable controls how Gnus finds news.
698 This variable should be a list where the first element says @dfn{how}
699 and the second element says @dfn{where}. This method is your native
700 method. All groups that are not fetched with this method are foreign
703 For instance, if you want to get your daily dosage of news from the
704 @samp{news.somewhere.edu} @sc{nntp} server, you'd say:
707 (setq gnus-select-method '(nntp "news.somewhere.edu"))
710 If you want to read directly from the local spool, say:
713 (setq gnus-select-method '(nnspool ""))
716 If you can use a local spool, you probably should, as it will almost
717 certainly be much faster.
719 @vindex gnus-nntpserver-file
721 @cindex @sc{nntp} server
722 If this variable is not set, Gnus will take a look at the
723 @code{NNTPSERVER} environment variable. If that variable isn't set,
724 Gnus will see whether @code{gnus-nntpserver-file} (default
725 @file{/etc/nntpserver}) has any opinions in the matter. It that fails
726 as well, Gnus will will try to use the machine that is running Emacs as
727 an @sc{nntp} server. That's a longshot, though.
729 @vindex gnus-nntp-server
730 If @code{gnus-nntp-server} is set, this variable will override
731 @code{gnus-select-method}. You should therefore set
732 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
734 @vindex gnus-secondary-servers
735 You can also make Gnus prompt you interactively for the name of an
736 @sc{nntp} server. If you give a non-numerical prefix to @code{gnus}
737 (i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
738 in the @code{gnus-secondary-servers} list (if any). You can also just
739 type in the name of any server you feel like visiting.
741 However, if you use one @sc{nntp} server regularly, and are just
742 interested in a couple of groups from a different server, you would be
743 better served by using the @code{gnus-group-browse-foreign-server}
744 command from the group buffer. It will let you have a look at what
745 groups are available, and you can subscribe to any of the groups you
746 want to. This also makes @file{.newsrc} maintenance much tidier.
747 @xref{Foreign Groups}.
749 @vindex gnus-secondary-select-methods
750 A slightly different approach to foreign groups is to set the
751 @code{gnus-secondary-select-methods} variable. The select methods
752 listed in this variable are in many ways just as native as the
753 @code{gnus-select-method} server. They will also be queried for active
754 files during startup (if that's required), and new newsgroups that
755 appear on these servers will be subscribed (or not) just as native
758 For instance, if you use the @code{nnmbox} backend to read you mail, you
759 would typically set this variable to
762 (setq gnus-secondary-select-methods '((nnmbox "")))
766 @section The First Time
767 @cindex first time usage
769 If no startup files exist, Gnus will try to determine what groups should
770 be subscribed by default.
772 @vindex gnus-default-subscribed-newsgroups
773 If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
774 will subscribe you to just those groups in that list, leaving the rest
775 killed. Your system administrator should have set this variable to
778 Since she hasn't, Gnus will just subscribe you to a few randomly picked
779 groups (i.e., @samp{*.newusers}). (@dfn{Random} is here defined as
780 "whatever Lars thinks you should read".)
782 You'll also be subscribed to the Gnus documentation group, which should
783 help you with most common problems.
785 If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
786 use the normal functions for handling new groups, and not do anything
789 @node The Server is Down
790 @section The Server is Down
791 @cindex server errors
793 If the default server is down, Gnus will understandably have some
794 problems starting. However, if you have some mail groups in addition to
795 the news groups, you may want to start Gnus anyway.
797 Gnus, being the trusting sort of program, will ask whether to proceed
798 without a native select method if that server can't be contacted. This
799 will happen whether the server doesn't actually exist (i.e., you have
800 given the wrong address) or the server has just momentarily taken ill
801 for some reason or other.
803 If Gnus says "nntp server on <your server> can't be opened. Continue?",
804 you do not want to continue unless you have some foreign groups that you
805 want to read. Even if you don't, Gnus will let you continue, but you'll
806 find it difficult to actually do anything in the group buffer. But,
807 hey, that's your problem. Blllrph!
809 @findex gnus-no-server
810 If you know that the server is definitely down, or you just want to read
811 your mail without bothering with the server at all, you can use the
812 @code{gnus-no-server} command to start Gnus. That might come in handy
813 if you're in a hurry as well.
817 @section Slave Gnusiï
820 You might want to run more than one Emacs with more than one Gnus at the
821 same time. If you are using different @file{.newsrc} files (eg., if you
822 are using the two different Gnusiï to read from two different servers),
823 that is no problem whatsoever. You just do it.
825 The problem appears when you want to run two Gnusiï that use the same
828 To work around that problem some, we here at the Think-Tank at the Gnus
829 Towers have come up with a new concept: @dfn{Masters} and
830 @dfn{servants}. (We have applied for a patent on this concept, and have
831 taken out a copyright on those words. If you wish to use those words in
832 conjunction with each other, you have to send $1 per usage instance to
833 me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
834 Applications}) will be much more expensive, of course.)
836 Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
837 however you do it). Each subsequent slave Gnusiï should be started with
838 @kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
839 files, but some slave files that contains information only on what
840 groups have been read in the slave session. When a master Gnus starts,
841 it will read (and delete) these slave files, incorporating all
842 information from all of them. (The slave files will be read in the
843 sequence they were created, so the latest changes will have precedence.)
845 Information from the slave files has, of course, presedence over the
846 information in the normal (i. e., master) @code{.newsrc} file.
849 @node Fetching a Group
850 @section Fetching a Group
852 @findex gnus-fetch-group
853 It it sometime convenient to be able to just say "I want to read this
854 group and I don't care whether Gnus has been started or not". This is
855 perhaps more useful for people who write code than for users, but the
856 command @code{gnus-fetch-group} provides this functionality in any
857 case. It takes the group name as a paramenter.
864 @vindex gnus-subscribe-newsgroup-method
865 What Gnus does when it encounters a new group is determined by the
866 @code{gnus-subscribe-newsgroup-method} variable.
868 This variable should contain a function. Some handy pre-fab values
873 @item gnus-subscribe-randomly
874 @vindex gnus-subscribe-randomly
875 Subscribe all new groups randomly.
877 @item gnus-subscribe-alphabetically
878 @vindex gnus-subscribe-alphabetically
879 Subscribe all new groups alphabetically.
881 @item gnus-subscribe-hierarchically
882 @vindex gnus-subscribe-hierarchically
883 Subscribe all new groups hierarchically.
885 @item gnus-subscribe-interactively
886 @vindex gnus-subscribe-interactively
887 Subscribe new groups interactively. This means that Gnus will ask
888 you about @strong{all} new groups.
890 @item gnus-subscribe-killed
891 @vindex gnus-subscribe-killed
894 @item gnus-subscribe-zombies
895 @vindex gnus-subscribe-zombies
896 Make all new groups zombies. You can browse the zombies later (with
897 @kbd{A z}) and either kill them all off properly, or subscribe to them.
901 @vindex gnus-subscribe-hierarchical-interactive
902 A closely related variable is
903 @code{gnus-subscribe-hierarchical-interactive}. (That's quite a
904 mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a
905 hierarchical fashion whether to subscribe to new groups or not. Gnus
906 will ask you for each sub-hierarchy whether you want to descend the
909 One common way to control which new newsgroups should be subscribed or
910 ignored is to put an @dfn{options} line at the start of the
911 @file{.newsrc} file. Here's an example:
914 options -n !alt.all !rec.all sci.all
917 @vindex gnus-subscribe-options-newsgroup-method
918 This line obviously belongs to a serious-minded intellectual scientific
919 person (or she may just be plain old boring), because it says that all
920 groups that have names beginning with @samp{alt} and @samp{rec} should
921 be ignored, and all groups with names beginning with @samp{sci} should
922 be subscribed. Gnus will not use the normal subscription method for
923 subscribing these groups.
924 @code{gnus-subscribe-options-newsgroup-method} is used instead. This
925 variable defaults to @code{gnus-subscribe-alphabetically}.
927 @vindex gnus-options-not-subscribe
928 @vindex gnus-options-subscribe
929 If you don't want to mess with your @file{.newsrc} file, you can just
930 set the two variables @code{gnus-options-subscribe} and
931 @code{gnus-options-not-subscribe}. These two variables do exactly the
932 same as the @file{.newsrc} options -n trick. Both are regexps, and if
933 the the new group matches the first, it will be unconditionally
934 subscribed, and if it matches the latter, it will be ignored.
936 @vindex gnus-auto-subscribed-groups
937 Yet another variable that meddles here is
938 @code{gnus-auto-subscribed-groups}. It works exactly like
939 @code{gnus-options-subscribe}, and is therefore really superfluos, but I
940 thought it would be nice to have two of these. This variable is more
941 meant for setting some ground rules, while the other variable is used
942 more for user fiddling. By default this variable makes all new groups
943 that come from mail backends (@code{nnml}, @code{nnbabyl},
944 @code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you
945 don't like that, just set this variable to @code{nil}.
947 @vindex gnus-check-new-newsgroups
948 If you are satisfied that you really never want to see any new groups,
949 you could set @code{gnus-check-new-newsgroups} to @code{nil}. This will
950 also save you some time at startup. Even if this variable is
951 @code{nil}, you can always subscribe to the new groups just by pressing
952 @kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
953 is @code{t} by default.
955 Gnus normally determines whether a group is new or not by comparing the
956 list of groups from the active file(s) with the lists of subscribed and
957 dead groups. This isn't a particularly fast method. If
958 @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
959 server for new groups since the last time. This is both faster &
960 cheaper. This also means that you can get rid of the list of killed
961 groups altogether, so you may set @code{gnus-save-killed-list} to
962 @code{nil}, which will save time both at startup, at exit, and all over.
963 Saves disk space, too. Why isn't this the default, then?
964 Unfortunately, not all servers support this function.
966 This variable can also be a list of select methods. If so, Gnus will
967 issue an @code{ask-server} command to each of the select methods, and
968 subscribe them (or not) using the normal methods. This might be handy
969 if you are monitoring a few servers for new groups. A side effect is
970 that startup will take much longer, so you can meditate while waiting.
971 Use the mantra "dingnusdingnusdingnus" to achieve permanent happiness.
974 @section Startup Files
975 @cindex startup files
978 Now, you all know about the @file{.newsrc} file. All subscription
979 information is traditionally stored in this file.
981 Things got a bit more complicated with @sc{gnus}. In addition to
982 keeping the @file{.newsrc} file updated, it also used a file called
983 @file{.newsrc.el} for storing all the information that didn't fit into
984 the @file{.newsrc} file. (Actually, it duplicated everything in the
985 @file{.newsrc} file.) @sc{gnus} would read whichever one of these files
986 that were the most recently saved, which enabled people to swap between
987 @sc{gnus} and other newsreaders.
989 That was kinda silly, so Gnus went one better: In addition to the
990 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
991 @file{.newsrc.eld}. It will read whichever of these files that are most
992 recent, but it will never write a @file{.newsrc.el} file.
994 @vindex gnus-save-newsrc-file
995 You can also turn off writing the @file{.newsrc} file by setting
996 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
997 the file and save some space, as well as making exit from Gnus faster.
998 However, this will make it impossible to use other newsreaders than
999 Gnus. But hey, who would want to, right?
1001 @vindex gnus-save-killed-list
1002 If @code{gnus-save-killed-list} is @code{nil}, Gnus will not save the
1003 list of killed groups to the startup file. This will save both time
1004 (when starting and quitting) and space (on disk). It will also means
1005 that Gnus has no record of what groups are new or old, so the automatic
1006 new groups subscription methods become meaningless. You should always
1007 set @code{gnus-check-new-newsgroups} to @code{nil} or @code{ask-server}
1008 if you set this variable to @code{nil} (@pxref{New Groups}).
1010 @vindex gnus-startup-file
1011 The @code{gnus-startup-file} variable says where the startup files are.
1012 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
1013 file being whatever that one is with a @samp{.eld} appended.
1015 @vindex gnus-save-newsrc-hook
1016 @vindex gnus-save-quick-newsrc-hook
1017 @vindex gnus-save-standard-newsrc-hook
1018 @code{gnus-save-newsrc-hook} is called before saving any of the newsrc
1019 files, while @code{gnus-save-quick-newsrc-hook} is called just before
1020 saving the @file{.newsrc.eld} file, and
1021 @code{gnus-save-standard-newsrc-hook} is called just before saving the
1022 @file{.newsrc} file. The latter two are commonly used to turn version
1023 control on or off. Version control is off by default when saving.
1027 @cindex dribble file
1030 Whenever you do something that changes the Gnus data (reading articles,
1031 catching up, killing/subscribing groups), the change is added to a
1032 special @dfn{dribble buffer}. This buffer is auto-saved the normal
1033 Emacs way. If your Emacs should crash before you have saved the
1034 @file{.newsrc} files, all changes you have made can be recovered from
1037 If Gnus detects this file at startup, it will ask the user whether to
1038 read it. The auto save file is deleted whenever the real startup file is
1041 @vindex gnus-use-dribble-file
1042 If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
1043 maintain a dribble buffer. The default is @code{t}.
1045 @vindex gnus-dribble-directory
1046 Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
1047 this variable is @code{nil}, which it is by default, Gnus will dribble
1048 into the same directory as the @file{.newsrc} file is located. (This is
1049 normally the user's home directory.)
1051 @node The Active File
1052 @section The Active File
1054 @cindex ignored groups
1056 When Gnus starts, or indeed whenever it tries to determine whether new
1057 articles have arrived, it reads the active file. This is a very large
1058 file that lists all the active groups and articles on the @sc{nntp}
1061 @vindex gnus-ignored-newsgroups
1062 Before examining the active file, Gnus deletes all lines that match the
1063 regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject
1064 any groups with bogus names, but you can use this variable to make Gnus
1065 ignore hierarchies you aren't ever interested in.
1067 @c @code{nil} by default, and will slow down active file handling somewhat
1068 @c if you set it to anything else.
1070 @vindex gnus-read-active-file
1071 The active file can be rather Huge, so if you have a slow network, you
1072 can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
1073 reading the active file. This variable is @code{t} by default.
1075 Gnus will try to make do by just getting information on the groups
1076 that you actually subscribe to.
1078 Note that if you subscribe to lots and lots of groups, setting this
1079 variable to @code{nil} will probably make Gnus slower, not faster. At
1080 present, having this variable @code{nil} will slow Gnus down
1081 considerably, unless you read news over a 2400 baud modem.
1083 This variable can also have the value @code{some}. Gnus will then
1084 attempt to read active info only on the subscribed groups. On some
1085 servers this is quite fast (on sparkling, brand new INN servers that
1086 support the @samp{LIST ACTIVE group} command), on others this is not
1087 fast at all. In any case, @code{some} should be faster than @code{nil},
1088 and is certainly faster than @code{t} over slow lines.
1090 If this variable is @code{nil}, Gnus will as for group info in total
1091 lock-step, which isn't very fast. If it is @code{some} and you use an
1092 @sc{nntp} server, Gnus will pump out commands as fast as it can, and
1093 read all the replies in one swoop. This will normally result in better
1094 performance, but if the server does not support the aforementioned
1095 @samp{LIST ACTIVE group} command, this isn't very nice to the server.
1097 In any case, if you use @code{some} or @code{nil}, you should kill all
1098 groups that you aren't interested in.
1100 @node Startup Variables
1101 @section Startup Variables
1105 @item gnus-load-hook
1106 @vindex gnus-load-hook
1107 A hook that is run while Gnus is being loaded. Note that this hook will
1108 normally be run just once in each Emacs session, no matter how many
1109 times you start Gnus.
1111 @item gnus-startup-hook
1112 @vindex gnus-startup-hook
1113 A hook that is run after starting up Gnus successfully.
1115 @item gnus-check-bogus-newsgroups
1116 @vindex gnus-check-bogus-newsgroups
1117 If non-@code{nil}, Gnus will check for and delete all bogus groups at
1118 startup. A @dfn{bogus group} is a group that you have in your
1119 @file{.newsrc} file, but doesn't exist on the news server. Checking for
1120 bogus groups isn't very quick, so to save time and resources, it's best
1121 to leave this option off, and instead do the checking for bogus groups
1122 once in a while from the group buffer (@pxref{Group Maintenance}).
1124 @item gnus-inhibit-startup-message
1125 @vindex gnus-inhibit-startup-message
1126 If non-@code{nil}, the startup message won't be displayed. That way,
1127 your boss might not notice that you are reading news instead of doing
1130 @item gnus-no-groups-message
1131 @vindex gnus-no-groups-message
1132 Message displayed by Gnus when no groups are available.
1135 @node The Group Buffer
1136 @chapter The Group Buffer
1137 @cindex group buffer
1139 The @dfn{group buffer} lists all (or parts) of the available groups. It
1140 is the first buffer shown when Gnus starts, and will never be killed as
1141 long as Gnus is active.
1144 * Group Buffer Format:: Information listed and how you can change it.
1145 * Group Maneuvering:: Commands for moving in the group buffer.
1146 * Selecting a Group:: Actually reading news.
1147 * Subscription Commands:: Unsubscribing, killing, subscribing.
1148 * Group Levels:: Levels? What are those, then?
1149 * Group Score:: A mechanism for finding out what groups you like.
1150 * Marking Groups:: You can mark groups for later processing.
1151 * Foreign Groups:: How to create foreign groups.
1152 * Group Parameters:: Each group may have different parameters set.
1153 * Listing Groups:: Gnus can list various subsets of the groups.
1154 * Sorting Groups:: Re-arrange the group order.
1155 * Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
1156 * Browse Foreign Server:: You can browse a server. See what if has to offer.
1157 * Exiting Gnus:: Stop reading news and get some work done.
1158 * Group Topics:: A folding group mode divided into topics.
1159 * Misc Group Stuff:: Other stuff that you can to do.
1162 @node Group Buffer Format
1163 @section Group Buffer Format
1164 @cindex group buffer format
1166 The default format of the group buffer is nice and dull, but you can
1167 make it as exciting and ugly as you feel like.
1169 Here's a couple of example group lines:
1172 25: news.announce.newusers
1173 * 0: alt.fan.andrea-dworkin
1178 You can see that there are 25 unread articles in
1179 @samp{news.announce.newusers}. There are no unread articles, but some
1180 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
1181 asterisk at the beginning of the line?)
1183 @vindex gnus-group-line-format
1184 You can fuck that up to your heart's delight by fiddling with the
1185 @code{gnus-group-line-format} variable. This variable works along the
1186 lines of a @code{format} specification, which is pretty much the same as
1187 a @code{printf} specifications, for those of you who use (feh!) C.
1188 @xref{Formatting Variables}.
1190 The default value that produced those lines above is
1191 @samp{"%M%S%5y: %(%g%)\n"}.
1193 There should always be a colon on the line; the cursor always moves to
1194 the colon after performing an operation. Nothing else is required---not
1195 even the group name. All displayed text is just window dressing, and is
1196 never examined by Gnus. Gnus stores all real information it needs using
1199 (Note that if you make a really strange, wonderful, spreadsheet-like
1200 layout, everybody will believe you are hard at work with the accounting
1201 instead of wasting time reading news.)
1203 Here's a list of all available format characters:
1208 Only marked articles.
1211 Whether the group is subscribed.
1214 Level of subscribedness.
1217 Number of unread articles.
1220 Number of dormant articles.
1223 Number of ticked articles.
1226 Number of read articles.
1229 Total number of articles.
1232 Number of unread, unticked, non-dormant articles.
1235 Number of ticked and dormant articles.
1244 Newsgroup description.
1259 A string that looks like @samp{<%s:%n>} if a foreign select method is
1263 Short (collapsed) group name.
1266 User defined specifier. The next character in the format string should
1267 be a letter. @sc{gnus} will call the function
1268 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
1269 following @samp{%u}. The function will be passed the current headers as
1270 argument. The function should return a string, which will be inserted
1271 into the buffer just like information from any other specifier.
1275 All the "number-of" specs will be filled with an asterisk (@samp{*}) if
1276 no info is available---for instance, if it is a non-activated foreign
1277 group, or a bogus (or semi-bogus) native group.
1279 @vindex gnus-group-mode-line-format
1280 The mode line can be changed by setting
1281 (@code{gnus-group-mode-line-format}). It doesn't understand that many
1286 The native news server.
1288 The native select method.
1291 @node Group Maneuvering
1292 @section Group Maneuvering
1293 @cindex group movement
1295 All movement commands understand the numeric prefix and will behave as
1296 expected, hopefully.
1302 @findex gnus-group-next-unread-group
1303 Go to the next group that has unread articles
1304 (@code{gnus-group-next-unread-group}).
1311 @findex gnus-group-prev-unread-group
1312 Go to the previous group group that has unread articles
1313 (@code{gnus-group-prev-unread-group}).
1317 @findex gnus-group-next-group
1318 Go to the next group (@code{gnus-group-next-group}).
1322 @findex gnus-group-prev-group
1323 Go to the previous group (@code{gnus-group-prev-group}).
1327 @findex gnus-group-next-unread-group-same-level
1328 Go to the next unread group on the same level (or lower)
1329 (@code{gnus-group-next-unread-group-same-level}).
1333 @findex gnus-group-prev-unread-group-same-level
1334 Go to the previous unread group on the same level (or lower)
1335 (@code{gnus-group-prev-unread-group-same-level}).
1338 Three commands for jumping to groups:
1344 @findex gnus-group-jump-to-group
1345 Jump to a group (and make it visible if it isn't already)
1346 (@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
1351 @findex gnus-group-best-unread-group
1352 Jump to the unread group with the lowest level
1353 (@code{gnus-group-best-unread-group}).
1357 @findex gnus-group-first-unread-group
1358 Jump to the first group with unread articles
1359 (@code{gnus-group-first-unread-group}).
1362 @vindex gnus-group-goto-unread
1363 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
1364 commands will move to the next group, not the next unread group. Even
1365 the commands that say they move to the next unread group. The default
1368 @node Selecting a Group
1369 @section Selecting a Group
1370 @cindex group selection
1375 @kindex SPACE (Group)
1376 @findex gnus-group-read-group
1377 Select the current group, switch to the summary buffer and display the
1378 first unread article (@code{gnus-group-read-group}). If there are no
1379 unread articles in the group, or if you give a non-numerical prefix to
1380 this command, Gnus will offer to fetch all the old articles in this
1381 group from the server. If you give a numerical prefix @var{N}, Gnus
1382 will fetch @var{N} number of articles. If @var{N} is positive, fetch
1383 the @var{N} newest articles, if @var{N} is negative, fetch the
1384 @var{abs(N)} oldest articles.
1388 @findex gnus-group-select-group
1389 Select the current group and switch to the summary buffer
1390 (@code{gnus-group-select-group}). Takes the same arguments as
1391 @code{gnus-group-read-group}---the only difference is that this command
1392 does not display the first unread article automatically upon group
1396 @kindex M-RET (Group)
1397 @findex gnus-group-quick-select-group
1398 This does the same as the command above, but tries to do it with the
1399 minimum amount off fuzz (@code{gnus-group-quick-select-group}). No
1400 scoring/killing will be performed, there will be no highlights and no
1401 expunging. This might be useful if you're in a real hurry and have to
1402 enter some humongous groups.
1405 @kindex M-RET (Group)
1406 @findex gnus-group-visible-select-group
1407 This is yet one more command that does the same as the one above, but
1408 this one does it without expunging and hiding dormants
1409 (@code{gnus-group-visible-select-group}).
1413 @findex gnus-group-catchup-current
1414 Mark all unticked articles in this group as read
1415 (@code{gnus-group-catchup-current}).
1419 @findex gnus-group-catchup-current-all
1420 Mark all articles in this group, even the ticked ones, as read
1421 (@code{gnus-group-catchup-current-all}).
1424 @vindex gnus-large-newsgroup
1425 The @code{gnus-large-newsgroup} variable says what Gnus should consider
1426 to be a big group. This is 200 by default. If the group has more
1427 unread articles than this, Gnus will query the user before entering the
1428 group. The user can then specify how many articles should be fetched
1429 from the server. If the user specifies a negative number (@samp{-n}),
1430 the @samp{n} oldest articles will be fetched. If it is positive, the
1431 @samp{n} articles that have arrived most recently will be fetched.
1433 @vindex gnus-select-group-hook
1434 @vindex gnus-auto-select-first
1435 @code{gnus-auto-select-first} control whether any articles are selected
1436 automatically when entering a group.
1441 Don't select any articles when entering the group. Just display the
1442 full summary buffer.
1445 Select the first unread article when entering the group.
1448 Select the most high-scored article in the group when entering the
1452 If you want to prevent automatic selection in some group (say, in a
1453 binary group with Huge articles) you can set this variable to @code{nil}
1454 in @code{gnus-select-group-hook}, which is called when a group is
1457 @findex gnus-thread-sort-by-total-score
1458 @findex gnus-thread-sort-by-date
1459 @findex gnus-thread-sort-by-score
1460 @findex gnus-thread-sort-by-subject
1461 @findex gnus-thread-sort-by-author
1462 @findex gnus-thread-sort-by-number
1463 @vindex gnus-thread-sort-functions
1464 If you are using a threaded summary display, you can sort the threads by
1465 setting @code{gnus-thread-sort-functions}, which is a list of functions.
1466 By default, sorting is done on article numbers. Ready-made sorting
1467 functions include @code{gnus-thread-sort-by-number},
1468 @code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
1469 @code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and
1470 @code{gnus-thread-sort-by-total-score}.
1472 Each function takes two threads and return non-@code{nil} if the first
1473 thread should be sorted before the other. If you use more than one
1474 function, the primary sort key should be the last function in the list.
1476 If you would like to sort by score, then by subject, and finally by
1477 date, you could do something like:
1480 (setq gnus-thread-sort-functions
1481 '(gnus-thread-sort-by-date
1482 gnus-thread-sort-by-subject
1483 gnus-thread-sort-by-score))
1486 @vindex gnus-thread-score-function
1487 The function in the @code{gnus-thread-score-function} variable (default
1488 @code{+}) is used for calculating the total score of a thread. Useful
1489 functions might be @code{max}, @code{min}, or squared means, or whatever
1492 @findex gnus-article-sort-functions
1493 @findex gnus-article-sort-by-date
1494 @findex gnus-article-sort-by-score
1495 @findex gnus-article-sort-by-subject
1496 @findex gnus-article-sort-by-author
1497 @findex gnus-article-sort-by-number
1498 If you are using an unthreaded display for some strange reason or other,
1499 you have to fiddle with the @code{gnus-article-sort-functions}
1500 variable. It is very similar to the @code{gnus-thread-sort-functions},
1501 except that is uses slightly different functions for article
1502 comparison. Available functions are @code{gnus-article-sort-by-number},
1503 @code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject},
1504 @code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}.
1507 @node Subscription Commands
1508 @section Subscription Commands
1517 @findex gnus-group-unsubscribe-current-group
1518 Toggle subscription to the current group
1519 (@code{gnus-group-unsubscribe-current-group}).
1525 @findex gnus-group-unsubscribe-group
1526 Prompt for a group to subscribe, and then subscribe it. If it was
1527 subscribed already, unsubscribe it instead
1528 (@code{gnus-group-unsubscribe-group}).
1534 @findex gnus-group-kill-group
1535 Kill the current group (@code{gnus-group-kill-group}).
1541 @findex gnus-group-yank-group
1542 Yank the last killed group (@code{gnus-group-yank-group}).
1548 @findex gnus-group-kill-region
1549 Kill all groups in the region (@code{gnus-group-kill-region}).
1553 @findex gnus-group-kill-all-zombies
1554 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
1557 @kindex S C-k (Group)
1558 @findex gnus-group-kill-level
1559 Kill all groups on a certain level (@code{gnus-group-kill-level}).
1560 These groups can't be yanked back after killing, so this command should
1561 be used with some caution. The only thing where this command comes in
1562 really handy is when you have a @file{.newsrc} with lots of unsubscribed
1563 groups that you want to get rid off. @kbd{S C-k} on level @code{7} will
1564 kill off all unsubscribed groups that do not have message numbers in the
1565 @file{.newsrc} file.
1569 Also @xref{Group Levels}.
1572 @section Group Levels
1575 All groups have a level of @dfn{subscribedness}. For instance, if a
1576 group is on level 2, it is more subscribed than a group on level 5. You
1577 can ask Gnus to just list groups on a given level or lower
1578 (@pxref{Listing Groups}), or to just check for new articles in groups on
1579 a given level or lower (@pxref{Misc Group Stuff}).
1585 @findex gnus-group-set-current-level
1586 Set the level of the current group. If a numeric prefix is given, the
1587 next @var{n} groups will have their levels set. The user will be
1588 prompted for a level.
1591 @vindex gnus-level-killed
1592 @vindex gnus-level-zombie
1593 @vindex gnus-level-unsubscribed
1594 @vindex gnus-level-subscribed
1595 Gnus considers groups on between levels 1 and
1596 @code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed,
1597 @code{gnus-level-subscribed} (exclusive) and
1598 @code{gnus-level-unsubscribed} (inclusive) (default 7) to be
1599 unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
1600 (default 8) and @code{gnus-level-killed} to be killed (default 9),
1601 completely dead. Gnus treats subscribed and unsubscribed groups exactly
1602 the same, but zombie and killed groups have no information on what
1603 articles you have read, etc, stored. This distinction between dead and
1604 living groups isn't done because it is nice or clever, it is done purely
1605 for reasons of efficiency.
1607 It is recommended that you keep all your mail groups (if any) on quite
1608 low levels (eg. 1 or 2).
1610 If you want to play with the level variables, you should show some care.
1611 Set them once, and don't touch them ever again. Better yet, don't touch
1612 them at all unless you know exactly what you're doing.
1614 @vindex gnus-level-default-unsubscribed
1615 @vindex gnus-level-default-subscribed
1616 Two closely related variables are @code{gnus-level-default-subscribed}
1617 (default 3) and @code{gnus-level-default-unsubscribed} (default 6),
1618 which are the levels that new groups will be put on if they are
1619 (un)subscribed. These two variables should, of course, be inside the
1620 relevant legal ranges.
1622 @vindex gnus-keep-same-level
1623 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
1624 will only move to groups that are of the same level (or lower). In
1625 particular, going from the last article in one group to the next group
1626 will go to the next group of the same level (or lower). This might be
1627 handy if you want to read the most important groups before you read the
1630 @vindex gnus-group-default-list-level
1631 All groups with a level less than or equal to
1632 @code{gnus-group-default-list-level} will be listed in the group buffer
1635 @vindex gnus-group-list-inactive-groups
1636 If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active
1637 groups will be listed along with the unread groups. This variable is
1638 @code{t} by default. If it is @code{nil}, inactive groups won't be
1641 @vindex gnus-group-use-permament-levels
1642 If @code{gnus-group-use-permament-levels} is non-@code{nil}, once you
1643 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
1644 use this level as the "work" level.
1646 @vindex gnus-activate-level
1647 Gnus will normally just activate groups that are on level
1648 @code{gnus-activate-level} or less. If you don't want to activate
1649 unsubscribed groups, for instance, you might set this variable to
1654 @section Group Score
1657 You would normally keep important groups on high levels, but that scheme
1658 is somewhat restrictive. Don't you wish you could have Gnus sort the
1659 group buffer according to how often you read groups, perhaps? Within
1662 This is what @dfn{group score} is for. You can assign a score to each
1663 group. You can then sort the group buffer based on this score.
1664 Alternatively, you can sort on score and then level. (Taken together,
1665 the level and the score is called the @dfn{rank} of the group. A group
1666 that is on level 4 and has a score of 1 has a higher rank than a group
1667 on level 5 that has a score of 300. (The level is the most significant
1668 part and the score is the least significant part.)
1670 @findex gnus-summary-bubble-group
1671 If you want groups you read often to get higher scores than groups you
1672 read seldom you can add the @code{gnus-summary-bubble-group} function to
1673 the @code{gnus-summary-exit-hook} hook. This will result (after
1674 sorting) in a bubbling sort of action. If you want to see that in
1675 action after each summary exit, you can add
1676 @code{gnus-group-sort-groups-by-rank} or
1677 @code{gnus-group-sort-groups-by-score} to the same hook, but that will
1678 slow things down somewhat.
1681 @node Marking Groups
1682 @section Marking Groups
1683 @cindex marking groups
1685 If you want to perform some command on several groups, and they appear
1686 subsequently in the group buffer, you would normally just give a
1687 numerical prefix to the command. Most group commands will then do your
1688 bidding on those groups.
1690 However, if the groups are not in sequential order, you can still
1691 perform a command on several groups. You simply mark the groups first
1692 with the process mark and then execute the command.
1700 @findex gnus-group-mark-group
1701 Set the mark on the current group (@code{gnus-group-mark-group}).
1707 @findex gnus-group-unmark-group
1708 Remove the mark from the current group
1709 (@code{gnus-group-unmark-group}).
1713 @findex gnus-group-mark-region
1714 Mark all groups between point and mark (@code{gnus-group-mark-region}).
1718 @findex gnus-group-mark-regexp
1719 Mark all groups that match some regular expression
1720 (@code{gnus-group-mark-regexp}).
1723 Also @xref{Process/Prefix}.
1726 @node Foreign Groups
1727 @section Foreign Groups
1728 @cindex foreign groups
1730 A @dfn{foreign group} is a group that is not read by the usual (or
1731 default) means. It could be, for instance, a group from a different
1732 @sc{nntp} server, it could be a virtual group, or it could be your own
1733 personal mail group.
1735 A foreign group (or any group, really) is specified by a @dfn{name} and
1736 a @dfn{select method}. To take the latter first, a select method is a
1737 list where the first element says what backend to use (eg. @code{nntp},
1738 @code{nnspool}, @code{nnml}) and the second element is the @dfn{server
1739 name}. There may be additional elements in the select method, where the
1740 value may have special meaning for the backend in question.
1742 One could say that a select method defines a @dfn{virtual server}---so
1743 we do just that (@pxref{The Server Buffer}).
1745 The @dfn{name} of the group is the name the backend will recognize the
1748 For instance, the group @samp{soc.motss} on the @sc{nntp} server
1749 @samp{some.where.edu} will have the name @samp{soc.motss} and select
1750 method @code{(nntp "some.where.edu")}. Gnus will call this group, in
1751 all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
1752 @code{nntp} backend just knows this group as @samp{soc.motss}.
1754 Here are some commands for making and editing general foreign groups,
1755 and some commands to ease the creation of some special-purpose groups:
1761 @findex gnus-group-make-group
1762 Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
1763 for a name, a method and possibly an @dfn{address}. For an easier way
1764 to subscribe to @sc{nntp} groups, @xref{Browse Foreign Server}.
1768 @findex gnus-group-rename-group
1769 Rename the current group to something else
1770 (@code{gnus-group-rename-group}). This is legal only on some groups --
1771 mail groups mostly. This command might very well be quite slow on some
1776 @findex gnus-group-edit-group-method
1777 Enter a buffer where you can edit the select method of the current
1778 group (@code{gnus-group-edit-group-method}).
1782 @findex gnus-group-edit-group-parameters
1783 Enter a buffer where you can edit the group parameters
1784 (@code{gnus-group-edit-group-parameters}).
1788 @findex gnus-group-edit-group
1789 Enter a buffer where you can edit the group info
1790 (@code{gnus-group-edit-group}).
1794 @findex gnus-group-make-directory-group
1795 Make a directory group. You will be prompted for a directory name
1796 (@code{gnus-group-make-directory-group}).
1800 @findex gnus-group-make-help-group
1801 Make the Gnus help group (@code{gnus-group-make-help-group}).
1805 @findex gnus-group-make-archive-group
1806 @vindex gnus-group-archive-directory
1807 @vindex gnus-group-recent-archive-directory
1808 Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
1809 default a group pointing to the most recent articles will be created
1810 (@code{gnus-group-recent-archibe-directory}), but given a prefix, a full
1811 group will be created from from @code{gnus-group-archive-directory}.
1815 @findex gnus-group-make-kiboze-group
1816 Make a kiboze group. You will be prompted for a name, for a regexp to
1817 match groups to be "included" in the kiboze group, and a series of
1818 strings to match on headers (@code{gnus-group-make-kiboze-group}).
1822 @findex gnus-group-enter-directory
1823 Read a random directory as if with were a newsgroup with the
1824 @code{nneething} backend (@code{gnus-group-enter-directory}).
1828 @findex gnus-group-make-doc-group
1829 Make a group based on some file or other
1830 (@code{gnus-group-make-doc-group}). If you give a prefix to this
1831 command, you will be prompted for a file name and a file type.
1832 Currently supported types are @code{babyl}, @code{mbox}, @code{digest},
1833 @code{mmdf}, @code{news}, @code{rnews}, and @code{forward}. If you run
1834 this command without a prefix, Gnus will guess at the file type.
1837 @kindex G DEL (Group)
1838 @findex gnus-group-delete-group
1839 This function will delete the current group
1840 (@code{gnus-group-delete-group}). If given a prefix, this function will
1841 actually delete all the articles in the group, and forcibly remove the
1842 group itself from the face of the Earth. Use a prefix only if you are
1843 sure of what you are doing.
1847 @findex gnus-group-make-empty-virtual
1848 Make a new, fresh, empty @code{nnvirtual} group
1849 (@code{gnus-group-make-empty-virtual}).
1853 @findex gnus-group-add-to-virtual
1854 Add the current group to an @code{nnvirtual} group
1855 (@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
1858 The different methods all have their peculiarities, of course.
1861 * nntp:: Reading news from a different @sc{nntp} server.
1862 * nnspool:: Reading news from the local spool.
1863 * nnvirtual:: Combining articles from many groups.
1864 * nnkiboze:: Looking through parts of the newsfeed for articles.
1865 * nndir:: You can read a directory as if it was a newsgroup.
1866 * nneething:: Dired? Who needs dired?
1867 * nndoc:: Single files can be the basis of a group.
1868 * SOUP:: Reading @sc{SOUP} packets "offline".
1869 * Reading Mail:: Reading your personal mail with Gnus.
1872 @vindex gnus-activate-foreign-newsgroups
1873 If the @code{gnus-activate-foreign-newsgroups} is a positive number,
1874 Gnus will check all foreign groups with this level or lower at startup.
1875 This might take quite a while, especially if you subscribe to lots of
1876 groups from different @sc{nntp} servers.
1882 Subscribing to a foreign group from an @sc{nntp} server is rather easy.
1883 You just specify @code{nntp} as method and the address of the @sc{nntp}
1884 server as the, uhm, address.
1886 If the @sc{nntp} server is located at a non-standard port, setting the
1887 third element of the select method to this port number should allow you
1888 to connect to the right port. You'll have to edit the group info for
1889 that (@pxref{Foreign Groups}).
1891 The name of the foreign group can be the same as a native group. In
1892 fact, you can subscribe to the same group from as many different servers
1893 you feel like. There will be no name collisions.
1895 The following variables can be used to create a virtual @code{nntp}
1900 @item nntp-server-opened-hook
1901 @vindex nntp-server-opened-hook
1902 @cindex @sc{mode reader}
1904 @cindex authentification
1905 @cindex nntp authentification
1906 @findex nntp-send-authinfo
1907 @findex nntp-send-mode-reader
1908 @code{nntp-server-opened-hook} is run after a connection has been made.
1909 It can be used to send commands to the @sc{nntp} server after it has
1910 been contacted. By default is sends the command @samp{MODE READER} to
1911 the server with the @code{nntp-send-mode-reader} function. Another
1912 popular function is @code{nntp-send-authinfo}, which will prompt you for
1913 an @sc{nntp} password and stuff.
1915 @item nntp-maximum-request
1916 @vindex nntp-maximum-request
1917 If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
1918 will collect headers by sending a series of @code{head} commands. To
1919 speed things up, the backend sends lots of these commands without
1920 waiting for reply, and then reads all the replies. This is controlled
1921 by the @code{nntp-maximum-request} variable, and is 400 by default. If
1922 your network is buggy, you should set this to 1.
1924 @item nntp-connection-timeout
1925 @vindex nntp-connection-timeout
1926 If you have lots of foreign @code{nntp} groups that you connect to
1927 regularly, you're sure to have problems with @sc{nntp} servers not
1928 responding properly, or being too loaded to reply within reasonable
1929 time. This is can lead to awkward problems, which can be helped
1930 somewhat by setting @code{nntp-connection-timeout}. This is an integer
1931 that says how many seconds the @code{nntp} backend should wait for a
1932 connection before giving up. If it is @code{nil}, which is the default,
1933 no timeouts are done.
1935 @item nntp-server-hook
1936 @vindex nntp-server-hook
1937 This hook is run as the last step when connecting to an @sc{nntp}
1940 @c @findex nntp-open-rlogin
1941 @c @findex nntp-open-network-stream
1942 @c @item nntp-open-server-function
1943 @c @vindex nntp-open-server-function
1944 @c This function is used to connect to the remote system. Two pre-made
1945 @c functions are @code{nntp-open-network-stream}, which is the default, and
1946 @c simply connects to some port or other on the remote system. The other
1947 @c is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
1948 @c and then does a telnet to the @sc{nntp} server available there.
1950 @c @item nntp-rlogin-parameters
1951 @c @vindex nntp-rlogin-parameters
1952 @c If you use @code{nntp-open-rlogin} as the
1953 @c @code{nntp-open-server-function}, this list will be used as the
1954 @c parameter list given to @code{rsh}.
1956 @c @item nntp-rlogin-user-name
1957 @c @vindex nntp-rlogin-user-name
1958 @c User name on the remote system when using the @code{rlogin} connect
1962 @vindex nntp-address
1963 The address of the remote system running the @sc{nntp} server.
1965 @item nntp-port-number
1966 @vindex nntp-port-number
1967 Port number to connect to when using the @code{nntp-open-network-stream}
1970 @item nntp-buggy-select
1971 @vindex nntp-buggy-select
1972 Set this to non-@code{nil} if your select routine is buggy.
1974 @item nntp-nov-is-evil
1975 @vindex nntp-nov-is-evil
1976 If the @sc{nntp} server does not support @sc{nov}, you could set this
1977 variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
1978 can be used automatically.
1980 @item nntp-xover-commands
1981 @vindex nntp-xover-commands
1982 List of strings that are used as commands to fetch @sc{nov} lines from a
1983 server. The default value of this variable is @code{("XOVER"
1987 @vindex nntp-nov-gap
1988 @code{nntp} normally sends just one big request for @sc{nov} lines to
1989 the server. The server responds with one huge list of lines. However,
1990 if you have read articles 2-5000 in the group, and only want to read
1991 article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
1992 lines that you do not want, and will not use. This variable says how
1993 big a gap between two consecutive articles is allowed to be before the
1994 @code{XOVER} request is split into several request. Note that if your
1995 network is fast, setting this variable to a really small number means
1996 that fetching will probably be slower. If this variable is @code{nil},
1997 @code{nntp} will never split requests.
1999 @item nntp-prepare-server-hook
2000 @vindex nntp-prepare-server-hook
2001 A hook run before attempting to connect to an @sc{nntp} server.
2003 @item nntp-async-number
2004 @vindex nntp-async-number
2005 How many articles should be pre-fetched when in asynchronous mode. If
2006 this variable is @code{t}, @code{nntp} will pre-fetch all the articles
2007 that it can without bound. If it is @code{nil}, no pre-fetching will be
2010 @item nntp-warn-about-losing-connection
2011 @vindex nntp-warn-about-losing-connection
2012 If this variable is non-@code{nil}, some noise will be made when a
2013 server closes connection.
2020 @cindex @code{nnspool}
2023 Subscribing to a foreign group from the local spool is extremely easy,
2024 and might be useful, for instance, to speed up reading groups like
2025 @samp{alt.binaries.pictures.furniture}.
2027 Anyways, you just specify @code{nnspool} as the method and @samp{""} (or
2028 anything else) as the address.
2030 If you have access to a local spool, you should probably use that as the
2031 native select method (@pxref{Finding the News}). It is normally faster
2032 than using an @code{nntp} select method, but might not be. It depends.
2033 You just have to try to find out what's best at your site.
2037 @item nnspool-inews-program
2038 @vindex nnspool-inews-program
2039 Program used to post an article.
2041 @item nnspool-inews-switches
2042 @vindex nnspool-inews-switches
2043 Parameters given to the inews program when posting an article.
2045 @item nnspool-spool-directory
2046 @vindex nnspool-spool-directory
2047 Where @code{nnspool} looks for the articles. This is normally
2048 @file{/usr/spool/news/}.
2050 @item nnspool-nov-directory
2051 @vindex nnspool-nov-directory
2052 Where @code{nnspool} will look for @sc{nov} files. This is normally
2053 @file{/usr/spool/news/over.view/}.
2055 @item nnspool-lib-dir
2056 @vindex nnspool-lib-dir
2057 Where the news lib dir is (@file{/usr/lib/news/} by default).
2059 @item nnspool-active-file
2060 @vindex nnspool-active-file
2061 The path of the active file.
2063 @item nnspool-newsgroups-file
2064 @vindex nnspool-newsgroups-file
2065 The path of the group descriptions file.
2067 @item nnspool-history-file
2068 @vindex nnspool-history-file
2069 The path of the news history file.
2071 @item nnspool-active-times-file
2072 @vindex nnspool-active-times-file
2073 The path of the active date file.
2075 @item nnspool-nov-is-evil
2076 @vindex nnspool-nov-is-evil
2077 If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
2080 @item nnspool-sift-nov-with-sed
2081 @vindex nnspool-sift-nov-with-sed
2082 If non-@code{nil}, which is the default, use @code{sed} to get the
2083 relevant portion from the overview file. If nil, @code{nnspool} will
2084 load the entire file into a buffer and process it there.
2089 @subsection nnvirtual
2090 @cindex @code{nnvirtual}
2091 @cindex virtual groups
2093 An @dfn{nnvirtual group} is really nothing more than a collection of
2096 For instance, if you are tired of reading many small group, you can
2097 put them all in one big group, and then grow tired of reading one
2098 big, unwieldy group. The joys of computing!
2100 You specify @code{nnvirtual} as the method. The address should be a
2101 regexp to match component groups.
2103 All marks in the virtual group will stick to the articles in the
2104 component groups. So if you tick an article in a virtual group, the
2105 article will also be ticked in the component group from whence it came.
2106 (And vice versa---marks from the component groups will also be shown in
2109 Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
2110 newsgroups into one, big, happy newsgroup:
2113 (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
2116 The component groups can be native or foreign; everything should work
2117 smoothly, but if your computer explodes, it was probably my fault.
2119 Collecting the same group from several servers might actually be a good
2120 idea if users have set the Distribution header to limit distribution.
2121 If you would like to read @samp{soc.motss} both from a server in Japan
2122 and a server in Norway, you could use the following as the group regexp:
2125 "^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
2128 This should work kinda smoothly---all articles from both groups should
2129 end up in this one, and there should be no duplicates. Threading (and
2130 the rest) will still work as usual, but there might be problems with the
2131 sequence of articles. Sorting on date might be an option here
2132 (@pxref{Selecting a Group}.
2134 One limitation, however---all groups that are included in a virtual
2135 group has to be alive (i.e., subscribed or unsubscribed). Killed or
2136 zombie groups can't be component groups for @code{nnvirtual} groups.
2140 @subsection nnkiboze
2141 @cindex @code{nnkiboze}
2144 @dfn{Kibozing} is defined by @sc{oed} as "grepping through (parts of)
2145 the news feed". @code{nnkiboze} is a backend that will do this for you. Oh
2146 joy! Now you can grind any @sc{nntp} server down to a halt with useless
2147 requests! Oh happiness!
2149 The address field of the @code{nnkiboze} method is, as with
2150 @code{nnvirtual}, a regexp to match groups to be "included" in the
2151 @code{nnkiboze} group. There most similarities between @code{nnkiboze}
2152 and @code{nnvirtual} ends.
2154 In addition to this regexp detailing component groups, an @code{nnkiboze} group
2155 must have a score file to say what articles that are to be included in
2156 the group (@pxref{Scoring}).
2158 @kindex M-x nnkiboze-generate-groups
2159 @findex nnkiboze-generate-groups
2160 You must run @kbd{M-x nnkiboze-generate-groups} after creating the
2161 @code{nnkiboze} groups you want to have. This command will take time. Lots of
2162 time. Oodles and oodles of time. Gnus has to fetch the headers from
2163 all the articles in all the components groups and run them through the
2164 scoring process to determine if there are any articles in the groups
2165 that are to be part of the @code{nnkiboze} groups.
2167 Please limit the number of component groups by using restrictive
2168 regexps. Otherwise your sysadmin may become annoyed with you, and the
2169 @sc{nntp} site may throw you off and never let you back in again.
2170 Stranger things have happened.
2172 @code{nnkiboze} component groups do not have to be alive---they can be dead,
2173 and they can be foreign. No restrictions.
2175 @vindex nnkiboze-directory
2176 The generation of an @code{nnkiboze} group means writing two files in
2177 @code{nnkiboze-directory}, which is @file{~/News/} by default. One
2178 contains the @sc{nov} header lines for all the articles in the group,
2179 and the other is an additional @file{.newsrc} file to store information
2180 on what groups that have been searched through to find component
2183 Articles that are marked as read in the @code{nnkiboze} group will have their
2184 @sc{nov} lines removed from the @sc{nov} file.
2188 @cindex @code{nndir}
2189 @cindex directory groups
2191 If you have a directory that has lots of articles in separate files in
2192 it, you might treat it as a newsgroup. The files have to have numerical
2195 This might be an opportune moment to mention @code{ange-ftp}, that most
2196 wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
2197 didn't think much about it---a backend to read directories. Big deal.
2199 @code{ange-ftp} changes that picture dramatically. For instance, if you
2200 enter @file{"/ftp@@sina.tcamc.uh.edu:/pub/emacs/ding-list/"} as the the
2201 directory name, ange-ftp will actually allow you to read this directory
2202 over at @samp{sina} as a newsgroup. Distributed news ahoy!
2204 @code{nndir} will use @sc{nov} files if they are present.
2206 @code{nndir} is a "read-only" backend---you can't delete or expire
2207 articles with this method. You can use @code{nnmh} or @code{nnml} for
2208 whatever you use @code{nndir} for, so you could switch to any of those
2209 methods if you feel the need to have a non-read-only @code{nndir}.
2212 @subsection nneething
2213 @cindex @code{nneething}
2215 From the @code{nndir} backend (which reads a single spool-like
2216 directory), it's just a hop and a skip to @code{nneething}, which
2217 pretends that any random directory is a newsgroup. Strange, but true.
2219 When @code{nneething} is presented with a directory, it will scan this
2220 directory and assign article numbers to each file. When you enter such a
2221 group, @code{nneething} must create "headers" that Gnus can use. After
2222 all, Gnus is a newsreader, in case you're forgetting. @code{nneething}
2223 does this in a two-step process. First, it snoops each file in question.
2224 If the file looks like an article (i.e., the first few lines look like
2225 headers), it will use this as the head. If this is just some random file
2226 without a head (eg. a C source file), @code{nneething} will cobble up a
2227 header out of thin air. It will use file ownership, name and date and do
2228 whatever it can with these elements.
2230 All this should happen automatically for you, and you will be presented
2231 with something that looks very much like a newsgroup. Totally like a
2232 newsgroup, to be precise. If you select an article, it will be displayed
2233 in the article buffer, just as usual.
2235 If you select a line that represents a directory, Gnus will pop you into
2236 a new summary buffer for this @code{nneething} group. And so on. You can
2237 traverse the entire disk this way, if you feel like, but remember that
2238 Gnus is not dired, really, and does not intend to be, either.
2240 There are two overall modes to this action---ephemeral or solid. When
2241 doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
2242 will not store information on what files you have read, and what files
2243 are new, and so on. If you create a solid @code{nneething} group the
2244 normal way with @kbd{G m}, Gnus will store a mapping table between
2245 article numbers and file names, and you can treat this group like any
2246 other groups. When you activate a solid @code{nneething} group, you will
2247 be told how many unread articles it contains, etc., etc.
2252 @item nneething-map-file-directory
2253 @vindex nneething-map-file-directory
2254 All the mapping files for solid @code{nneething} groups will be stored
2255 in this directory, which defaults to @file{~/.nneething/}.
2257 @item nneething-exclude-files
2258 @vindex nneething-exclude-files
2259 All files that match this regexp will be ignored. Nice to use to exclude
2260 auto-save files and the like, which is what it does by default.
2262 @item nneething-map-file
2263 @vindex nneething-map-file
2264 Name of the map files.
2270 @cindex @code{nndoc}
2271 @cindex documentation group
2274 @code{nndoc} is a cute little thing that will let you read a single file
2275 as a newsgroup. Several files types are supported:
2282 The babyl (rmail) mail box.
2287 The standard Unix mbox file.
2288 @cindex MMDF mail box
2291 The MMDF mail box format.
2294 Several news articles appended into a file.
2297 @cindex rnews batch files
2298 The rnews batch transport format.
2299 @cindex forwarded messages
2308 @cindex RFC 1153 digest
2309 @cindex RFC 341 digest
2310 MIME (RFC 1341) digest format.
2312 @item standard-digest
2313 The standard (RFC 1153) digest format.
2316 Non-standard digest format---matches most things, but does it badly.
2319 You can also use the special "file type" @code{guess}, which means that
2320 @code{nndoc} will try to guess what file type it is looking at.
2321 @code{digest} means that @code{nndoc} should guess what digest type the
2324 @code{nndoc} will not try to change the file or insert any extra headers into
2325 it---it will simply, like, let you use the file as the basis for a
2326 group. And that's it.
2328 If you have some old archived articles that you want to insert into your
2329 new & spiffy Gnus mail backend, @code{nndoc} can probably help you with
2330 that. Say you have an old @file{RMAIL} file with mail that you now want
2331 to split into your new @code{nnml} groups. You look at that file using
2332 @code{nndoc}, set the process mark on all the articles in the buffer
2333 (@kbd{M P b}, for instance), and then respool (@kbd{B r}) using
2334 @code{nnml}. If all goes well, all the mail in the @file{RMAIL} file is
2335 now also stored in lots of @code{nnml} directories, and you can delete
2336 that pesky @file{RMAIL} file. If you have the guts!
2338 Virtual server variables:
2341 @item nndoc-article-type
2342 @vindex nndoc-article-type
2343 This should be one of @code{mbox}, @code{babyl}, @code{digest},
2344 @code{mmdf}, @code{forward}, or @code{guess}.
2349 @subsection @sc{soup}
2353 In the PC world people often talk about "offline" newsreaders. These
2354 are thingies that are combined reader/news transport monstrosities.
2355 With built-in modem programs. Yecchh!
2357 Of course, us Unix Weenie types of human beans use things like
2358 @code{uucp} and, like, @code{nntpd} and set up proper news and mail
2359 transport things like Ghod inteded. And then we just use normal
2362 However, it can sometimes be convenient to do something a that's a bit
2363 easier on the brain if you have a very slow modem, and you're not really
2364 that interested in doing things properly.
2366 A file format called @sc{soup} has been developed for transporting news
2367 and mail from servers to home machines and back again. It can be a bit
2373 You log in on the server and create a @sc{soup} packet. You can either
2374 use a dedicated @sc{soup} thingie, or you can use Gnus to create the
2375 packet with the @kbd{O s} command.
2378 You transfer the packet home. Rail, boat, car or modem will do fine.
2381 You put the packet in your home directory.
2384 You fire up Gnus using the @code{nnsoup} backend as the native server.
2387 You read articles and mail and answer and followup to the things you
2391 You do the @kbd{G s r} command to pack these replies into a @sc{soup}
2395 You transfer this packet to the server.
2398 You use Gnus to mail this packet out with the @kbd{G s s} command.
2401 You then repeat until you die.
2405 So you basically have a bipartite system---you use @code{nnsoup} for
2406 reading and Gnus for packing/sending these @sc{soup} packets.
2409 * SOUP Commands:: Commands for creating and sending @sc{soup} packets
2410 * nnsoup:: A backend for reading @sc{soup} packets.
2411 * SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
2416 @subsubsection @sc{soup} Commands
2420 @kindex G s b (Group)
2421 @findex gnus-group-brew-soup
2422 Pack all unread articles in the current group
2423 (@code{gnus-group-brew-soup}). This command understands the
2424 process/prefix convention.
2427 @kindex G s w (Group)
2428 @findex gnus-soup-save-areas
2429 Save all data files (@code{gnus-soup-save-areas}).
2432 @kindex G s s (Group)
2433 @findex gnus-soup-send-replies
2434 Send all replies from the replies packet
2435 (@code{gnus-soup-send-replies}).
2438 @kindex G s p (Group)
2439 @findex gnus-soup-pack-packet
2440 Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
2443 @kindex G s r (Group)
2444 @findex nnsoup-pack-replies
2445 Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
2448 @kindex O s (Summary)
2449 @findex gnus-soup-add-article
2450 This summary-mode command adds the current article to a @sc{soup} packet
2451 (@code{gnus-soup-add-article}). It understands the process/prefix
2457 There are a few variables to customize where Gnus will put all these
2462 @item gnus-soup-directory
2463 @vindex gnus-soup-directory
2464 Directory where Gnus will save intermediate files while composing
2465 @sc{soup} packets. The default is @file{~/SoupBrew/}.
2467 @item gnus-soup-replies-directory
2468 @vindex gnus-soup-replies-directory
2469 This is what Gnus will use as a temporary directory while sending our
2470 reply packets. The default is @file{~/SoupBrew/SoupReplies/}.
2472 @item gnus-soup-prefix-file
2473 @vindex gnus-soup-prefix-file
2474 Name of the file where Gnus stores the last used prefix. The default is
2475 @samp{"gnus-prefix"}.
2477 @item gnus-soup-packer
2478 @vindex gnus-soup-packer
2479 A format string command for packing a @sc{soup} packet. The default is
2480 @samp{ "tar cf - %s | gzip > $HOME/Soupout%d.tgz"}.
2482 @item gnus-soup-unpacker
2483 @vindex gnus-soup-unpacker
2484 Format string command for unpacking a @sc{soup} packet. The default is
2485 @samp{"gunzip -c %s | tar xvf -"}.
2487 @item gnus-soup-packet-directory
2488 @vindex gnus-soup-packet-directory
2489 Wehre Gnus will look for reply packets. The default is @file{~/}.
2491 @item gnus-soup-packet-regexp
2492 @vindex gnus-soup-packet-regexp
2493 Regular expression matching @sc{soup} reply packets in
2494 @code{gnus-soup-packet-directory}.
2500 @subsubsection nnsoup
2501 @cindex @code{nnsoup}
2503 @code{nnsoup} is the backend for reading @sc{soup} packets. It will
2504 read incoming packets, unpack them, and put them in a directory where
2505 you can read them at leisure.
2507 These are the variables you can use to customize its behavior:
2511 @item nnsoup-directory
2512 @vindex nnsoup-directory
2513 @code{nnsoup} will move all incoming @sc{soup} packets to this directory
2514 and unpack them there. The default is @file{~/SOUP/}.
2516 @item nnsoup-replies-directory
2517 @vindex nnsoup-replies-directory
2518 All replies will stored in this directory before being packed into a
2519 reply packet. The default is @file{~/SOUP/replies/"}.
2521 @item nnsoup-replies-format-type
2522 @vindex nnsoup-replies-format-type
2523 The @sc{soup} format of the replies packets. The default is @samp{?n}
2524 (rnews), and I don't think you should touch that variable. I probaly
2525 shouldn't even have documented it. Drats! Too late!
2527 @item nnsoup-replies-index-type
2528 @vindex nnsoup-replies-index-type
2529 The index type of the replies packet. The is @samp{?n}, which means
2530 "none". Don't fiddle with this one either!
2532 @item nnsoup-active-file
2533 @vindex nnsoup-active-file
2534 Where @code{nnsoup} stores lots of information. This is not an "active
2535 file" in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
2536 this file or mess it up in any way, you're dead. The default is
2537 @file{~/SOUP/active}.
2540 @vindex nnsoup-packer
2541 Format string command for packing a reply @sc{soup} packet. The default
2542 is @samp{"tar cf - %s | gzip > $HOME/Soupin%d.tgz"}.
2544 @item nnsoup-unpacker
2545 @vindex nnsoup-unpacker
2546 Format string command for unpacking incoming @sc{soup} packets. The
2547 default is @samp{"gunzip -c %s | tar xvf -"}.
2549 @item nnsoup-packet-directory
2550 @vindex nnsoup-packet-directory
2551 Where @code{nnsoup} will look for incoming packets. The default is
2554 @item nnsoup-packet-regexp
2555 @vindex nnsoup-packet-regexp
2556 Regular expression matching incoming @sc{soup} packets. The default is
2563 @subsubsection @sc{SOUP} Replies
2565 Just using @code{nnsoup} won't mean that your postings and mailings end
2566 up in @sc{soup} reply packets automagically. You have to work a bit
2567 more for that to happen.
2569 @findex nnsoup-set-variables
2570 The @code{nnsoup-set-variables} command will set the appropriate
2571 variables to ensure that all your followups and replies end up in the
2574 In specific, this is what it does:
2577 (setq gnus-inews-article-function 'nnsoup-request-post)
2578 (setq send-mail-function 'nnsoup-request-mail)
2581 And that's it, really. If you only want news to go into the @sc{soup}
2582 system you just use the first line. If you only want mail to be
2583 @sc{soup}ed you use the second.
2587 @subsection Reading Mail
2588 @cindex reading mail
2591 Reading mail with a newsreader---isn't that just plain WeIrD? But of
2594 Gnus will read the mail spool when you activate a mail group. The mail
2595 file is first copied to your home directory. What happens after that
2596 depends on what format you want to store your mail in.
2599 * Creating Mail Groups:: How to create mail groups.
2600 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
2601 * Mail & Procmail:: Reading mail groups that procmail create.
2602 * Expiring Old Mail Articles:: Getting rid of unwanted mail.
2603 * Not Reading Mail:: Using mail backends for reading other files.
2604 * nnmbox:: Using the (quite) standard Un*x mbox.
2605 * nnbabyl:: Emacs programs use the rmail babyl format.
2606 * nnml:: Store your mail in a private spool?
2607 * nnmh:: An mhspool-like backend.
2608 * nnfolder:: Having one file for each group.
2611 @vindex nnmail-read-incoming-hook
2612 The mail backends all call @code{nnmail-read-incoming-hook} after
2613 reading new mail. You can use this hook to notify any mail watch
2614 programs, if you want to.
2616 @vindex nnmail-spool-file
2618 @code{nnmail-spool-file} says where to look for new mail. If this
2619 variable is @code{nil}, the mail backends will never attempt to fetch
2620 mail by themselves. If you are using a POP mail server and your name is
2621 @samp{"larsi"}, you should set this variable to @samp{"po:larsi"}. If
2622 your name is not @samp{"larsi"}, you should probably modify that
2623 slightly, but you may have guessed that already, you smart & handsome
2624 devil! You can also set this variable to @code{pop}, and Gnus will try
2625 to figure out the POP mail string by itself.
2627 When you use a mail backend, Gnus will slurp all your mail from your
2628 inbox and plonk it down in your home directory. Gnus doesn't move any
2629 mail if you're not using a mail backend---you have to do a lot of magic
2630 invocations first. At the time when you have finished drawing the
2631 pentagram, lightened the candles, and sacrificed the goat, you really
2632 shouldn't be too suprised when Gnus moves your mail.
2634 @vindex nnmail-use-procmail
2635 If @code{nnmail-use-procmail} is non-@code{nil}, the mail backends will
2636 look in @code{nnmail-procmail-directory} for incoming mail. All the
2637 files in that directory that have names ending in
2638 @code{gnus-procmail-suffix} will be considered incoming mailboxes, and
2639 will be searched for new mail.
2641 @vindex nnmail-prepare-incoming-hook
2642 @code{nnmail-prepare-incoming-hook} is run in a buffer that holds all
2643 the new incoming mail, and can be used for, well, anything, really.
2645 @vindex nnmail-tmp-directory
2646 @code{nnmail-tmp-directory} says where to move the incoming mail to
2647 while processing it. This is usually done in the same directory that
2648 the mail backend inhabits (i.e., @file{~/Mail/}), but if this variable is
2649 non-@code{nil}, it will be used instead.
2651 @vindex nnmail-movemail-program
2652 @code{nnmail-movemail-program} is executed to move mail from the user's
2653 inbox to her home directory. The default is @samp{"movemail"}.
2655 @vindex nnmail-delete-incoming
2656 If @code{nnmail-delete-incoming} is non-@code{nil}, the mail backends
2657 will delete the temporary incoming file after splitting mail into the
2658 proper groups. This is @code{nil} by default for reasons of security.
2660 @vindex nnmail-use-long-file-names
2661 If @code{nnmail-use-long-file-names} is non-@code{nil} the mail backends
2662 will use long file and directory names. Groups like @samp{mail.misc}
2663 will end up in directories like @file{mail.misc/}. If it is @code{nil},
2664 the same group will end up in @file{mail/misc/}.
2666 @vindex nnmail-message-id-cache-length
2667 @vindex nnmail-message-id-cache-file
2668 @vindex nnmail-delete-duplicates
2669 @cindex duplicate mails
2670 If you are a member of a couple of mailing list, you will sometime
2671 receive two copies of the same mail. This can be quite annoying, so
2672 @code{nnmail} checks for and discards any duplicates it might find. To
2673 do this, it keeps a cache of old @code{Message-ID}s -
2674 @code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
2675 default. The approximate maximum number of @code{Message-ID}s stored
2676 there is controlled by the @code{nnmail-message-id-cache-length}
2677 variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
2678 stored.) If all this sounds scary to you, you can set
2679 @code{nnmail-delete-duplicates} to @code{nil} (which is what it is by
2680 default), and @code{nnmail} won't do any duplicate checking.
2682 Here's a neat feature: If you know that the recipient reads her mail
2683 with Gnus, and that she has @code{nnmail-delete-duplicates} set to
2684 @code{t}, you can send her as many insults as you like, just by using a
2685 @code{Message-ID} of a mail that you know that she's already received.
2686 Think of all the fun! She'll never see any of it! Whee!
2688 Gnus gives you all the opportunity you could possibly want for shooting
2689 yourself in the foot. Let's say you create a group that will contain
2690 all the mail you get from your boss. And then you accidentally
2691 unsubscribe from the group. Gnus will still put all the mail from your
2692 boss in the unsubscribed group, and so, when your boss mails you "Have
2693 that report ready by Monday or you're fired!", you'll never see it and,
2694 come Tuesday, you'll still believe that you're gainfully employed while
2695 you really should be out collecting empty bottles to save up for next
2698 @node Creating Mail Groups
2699 @subsubsection Creating Mail Groups
2700 @cindex creating mail groups
2702 You can make Gnus read your personal, private, secret mail.
2704 You should first set @code{gnus-secondary-select-methods} to, for
2705 instance, @code{((nnmbox ""))}. When you start up Gnus, Gnus will ask
2706 this backend for what groups it carries (@samp{mail.misc} by default)
2707 and subscribe it the normal way. (Which means you may have to look for
2708 it among the zombie groups, I guess, all depending on your
2709 @code{gnus-subscribe-newsgroup-method} variable.)
2711 @vindex nnmail-split-methods
2712 Then you should set the variable @code{nnmail-split-methods} to specify
2713 how the incoming mail is to be split into groups.
2716 (setq nnmail-split-methods
2717 '(("mail.junk" "^From:.*Lars Ingebrigtsen")
2718 ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
2722 This variable is a list of lists, where the first element of each of
2723 these lists is the name of the mail group (they do not have to be called
2724 something beginning with @samp{mail}, by the way), and the second
2725 element is a regular expression used on the header of each mail to
2726 determine if it belongs in this mail group.
2728 The second element can also be a function. In that case, it will be
2729 called narrowed to the headers with the first element of the rule as the
2730 argument. It should return a non-@code{nil} value if it thinks that the
2731 mail belongs in that group.
2733 The last of these groups should always be a general one, and the regular
2734 expression should @emph{always} be @samp{""} so that it matches any
2735 mails that haven't been matched by any of the other regexps.
2737 If you like to tinker with this yourself, you can set this variable to a
2738 function of your choice. This function will be called without any
2739 arguments in a buffer narrowed to the headers of an incoming mail
2740 message. The function should return a list of groups names that it
2741 thinks should carry this mail message.
2743 Note that the mail backends are free to maul the poor, innocent
2744 incoming headers all they want to. They all add @code{Lines} headers;
2745 some add @code{X-Gnus-Group} headers; most rename the Unix mbox
2746 @code{From<SPC>} line to something else.
2748 @vindex nnmail-crosspost
2749 The mail backends all support cross-posting. If several regexps match,
2750 the mail will be "cross-posted" to all those groups.
2751 @code{nnmail-crosspost} says whether to use this mechanism or not. Note
2752 that no articles are crossposted to the general (@samp{""}) group.
2756 @node Fancy Mail Splitting
2757 @subsubsection Fancy Mail Splitting
2758 @cindex mail splitting
2759 @cindex fancy mail splitting
2761 @vindex nnmail-split-fancy
2762 @findex nnmail-split-fancy
2763 If the rather simple, standard method for specifying how to split mail
2764 doesn't allow you to do what you want, you can set
2765 @code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
2766 play with the @code{nnmail-split-fancy} variable.
2768 Let's look at an example value of this variable first:
2771 ;; Messages from the mailer daemon are not crossposted to any of
2772 ;; the ordinary groups. Warnings are put in a separate group
2773 ;; from real errors.
2774 (| ("from" mail (| ("subject" "warn.*" "mail.warning")
2776 ;; Non-error messages are crossposted to all relevant
2777 ;; groups, but we don't crosspost between the group for the
2778 ;; (ding) list and the group for other (ding) related mail.
2779 (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
2780 ("subject" "ding" "ding.misc"))
2781 ;; Other mailing lists...
2782 (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
2783 (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
2785 (any "larsi@@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
2786 ;; Unmatched mail goes to the catch all group.
2790 This variable has the format of a @dfn{split}. A split is a (possibly)
2791 recursive structure where each split may contain other splits. Here are
2792 the four possible split syntaxes:
2797 If the split is a string, that will be taken as a group name.
2799 @item (FIELD VALUE SPLIT)
2800 If the split is a list, and the first element is a string, then that
2801 means that if header FIELD (a regexp) contains VALUE (also a regexp),
2802 then store the message as specified by SPLIT.
2805 If the split is a list, and the first element is @code{|} (vertical
2806 bar), then process each SPLIT until one of them matches. A SPLIT is
2807 said to match if it will cause the mail message to be stored in one or
2811 If the split is a list, and the first element is @code{&}, then process
2812 all SPLITs in the list.
2815 In these splits, FIELD must match a complete field name. VALUE must
2816 match a complete word according to the fundamental mode syntax table.
2817 You can use @code{.*} in the regexps to match partial field names or
2820 @vindex nnmail-split-abbrev-alist
2821 FIELD and VALUE can also be lisp symbols, in that case they are expanded
2822 as specified by the variable @code{nnmail-split-abbrev-alist}. This is
2823 an alist of cons cells, where the car of the cells contains the key, and
2824 the cdr contains a string.
2826 @node Mail & Procmail
2827 @subsubsection Mail & Procmail
2830 Many people use @code{procmail} to split incoming mail into groups. If
2831 you do that, you should set @code{nnmail-spool-file} to @code{procmail}
2832 to ensure that the mail backends never ever try to fetch mail by
2835 This also means that you probably don't want to set
2836 @code{nnmail-split-methods} either, which has some, perhaps, unexpected
2839 When a mail backend is queried for what groups it carries, it replies
2840 with the contents of that variable, along with any groups it has figured
2841 out that it carries by other means. None of the backends (except
2842 @code{nnmh}) actually go out to the disk and check what groups actually
2843 exist. (It's not trivial to distinguish between what the user thinks is
2844 a basis for a newsgroup and what is just a plain old file or directory.)
2846 This means that you have to tell Gnus (and the backends) what groups
2849 Let's take the @code{nnmh} backend as an example.
2851 The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
2852 There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
2854 Go to the group buffer and type @kbd{G m}. When prompted, answer
2855 @samp{foo} for the name and @samp{nnmh} for the method. Repeat
2856 twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
2857 to include all your mail groups.
2859 That's it. You are now set to read your mail. An active file for this
2860 method will be created automatically.
2862 @vindex nnmail-procmail-suffix
2863 @vindex nnmail-procmail-directory
2864 If you use @code{nnfolder} or any other backend that store more than a
2865 single article in each file, you should never have procmail add mails to
2866 the file that Gnus sees. Instead, procmail should put all incoming mail
2867 in @code{nnmail-procmail-directory}. To arrive at the file name to put
2868 the incoming mail in, append @code{nnmail-procmail-suffix} to the group
2869 name. The mail backends will read the mail from these files.
2871 @vindex nnmail-resplit-incoming
2872 When Gnus reads a file called @file{mail.misc.spool}, this mail will be
2873 put in the @code{mail.misc}, as one would expect. However, if you want
2874 Gnus to split the mail the normal way, you could set
2875 @code{nnmail-resplit-incoming} to @code{t}.
2877 @vindex nnmail-keep-last-article
2878 If you use @code{procmail} to split things directory into an @code{nnmh}
2879 directory (which you shouldn't do), you should set
2880 @code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
2881 ever expiring the final article in a mail newsgroup. This is quite,
2885 @node Expiring Old Mail Articles
2886 @subsubsection Expiring Old Mail Articles
2887 @cindex article expiry
2889 Traditional mail readers have a tendency to remove mail articles when
2890 you mark them as read, in some way. Gnus takes a fundamentally
2891 different approach to mail reading.
2893 Gnus basically considers mail just to be news that has been received in
2894 a rather peculiar manner. It does not think that it has the power to
2895 actually change the mail, or delete any mail messages. If you enter a
2896 mail group, and mark articles as "read", or kill them in some other
2897 fashion, the mail articles will still exist on the system. I repeat:
2898 Gnus will not delete your old, read mail. Unless you ask it to, of
2901 To make Gnus get rid of your unwanted mail, you have to mark the
2902 articles as @dfn{expirable}. This does not mean that the articles will
2903 disappear right away, however. In general, a mail article will be
2904 deleted from your system if, 1) it is marked as expirable, AND 2) it is
2905 more than one week old. If you do not mark an article as expirable, it
2906 will remain on your system until hell freezes over. This bears
2907 repeating one more time, with some spurious capitalizations: IF you do
2908 NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
2910 @vindex gnus-auto-expirable-newsgroups
2911 You do not have to mark articles as expirable by hand. Groups that
2912 match the regular expression @code{gnus-auto-expirable-newsgroups} will
2913 have all articles that you read marked as expirable automatically. All
2914 articles that are marked as expirable have an @samp{E} in the first
2915 column in the summary buffer.
2917 Let's say you subscribe to a couple of mailing lists, and you want the
2918 articles you have read to disappear after a while:
2921 (setq gnus-auto-expirable-newsgroups
2922 "mail.nonsense-list\\|mail.nice-list")
2925 Another way to have auto-expiry happen is to have the element
2926 @code{auto-expire} in the select method of the group.
2928 @vindex nnmail-expiry-wait
2929 The @code{nnmail-expiry-wait} variable supplies the default time an
2930 expirable article has to live. The default is seven days.
2932 Gnus also supplies a function that lets you fine-tune how long articles
2933 are to live, based on what group they are in. Let's say you want to
2934 have one month expiry period in the @samp{mail.private} group, a one day
2935 expiry period in the @samp{mail.junk} group, and a six day expiry period
2939 (setq nnmail-expiry-wait-function
2941 (cond ((string= group "mail.private")
2943 ((string= group "mail.junk")
2945 ((string= group "important")
2951 The group names that this function is fed are "unadorned" group
2952 names---no @samp{"nnml:"} prefixes and the like.
2954 The @code{nnmail-expiry-wait} variable and
2955 @code{nnmail-expiry-wait-function} function can be either a number (not
2956 necessarily an integer) or the symbols @code{immediate} or
2959 @vindex nnmail-keep-last-article
2960 If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
2961 expire the final article in a mail newsgroup. This is to make life
2962 easier for procmail users.
2964 @vindex gnus-total-expirable-newsgroups
2965 By the way, that line up there about Gnus never expiring non-expirable
2966 articles is a lie. If you put @code{total-expire} in the group
2967 parameters, articles will not be marked as expirable, but all read
2968 articles will be put through the expiry process. Use with extreme
2969 caution. Even more dangerous is the
2970 @code{gnus-total-expirable-newsgroups} variable. All groups that match
2971 this regexp will have all read articles put through the expiry process,
2972 which means that @emph{all} old mail articles in the groups in question
2973 will be deleted after a while. Use with extreme caution, and don't come
2974 crying to me when you discover that the regexp you used matched the
2975 wrong group and all your important mail has disappeared. Be a
2976 @emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
2980 @node Not Reading Mail
2981 @subsubsection Not Reading Mail
2983 If you start using any of the mail backends, they have the annoying
2984 habit of assuming that you want to read mail with them. This might not
2985 be unreasonable, but it might not be what you want.
2987 If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
2988 will ever attempt to read incoming mail, which should help.
2990 @vindex nnbabyl-get-new-mail
2991 @vindex nnmbox-get-new-mail
2992 @vindex nnml-get-new-mail
2993 @vindex nnmh-get-new-mail
2994 @vindex nnfolder-get-new-mail
2995 This might be too much, if, for instance, you are reading mail quite
2996 happily with @code{nnml} and just want to peek at some old @sc{rmail}
2997 file you have stashed away with @code{nnbabyl}. All backends have
2998 variables called backend-@code{get-new-mail}. If you want to disable
2999 the @code{nnbabyl} mail reading, you edit the virtual server for the
3000 group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
3002 All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
3003 narrowed to the article to be saved before saving it when reading
3007 @subsubsection nnmbox
3008 @cindex @code{nnmbox}
3009 @cindex unix mail box
3011 @vindex nnmbox-active-file
3012 @vindex nnmbox-mbox-file
3013 The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
3014 mail. @code{nnmbox} will add extra headers to each mail article to say
3015 which group it belongs in.
3017 Virtual server settings:
3020 @item nnmbox-mbox-file
3021 @vindex nnmbox-mbox-file
3022 The name of the mail box in the user's home directory.
3024 @item nnmbox-active-file
3025 @vindex nnmbox-active-file
3026 The name of the active file for the mail box.
3028 @item nnmbox-get-new-mail
3029 @vindex nnmbox-get-new-mail
3030 If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
3035 @subsubsection nnbabyl
3036 @cindex @code{nnbabyl}
3039 @vindex nnbabyl-active-file
3040 @vindex nnbabyl-mbox-file
3041 The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
3042 mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
3043 article to say which group it belongs in.
3045 Virtual server settings:
3048 @item nnbabyl-mbox-file
3049 @vindex nnbabyl-mbox-file
3050 The name of the rmail mbox file.
3052 @item nnbabyl-active-file
3053 @vindex nnbabyl-active-file
3054 The name of the active file for the rmail box.
3056 @item nnbabyl-get-new-mail
3057 @vindex nnbabyl-get-new-mail
3058 If non-@code{nil}, @code{nnbabyl} will read incoming mail.
3064 @cindex mail @sc{nov} spool
3066 The @dfn{nnml} spool mail format isn't compatible with any other known
3067 format. It should be used with some caution.
3069 @vindex nnml-directory
3070 If you use this backend, Gnus will split all incoming mail into files;
3071 one file for each mail, and put the articles into the correct
3072 directories under the directory specified by the @code{nnml-directory}
3073 variable. The default value is @file{~/Mail/}.
3075 You do not have to create any directories beforehand; Gnus will take
3078 If you have a strict limit as to how many files you are allowed to store
3079 in your account, you should not use this backend. As each mail gets its
3080 own file, you might very well occupy thousands of inodes within a few
3081 weeks. If this is no problem for you, and it isn't a problem for you
3082 having your friendly systems administrator walking around, madly,
3083 shouting "Who is eating all my inodes?! Who? Who!?!", then you should
3084 know that this is probably the fastest format to use. You do not have
3085 to trudge through a big mbox file just to read your new mail.
3087 @code{nnml} is probably the slowest backend when it comes to article
3088 splitting. It has to create lots of files, and it also generates
3089 @sc{nov} databases for the incoming mails. This makes is the fastest
3090 backend when it comes to reading mail.
3092 Virtual server settings:
3095 @item nnml-directory
3096 @vindex nnml-directory
3097 All @code{nnml} directories will be placed under this directory.
3099 @item nnml-active-file
3100 @vindex nnml-active-file
3101 The active file for the @code{nnml} server.
3103 @item nnml-newsgroups-file
3104 @vindex nnml-newsgroups-file
3105 The @code{nnml} group descriptions file. @xref{Newsgroups File
3108 @item nnml-get-new-mail
3109 @vindex nnml-get-new-mail
3110 If non-@code{nil}, @code{nnml} will read incoming mail.
3112 @item nnml-nov-is-evil
3113 @vindex nnml-nov-is-evil
3114 If non-@code{nil}, this backend will ignore any @sc{nov} files.
3116 @item nnml-nov-file-name
3117 @vindex nnml-nov-file-name
3118 The name of the @sc{nov} files. The default is @file{.overview}.
3122 @findex nnml-generate-nov-databases
3123 If your @code{nnml} groups and @sc{nov} files get totally out of whack,
3124 you can do a complete update by typing @kbd{M-x
3125 nnml-generate-nov-databases}. This command will trawl through the
3126 entire @code{nnml} hierarchy, looking at each and every article, so it
3127 might take a while to complete.
3132 @cindex mh-e mail spool
3134 @code{nnmh} is just like @code{nnml}, except that is doesn't generate
3135 @sc{nov} databases and it doesn't keep an active file. This makes
3136 @code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
3137 makes it easier to write procmail scripts for.
3139 Virtual server settings:
3142 @item nnmh-directory
3143 @vindex nnmh-directory
3144 All @code{nnmh} directories will be located under this directory.
3146 @item nnmh-get-new-mail
3147 @vindex nnmh-get-new-mail
3148 If non-@code{nil}, @code{nnmh} will read incoming mail.
3151 @vindex nnmh-be-safe
3152 If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
3153 sure that the articles in the folder are actually what Gnus thinks they
3154 are. It will check date stamps and stat everything in sight, so
3155 setting this to @code{t} will mean a serious slow-down. If you never
3156 use anything but Gnus to read the @code{nnmh} articles, you do not have
3157 to set this variable to @code{t}.
3161 @subsubsection nnfolder
3162 @cindex @code{nnfolder}
3163 @cindex mbox folders
3165 @code{nnfolder} is a backend for storing each mail group in a separate
3166 file. Each file is in the standard Un*x mbox format. @code{nnfolder}
3167 will add extra headers to keep track of article numbers and arrival
3170 Virtual server settings:
3173 @item nnfolder-directory
3174 @vindex nnfolder-directory
3175 All the @code{nnfolder} mail boxes will be stored under this directory.
3177 @item nnfolder-active-file
3178 @vindex nnfolder-active-file
3179 The name of the active file.
3181 @item nnfolder-newsgroups-file
3182 @vindex nnfolder-newsgroups-file
3183 The name of the group descriptions file. @xref{Newsgroups File Format}.
3185 @item nnfolder-get-new-mail
3186 @vindex nnfolder-get-new-mail
3187 If non-@code{nil}, @code{nnfolder} will read incoming mail.
3191 @node Group Parameters
3192 @section Group Parameters
3193 @cindex group parameters
3195 Gnus stores all information on a group in a list that is usually known
3196 as the @dfn{group info}. This list has from three to six elements.
3197 Here's an example info.
3200 ("nnml:mail.ding" 3 ((1 . 232) 244 (256 . 270)) ((tick 246 249))
3201 (nnml "private") ((to-address . "ding@@ifi.uio.no")))
3204 The first element is the @dfn{group name}, as Gnus knows the group,
3205 anyway. The second element is the @dfn{subscription level}, which
3206 normally is a small integer. The third element is a list of ranges of
3207 read articles. The fourth element is a list of lists of article marks
3208 of various kinds. The fifth element is the select method (or virtual
3209 server, if you like). The sixth element is a list of @dfn{group
3210 parameters}, which is what this section is about.
3212 Any of the last three elements may be missing if they are not required.
3213 In fact, the vast majority of groups will normally only have the first
3214 three elements, which saves quite a lot of cons cells.
3216 The group parameters store information local to a particular group:
3221 If the group parameter list contains an element that looks like
3222 @samp{(to-address . "some@@where.com")}, that address will be used by
3223 the backend when doing followups and posts. This is primarily useful in
3224 mail groups that represent close mailing lists. You just set this
3225 address to whatever the list address is.
3227 This trick will actually work whether the group is foreign or not.
3228 Let's say there's a group on the server that is called @samp{fa.4ad-l}.
3229 This is a real newsgroup, but the server has gotten the articles from a
3230 mail-to-news gateway. Posting directly to this group is therefore
3231 impossible---you have to send mail to the mailing list address instead.
3232 Also @xref{Mail & Post}.
3236 If the group parameter list has an element that looks like
3237 @samp{(to-list . "some@@where.com")}, that address will be used when
3238 doing a @kbd{a} in any group. It is totally ignored when doing a
3239 followup---except that if it is present in a news group, you'll get mail
3240 group semantics when doing @kbd{f}.
3244 If the group parameter list contains an element like @code{(to-group
3245 . "some.group.name")}, all posts will be sent to that group.
3249 If this symbol is present in the group parameter list, all articles that
3250 are read will be marked as expirable. For an alternative approach,
3251 @xref{Expiring Old Mail Articles}.
3254 @cindex total-expire
3255 If this symbol is present, all read articles will be put through the
3256 expiry process, even if they are not marked as expirable. Use with
3261 If the group parameter has an element that looks like @samp{(expiry-wait
3262 . 10)}, this value will override any @code{nnmail-expiry-wait} and
3263 @code{nnmail-expiry-wait-functions} when expiring expirable messages.
3264 The value can either be a number of days (not necessarily an integer) or
3265 the symbols @code{never} or @code{immediate}.
3268 Elements that look like @samp{(score-file . "file")} will make
3269 @samp{file} into the current score file for the group in question. This
3270 means that all score commands you issue will end up in that file.
3273 When unsubscribing to a mailing list you should never send the
3274 unsubscription notice to the mailing list itself. Instead, you'd send
3275 messages to the administrative address. This parameter allows you to
3276 put the admin address somewhere convenient.
3279 This parameter allows you to enter a random comment on the group.
3281 @item @var{(variable form)}
3282 You can use the group parameters to set variables local to the group you
3283 are entering. Say you want to turn threading off in
3284 @samp{news.answers}. You'd then put @code{(gnus-show-threads nil)} in
3285 the group parameters of that group. @code{gnus-show-threads} will be
3286 made into a local variable in the summary buffer you enter, and the form
3287 @code{nil} will be @code{eval}ed there.
3289 This can also be used as a group-specific hook function, if you'd like.
3290 If you want to hear a beep when you enter the group
3291 @samp{alt.binaries.pictures.furniture}, you could put something like
3292 @code{(dummy-variable (ding))} in the parameters of that group.
3293 @code{dummy-variable} will be set to the result of the @code{(ding)}
3294 form, but who cares?
3298 If you want to change the group info you can use the @kbd{G E} command
3299 to enter a buffer where you can edit it.
3301 You usually don't want to edit the entire group info, so you'd be better
3302 off using the @kbd{G p} command to just edit the group parameters.
3304 @node Listing Groups
3305 @section Listing Groups
3306 @cindex group listing
3308 These commands all list various slices of the groups that are available.
3316 @findex gnus-group-list-groups
3317 List all groups that have unread articles
3318 (@code{gnus-group-list-groups}). If the numeric prefix is used, this
3319 command will list only groups of level ARG and lower. By default, it
3320 only lists groups of level five or lower (i.e., just subscribed groups).
3326 @findex gnus-group-list-all-groups
3327 List all groups, whether they have unread articles or not
3328 (@code{gnus-group-list-all-groups}). If the numeric prefix is used,
3329 this command will list only groups of level ARG and lower. By default,
3330 it lists groups of level seven or lower (i.e., just subscribed and
3331 unsubscribed groups).
3335 @findex gnus-group-list-level
3336 List all unread groups on a specific level
3337 (@code{gnus-group-list-level}). If given a prefix, also list the groups
3338 with no unread articles.
3342 @findex gnus-group-list-killed
3343 List all killed groups (@code{gnus-group-list-killed}). If given a
3344 prefix argument, really list all groups that are available, but aren't
3345 currently (un)subscribed. This could entail reading the active file
3350 @findex gnus-group-list-zombies
3351 List all zombie groups (@code{gnus-group-list-zombies}).
3355 @findex gnus-group-list-matching
3356 List all subscribed groups with unread articles that match a regexp
3357 (@code{gnus-group-list-matching}).
3361 @findex gnus-group-list-all-matching
3362 List groups that match a regexp (@code{gnus-group-list-all-matching}).
3366 @findex gnus-group-list-active
3367 List absolutely all groups that are in the active file(s) of the
3368 server(s) you are connected to (@code{gnus-group-list-active}). This
3369 might very well take quite a while. It might actually be a better idea
3370 to do a @kbd{A m} to list all matching, and just give @samp{.} as the
3375 @vindex gnus-permanently-visible-groups
3376 @cindex visible group paramenter
3377 Groups that match the @code{gnus-permanently-visible-groups} regexp will
3378 always be shown, whether they have unread articles or not. You can also
3379 add the @code{visible} element to the group parameters in question to
3380 get the same effect.
3382 @node Sorting Groups
3383 @section Sorting Groups
3384 @cindex sorting groups
3386 @kindex C-c C-s (Group)
3387 @findex gnus-group-sort-groups
3388 @vindex gnus-group-sort-function
3389 The @kbd{C-c C-s} (@code{gnus-group-srot-groups}) command sorts the
3390 group buffer according to the function(s) given by the
3391 @code{gnus-group-sort-function} variable. Available sorting functions
3396 @item gnus-group-sort-by-alphabet
3397 @findex gnus-group-sort-by-alphabet
3398 Sort the group names alphabetically. This is the default.
3400 @item gnus-group-sort-by-level
3401 @findex gnus-group-sort-by-level
3402 Sort by group level.
3404 @item gnus-group-sort-by-score
3405 @findex gnus-group-sort-by-score
3406 Sort by group score.
3408 @item gnus-group-sort-by-rank
3409 @findex gnus-group-sort-by-rank
3410 Sort by group score and then the group level. The level and the score
3411 are, when taken together, the group's @dfn{rank}.
3413 @item gnus-group-sort-by-unread
3414 @findex gnus-group-sort-by-unread
3415 Sort by number of unread articles.
3417 @item gnus-group-sort-by-method
3418 @findex gnus-group-sort-by-method
3419 Sort by alphabetically on the select method.
3424 @code{gnus-group-sort-function} can also be a list of sorting
3425 functions. In that case, the most significant sort key function must be
3429 There are also a number of commands for sorting directly according to
3430 some sorting criteria:
3434 @kindex G S a (Group)
3435 @findex gnus-group-sort-groups-by-alphabet
3436 Sort the group buffer alphabetically by group name
3437 (@code{gnus-group-sort-groups-by-alphabet}).
3440 @kindex G S u (Group)
3441 @findex gnus-group-sort-groups-by-unread
3442 Sort the group buffer by the number of unread articles
3443 (@code{gnus-group-sort-groups-by-unread}).
3446 @kindex G S l (Group)
3447 @findex gnus-group-sort-groups-by-level
3448 Sort the group buffer by group level
3449 (@code{gnus-group-sort-groups-by-level}).
3452 @kindex G S v (Group)
3453 @findex gnus-group-sort-groups-by-score
3454 Sort the group buffer by group score
3455 (@code{gnus-group-sort-groups-by-score}).
3458 @kindex G S r (Group)
3459 @findex gnus-group-sort-groups-by-rank
3460 Sort the group buffer by group level
3461 (@code{gnus-group-sort-groups-by-rank}).
3464 @kindex G S m (Group)
3465 @findex gnus-group-sort-groups-by-method
3466 Sort the group buffer alphabetically by backend name
3467 (@code{gnus-group-sort-groups-by-method}).
3471 When given a prefix, all these commands will sort in reverse order.
3475 @node Group Maintenance
3476 @section Group Maintenance
3477 @cindex bogus groups
3482 @findex gnus-group-check-bogus-groups
3483 Find bogus groups and delete them
3484 (@code{gnus-group-check-bogus-groups}).
3488 @findex gnus-find-new-newsgroups
3489 Find new groups and process them (@code{gnus-find-new-newsgroups}).
3492 @kindex C-c C-x (Group)
3493 @findex gnus-group-expire-articles
3494 Run all expirable articles in the current group through the expiry
3495 process (if any) (@code{gnus-group-expire-articles}).
3498 @kindex C-c M-C-x (Group)
3499 @findex gnus-group-expire-all-groups
3500 Run all articles in all groups through the expiry process
3501 (@code{gnus-group-expire-all-groups}).
3506 @node Browse Foreign Server
3507 @section Browse Foreign Server
3508 @cindex foreign servers
3509 @cindex browsing servers
3514 @findex gnus-group-browse-foreign-server
3515 You will be queried for a select method and a server name. Gnus will
3516 then attempt to contact this server and let you browse the groups there
3517 (@code{gnus-group-browse-foreign-server}).
3520 @findex gnus-browse-server-mode
3521 A new buffer with a list of available groups will appear. This buffer
3522 will be use the @code{gnus-browse-server-mode}. This buffer looks a bit
3523 (well, a lot) like a normal group buffer, but with one major difference
3524 - you can't enter any of the groups. If you want to read any of the
3525 news available on that server, you have to subscribe to the groups you
3526 think may be interesting, and then you have to exit this buffer. The
3527 new groups will be added to the group buffer, and then you can read them
3528 as you would any other group.
3530 Future versions of Gnus may possibly permit reading groups straight from
3533 Here's a list of keystrokes available in the browse mode:
3538 @findex gnus-group-next-group
3539 Go to the next group (@code{gnus-group-next-group}).
3543 @findex gnus-group-prev-group
3544 Go to the previous group (@code{gnus-group-prev-group}).
3547 @kindex SPACE (Browse)
3548 @findex gnus-browse-read-group
3549 Enter the current group and display the first article
3550 (@code{gnus-browse-read-group}).
3553 @kindex RET (Browse)
3554 @findex gnus-browse-select-group
3555 Enter the current group (@code{gnus-browse-select-group}).
3559 @findex gnus-browse-unsubscribe-current-group
3560 Unsubscribe to the current group, or, as will be the case here,
3561 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
3567 @findex gnus-browse-exit
3568 Exit browse mode (@code{gnus-browse-exit}).
3572 @findex gnus-browse-describe-briefly
3573 Describe browse mode briefly (well, there's not much to describe, is
3574 there) (@code{gnus-browse-describe-briefly}).
3578 @section Exiting Gnus
3579 @cindex exiting Gnus
3581 Yes, Gnus is ex(c)iting.
3586 @findex gnus-group-suspend
3587 Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
3588 but it kills all buffers except the Group buffer. I'm not sure why this
3589 is a gain, but then who am I to judge?
3593 @findex gnus-group-exit
3594 Quit Gnus (@code{gnus-group-exit}).
3598 @findex gnus-group-quit
3599 Quit Gnus without saving any startup files (@code{gnus-group-quit}).
3602 @vindex gnus-exit-gnus-hook
3603 @vindex gnus-suspend-gnus-hook
3604 @code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
3605 @code{gnus-exit-gnus-hook} is called when you quit Gnus.
3609 If you wish to completely unload Gnus and all its adherents, you can use
3610 the @code{gnus-unload} command. This command is also very handy when
3611 trying to custoize meta-variables.
3616 Miss Lisa Cannifax, while sitting in English class, feels her feet go
3617 numbly heavy and herself fall into a hazy trance as the boy sitting
3618 behind her drew repeated lines with his pencil across the back of her
3624 @section Group Topics
3627 If you read lots and lots of groups, it might be convenient to group
3628 them hierarchically according to topics. You put your Emacs groups over
3629 here, your sex groups over there, and the rest (what, two groups or so?)
3630 you put in some misc section that you never bother with anyway. You can
3631 even group the Emacs sex groups as a sub-topic to either the Emacs
3632 groups or the sex groups---or both! Go wild!
3634 @findex gnus-topic-mode
3636 To get this @emph{fab} functionality you simply turn on (ooh!) the
3637 @code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This
3638 is a toggling command.)
3640 Go ahead, just try it. I'll still be here when you get back. La de
3641 dum... Nice tune, that... la la la... What, you're back? Yes, and now
3642 press @kbd{l}. There. All your groups are now listed under
3643 @samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
3646 If you want this permanently enabled, you should add that minor mode to
3647 the hook for the group mode:
3650 (add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
3654 * Topic Variables:: How to customize the topics the Lisp Way.
3655 * Topic Commands:: Interactive E-Z commands.
3656 * Topic Topology:: A map of the world.
3660 @node Topic Variables
3661 @subsection Topic Variables
3662 @cindex topic variables
3665 @vindex gnus-group-topic-topics-only
3666 Whoo, this is complicated. If @code{gnus-group-topic-topics-only} is
3667 @code{nil}, all groups and topics will be listed, as you would expect.
3668 If this variable is non-@code{nil}, only the topics will be listed, and
3669 the groups will not be listed. This makes the group buffer much shorter,
3670 I'm sure you'll agree. This is all modified on a topic-by-topic basis
3671 by the @var{show} parameter. It makes perfect sense, really.
3673 @vindex gnus-topic-unique
3674 If @code{gnus-topic-unique} is non-@code{nil}, each group will be member
3675 of (tops) one topic each. If this is @code{nil}, each group might end
3676 up being a member of several topics.
3678 Now, if you select a topic, if will fold/unfold that topic, which is
3679 really neat, I think.
3681 @vindex gnus-topic-line-format
3682 The topic lines themselves are created according to the
3683 @code{gnus-topic-line-format} variable. @xref{Formatting Variables}.
3684 Elements allowed are:
3696 Number of groups in the topic.
3698 Number of unread articles in the topic.
3702 @node Topic Commands
3703 @subsection Topic Commands
3704 @cindex topic commands
3706 When the topic minor mode is turned on, a new @kbd{T} submap will be
3707 available. In addition, a few of the standard keys change their
3708 definitions slightly.
3714 @findex gnus-topic-create-topic
3715 Create a new topic (@code{gnus-topic-create-subtopic}). You will be
3716 prompted for a topic name and the name of the parent topic.
3720 @findex gnus-topic-move-group
3721 Move the current group to some other topic
3722 (@code{gnus-topic-move-group}). This command understands the
3723 process/prefix convention (@pxref{Process/Prefix}).
3727 @findex gnus-topic-copy-group
3728 Copy the current group to some other topic
3729 (@code{gnus-topic-copy-group}). This command understands the
3730 process/prefix convention (@pxref{Process/Prefix}).
3734 @findex gnus-topic-move-matching
3735 Move all groups that match some regular expression to a topic
3736 (@code{gnus-topic-move-matching}).
3740 @findex gnus-topic-copy-matching
3741 Copy all groups that match some regular expression to a topic
3742 (@code{gnus-topic-copy-matching}).
3746 @findex gnus-topic-select-group
3748 Either select a group or fold a topic (@code{gnus-topic-select-group}).
3749 When you perform this command on a group, you'll enter the group, as
3750 usual. When done on a topic line, the topic will be folded (if it was
3751 visible) or unfolded (if it was folded already). So it's basically a
3752 toggling command on topics. In addition, if you give a numerical
3753 prefix, group on that level (and lower) will be displayed.
3757 @findex gnus-topic-kill-group
3758 Kill a group or topic (@code{gnus-topic-kill-group}).
3762 @findex gnus-topic-yank-group
3763 Yank the previosuly killed group or topic (@code{gnus-topic-yank-group}).
3764 Note that all topics will be yanked before all groups.
3768 @findex gnus-topic-rename
3769 Rename a topic (@code{gnus-topic-rename}).
3772 @kindex T DEL (Group)
3773 @findex gnus-topic-delete
3774 Delete an empty topic (@code{gnus-topic-delete}).
3779 @node Topic Topology
3780 @subsection Topic Topology
3781 @cindex topic topology
3784 So, let's have a look at an example group buffer:
3790 2: alt.religion.emacs
3793 0: comp.talk.emacs.recovery
3795 8: comp.binaries.fractals
3796 13: comp.sources.unix
3799 So, here we have one top-level topic, two topics under that, and one
3800 sub-topic under one of the sub-topics. (There is always just one (1)
3801 top-level topic). This topology can be expressed as follows:
3805 (("Emacs -- I wuw it!" visible)
3806 (("Naughty Emacs" visible)))
3810 This is in fact how the variable @code{gnus-topic-topology} would look
3811 for the display above. That variable is saved in the @file{.newsrc.eld}
3812 file, and shouldn't be messed with manually---unless you really want
3813 to. Since this variable is read from the @file{.newsrc.eld} file,
3814 setting it in any other startup files will have no effect.
3816 This topology shows what topics are sub-topics of what topics (right),
3817 and which topics are visible. Two settings are currently
3818 allowed---@code{visible} and @code{invisible}.
3820 @vindex gnus-topic-hide-subtopics
3821 If @code{gnus-topic-hide-subtopics} is non-@code{nil} (which it is by
3822 default), sub-topics will be folded along with any groups that belong to
3823 the topic. If this variable is @code{nil}, all topics will always be
3824 visible, even though the parent topics are folded.
3827 @node Misc Group Stuff
3828 @section Misc Group Stuff
3834 @findex gnus-group-get-new-news
3835 Check the server(s) for new articles. If the numerical prefix is used,
3836 this command will check only groups of level @var{arg} and lower
3837 (@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
3838 command will force a total rereading of the active file(s) from the
3843 @findex gnus-group-get-new-news-this-group
3844 Check whether new articles have arrived in the current group
3845 (@code{gnus-group-get-new-news-this-group}).
3847 @findex gnus-activate-all-groups
3849 @kindex C-c M-g (Group)
3850 Activate absolutely all groups (@code{gnus-activate-all-groups}).
3854 @findex gnus-group-enter-server-mode
3855 Enter the server buffer (@code{gnus-group-enter-server-mode}). @xref{The
3860 @findex gnus-group-fetch-faq
3861 Try to fetch the FAQ for the current group
3862 (@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
3863 @code{gnus-group-faq-directory}, which is usually a directory on a
3864 remote machine. @code{ange-ftp} will be used for fetching the file.
3868 @findex gnus-group-restart
3869 Restart Gnus (@code{gnus-group-restart}).
3873 @findex gnus-group-read-init-file
3874 @vindex gnus-init-file
3875 Read the init file (@code{gnus-init-file}, which defaults to
3876 @file{~/.gnus}) (@code{gnus-group-read-init-file}).
3880 @findex gnus-group-save-newsrc
3881 Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
3882 (@code{gnus-group-save-newsrc}). If given a prefix, force saving the
3883 file(s) whether Gnus thinks it is necessary or not.
3887 @findex gnus-group-clear-dribble
3888 Clear the dribble buffer (@code{gnus-group-clear-dribble}).
3892 @findex gnus-group-describe-group
3893 Describe the current group (@code{gnus-group-describe-group}). If given
3894 a prefix, force Gnus to re-read the description from the server.
3898 @findex gnus-group-apropos
3899 List all groups that have names that match a regexp
3900 (@code{gnus-group-apropos}).
3904 @findex gnus-group-description-apropos
3905 List all groups that have names or descriptions that match a regexp
3906 (@code{gnus-group-description-apropos}).
3910 @findex gnus-group-post-news
3911 Post an article to a group (@code{gnus-group-post-news}). The current
3912 group name will be used as the default.
3916 @findex gnus-group-mail
3917 Mail a message somewhere (@code{gnus-group-mail}).
3920 @kindex C-x C-t (Group)
3921 @findex gnus-group-transpose-groups
3922 Transpose two groups (@code{gnus-group-transpose-groups}).
3926 @findex gnus-version
3927 Display current Gnus version numbers (@code{gnus-version}).
3931 @findex gnus-group-describe-all-groups
3932 Describe all groups (@code{gnus-group-describe-all-groups}). If given a
3933 prefix, force Gnus to re-read the description file from the server.
3937 @findex gnus-group-describe-briefly
3938 Give a very short help message (@code{gnus-group-describe-briefly}).
3941 @kindex C-c C-i (Group)
3942 @findex gnus-info-find-node
3943 Go to the Gnus info node (@code{gnus-info-find-node}).
3946 @vindex gnus-group-prepare-hook
3947 @code{gnus-group-prepare-hook} is called after the group buffer is
3948 generated. It may be used to modify the buffer in some strange,
3951 @node The Summary Buffer
3952 @chapter The Summary Buffer
3953 @cindex summary buffer
3955 A line for each article is displayed in the summary buffer. You can
3956 move around, read articles, post articles and reply to articles.
3959 * Summary Buffer Format:: Deciding how the summary buffer is to look.
3960 * Summary Maneuvering:: Moving around the summary buffer.
3961 * Choosing Articles:: Reading articles.
3962 * Paging the Article:: Scrolling the current article.
3963 * Reply Followup and Post:: Posting articles.
3964 * Canceling and Superseding:: "Whoops, I shouldn't have called him that."
3965 * Marking Articles:: Marking articles as read, expirable, etc.
3966 * Limiting:: You can limit the summary buffer.
3967 * Threading:: How threads are made.
3968 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
3969 * Article Caching:: You may store articles in a cache.
3970 * Persistent Articles:: Making articles expiry-resistant.
3971 * Article Backlog:: Having already read articles hang around.
3972 * Exiting the Summary Buffer:: Returning to the Group buffer.
3973 * Process/Prefix:: A convention used by many treatment commands.
3974 * Saving Articles:: Ways of customizing article saving.
3975 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
3976 * Article Treatment:: The article buffer can be mangled at will.
3977 * Summary Sorting:: You can sort the summary buffer four ways.
3978 * Finding the Parent:: No child support? Get the parent.
3979 * Mail Group Commands:: Some commands can only be used in mail groups.
3980 * Various Summary Stuff:: What didn't fit anywhere else.
3984 @node Summary Buffer Format
3985 @section Summary Buffer Format
3986 @cindex summary buffer format
3989 * Summary Buffer Lines:: You can specify how summary lines should look.
3990 * Summary Buffer Mode Line:: You can say how the mode line should look.
3993 @findex mail-extract-address-components
3994 @findex gnus-extract-address-components
3995 @vindex gnus-extract-address-components
3996 Gnus will use the value of the @code{gnus-extract-address-components}
3997 variable as a function for getting the name and address parts of a
3998 @code{From} header. Two pre-defined function exist:
3999 @code{gnus-extract-address-components}, which is the default, quite
4000 fast, and too simplistic solution; and
4001 @code{mail-extract-address-components}, which works very nicely, but is
4004 @vindex gnus-summary-same-subject
4005 @code{gnus-summary-same-subject} is a string indicating that the current
4006 article has the same subject as the previous. This string will be used
4007 with those specs that require it. The default is @samp{""}.
4009 @node Summary Buffer Lines
4010 @subsection Summary Buffer Lines
4012 @vindex gnus-summary-line-format
4013 You can change the format of the lines in the summary buffer by changing
4014 the @code{gnus-summary-line-format} variable. It works along the same
4015 lines a a normal @code{format} string, with some extensions.
4017 The default string is @samp{"%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n"}.
4019 The following format specification characters are understood:
4027 Subject if the article is the root, @code{gnus-summary-same-subject}
4030 Full @code{From} line.
4032 The name (from the @code{From} header).
4034 The name (from the @code{From} header). This differs from the @code{n}
4035 spec in that it uses @code{gnus-extract-address-components}, which is
4036 slower, but may be more thorough.
4038 The address (from the @code{From} header). This works the same way as
4041 Number of lines in the article.
4043 Number of characters in the article.
4045 Indentation based on thread level (@pxref{Customizing Threading}).
4047 Nothing if the article is a root and lots of spaces if it isn't (it
4048 pushes everything after it off the screen).
4050 Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
4051 for adopted articles.
4053 Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
4054 for adopted articles.
4056 One space for each thread level.
4058 Twenty minus thread level spaces.
4066 @vindex gnus-summary-zcore-fuzz
4067 Zcore, @samp{+} if above the default level and @samp{-} if below the
4068 default level. If the difference between
4069 @code{gnus-summary-default-level} and the score is less than
4070 @code{gnus-summary-zcore-fuzz}, this spec will not be used.
4080 Number of articles in the current sub-thread. Using this spec will slow
4081 down summary buffer generation somewhat.
4083 A single character will be displayed if the article has any children.
4085 User defined specifier. The next character in the format string should
4086 be a letter. @sc{gnus} will call the function
4087 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
4088 following @samp{%u}. The function will be passed the current header as
4089 argument. The function should return a string, which will be inserted
4090 into the summary just like information from any other summary specifier.
4093 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
4094 have to be handled with care. For reasons of efficiency, Gnus will
4095 compute what column these characters will end up in, and "hard-code"
4096 that. This means that it is illegal to have these specs after a
4097 variable-length spec. Well, you might not be arrested, but your summary
4098 buffer will look strange, which is bad enough.
4100 The smart choice is to have these specs as far to the left as possible.
4101 (Isn't that the case with everything, though? But I digress.)
4103 This restriction may disappear in later versions of Gnus.
4105 @node Summary Buffer Mode Line
4106 @subsection Summary Buffer Mode Line
4108 @vindex gnus-summary-mode-line-format
4109 You can also change the format of the summary mode bar. Set
4110 @code{gnus-summary-mode-line-format} to whatever you like. Here are the
4111 elements you can play with:
4117 Unprefixed group name.
4119 Current article number.
4123 Number of unread articles in this group.
4125 Number of unselected articles in this group.
4127 A string with the number of unread and unselected articles represented
4128 either as @samp{<%U(+%u) more>} if there are both unread and unselected
4129 articles, and just as @samp{<%U more>} if there are just unread articles
4130 and no unselected ones.
4132 Shortish group name. For instance, @samp{rec.arts.anime} will be
4133 shortened to @samp{r.a.anime}.
4135 Subject of the current article.
4139 Name of the current score file.
4141 Number of dormant articles.
4143 Number of ticked articles.
4145 Number of articles that have been marked as read in this session.
4147 Number of articles expunged by the score files.
4151 @node Summary Maneuvering
4152 @section Summary Maneuvering
4153 @cindex summary movement
4155 All the straight movement commands understand the numeric prefix and
4156 behave pretty much as you'd expect.
4158 None of these commands select articles.
4163 @kindex M-n (Summary)
4164 @kindex G M-n (Summary)
4165 @findex gnus-summary-next-unread-subject
4166 Go to the next summary line of an unread article
4167 (@code{gnus-summary-next-unread-subject}).
4171 @kindex M-p (Summary)
4172 @kindex G M-p (Summary)
4173 @findex gnus-summary-prev-unread-subject
4174 Go to the previous summary line of an unread article
4175 (@code{gnus-summary-prev-unread-subject}).
4180 @kindex G g (Summary)
4181 @findex gnus-summary-goto-subject
4182 Ask for an article number and then go to this summary line
4183 (@code{gnus-summary-goto-subject}).
4186 @vindex gnus-auto-select-next
4187 If you are at the end of the group and issue one of the movement
4188 commands, Gnus will offer to go to the next group. If
4189 @code{gnus-auto-select-next} is @code{t} and the next group is empty,
4190 Gnus will exit summary mode and return to the group buffer. If this
4191 variable is neither @code{t} nor @code{nil}, Gnus will select the next
4192 group, no matter whether it has any unread articles or not. As a
4193 special case, if this variable is @code{quietly}, Gnus will select the
4194 next group without asking for confirmation. If this variable is
4195 @code{almost-quietly}, the same will happen only if you are located on
4196 the last article in the group. Also @xref{Group Levels}.
4198 If Gnus asks you to press a key to confirm going to the next group, you
4199 can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
4200 buffer, searching for the next group to read without actually returning
4201 to the group buffer.
4203 @vindex gnus-auto-select-same
4204 If @code{gnus-auto-select-same} is non-@code{nil}, all the movement
4205 commands will try to go to the next article with the same subject as the
4206 current. This variable is not particularly useful if you use a threaded
4209 @vindex gnus-summary-check-current
4210 If @code{gnus-summary-check-current} is non-@code{nil}, all the "unread"
4211 movement commands will not proceed to the next (or previous) article if
4212 the current article is unread. Instead, they will choose the current
4215 @vindex gnus-auto-center-summary
4216 If @code{gnus-auto-center-summary} is non-@code{nil}, Gnus will keep the
4217 point in the summary buffer centered at all times. This makes things
4218 quite tidy, but if you have a slow network connection, or simply do not
4219 like this un-Emacsism, you can set this variable to @code{nil} to get
4220 the normal Emacs scrolling action.
4222 @node Choosing Articles
4223 @section Choosing Articles
4224 @cindex selecting articles
4226 None of the following movement commands understand the numeric prefix,
4227 and they all select and display an article.
4231 @kindex SPACE (Summary)
4232 @findex gnus-summary-next-page
4233 Select the current article, or, if that one's read already, the next
4234 unread article (@code{gnus-summary-next-page}).
4239 @kindex G n (Summary)
4240 @findex gnus-summary-next-unread-article
4241 Go to next unread article (@code{gnus-summary-next-unread-article}).
4246 @findex gnus-summary-prev-unread-article
4247 Go to previous unread article (@code{gnus-summary-prev-unread-article}).
4252 @kindex G N (Summary)
4253 @findex gnus-summary-next-article
4254 Go to the next article (@code{gnus-summary-next-article}).
4259 @kindex G P (Summary)
4260 @findex gnus-summary-prev-article
4261 Go to the previous article (@code{gnus-summary-prev-article}).
4264 @kindex G C-n (Summary)
4265 @findex gnus-summary-next-same-subject
4266 Go to the next article with the same subject
4267 (@code{gnus-summary-next-same-subject}).
4270 @kindex G C-p (Summary)
4271 @findex gnus-summary-prev-same-subject
4272 Go to the previous article with the same subject
4273 (@code{gnus-summary-prev-same-subject}).
4277 @kindex G f (Summary)
4279 @findex gnus-summary-first-unread-article
4280 Go to the first unread article
4281 (@code{gnus-summary-first-unread-article}).
4285 @kindex G b (Summary)
4287 Go to the article with the highest score
4288 (@code{gnus-summary-best-unread-article}).
4293 @kindex G l (Summary)
4294 @findex gnus-summary-goto-last-article
4295 Go to the previous article read (@code{gnus-summary-goto-last-article}).
4298 @kindex G p (Summary)
4299 @findex gnus-summary-pop-article
4300 Pop an article off the summary history and go to this article
4301 (@code{gnus-summary-pop-article}). This command differs from the
4302 command above in that you can pop as many previous articles off the
4303 history as you like.
4306 Some variables that are relevant for moving and selecting articles:
4309 @item gnus-auto-extend-newsgroup
4310 @vindex gnus-auto-extend-newsgroup
4311 All the movement commands will try to go to the previous (or next)
4312 article, even if that article isn't displayed in the Summary buffer if
4313 this variable is non-@code{nil}. Gnus will then fetch the article from
4314 the server and display it in the article buffer.
4316 @item gnus-select-article-hook
4317 @vindex gnus-select-article-hook
4318 This hook is called whenever an article is selected. By default it
4319 exposes any threads hidden under the selected article.
4321 @item gnus-mark-article-hook
4322 @vindex gnus-mark-article-hook
4323 This hook is called whenever an article is selected. It is intended to
4324 be used for marking articles as read.
4326 @item gnus-visual-mark-article-hook
4327 @vindex gnus-visual-mark-article-hook
4328 This hook is run after selecting an article. It is meant to be used for
4329 highlighting the article in some way. It is not run if
4330 @code{gnus-visual} is @code{nil}.
4332 @item gnus-summary-update-hook
4333 @vindex gnus-summary-update-hook
4334 This hook is called when a summary line is changed. It is not run if
4335 @code{gnus-visual} is @code{nil}.
4337 @item gnus-summary-selected-face
4338 @vindex gnus-summary-selected-face
4339 This is the face (or @dfn{font} as some people call it) that is used to
4340 highlight the current article in the summary buffer.
4342 @item gnus-summary-highlight
4343 @vindex gnus-summary-highlight
4344 Summary lines are highlighted according to this variable, which is a
4345 list where the elements are on the format @code{(FORM . FACE)}. If you
4346 would, for instance, like ticked articles to be italic and high-scored
4347 articles to be bold, you could set this variable to something like
4349 (((eq mark gnus-ticked-mark) . italic)
4350 ((> score default) . bold))
4352 As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
4353 @var{FACE} will be applied to the line.
4356 @node Paging the Article
4357 @section Scrolling the Article
4358 @cindex article scrolling
4363 @kindex SPACE (Summary)
4364 @findex gnus-summary-next-page
4365 Pressing @kbd{SPACE} will scroll the current article forward one page,
4366 or, if you have come to the end of the current article, will choose the
4367 next article (@code{gnus-summary-next-page}).
4370 @kindex DEL (Summary)
4371 @findex gnus-summary-prev-page
4372 Scroll the current article back one page (@code{gnus-summary-prev-page}).
4375 @kindex RET (Summary)
4376 @findex gnus-summary-scroll-up
4377 Scroll the current article one line forward
4378 (@code{gnus-summary-scroll-up}).
4383 @kindex A < (Summary)
4384 @findex gnus-summary-beginning-of-article
4385 Scroll to the beginning of the article
4386 (@code{gnus-summary-beginning-of-article}).
4391 @kindex A > (Summary)
4392 @findex gnus-summary-end-of-article
4393 Scroll to the end of the article (@code{gnus-summary-end-of-article}).
4396 @kindex A s (Summary)
4397 @findex gnus-summary-isearch-article
4398 Perform an isearch in the article buffer
4399 (@code{gnus-summary-isearch-article}).
4403 @node Reply Followup and Post
4404 @section Reply, Followup and Post
4409 @kindex C-c C-c (Post)
4410 All the commands for posting and mailing will put you in a post or mail
4411 buffer where you can edit the article all you like, before you send the
4412 article by pressing @kbd{C-c C-c}. If you are in a foreign news group,
4413 and you wish to post the article using the foreign server, you can give
4414 a prefix to @kbd{C-c C-c} to make Gnus try to post using the foreign
4418 * Mail:: Mailing & replying.
4419 * Post:: Posting and following up.
4420 * Posting Server:: What server should you post via?
4421 * Mail & Post:: Mailing and posting at the same time.
4422 * Posting Styles:: An easier way to configure some key elements.
4423 * Drafts:: Postponing messages and rejected messages.
4424 * Rejected Articles:: What happens if the server doesn't like your article?
4430 Commands for composing a mail message:
4436 @kindex S r (Summary)
4438 @findex gnus-summary-reply
4439 Mail a reply to the author of the current article
4440 (@code{gnus-summary-reply}).
4445 @kindex S R (Summary)
4446 @findex gnus-summary-reply-with-original
4447 Mail a reply to the author of the current article and include the
4448 original message (@code{gnus-summary-reply-with-original}). This
4449 command uses the process/prefix convention.
4452 @kindex S o m (Summary)
4453 @findex gnus-summary-mail-forward
4454 Forward the current article to some other person
4455 (@code{gnus-summary-mail-forward}).
4458 @kindex S o p (Summary)
4459 @findex gnus-summary-post-forward
4460 Forward the current article to a newsgroup
4461 (@code{gnus-summary-post-forward}).
4466 @kindex S m (Summary)
4467 @findex gnus-summary-mail-other-window
4468 Send a mail to some other person
4469 (@code{gnus-summary-mail-other-window}).
4472 @kindex S D b (Summary)
4473 @findex gnus-summary-resend-bounced-mail
4474 If you have sent a mail, but the mail was bounced back to you for some
4475 reason (wrong address, transient failure), you can use this command to
4476 resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
4477 will be popped into a mail buffer where you can edit the headers before
4478 sending the mail off again. The headers that match the regexp
4479 @code{gnus-bounced-headers-junk} (default @samp{^Received:}) are
4480 automatically deleted first. If you give a prefix to this command, and
4481 the bounced mail is a reply to some other mail, Gnus will try to fetch
4482 that mail and display it for easy perusal of its headers. This might
4483 very well fail, though.
4486 @kindex S D r (Summary)
4487 @findex gnus-summary-resend-message
4488 Not to be confused with the previous command,
4489 @code{gnus-summary-resend-message} will prompt you for an address to
4490 send the current message off to, and then send it to that place. The
4491 headers of the message won't be altered---but lots of headers that say
4492 @samp{Resent-To}, @samp{Resent-From} and so on will be added. This
4493 means that you actually send a mail to someone that has a @samp{To}
4494 header that (proabbly) points to yourself. This will confuse people.
4495 So, natcherly you'll only do that if you're really eVIl.
4497 This command is mainly used if you have several accounts and want to
4498 ship a mail to a different account of yours. (If you're both
4499 @samp{root} and @samp{postmaster} and get a mail for @samp{postmaster}
4500 to the @samp{root} account, you may want to resend it to
4501 @samp{postmaster}. Ordnung muss sein!
4504 @kindex S O m (Summary)
4505 @findex gnus-uu-digest-mail-forward
4506 Digest the current series and forward the result using mail
4507 (@code{gnus-uu-digest-mail-forward}). This command uses the
4508 process/prefix convention (@pxref{Process/Prefix}).
4511 @kindex S O p (Summary)
4512 @findex gnus-uu-digest-post-forward
4513 Digest the current series and forward the result to a newsgroup
4514 (@code{gnus-uu-digest-mail-forward}).
4517 Variables for customizing outgoing mail:
4520 @item gnus-reply-to-function
4521 @vindex gnus-reply-to-function
4522 Gnus uses the normal methods to determine where replies are to go, but
4523 you can change the behavior to suit your needs by fiddling with this
4526 If you want the replies to go to the @samp{Sender} instead of the
4527 @samp{From} in the group @samp{mail.stupid-list}, you could do something
4531 (setq gnus-reply-to-function
4533 (cond ((string= group "mail.stupid-list")
4534 (mail-fetch-field "sender"))
4539 This function will be called narrowed to the head of the article that is
4542 As you can see, this function should return a string if it has an
4543 opinion as to what the To header should be. If it does not, it should
4544 just return @code{nil}, and the normal methods for determining the To
4545 header will be used.
4547 This function can also return a list. In that case, each list element
4548 should be a cons, where the car should be the name of an header
4549 (eg. @samp{Cc}) and the cdr should be the header value
4550 (eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into
4551 the head of the outgoing mail.
4553 @item gnus-mail-send-method
4554 @vindex gnus-mail-send-method
4555 This variable says how a mail should be mailed. It uses the function in
4556 the @code{send-mail-function} variable as the default.
4558 @item gnus-uu-digest-headers
4559 @vindex gnus-uu-digest-headers
4560 List of regexps to match headers included in digested messages. The
4561 headers will be included in the sequence they are matched.
4563 @item gnus-mail-hook
4564 @vindex gnus-mail-hook
4565 Hook called as the last thing after setting up a mail buffer.
4567 @item gnus-required-mail-headers
4568 @vindex gnus-required-mail-headers
4569 Gnus will generate headers in all outgoing mail instead of letting
4570 @code{sendmail} do it for us. This makes it possible to do more neat
4571 stuff, like putting mail without sending it, do hairy @code{Fcc}
4572 handling, and much more. This variable controls what headers Gnus will
4573 generate, and is of the exact same form as @code{gnus-required-headers},
4574 which does the same for news articles (@pxref{Post}).
4576 The @code{Newsgroups} header is illegal in this list, while @code{To} is
4577 required, and @code{X-Mailer} can be added if you so should want.
4579 @findex gnus-forward-start-separator
4580 @item gnus-forward-start-separator
4581 Delimiter inserted before forwarded messages.
4583 @findex gnus-forward-end-separator
4584 @item gnus-forward-end-separator
4585 Delimiter inserted after forwarded messages.
4587 @findex gnus-signature-before-forwarded-message
4588 @item gnus-signature-before-forwarded-message
4589 If this variable is @code{t}, which it is by default, your personal
4590 signature will be inserted before the forwarded message. If not, the
4591 forwarded message will be inserted first in the new mail.
4595 @kindex C-c C-c (Mail)
4596 @kindex C-c C-p (Mail)
4597 @findex gnus-put-message
4598 You normally send a mail message by pressing @kbd{C-c C-c}. However,
4599 you may wish to just put the mail message you have just written in your
4600 own local mail group instead of sending it. Sounds quite unlikely, but
4601 I found that useful, so you can now also press @kbd{C-c C-p} to
4602 @dfn{put} the article in the current mail group, or, if there is no such
4603 thing, you will be prompted for a mail group, and then the article will
4604 be put there. This means that the article is @dfn{not} mailed.
4606 There are three "methods" for handling all mail. The default is
4607 @code{sendmail}. Some people like what @code{mh} does better, and some
4608 people prefer @code{vm}.
4610 Three variables for customizing what to use when:
4614 @vindex gnus-mail-reply-method
4615 @item gnus-mail-reply-method
4616 This function is used to compose replies. The three functions avaibale
4619 @findex gnus-mail-reply-using-vm
4620 @findex gnus-mail-reply-using-mhe
4621 @findex gnus-mail-reply-using-mail
4624 @code{gnus-mail-reply-using-mail} (sendmail)
4626 @code{gnus-mail-reply-using-mhe} (mh)
4628 @code{gnus-mail-reply-using-vm} (vm)
4631 @vindex gnus-mail-forward-method
4632 @item gnus-mail-forward-method
4633 This function is used to forward messages. The three functions avaibale
4636 @findex gnus-mail-forward-using-vm
4637 @findex gnus-mail-forward-using-mhe
4638 @findex gnus-mail-forward-using-mail
4641 @code{gnus-mail-forward-using-mail} (sendmail)
4643 @code{gnus-mail-forward-using-mhe} (mh)
4645 @code{gnus-mail-forward-using-vm} (vm)
4648 @vindex gnus-mail-other-window-method
4649 @item gnus-mail-other-window-method
4650 This function is used to send mails. The three functions avaibale are:
4652 @findex gnus-mail-other-window-using-vm
4653 @findex gnus-mail-other-window-using-mhe
4654 @findex gnus-mail-other-window-using-mail
4657 @code{gnus-mail-other-window-using-mail} (sendmail)
4659 @code{gnus-mail-other-window-using-mhe} (mh)
4661 @code{gnus-mail-other-window-using-vm} (vm)
4670 Commands for posting an article:
4676 @kindex S p (Summary)
4677 @findex gnus-summary-post-news
4678 Post an article to the current group
4679 (@code{gnus-summary-post-news}).
4684 @kindex S f (Summary)
4685 @findex gnus-summary-followup
4686 Post a followup to the current article (@code{gnus-summary-followup}).
4690 @kindex S F (Summary)
4692 @findex gnus-summary-followup-with-original
4693 Post a followup to the current article and include the original message
4694 (@code{gnus-summary-followup-with-original}). This command uses the
4695 process/prefix convention.
4698 @kindex S u (Summary)
4699 @findex gnus-uu-post-news
4700 Uuencode a file, split it into parts, and post it as a series
4701 (@code{gnus-uu-post-news}).
4702 @c (@pxref{Uuencoding & Posting}).
4705 @vindex gnus-required-headers
4706 @code{gnus-required-headers} a list of header symbols. These headers
4707 will either be automatically generated, or, if that's impossible, they
4708 will be prompted for. The following symbols are legal:
4713 This required header will be filled out with the result of the
4714 @code{gnus-inews-user-name} function, which depends on the
4715 @code{gnus-user-from-line}, @code{gnus-user-login-name},
4716 @code{gnus-local-domain} and @code{user-mail-address} variables.
4719 This required header will be prompted for if not present already.
4722 This required header says which newsgroups the article is to be posted
4723 to. If it isn't present already, it will be prompted for.
4726 @cindex organization
4727 @vindex gnus-local-organization
4728 @vindex gnus-organization-file
4729 This optional header will be filled out depending on the
4730 @code{gnus-local-organization} variable. @code{gnus-organization-file}
4731 will be used if that variable is nil.
4734 This optional header will be computed by Gnus.
4738 This required header will be generated by Gnus. A unique ID will be
4739 created based on date, time, user name and system name.
4742 @cindex X-Newsreader
4743 This optional header will be filled out with the Gnus version numbers.
4746 @vindex gnus-article-expires
4748 This extremely optional header will be inserted according to the
4749 @code{gnus-article-expires} variable. It is highly deprecated and
4750 shouldn't be used unless you know what you're doing.
4753 This optional header is filled out according to the
4754 @code{gnus-distribution-function} variable. It is a deprecated and much
4755 misunderstood header.
4758 In addition, you can enter conses into this list. The car of this cons
4759 should be a symbol. This symbol's name is the name of the header, and
4760 the cdr can either be a string to be entered verbatim as the value of
4761 this header, or it can be a function to be called. This function should
4762 return a string to be inserted. For instance, if you want to insert
4763 @samp{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
4764 into the list. If you want to insert a funny quote, you could enter
4765 something like @code{(X-Yow . yow)} into the list. The function
4766 @code{yow} will then be called without any arguments.
4768 The list contains a cons where the car of the cons is @code{optional},
4769 the cdr of this cons will only be inserted if it is non-@code{nil}.
4771 Other variables for customizing outgoing articles:
4774 @item nntp-news-default-headers
4775 @vindex nntp-news-default-headers
4776 If non-@code{nil}, this variable will override
4777 @code{mail-default-headers} when posting. This variable should then be
4778 a string. This string will be inserted, as is, in the head of all
4781 @item gnus-use-followup-to
4782 @vindex gnus-use-followup-to
4783 If @code{nil}, always ignore the Followup-To header. If it is @code{t},
4784 use its value, but ignore the special value @samp{poster}, which will
4785 send the followup as a reply mail to the person you are responding to.
4786 If it is the symbol @code{ask}, query the user before posting.
4787 If it is the symbol @code{use}, always use the value.
4789 @item gnus-followup-to-function
4790 @vindex gnus-followup-to-function
4791 This variable is most useful in mail groups, where "following up" really
4792 means sending a mail to a list address. Gnus uses the normal methods to
4793 determine where follow-ups are to go, but you can change the behavior
4794 to suit your needs by fiddling with this variable.
4796 If you want the followups to go to the @samp{Sender} instead of the
4797 @samp{From} in the group @samp{mail.stupid-list}, you could do something
4801 (setq gnus-followup-to-function
4803 (cond ((string= group "mail.stupid-list")
4804 (mail-fetch-field "sender"))
4809 This function will be called narrowed to header of the article that is
4812 @item gnus-removable-headers
4813 @vindex gnus-removable-headers
4814 Some headers that are generated are toxic to the @sc{nntp} server.
4815 These include the @code{NNTP-Posting-Host}, @code{Bcc} and @code{Xref},
4816 so these headers are deleted if they are present in this list of
4819 @item gnus-deletable-headers
4820 @vindex gnus-deletable-headers
4821 Headers in this list that were previously generated by Gnus will be
4822 deleted before posting. Let's say you post an article. Then you decide
4823 to post it again to some other group, you naughty boy, so you jump back
4824 to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
4825 ship it off again. By default, this variable makes sure that the old
4826 generated @code{Message-ID} is deleted, and a new one generated. If
4827 this isn't done, the entire empire would probably crumble, anarchy would
4828 prevail, and cats would start walking on two legs and rule the world.
4831 @item gnus-signature-function
4832 @vindex gnus-signature-function
4833 If non-@code{nil}, this variable should be a function that returns a
4834 signature file name. The function will be called with the name of the
4835 group being posted to. If the function returns a string that doesn't
4836 correspond to a file, the string itself is inserted. If the function
4837 returns @code{nil}, the @code{gnus-signature-file} variable will be used
4840 @item gnus-post-prepare-function
4841 @vindex gnus-post-prepare-function
4842 This function is called with the name of the current group after the
4843 post buffer has been initialized, and can be used for inserting a
4844 signature. Nice if you use different signatures in different groups.
4846 @item gnus-post-prepare-hook
4847 @vindex gnus-post-prepare-hook
4848 This hook is called after a post buffer has been prepared. If you want
4849 to insert a signature at this point, you could put
4850 @code{gnus-inews-insert-signature} into this hook.
4852 @item news-reply-header-hook
4853 @vindex news-reply-header-hook
4854 A related variable when following up and replying is this variable,
4855 which inserts the @dfn{quote line}. The default value is:
4858 (defvar news-reply-header-hook
4860 (insert "In article " news-reply-yank-message-id
4861 " " news-reply-yank-from " writes:\n\n")))
4864 This will create lines like:
4867 In article <zngay8jrql@@eyesore.no> Lars Mars <lars@@eyesore.no> writes:
4870 Having the @code{Message-ID} in this line is probably overkill, so I
4871 would suggest this hook instead:
4874 (setq news-reply-header-hook
4875 (lambda () (insert news-reply-yank-from " writes:\n\n")))
4878 @item gnus-prepare-article-hook
4879 @vindex gnus-prepare-article-hook
4880 This hook is called before the headers have been prepared.
4882 @item gnus-inews-article-function
4883 @vindex gnus-inews-article-function
4884 This function is used to do the actual article processing and header
4885 checking/generation.
4887 @item gnus-inews-article-hook
4888 @vindex gnus-inews-article-hook
4889 This hook is called right before the article is posted. By default it
4890 handles FCC processing (i.e., saving the article to a file.) You can
4891 also have this hook add a score to all followups to the article you've
4892 written (@pxref{Followups To Yourself}).
4894 @item gnus-inews-article-header-hook
4895 @vindex gnus-inews-article-header-hook
4896 This hook is called after inserting the required headers in an article
4897 to be posted. The hook is called from the @code{*post-news*} buffer,
4898 narrowed to the head, and is intended for people who would like to
4899 insert additional headers, or just change headers in some way or other.
4901 @item gnus-check-before-posting
4902 @vindex gnus-check-before-posting
4903 If non-@code{nil}, Gnus will attempt to check the legality of the
4904 headers, as well as some other stuff, before posting. You can control
4905 the granularity of the check by adding or removing elements from this
4906 list. Legal elemetents are:
4910 Check the subject for commands.
4912 Insert a new @code{Sender} header if the @code{From} header looks odd.
4913 @item multiple-headers
4914 Check for the existence of multiple equal headers.
4916 Check for the existence of version and sendsys commands.
4918 Check whether the @code{Message-ID} looks ok.
4920 Check whether the @code{From} header seems nice.
4922 Check for too long lines.
4924 Check for illegal characters.
4926 Check for excessive size.
4928 Check whether there is any new text in the messages.
4930 Check the length of the signature.
4932 Check whether the article has an @code{Approved} header, which is
4933 something only moderators should include.
4939 @node Posting Server
4940 @subsection Posting Server
4942 When you press those magical @kbd{C-c C-c} keys to ship off your latest
4943 (extremely intelligent, of course) article, where does it go?
4945 Thank you for asking. I hate you.
4947 @vindex gnus-post-method
4949 It can be quite complicated. Normally, Gnus will use the same native
4950 server. However. If your native server doesn't allow posting, just
4951 reading, you probably want to use some other server to post your
4952 (extremely intelligent and fabulously interesting) articles. You can
4953 then set the @code{gnus-post-method} to some other method:
4956 (setq gnus-post-method '(nnspool ""))
4959 Now, if you've done this, and then this server rejects your article, or
4960 this server is down, what do you do then? To override this variable you
4961 can use a prefix to the @kbd{C-c C-c} command to force using the
4962 "current" server for posting.
4966 @subsection Mail & Post
4968 Commands for sending mail and post at the same time:
4972 @kindex S b (Summary)
4973 @findex gnus-summary-followup-and-reply
4974 Post a followup and send a reply to the current article
4975 (@code{gnus-summary-followup-and-reply}).
4978 @kindex S B (Summary)
4979 @findex gnus-summary-followup-and-reply-with-original
4980 Post a followup and send a reply to the current article and include the
4981 original message (@code{gnus-summary-followup-and-reply-with-original}).
4982 This command uses the process/prefix convention.
4985 Here's a list of variables that are relevant to both mailing and
4989 @item gnus-signature-file
4990 @itemx mail-signature
4991 @vindex mail-signature
4992 @vindex gnus-signature-file
4993 @cindex double signature
4995 If @code{gnus-signature-file} is non-@code{nil}, it should be the name
4996 of a file containing a signature (@samp{~/.signature} by default). This
4997 signature will be appended to all outgoing post. Most people find it
4998 more convenient to use @code{mail-signature}, which (sort of) does the
4999 same, but inserts the signature into the buffer before you start editing
5000 the post (or mail). So---if you have both of these variables set, you
5001 will get two signatures. Note that @code{mail-signature} does not work
5002 the same way as @code{gnus-signature-file}, which is a bit confusing.
5003 If @code{mail-signature} is @code{t}, it will insert
5004 @file{~/.signature}. If it is a string, this string will be inserted.
5006 Note that RFC1036 says that a signature should be preceded by the three
5007 characters @samp{-- } on a line by themselves. This is to make it
5008 easier for the recipient to automatically recognize and process the
5009 signature. So don't remove those characters, even though you might feel
5010 that they ruin you beautiful design, like, totally.
5012 Also note that no signature should be more than four lines long.
5013 Including ASCII graphics is an efficient way to get everybody to believe
5014 that you are silly and have nothing important to say.
5016 @item mail-yank-prefix
5017 @vindex mail-yank-prefix
5020 When you are replying to or following up an article, you normally want
5021 to quote the person you are answering. Inserting quoted text is done by
5022 @dfn{yanking}, and each quoted line you yank will have
5023 @code{mail-yank-prefix} prepended to it. This is @samp{ } by default,
5024 which isn't very pretty. Most everybody prefers that lines are
5025 prepended with @samp{> }, so @code{(setq mail-yank-prefix "> ")} in your
5028 @item mail-yank-ignored-headers
5029 @vindex mail-yank-ignored-headers
5030 When you yank a message, you do not want to quote any headers, so
5031 @code{(setq mail-yank-ignored-headers "^")}.
5033 @item user-mail-address
5034 @vindex user-mail-address
5035 If all of @code{gnus-user-login-name}, @code{gnus-use-generic-from} and
5036 @code{gnus-local-domain} are @code{nil}, Gnus will use
5037 @code{user-mail-address} as the address part of the @code{From} header.
5039 @item gnus-local-domain
5040 @vindex gnus-local-domain
5042 The local doman name excluding the host name. If your host is called
5043 @samp{"narfi.ifi.uio.no"}, then this variable should be
5044 @samp{"ifi.uio.no"}.
5046 @item gnus-local-domain
5047 @vindex gnus-local-domain
5049 The local doman name excluding the host name. If your host is called
5050 @samp{"narfi.ifi.uio.no"}, then this variable should be
5051 @samp{"ifi.uio.no"}.
5053 @item gnus-user-from-line
5054 @vindex gnus-user-from-line
5055 Your full, complete e-mail address with name. This variable overrides
5056 the other Gnus variables if it is non-@code{nil}.
5058 Here are two example values of this variable: @samp{"larsi@@ifi.uio.no
5059 (Lars Magne Ingebrigtsen)"} and @samp{"Lars Magne Ingebrigtsen
5060 <larsi@@ifi.uio.no>"}. The latter version is recommended in news (and is
5061 probably illegal in mail), but the name has to be quoted if it contains
5062 non-alpha-numerical characters---@samp{"\"Lars M. Ingebrigtsen\"
5063 <larsi@@ifi.uio.no>"}.
5065 @item mail-default-headers
5066 @vindex mail-default-headers
5067 This is a string that will be inserted into the header of all outgoing
5068 mail messages and news articles. Convenient to use to insert standard
5069 headers. If @code{nntp-news-default-headers} is non-@code{nil}, that
5070 variable will override this one when posting articles.
5072 @item gnus-auto-mail-to-author
5073 @vindex gnus-auto-mail-to-author
5074 If @code{ask}, you will be prompted for whether you want to send a mail
5075 copy to the author of the article you are following up. If
5076 non-@code{nil} and not @code{ask}, Gnus will send a mail with a copy of
5077 all follow-ups to the authors of the articles you follow up. It's nice
5078 in one way---you make sure that the person you are responding to gets
5079 your response. Other people loathe this method and will hate you dearly
5080 for it, because it means that they will first get a mail, and then have
5081 to read the same article later when they read the news. It is
5082 @code{nil} by default.
5084 @item gnus-mail-courtesy-message
5085 @vindex gnus-mail-courtesy-message
5086 This is a string that will be prepended to all mails that are the result
5087 of using the variable described above.
5089 @item gnus-outgoing-message-group
5090 @vindex gnus-outgoing-message-group
5091 All outgoing messages will be put in this group. If you want to store
5092 all your outgoing mail and articles in the group @samp{nnml:archive},
5093 you set this variable to that value. This variable can also be a list of
5096 If you want to have greater control over what group to put each
5097 message in, you can set this variable to a function that checks the
5098 current newsgroup name and then returns a suitable group name (or list
5101 @item gnus-mailing-list-groups
5102 @findex gnus-mailing-list-groups
5103 @cindex mailing lists
5105 If your newsserver offer groups that are really mailing lists that are
5106 gatewayed to the @sc{nntp} server, you can read those groups without
5107 problems, but you can't post/followup to them without some difficulty.
5108 One solution is to add a @code{to-address} to the group parameters
5109 (@pxref{Group Parameters}). An easier thing to do is set the
5110 @code{gnus-mailing-list-groups} to a regexp that match the groups that
5111 really are mailing lists. Then, at least, followups to the mailing
5112 lists will work most of the time. Posting to these groups (@kbd{a}) is
5113 still a pain, though.
5118 You may want to do spell-checking on messages that you send out. Or, if
5119 you don't want to spell-check by hand, you could add automatic
5120 spell-checking via the @code{ispell} package:
5122 @vindex news-inews-hook
5124 (add-hook 'news-inews-hook 'ispell-message) ;For news posts
5125 (add-hook 'mail-send-hook 'ispell-message) ;for mail posts via sendmail
5128 @findex gnus-inews-insert-mime-headers
5129 If you want to insert some @sc{mime} headers into the articles you post,
5130 without doing any actual encoding, you could add
5131 @code{gnus-inews-insert-mime-headers} to @code{gnus-inews-article-hook}.
5134 @node Posting Styles
5135 @subsection Posting Styles
5136 @cindex posting styles
5139 All them variables, they make my head swim.
5141 So what if you want a different @code{Organization} and signature based
5142 on what groups you post to? And you post both from your home machine
5143 and your work machine, and you want different @code{From} lines, and so
5146 @vindex gnus-posting-styles
5147 One way to do stuff like that is to write clever hooks that change the
5148 variables you need to have changed. That's a bit boring, so somebody
5149 came up with the bright idea of letting the user specify these things in
5150 a handy alist. Here's an example of a @code{gnus-posting-styles}
5154 ((".*" (signature . "Peace and happiness") (organization . "What me?"))
5155 ("^comp" (signature . "Death to everybody"))
5156 ("comp.emacs.i-love-it" (organization . "Emacs is it")))
5159 As you might surmise from this example, this alist consists of several
5160 @dfn{styles}. Each style will be applicable if the first element
5161 "matches", in some form or other. The entire alist will be iterated
5162 over, from the beginning towards the end, and each match will be
5163 applied, which means that attributes in later styles that match override
5164 the same attributes in earlier matching styles. So
5165 @samp{comp.programming.literate} will have the @samp{Death to everybody}
5166 signature and the @samp{What me?} @code{Organization} header.
5168 The first element in each style is called the @code{match}. If it's a
5169 string, then Gnus will try to regexp match it against the group name.
5170 If it's a function symbol, that function will be called with no
5171 arguments. If it's a variable symbol, then the variable will be
5172 referenced. If it's a list, then that list will be @code{eval}ed. In
5173 any case, if this returns a non-@code{nil} value, then the style is said
5176 Each style may contain a random amount of @dfn{attributes}. Each
5177 attribute consists of a @var{(name . value)} pair. The attribute name
5178 can be one of @code{signature}, @code{organization} or @code{from}.
5179 The attribute name can also be a string. In that case, this will be
5180 used as a header name, and the value will be inserted in the headers of
5183 The attribute value can be a string (used verbatim), a function (the
5184 return value will be used), a variable (its value will be used) or a
5185 list (it will be @code{eval}ed and the return value will be used).
5187 So here's a new example:
5190 (setq gnus-posting-styles
5192 (signature . "~/.signature")
5193 (from . "user@@foo (user)")
5194 ("X-Home-Page" . (getenv "WWW_HOME"))
5195 (organization . "People's Front Against MWM"))
5197 (signature . my-funny-signature-randomizer))
5198 ((equal (system-name) "gnarly")
5199 (signature . my-quote-randomizer))
5200 (posting-from-work-p
5201 (signature . "~/.work-signature")
5202 (from . "user@@bar.foo (user)")
5203 (organization . "Important Work, Inc"))
5205 (signature . "~/.mail-signature"))))
5214 If you are writing a message (mail or news) and suddenly remember that
5215 you have a steak in the oven (or some pesto in the food processor, you
5216 craazy vegetarians), you'll probably wish there was a method to save the
5217 message you are writing so that you can continue editing it some other
5218 day, and send it when you feel its finished.
5220 Well, don't worry about it. Whenever you start composing a message of
5221 some sort using the Gnus mail and post commands, the buffer you get will
5222 automatically associate to an article in a special @dfn{draft} group.
5223 If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the
5224 article will be saved there. (Auto-save files also go to the draft
5227 The draft group is a special draft group (which is implemented as an
5228 @code{nndraft} group, if you absolutely have to know) called
5229 @samp{nndraft:drafts}. The variable @code{gnus-draft-group-directory}
5230 controls both the name of the group and the location---the leaf element
5231 in the path will be used as the name of the group. What makes this
5232 group special is that you can't tick any articles in it or mark any
5233 articles as read---all articles in the group are permanently unread.
5235 If the group doesn't exist, it will be created and you'll be subscribed
5238 @findex gnus-summary-send-draft
5239 @kindex S D c (Summary)
5240 When you want to continue editing the article, you simply enter the
5241 draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
5242 that. You will be placed in a buffer where you left off.
5244 Rejected articles will also be put in this draft group (@pxref{Rejected
5247 @findex gnus-summary-send-all-drafts
5248 If you have lots of rejected messages you want to post (or mail) without
5249 doing further editing, you can use the @kbd{S D a} command
5250 (@code{gnus-summary-send-all-drafts}). This command understands the
5251 process/prefix convention (@pxref{Process/Prefix}).
5254 @node Rejected Articles
5255 @subsection Rejected Articles
5256 @cindex rejected articles
5258 Sometimes a news server will reject an article. Perhaps the server
5259 doesn't like your face. Perhaps it just feels miserable. Perhaps
5260 @emph{there be demons}. Perhaps you have included too much cited text.
5261 Perhaps the disk is full. Perhaps the server is down.
5263 These situations are, of course, totally beyond the control of Gnus.
5264 (Gnus, of course, loves the way you look, always feels great, has angels
5265 fluttering around inside of it, doesn't care about how much cited text
5266 you include, never runs full and never goes down.) So Gnus saves these
5267 articles until some later time when the server feels better.
5269 The rejected articles will automatically be put in a special draft group
5270 (@pxref{Drafts}). When the server comes back up again, you'd then
5271 typically enter that group and send all the articles off.
5274 @node Canceling and Superseding
5275 @section Canceling Articles
5276 @cindex canceling articles
5277 @cindex superseding articles
5279 Have you ever written something, and then decided that you really,
5280 really, really wish you hadn't posted that?
5282 Well, you can't cancel mail, but you can cancel posts.
5284 @findex gnus-summary-cancel-article
5286 Find the article you wish to cancel (you can only cancel your own
5287 articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
5288 c} (@code{gnus-summary-cancel-article}). Your article will be
5289 canceled---machines all over the world will be deleting your article.
5291 Be aware, however, that not all sites honor cancels, so your article may
5292 live on here and there, while most sites will delete the article in
5295 If you discover that you have made some mistakes and want to do some
5296 corrections, you can post a @dfn{superseding} article that will replace
5297 your original article.
5299 @findex gnus-summary-supersede-article
5301 Go to the original article and press @kbd{S s}
5302 (@code{gnus-summary-supersede-article}). You will be put in a buffer
5303 where you can edit the article all you want before sending it off the
5306 @vindex gnus-delete-supersedes-headers
5307 You probably want to delete some of the old headers before sending the
5308 superseding article---@code{Path} and @code{Date} are probably
5309 incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
5310 match the lines you want removed. The default is
5311 @samp{"^Path:\\|^Date"}.
5313 The same goes for superseding as for canceling, only more so: Some
5314 sites do not honor superseding. On those sites, it will appear that you
5315 have posted almost the same article twice.
5317 If you have just posted the article, and change your mind right away,
5318 there is a trick you can use to cancel/supersede the article without
5319 waiting for the article to appear on your site first. You simply return
5320 to the post buffer (which is called @code{*post-buf*}). There you will
5321 find the article you just posted, with all the headers intact. Change
5322 the @samp{Message-ID} header to a @samp{Cancel} or @samp{Supersedes}
5323 header by substituting one of those words for @samp{Message-ID}. Then
5324 just press @kbd{C-c C-c} to send the article as you would do normally.
5325 The previous article will be canceled/superseded.
5327 Just remember, kids: There is no 'c' in 'supersede'.
5329 @node Marking Articles
5330 @section Marking Articles
5331 @cindex article marking
5332 @cindex article ticking
5335 There are several marks you can set on an article.
5337 You have marks that decide the @dfn{readed-ness} (whoo, neato-keano
5338 neologism ohoy!) of the article. Alphabetic marks generally mean
5339 @dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
5341 In addition, you also have marks that do not affect readedness.
5344 * Unread Articles:: Marks for unread articles.
5345 * Read Articles:: Marks for read articles.
5346 * Other Marks:: Marks that do not affect readedness.
5350 There's a plethora of commands for manipulating these marks:
5354 * Setting Marks:: How to set and remove marks.
5355 * Setting Process Marks:: How to mark articles for later processing.
5358 @node Unread Articles
5359 @subsection Unread Articles
5361 The following marks mark articles as unread, in one form or other.
5363 @vindex gnus-dormant-mark
5364 @vindex gnus-ticked-mark
5367 @dfn{Ticked articles} are articles that will remain visible always. If
5368 you see an article that you find interesting, or you want to put off
5369 reading it, or replying to it, until sometime later, you'd typically
5370 tick it. However, articles can be expired, so if you want to keep an
5371 article forever, you'll have to save it. Ticked articles have a
5372 @samp{!} (@code{gnus-ticked-mark}) in the first column.
5375 A @dfn{dormant} article is marked with a @samp{?}
5376 (@code{gnus-dormant-mark}), and will only appear in the summary buffer
5377 if there are followups to it.
5380 An @dfn{unread} article is marked with a @samp{SPC}
5381 (@code{gnus-unread-mark}). These are articles that haven't been read at
5386 @subsection Read Articles
5387 @cindex expirable mark
5389 All the following marks mark articles as read.
5394 Articles that are marked as read. They have a @samp{r}
5395 (@code{gnus-del-mark}) in the first column. These are articles that the
5396 user has marked as read more or less manually.
5399 Articles that are actually read are marked with @samp{R}
5400 (@code{gnus-read-mark}).
5403 Articles that were marked as read in previous sessions are now
5404 @dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
5407 Marked as killed (@code{gnus-killed-mark}).
5410 Marked as killed by kill files (@code{gnus-kill-file-mark}).
5413 Marked as read by having a too low score (@code{gnus-low-score-mark}).
5416 Marked as read by a catchup (@code{gnus-catchup-mark}).
5419 Canceled article (@code{gnus-cancelled-mark})
5422 All these marks just mean that the article is marked as read, really.
5423 They are interpreted differently by the adaptive scoring scheme,
5426 One more special mark, though:
5430 You can also mark articles as @dfn{expirable} (or have them marked as
5431 such automatically). That doesn't make much sense in normal groups,
5432 because a user does not control the expiring of news articles, but in
5433 mail groups, for instance, articles that are marked as @dfn{expirable}
5434 can be deleted by Gnus at any time. Expirable articles are marked with
5435 @samp{E} (@code{gnus-expirable-mark}).
5439 @subsection Other Marks
5440 @cindex process mark
5443 There are some marks that have nothing to do with whether the article is
5449 You can set a bookmark in the current article. Say you are reading a
5450 long thesis on cats' urinary tracts, and have to go home for dinner
5451 before you've finished reading the thesis. You can then set a bookmark
5452 in the article, and Gnus will jump to this bookmark the next time it
5453 encounters the article.
5456 All articles that you have replied to or made a followup to (i.e., have
5457 answered) will be marked with an @samp{A} in the second column
5458 (@code{gnus-replied-mark}).
5461 Articles that are stored in the article cache will be marked with an
5462 @samp{*} in the second column (@code{gnus-cached-mark}).
5465 Articles that are "saved" (in some manner or other; not necessarily
5466 religously) are marked with an @samp{S} in the second column
5467 (@code{gnus-saved-mark}.
5470 @vindex gnus-not-empty-thread-mark
5471 @vindex gnus-empty-thread-mark
5472 It the @samp{%e} spec is used, the presence of threads or not will be
5473 marked with @code{gnus-not-empty-thread-mark} and
5474 @code{gnus-empty-thread-mark} in the third column, respectively.
5477 @vindex gnus-process-mark
5478 Finally we have the @dfn{process mark} (@code{gnus-process-mark}. A
5479 variety of commands react to the presence of the process mark. For
5480 instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
5481 all articles that have been marked with the process mark. Articles
5482 marked with the process mark have a @samp{#} in the second column.
5486 You might have noticed that most of these "non-readedness" marks appear
5487 in the second column by default. So if you have a cached, saved,
5488 replied article that you have process-marked, what will that look like?
5490 Nothing much. The presedence rules go as follows: process -> cache ->
5491 replied -> saved. So if the article is in the cache and is replied,
5492 you'll only see the cache mark and not the replied mark.
5496 @subsection Setting Marks
5497 @cindex setting marks
5499 All the marking commands understand the numeric prefix.
5505 @kindex M t (Summary)
5506 @findex gnus-summary-tick-article-forward
5507 Tick the current article (@code{gnus-summary-tick-article-forward}).
5512 @kindex M ? (Summary)
5513 @findex gnus-summary-mark-as-dormant
5514 Mark the current article as dormant
5515 (@code{gnus-summary-mark-as-dormant}).
5519 @kindex M d (Summary)
5521 @findex gnus-summary-mark-as-read-forward
5522 Mark the current article as read
5523 (@code{gnus-summary-mark-as-read-forward}).
5528 @kindex M k (Summary)
5529 @findex gnus-summary-kill-same-subject-and-select
5530 Mark all articles that have the same subject as the current one as read,
5531 and then select the next unread article
5532 (@code{gnus-summary-kill-same-subject-and-select}).
5536 @kindex M K (Summary)
5537 @kindex C-k (Summary)
5538 @findex gnus-summary-kill-same-subject
5539 Mark all articles that have the same subject as the current one as read
5540 (@code{gnus-summary-kill-same-subject}).
5543 @kindex M C (Summary)
5544 @findex gnus-summary-catchup
5545 Mark all unread articles in the group as read
5546 (@code{gnus-summary-catchup}).
5549 @kindex M C-c (Summary)
5550 @findex gnus-summary-catchup-all
5551 Mark all articles in the group as read---even the ticked and dormant
5552 articles (@code{gnus-summary-catchup-all}).
5555 @kindex M H (Summary)
5556 @findex gnus-summary-catchup-to-here
5557 Catchup the current group to point
5558 (@code{gnus-summary-catchup-to-here}).
5561 @kindex C-w (Summary)
5562 @findex gnus-summary-mark-region-as-read
5563 Mark all articles between point and mark as read
5564 (@code{gnus-summary-mark-region-as-read}).
5567 @kindex M V k (Summary)
5568 @findex gnus-summary-kill-below
5569 Kill all articles with scores below the default score (or below the
5570 numeric prefix) (@code{gnus-summary-kill-below}).
5574 @kindex M c (Summary)
5575 @kindex M-u (Summary)
5576 @findex gnus-summary-clear-mark-forward
5577 Clear all readedness-marks from the current article
5578 (@code{gnus-summary-clear-mark-forward}).
5582 @kindex M e (Summary)
5584 @findex gnus-summary-mark-as-expirable
5585 Mark the current article as expirable
5586 (@code{gnus-summary-mark-as-expirable}).
5589 @kindex M b (Summary)
5590 @findex gnus-summary-set-bookmark
5591 Set a bookmark in the current article
5592 (@code{gnus-summary-set-bookmark}).
5595 @kindex M B (Summary)
5596 @findex gnus-summary-remove-bookmark
5597 Remove the bookmark from the current article
5598 (@code{gnus-summary-remove-bookmark}).
5601 @kindex M V c (Summary)
5602 @findex gnus-summary-clear-above
5603 Clear all marks from articles with scores over the default score (or
5604 over the numeric prefix) (@code{gnus-summary-clear-above}).
5607 @kindex M V u (Summary)
5608 @findex gnus-summary-tick-above
5609 Tick all articles with scores over the default score (or over the
5610 numeric prefix) (@code{gnus-summary-tick-above}).
5613 @kindex M V m (Summary)
5614 @findex gnus-summary-mark-above
5615 Prompt for a mark, and mark all articles with scores over the default
5616 score (or over the numeric prefix) with this mark
5617 (@code{gnus-summary-clear-above}).
5620 @code{gnus-summary-goto-unread}
5621 The @code{gnus-summary-goto-unread} variable controls what action should
5622 be taken after setting a mark. If non-@code{nil}, point will move to
5623 the next/previous unread article. If @code{nil}, point will just move
5624 one line up or down. The default is @code{t}.
5627 @node Setting Process Marks
5628 @subsection Setting Process Marks
5629 @cindex setting process marks
5636 @kindex M P p (Summary)
5637 @findex gnus-summary-mark-as-processable
5638 Mark the current article with the process mark
5639 (@code{gnus-summary-mark-as-processable}).
5640 @findex gnus-summary-unmark-as-processable
5644 @kindex M P u (Summary)
5645 @kindex M-# (Summary)
5646 Remove the process mark, if any, from the current article
5647 (@code{gnus-summary-unmark-as-processable}).
5650 @kindex M P U (Summary)
5651 @findex gnus-summary-unmark-all-processable
5652 Remove the process mark from all articles
5653 (@code{gnus-summary-unmark-all-processable}).
5656 @kindex M P R (Summary)
5657 @findex gnus-uu-mark-by-regexp
5658 Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
5661 @kindex M P r (Summary)
5662 @findex gnus-uu-mark-region
5663 Mark articles in region (@code{gnus-uu-mark-region}).
5666 @kindex M P t (Summary)
5667 @findex gnus-uu-mark-thread
5668 Mark all articles in the current (sub)thread
5669 (@code{gnus-uu-mark-thread}).
5672 @kindex M P T (Summary)
5673 @findex gnus-uu-unmark-thread
5674 Unmark all articles in the current (sub)thread
5675 (@code{gnus-uu-unmark-thread}).
5678 @kindex M P s (Summary)
5679 @findex gnus-uu-mark-series
5680 Mark all articles in the current series (@code{gnus-uu-mark-series}).
5683 @kindex M P S (Summary)
5684 @findex gnus-uu-mark-sparse
5685 Mark all series that have already had some articles marked
5686 (@code{gnus-uu-mark-sparse}).
5689 @kindex M P a (Summary)
5690 @findex gnus-uu-mark-all
5691 Mark all articles in series order (@code{gnus-uu-mark-series}).
5694 @kindex M P b (Summary)
5695 @findex gnus-uu-mark-buffer
5696 Mark all articles in the buffer in the order they appear
5697 (@code{gnus-uu-mark-buffer}).
5705 It can be convenient to limit the summary buffer to just show some
5706 subset of the articles currently in the group. The effect most limit
5707 commands have is to remove a few (or many) articles from the summary
5713 @kindex / / (Summary)
5714 @findex gnus-summary-limit-to-subject
5715 Limit the summary buffer to articles that match some subject
5716 (@code{gnus-summary-limit-to-subject}).
5720 @kindex / u (Summary)
5722 @findex gnus-summary-limit-to-unread
5723 Limit the summary buffer to articles that are not marked as read
5724 (@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
5725 buffer to articles that are strictly unread. This means that ticked and
5726 dormant articles will also be excluded.
5729 @kindex / m (Summary)
5730 @findex gnus-summary-limit-to-marks
5731 Ask for a mark and then limit to all articles that have not been marked
5732 with that mark (@code{gnus-summary-limit-to-marks}).
5735 @kindex / n (Summary)
5736 @findex gnus-summary-limit-to-articles
5737 Limit the summary buffer to the current article
5738 (@code{gnus-summary-limit-to-articles}). Uses the process/prefix
5739 convention (@pxref{Process/Prefix}).
5742 @kindex / w (Summary)
5743 @findex gnus-summary-pop-limit
5744 Pop the previous limit off the stack and restore it
5745 (@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
5750 @kindex / s (Summary)
5752 @findex gnus-summary-limit-to-subject
5753 Limit the summary buffer to articles that have a subject that matches a
5754 regexp (@code{gnus-summary-limit-to-subject}).
5757 @kindex / v (Summary)
5758 @findex gnus-summary-limit-to-score
5759 Limit the summary buffer to articles that have a score at or above some
5760 score (@code{gnus-summary-limit-to-score}).
5764 @kindex M S (Summary)
5765 @kindex / E (Summary)
5766 @findex gnus-summary-limit-include-expunged
5767 Display all expunged articles
5768 (@code{gnus-summary-limit-include-expunged}).
5771 @kindex / D (Summary)
5772 @findex gnus-summary-limit-include-dormant
5773 Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
5776 @kindex / d (Summary)
5777 @findex gnus-summary-limit-exclude-dormant
5778 Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
5781 @kindex / c (Summary)
5782 @findex gnus-summary-limit-exclude-childless-dormant
5783 Hide all dormant articles that have no children
5784 (@code{gnus-summary-limit-exclude-childless-dormant}).
5792 @cindex article threading
5794 Gnus threads articles by default. @dfn{To thread} is to put replies to
5795 articles directly after the articles they reply to---in a hierarchical
5799 * Customizing Threading:: Variables you can change to affect the threading.
5800 * Thread Commands:: Thread based commands in the summary buffer.
5803 @node Customizing Threading
5804 @subsection Customizing Threading
5805 @cindex customizing threading
5811 @item gnus-show-threads
5812 @vindex gnus-show-threads
5813 If this variable is @code{nil}, no threading will be done, and all of
5814 the rest of the variables here will have no effect. Turning threading
5815 off will speed group selection up a bit, but it is sure to make reading
5816 slower and more awkward.
5818 @item gnus-fetch-old-headers
5819 @vindex gnus-fetch-old-headers
5820 If non-@code{nil}, Gnus will attempt to build old threads by fetching
5821 more old headers---headers to articles that are marked as read. If you
5822 would like to display as few summary lines as possible, but still
5823 connect as many loose threads as possible, you should set this variable
5824 to @code{some} or a number. If you set it to a number, no more than
5825 that number of extra old headers will be fetched. In either case,
5826 fetching old headers only works if the backend you are using carries
5827 overview files---this would normally be @code{nntp}, @code{nnspool} and
5828 @code{nnml}. Also remember that if the root of the thread has been
5829 expired by the server, there's not much Gnus can do about that.
5831 @item gnus-summary-gather-subject-limit
5832 Loose threads are gathered by comparing subjects of articles. If this
5833 variable is @code{nil}, Gnus requires an exact match between the
5834 subjects of the loose threads before gathering them into one big
5835 super-thread. This might be too strict a requirement, what with the
5836 presence of stupid newsreaders that chop off long subjects lines. If
5837 you think so, set this variable to, say, 20 to require that only the
5838 first 20 characters of the subjects have to match. If you set this
5839 variable to a real low number, you'll find that Gnus will gather
5840 everything in sight into one thread, which isn't very helpful.
5842 @cindex fuzzy article gathering
5843 If you set this variable to the special value @code{fuzzy}, Gnus will
5844 use a fuzzy string comparison algorithm on the subjects.
5846 @vindex gnus-summary-gather-exclude-subject
5847 Since loose thread gathering is done on subjects only, that might lead
5848 to many false hits, especially with certain common subjects like
5849 @samp{""} and @samp{"(none)"}. To make the situation slightly better,
5850 you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
5851 what subjects should be excluded from the gathering process. The
5852 default is @samp{"^ *$\\|^(none)$"}.
5854 @item gnus-summary-make-false-root
5855 @vindex gnus-summary-make-false-root
5856 If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
5857 and create a dummy root at the top. (Wait a minute. Root at the top?
5858 Yup.) Loose subtrees occur when the real root has expired, or you've
5859 read or killed the root in a previous session.
5861 When there is no real root of a thread, Gnus will have to fudge
5862 something. This variable says what fudging method Gnus should use.
5863 There are four possible values:
5865 @cindex adopting articles
5870 Gnus will make the first of the orphaned articles the parent. This
5871 parent will adopt all the other articles. The adopted articles will be
5872 marked as such by pointy brackets (@samp{<>}) instead of the standard
5873 square brackets (@samp{[]}). This is the default method.
5876 Gnus will create a dummy summary line that will pretend to be the
5877 parent. This dummy line does not correspond to any real article, so
5878 selecting it will just select the first real article after the dummy
5882 Gnus won't actually make any article the parent, but simply leave the
5883 subject field of all orphans except the first empty. (Actually, it will
5884 use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
5888 Don't make any article parent at all. Just gather the threads and
5889 display them after one another.
5892 Don't gather loose threads.
5895 @item gnus-thread-hide-subtree
5896 @vindex gnus-thread-hide-subtree
5897 If non-@code{nil}, all threads will be hidden when the summary buffer is
5900 @item gnus-thread-hide-killed
5901 @vindex gnus-thread-hide-killed
5902 if you kill a thread and this variable is non-@code{nil}, the subtree
5905 @item gnus-thread-ignore-subject
5906 @vindex gnus-thread-ignore-subject
5907 Sometimes somebody changes the subject in the middle of a thread. If
5908 this variable is non-@code{nil}, the subject change is ignored. If it
5909 is @code{nil}, which is the default, a change in the subject will result
5912 @item gnus-thread-indent-level
5913 @vindex gnus-thread-indent-level
5914 This is a number that says how much each sub-thread should be indented.
5915 The default is @samp{4}.
5918 @node Thread Commands
5919 @subsection Thread Commands
5920 @cindex thread commands
5926 @kindex T k (Summary)
5927 @kindex M-C-k (Summary)
5928 @findex gnus-summary-kill-thread
5929 Mark all articles in the current sub-thread as read
5930 (@code{gnus-summary-kill-thread}). If the prefix argument is positive,
5931 remove all marks instead. If the prefix argument is negative, tick
5936 @kindex T l (Summary)
5937 @kindex M-C-l (Summary)
5938 @findex gnus-summary-lower-thread
5939 Lower the score of the current thread
5940 (@code{gnus-summary-lower-thread}).
5943 @kindex T i (Summary)
5944 @findex gnus-summary-raise-thread
5945 Increase the score of the current thread
5946 (@code{gnus-summary-raise-thread}).
5949 @kindex T # (Summary)
5950 @findex gnus-uu-mark-thread
5951 Set the process mark on the current thread
5952 (@code{gnus-uu-mark-thread}).
5955 @kindex T M-# (Summary)
5956 @findex gnus-uu-unmark-thread
5957 Remove the process mark from the current thread
5958 (@code{gnus-uu-unmark-thread}).
5961 @kindex T T (Summary)
5962 @findex gnus-summary-toggle-threads
5963 Toggle threading (@code{gnus-summary-toggle-threads}).
5966 @kindex T s (Summary)
5967 @findex gnus-summary-show-thread
5968 Expose the thread hidden under the current article, if any
5969 (@code{gnus-summary-show-thread}).
5972 @kindex T h (Summary)
5973 @findex gnus-summary-hide-thread
5974 Hide the current (sub)thread (@code{gnus-summary-hide-thread}).
5977 @kindex T S (Summary)
5978 @findex gnus-summary-show-all-threads
5979 Expose all hidden threads (@code{gnus-summary-show-all-threads}).
5982 @kindex T H (Summary)
5983 @findex gnus-summary-hide-all-threads
5984 Hide all threads (@code{gnus-summary-hide-all-threads}).
5987 @kindex T R (Summary)
5988 @findex gnus-summary-rethread-current
5989 Re-thread the thread the current article is part of
5990 (@code{gnus-summary-rethread-current}). This works even when the
5991 summary buffer is otherwise unthreaded.
5995 The following commands are thread movement commands. They all
5996 understand the numeric prefix.
6001 @kindex T n (Summary)
6002 @findex gnus-summary-next-thread
6003 Go to the next thread (@code{gnus-summary-next-thread}).
6006 @kindex T p (Summary)
6007 @findex gnus-summary-prev-thread
6008 Go to the previous thread (@code{gnus-summary-prev-thread}).
6011 @kindex T d (Summary)
6012 @findex gnus-summary-down-thread
6013 Descend the thread (@code{gnus-summary-down-thread}).
6016 @kindex T u (Summary)
6017 @findex gnus-summary-up-thread
6018 Ascend the thread (@code{gnus-summary-up-thread}).
6021 @vindex gnus-thread-operation-ignore-subject
6022 If you ignore subject while threading, you'll naturally end up with
6023 threads that have several different subjects in them. If you then issue
6024 a command like `T k' (@code{gnus-summary-kill-thread}) you might not
6025 wish to kill the entire thread, but just those parts of the thread that
6026 have the same subject as the current article. If you like this idea,
6027 you can fiddle with @code{gnus-thread-operation-ignore-subject}. If is
6028 is non-@code{nil} (which it is by default), subjects will be ignored
6029 when doing thread commands. If this variable is @code{nil}, articles in
6030 the same thread with different subjects will not be included in the
6031 operation in question. If this variable is @code{fuzzy}, only articles
6032 that have subjects that are fuzzily equal will be included.
6035 @node Asynchronous Fetching
6036 @section Asynchronous Article Fetching
6037 @cindex asynchronous article fetching
6039 If you read your news from an @sc{nntp} server that's far away, the
6040 network latencies may make reading articles a chore. You have to wait
6041 for a while after pressing @kbd{n} to go to the next article before the
6042 article appears. Why can't Gnus just go ahead and fetch the article
6043 while you are reading the previous one? Why not, indeed.
6045 First, some caveats. There are some pitfalls to using asynchronous
6046 article fetching, especially the way Gnus does it.
6048 Let's say you are reading article 1, which is short, and article 2 is
6049 quite long, and you are not interested in reading that. Gnus does not
6050 know this, so it goes ahead and fetches article 2. You decide to read
6051 article 3, but since Gnus is in the process of fetching article 2, the
6052 connection is blocked.
6054 To avoid these situations, Gnus will open two (count 'em two)
6055 connections to the server. Some people may think this isn't a very nice
6056 thing to do, but I don't see any real alternatives. Setting up that
6057 extra connection takes some time, so Gnus startup will be slower.
6059 Gnus will fetch more articles than you will read. This will mean that
6060 the link between your machine and the @sc{nntp} server will become more
6061 loaded than if you didn't use article pre-fetch. The server itself will
6062 also become more loaded---both with the extra article requests, and the
6065 Ok, so now you know that you shouldn't really use this thing... unless
6068 @vindex gnus-asynchronous
6069 Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
6070 happen automatically.
6072 @vindex nntp-async-number
6073 You can control how many articles that are to be pre-fetched by setting
6074 @code{nntp-async-number}. This is five by default, which means that when
6075 you read an article in the group, @code{nntp} will pre-fetch the next
6076 five articles. If this variable is @code{t}, @code{nntp} will pre-fetch
6077 all the articles that it can without bound. If it is @code{nil}, no
6078 pre-fetching will be made.
6080 @vindex gnus-asynchronous-article-function
6081 You may wish to create some sort of scheme for choosing which articles
6082 that @code{nntp} should consider as candidates for pre-fetching. For
6083 instance, you may wish to pre-fetch all articles with high scores, and
6084 not pre-fetch low-scored articles. You can do that by setting the
6085 @code{gnus-asynchronous-article-function}, which will be called with an
6086 alist where the keys are the article numbers. Your function should
6087 return an alist where the articles you are not interested in have been
6088 removed. You could also do sorting on article score and the like.
6090 @node Article Caching
6091 @section Article Caching
6092 @cindex article caching
6095 If you have an @emph{extremely} slow @sc{nntp} connection, you may
6096 consider turning article caching on. Each article will then be stored
6097 locally under your home directory. As you may surmise, this could
6098 potentially use @emph{huge} amounts of disk space, as well as eat up all
6099 your inodes so fast it will make your head swim. In vodka.
6101 Used carefully, though, it could be just an easier way to save articles.
6103 @vindex gnus-use-long-file-name
6104 @vindex gnus-cache-directory
6105 @vindex gnus-use-cache
6106 To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
6107 all articles that are ticked or marked as dormant will then be copied
6108 over to your local cache (@code{gnus-cache-directory}). Whether this
6109 cache is flat or hierarchal is controlled by the
6110 @code{gnus-use-long-file-name} variable, as usual.
6112 When re-select a ticked or dormant article, it will be fetched from the
6113 cache instead of from the server. As articles in your cache will never
6114 expire, this might serve as a method of saving articles while still
6115 keeping them where they belong. Just mark all articles you want to save
6116 as dormant, and don't worry.
6118 When an article is marked as read, is it removed from the cache.
6120 @vindex gnus-cache-remove-articles
6121 @vindex gnus-cache-enter-articles
6122 The entering/removal of articles from the cache is controlled by the
6123 @code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
6124 variables. Both are lists of symbols. The first is @code{(ticked
6125 dormant)} by default, meaning that ticked and dormant articles will be
6126 put in the cache. The latter is @code{(read)} by default, meaning that
6127 articles that are marked as read are removed from the cache. Possibly
6128 symbols in these two lists are @code{ticked}, @code{dormant},
6129 @code{unread} and @code{read}.
6131 @findex gnus-jog-cache
6132 So where does the massive article-fetching and storing come into the
6133 picture? The @code{gnus-jog-cache} command will go through all
6134 subscribed newsgroups, request all unread articles, and store them in
6135 the cache. You should only ever, ever ever ever, use this command if 1)
6136 your connection to the @sc{nntp} server is really, really, really slow
6137 and 2) you have a really, really, really huge disk. Seriously.
6139 @vindex gnus-uncacheable-groups
6140 It is likely that you do not want caching on some groups. For instance,
6141 if your @code{nnml} mail is located under your home directory, it makes no
6142 sense to cache it somewhere else under your home directory. Unless you
6143 feel that it's neat to use twice as much space. To limit the caching,
6144 you could set the @code{gnus-uncacheable-groups} regexp to
6145 @samp{"^nnml"}, for instance. This variable is @samp{"^nnvirtual"} by
6146 default, since caching doesn't really work in @code{nnvirtual} groups,
6147 since @code{nnvirtual} assigns random article numbers to its articles.
6149 @findex gnus-cache-generate-nov-databases
6150 @findex gnus-cache-generate-active
6151 If your cache becomes all messed up for some reason or other, Gnus
6152 offers two functions that will try to set things right. @kbd{M-x
6153 gnus-cache-generate-nov-databases} will (re)build all the @sc{nov}
6154 files, and @kbd{gnus-cache-generate-active} will (re)generate the active
6158 @node Persistent Articles
6159 @section Persistent Articles
6160 @cindex persistent articles
6162 Closely related to article caching, we have @dfn{persistent articles}.
6163 In fact, it's just a different way of looking at caching, and much more
6164 useful in my opinion.
6166 Say you're reading a newsgroup, and you happen on to some valuable gem
6167 that you want to keep and treasure forever. You'd normally just save it
6168 (using one of the many saving commands) in some file. The problem with
6169 that is that it's just, well, yucky. Ideally you'd prefer just having
6170 the article remain in the group where you found it forever; untouched by
6171 the expiry going on at the news server.
6173 This is what a @dfn{persistent article} is---an article that just won't
6174 be deleted. It's implemented using the normal cache functions, but
6175 you use two explicit commands for managing persistent articles:
6181 @findex gnus-cache-enter-article
6182 Make the current article persistent (@code{gnus-cache-enter-article}).
6185 @kindex M-* (Summary)
6186 @findex gnus-cache-remove-article
6187 Remove the current article from the persistent articles
6188 (@code{gnus-cache-remove-article}). This will normally delete the
6192 Both these commands understand the process/prefix convention.
6194 To avoid having all ticked articles (and stuff) entered into the cache,
6195 you should set @code{gnus-use-cache} to @code{passive} if you're just
6196 interested in persistent articles:
6199 (setq gnus-use-cache 'passive)
6203 @node Article Backlog
6204 @section Article Backlog
6206 @cindex article backlog
6208 If you have a slow connection, but the idea of using caching seems
6209 unappealing to you (and it is, really), you can help the situation some
6210 by switching on the @dfn{backlog}. This is where Gnus will buffer
6211 already read articles so that it doesn't have to re-fetch articles
6212 you've already read. This only helps if you are in the habit of
6213 re-selecting articles you've recently read, of course. If you never do
6214 that, turning the backlog on will slow Gnus down a little bit, and
6215 increase memory usage some.
6217 @vindex gnus-keep-backlog
6218 If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store
6219 at most @var{n} old articles in a buffer for later re-fetching. If this
6220 variable is non-@code{nil} and is not a number, Gnus will store
6221 @emph{all} read articles, which means that your Emacs will group without
6222 bound before exploding and taking your machine down with you. I put
6223 that in there just to keep y'all on your toes.
6225 This variable is @code{nil} by default.
6228 @node Exiting the Summary Buffer
6229 @section Exiting the Summary Buffer
6230 @cindex summary exit
6232 Exiting from the summary buffer will normally update all info on the
6233 group and return you to the group buffer.
6239 @kindex Z Z (Summary)
6241 @findex gnus-summary-exit
6242 @vindex gnus-summary-exit-hook
6243 @vindex gnus-summary-prepare-exit-hook
6244 Exit the current group and update all information on the group
6245 (@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
6246 called before doing much of the exiting, and calls
6247 @code{gnus-summary-expire-articles} by default.
6248 @code{gnus-summary-exit-hook} is called after finishing the exiting
6253 @kindex Z E (Summary)
6255 @findex gnus-summary-exit-no-update
6256 Exit the current group without updating any information on the group
6257 (@code{gnus-summary-exit-no-update}).
6261 @kindex Z c (Summary)
6263 @findex gnus-summary-catchup-and-exit
6264 Mark all unticked articles in the group as read and then exit
6265 (@code{gnus-summary-catchup-and-exit}).
6268 @kindex Z C (Summary)
6269 @findex gnus-summary-catchup-all-and-exit
6270 Mark all articles, even the ticked ones, as read and then exit
6271 (@code{gnus-summary-catchup-all-and-exit}).
6274 @kindex Z n (Summary)
6275 @findex gnus-summary-catchup-and-goto-next-group
6276 Mark all articles as read and go to the next group
6277 (@code{gnus-summary-catchup-and-goto-next-group}).
6280 @kindex Z R (Summary)
6281 @findex gnus-summary-reselect-current-group
6282 Exit this group, and then enter it again
6283 (@code{gnus-summary-reselect-current-group}). If given a prefix, select
6284 all articles, both read and unread.
6288 @kindex Z G (Summary)
6289 @kindex M-g (Summary)
6290 @findex gnus-summary-rescan-group
6291 Exit the group, check for new articles in the group, and select the
6292 group (@code{gnus-summary-rescan-group}). If given a prefix, select all
6293 articles, both read and unread.
6296 @kindex Z N (Summary)
6297 @findex gnus-summary-next-group
6298 Exit the group and go to the next group
6299 (@code{gnus-summary-next-group}).
6302 @kindex Z P (Summary)
6303 @findex gnus-summary-prev-group
6304 Exit the group and go to the previous group
6305 (@code{gnus-summary-prev-group}).
6308 @vindex gnus-exit-group-hook
6309 @code{gnus-exit-group-hook} is called when you exit the current
6312 @findex gnus-summary-wake-up-the-dead
6313 @findex gnus-dead-summary-mode
6314 @vindex gnus-kill-summary-on-exit
6315 If you're in the habit of exiting groups, and then changing your mind
6316 about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}.
6317 If you do that, Gnus won't kill the summary buffer when you exit it.
6318 (Quelle surprise!) Instead it will change the name of the buffer to
6319 something like @samp{"*Dead Summary ... *"} and install a minor mode
6320 called @code{gnus-dead-summary-mode}. Now, if you switch back to this
6321 buffer, you'll find that all keys are mapped to a function called
6322 @code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead
6323 summary buffer will result in a live, normal summary buffer.
6325 There will never be more than one dead summary buffer at any one time.
6327 @vindex gnus-use-cross-reference
6328 The data on the current group will be updated (which articles you have
6329 read, which articles you have replied to, etc.) when you exit the
6330 summary buffer. If the @code{gnus-use-cross-reference} variable is
6331 @code{t} (which is the default), articles that are cross-referenced to
6332 this group and are marked as read, will also be marked as read in the
6333 other subscribed groups they were cross-posted to. If this variable is
6334 neither @code{nil} nor @code{t}, the article will be marked as read in
6335 both subscribed and unsubscribed groups.
6337 Marking cross-posted articles as read ensures that you'll never have to
6338 read the same article more than once. Unless, of course, somebody has
6339 posted it to several groups separately. Posting the same article to
6340 several groups (not cross-posting) is called @dfn{spamming}, and you are
6341 by law required to send nasty-grams to anyone who perpetrates such a
6344 Remember: Cross-posting is kinda ok, but posting the same article
6345 separately to several groups is not.
6347 One thing that may cause Gnus to not do the cross-posting thing
6348 correctly is if you use an @sc{nntp} server that supports @sc{xover}
6349 (which is very nice, because it speeds things up considerably) which
6350 does not include the @code{Xref} header in its @sc{nov} lines. This is
6351 Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
6352 even with @sc{xover} by registering the @code{Xref} lines of all
6353 articles you actually read, but if you kill the articles, or just mark
6354 them as read without reading them, Gnus will not get a chance to snoop
6355 the @code{Xref} lines out of these articles, and will be unable to use
6356 the cross reference mechanism.
6358 @vindex gnus-nov-is-evil
6359 If you want Gnus to get the @code{Xref}s right all the time, you have to
6360 set @code{gnus-nov-is-evil} to @code{t}, which slows things down
6366 @node Process/Prefix
6367 @section Process/Prefix
6368 @cindex process/prefix convention
6370 Many functions, among them functions for moving, decoding and saving
6371 articles, use what is known as the @dfn{Process/Prefix convention}.
6373 This is a method for figuring out what articles that the user wants the
6374 command to be performed on.
6378 If the numeric prefix is N, perform the operation on the next N
6379 articles, starting with the current one. If the numeric prefix is
6380 negative, perform the operation on the previous N articles, starting
6381 with the current one.
6383 If @code{transient-mark-mode} in non-@code{nil} and the region is
6384 active, all articles in the region will be worked upon.
6386 If there is no numeric prefix, but some articles are marked with the
6387 process mark, perform the operation on the articles that are marked with
6390 If there is neither a numeric prefix nor any articles marked with the
6391 process mark, just perform the operation on the current article.
6393 Quite simple, really, but it needs to be made clear so that surprises
6396 @vindex gnus-summary-goto-unread
6397 One thing that seems to shock & horrify lots of people is that, for
6398 instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}.
6399 Since each @kbd{d} (which marks the current article as read) by default
6400 goes to the next unread article after marking, this means that @kbd{3 d}
6401 will mark the next three unread articles as read, no matter what the
6402 summary buffer looks like. Set @code{gnus-summary-goto-unread} to
6403 @code{nil} for a more straightforward action.
6406 @node Saving Articles
6407 @section Saving Articles
6408 @cindex saving articles
6410 Gnus can save articles in a number of ways. Below is the documentation
6411 for saving articles in a fairly straight-forward fashion (i.e., little
6412 processing of the article is done before it is saved). For a different
6413 approach (uudecoding, unsharing) you should use @code{gnus-uu}
6414 (@pxref{Decoding Articles}).
6416 @vindex gnus-save-all-headers
6417 If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
6418 unwanted headers before saving the article.
6420 @vindex gnus-saved-headers
6421 If the preceeding variable is @code{nil}, all headers that match the
6422 @code{gnus-saved-headers} regexp will be kept, while the rest will be
6423 deleted before saving.
6429 @kindex O o (Summary)
6431 @findex gnus-summary-save-article
6432 Save the current article using the default article saver
6433 (@code{gnus-summary-save-article}).
6436 @kindex O m (Summary)
6437 @findex gnus-summary-save-article-mail
6438 Save the current article in mail format
6439 (@code{gnus-summary-save-article-mail}).
6442 @kindex O r (Summary)
6443 @findex gnus-summary-save-article-mail
6444 Save the current article in rmail format
6445 (@code{gnus-summary-save-article-rmail}).
6448 @kindex O f (Summary)
6449 @findex gnus-summary-save-article-file
6450 Save the current article in plain file format
6451 (@code{gnus-summary-save-article-file}).
6454 @kindex O b (Summary)
6455 @findex gnus-summary-save-article-body-file
6456 Save the current article body in plain file format
6457 (@code{gnus-summary-save-article-body-file}).
6460 @kindex O h (Summary)
6461 @findex gnus-summary-save-article-folder
6462 Save the current article in mh folder format
6463 (@code{gnus-summary-save-article-folder}).
6466 @kindex O p (Summary)
6467 @findex gnus-summary-pipe-output
6468 Save the current article in a pipe. Uhm, like, what I mean is---Pipe
6469 the current article to a process (@code{gnus-summary-pipe-output}).
6472 @vindex gnus-prompt-before-saving
6473 All these commands use the process/prefix convention
6474 (@pxref{Process/Prefix}). If you save bunches of articles using these
6475 functions, you might get tired of being prompted for files to save each
6476 and every article in. The prompting action is controlled by
6477 the @code{gnus-prompt-before-saving} variable, which is @code{always} by
6478 default, giving you that excessive prompting action you know and
6479 loathe. If you set this variable to @code{t} instead, you'll be promted
6480 just once for each series of articles you save. If you like to really
6481 have Gnus do all your thinking for you, you can even set this variable
6482 to @code{nil}, which means that you will never be prompted for files to
6483 save articles in. Gnus will simply save all the articles in the default
6487 @vindex gnus-default-article-saver
6488 You can customize the @code{gnus-default-article-saver} variable to make
6489 Gnus do what you want it to. You can use any of the four ready-made
6490 functions below, or you can create your own.
6494 @item gnus-summary-save-in-rmail
6495 @findex gnus-summary-save-in-rmail
6496 This is the default format, @dfn{babyl}. Uses the function in the
6497 @code{gnus-rmail-save-name} variable to get a file name to save the
6498 article in. The default is @code{gnus-plain-save-name}.
6500 @item gnus-summary-save-in-mail
6501 @findex gnus-summary-save-in-mail
6502 Save in a Unix mail (mbox) file. Uses the function in the
6503 @code{gnus-mail-save-name} variable to get a file name to save the
6504 article in. The default is @code{gnus-plain-save-name}.
6506 @item gnus-summary-save-in-file
6507 @findex gnus-summary-save-in-file
6508 Append the article straight to an ordinary file. Uses the function in
6509 the @code{gnus-file-save-name} variable to get a file name to save the
6510 article in. The default is @code{gnus-numeric-save-name}.
6512 @item gnus-summary-save-body-in-file
6513 @findex gnus-summary-save-body-in-file
6514 Append the article body to an ordinary file. Uses the function in the
6515 @code{gnus-file-save-name} variable to get a file name to save the
6516 article in. The default is @code{gnus-numeric-save-name}.
6518 @item gnus-summary-save-in-folder
6519 @findex gnus-summary-save-in-folder
6520 Save the article to an MH folder using @code{rcvstore} from the MH
6523 @item gnus-summary-save-in-vm
6524 @findex gnus-summary-save-in-vm
6525 Save the article in a VM folder. You have to have the VM mail
6526 reader to use this setting.
6529 All of these functions, except for the last one, will save the article
6530 in the @code{gnus-article-save-directory}, which is initialized from the
6531 @samp{SAVEDIR} environment variable. This is @file{~/News/} by
6534 As you can see above, the functions use different functions to find a
6535 suitable name of a file to save the article in. Below is a list of
6536 available functions that generate names:
6540 @item gnus-Numeric-save-name
6541 @findex gnus-Numeric-save-name
6542 Generates file names that look like @samp{~/News/Alt.andrea-dworkin/45}.
6544 @item gnus-numeric-save-name
6545 @findex gnus-numeric-save-name
6546 Generates file names that look like @samp{~/News/alt.andrea-dworkin/45}.
6548 @item gnus-Plain-save-name
6549 @findex gnus-Plain-save-name
6550 Generates file names that look like @samp{~/News/Alt.andrea-dworkin}.
6552 @item gnus-plain-save-name
6553 @findex gnus-plain-save-name
6554 Generates file names that look like @samp{~/News/alt.andrea-dworkin}.
6557 @vindex gnus-split-methods
6558 You can have Gnus suggest where to save articles by plonking regexp into
6559 the @code{gnus-split-methods} alist. For instance, if you would like to
6560 save articles related to Gnus in the file @file{gnus-stuff}, and articles
6561 related to VM in @code{vm-stuff}, you could set this variable to something
6565 (("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
6566 ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff")
6567 (my-choosing-function "../other-dir/my-stuff")
6568 ((equal gnus-newsgroup-name "mail.misc") "mail-stuff"))
6571 We see that this is a list where each element is a list that has two
6572 elements---the @dfn{match} and the @dfn{file}. The match can either be
6573 a string (in which case it is used as a regexp to match on the article
6574 head); it can be a symbol (which will be called as a function); or it
6575 can be a list (which will be @code{eval}ed). If any of these actions
6576 have a non-@code{nil} result, the @dfn{file} will be used as a default
6577 prompt. In addition, the result of the operation itself will be used if
6578 the function or form called returns a string or a list of strings.
6580 You basically end up with a list of file names that might be used when
6581 saving the current article. (All "matches" will be used.) You will
6582 then be prompted for what you really want to use as a name, with file
6583 name completion over the results from applying this variable.
6585 This variable is @code{((gnus-article-archive-name))} by default, which
6586 means that Gnus will look at the articles it saves for an
6587 @samp{Archive-name} line and use that as a suggestion for the file
6590 @vindex gnus-use-long-file-name
6591 Finally, you have the @code{gnus-use-long-file-name} variable. If it is
6592 @code{nil}, all the preceding functions will replace all periods
6593 (@samp{.}) in the group names with slashes (@samp{/})---which means that
6594 the functions will generate hierarchies of directories instead of having
6595 all the files in the toplevel directory
6596 (@samp{~/News/alt/andrea-dworkin} instead of
6597 @samp{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default
6598 on most systems. However, for historical reasons, this is @code{nil} on
6599 Xenix and usg-unix-v machines by default.
6601 This function also affects kill and score file names. If this variable
6602 is a list, and the list contains the element @code{not-score}, long file
6603 names will not be used for score files, if it contains the element
6604 @code{not-save}, long file names will not be used for saving, and if it
6605 contains the element @code{not-kill}, long file names will not be used
6608 If you'd like to save articles in a hierarchy that looks something like
6612 (setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
6613 (setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
6616 Then just save with @kbd{o}. You'd then read this hierarchy with
6617 ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
6618 the toplevel directory as the argument (@file{~/News/}). Then just walk
6619 around to the groups/directories with @code{nneething}.
6622 @node Decoding Articles
6623 @section Decoding Articles
6624 @cindex decoding articles
6626 Sometime users post articles (or series of articles) that have been
6627 encoded in some way or other. Gnus can decode them for you.
6630 * Uuencoded Articles:: Uudecode articles.
6631 * Shared Articles:: Unshar articles.
6632 * PostScript Files:: Split PostScript.
6633 * Decoding Variables:: Variables for a happy decoding.
6634 * Viewing Files:: You want to look at the result of the decoding?
6637 All these functions use the process/prefix convention
6638 (@pxref{Process/Prefix}) for finding out what articles to work on, with
6639 the extension that a "single article" means "a single series". Gnus can
6640 find out by itself what articles belong to a series, decode all the
6641 articles and unpack/view/save the resulting file(s).
6643 Gnus guesses what articles are in the series according to the following
6644 simplish rule: The subjects must be (nearly) identical, except for the
6645 last two numbers of the line. (Spaces are largely ignored, however.)
6647 For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus
6648 will find all the articles that match the regexp @samp{^cat.gif
6649 ([0-9]+/[0-9]+).*$}.
6651 Subjects that are nonstandard, like @samp{cat.gif (2/3) Part 6 of a
6652 series}, will not be properly recognized by any of the automatic viewing
6653 commands, and you have to mark the articles manually with @key{#}.
6655 @node Uuencoded Articles
6656 @subsection Uuencoded Articles
6658 @cindex uuencoded articles
6663 @kindex X u (Summary)
6664 @findex gnus-uu-decode-uu
6665 Uudecodes the current series (@code{gnus-uu-decode-uu}).
6668 @kindex X U (Summary)
6669 @findex gnus-uu-decode-uu-and-save
6670 Uudecodes and saves the current series
6671 (@code{gnus-uu-decode-uu-and-save}).
6674 @kindex X v u (Summary)
6675 @findex gnus-uu-decode-uu-view
6676 Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
6679 @kindex X v U (Summary)
6680 @findex gnus-uu-decode-uu-and-save-view
6681 Uudecodes, views and saves the current series
6682 (@code{gnus-uu-decode-uu-and-save-view}).
6685 Remember that these all react to the presence of articles marked with
6686 the process mark. If, for instance, you'd like to uncode and save an
6687 entire newsgroup, you'd typically do @kbd{M P a}
6688 (@code{gnus-uu-mark-all}) and then @kbd{X U}
6689 (@code{gnus-uu-decode-uu-and-save}).
6691 All this is very much different from how @code{gnus-uu} worked with
6692 @sc{gnus 4.1}, where you had explicit keystrokes for everything under
6693 the sun. This version of @code{gnus-uu} generally assumes that you mark
6694 articles in some way (@pxref{Setting Process Marks}) and then press
6697 Note: When trying to decode articles that have names matching
6698 @code{gnus-uu-notify-files}, which is hard-coded to
6699 @samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
6700 automatically post an article on @samp{comp.unix.wizards} saying that
6701 you have just viewed the file in question. This feature can't be turned
6704 @node Shared Articles
6705 @subsection Shared Articles
6707 @cindex shared articles
6712 @kindex X s (Summary)
6713 @findex gnus-uu-decode-unshar
6714 Unshars the current series (@code{gnus-uu-decode-unshar}).
6717 @kindex X S (Summary)
6718 @findex gnus-uu-decode-unshar-and-save
6719 Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
6722 @kindex X v s (Summary)
6723 @findex gnus-uu-decode-unshar-view
6724 Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
6727 @kindex X v S (Summary)
6728 @findex gnus-uu-decode-unshar-and-save-view
6729 Unshars, views and saves the current series
6730 (@code{gnus-uu-decode-unshar-and-save-view}).
6733 @node PostScript Files
6734 @subsection PostScript Files
6740 @kindex X p (Summary)
6741 @findex gnus-uu-decode-postscript
6742 Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
6745 @kindex X P (Summary)
6746 @findex gnus-uu-decode-postscript-and-save
6747 Unpack and save the current PostScript series
6748 (@code{gnus-uu-decode-postscript-and-save}).
6751 @kindex X v p (Summary)
6752 @findex gnus-uu-decode-postscript-view
6753 View the current PostScript series
6754 (@code{gnus-uu-decode-postscript-view}).
6757 @kindex X v P (Summary)
6758 @findex gnus-uu-decode-postscript-and-save-view
6759 View and save the current PostScript series
6760 (@code{gnus-uu-decode-postscript-and-save-view}).
6763 @node Decoding Variables
6764 @subsection Decoding Variables
6766 Adjective, not verb.
6769 * Rule Variables:: Variables that say how a file is to be viewed.
6770 * Other Decode Variables:: Other decode variables.
6771 * Uuencoding & Posting:: Variables for customizing uuencoding.
6774 @node Rule Variables
6775 @subsubsection Rule Variables
6776 @cindex rule variables
6778 Gnus uses @dfn{rule variables} to decide how to view a file. All these
6779 variables are on the form
6782 (list '(regexp1 command2)
6789 @item gnus-uu-user-view-rules
6790 @vindex gnus-uu-user-view-rules
6791 This variable is consulted first when viewing files. If you wish to use,
6792 for instance, @code{sox} to convert an @samp{.au} sound file, you could
6795 (setq gnus-uu-user-view-rules
6796 (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
6799 @item gnus-uu-user-view-rules-end
6800 @vindex gnus-uu-user-view-rules-end
6801 This variable is consulted if Gnus couldn't make any matches from the
6802 user and default view rules.
6804 @item gnus-uu-user-archive-rules
6805 @vindex gnus-uu-user-archive-rules
6806 This variable can be used to say what commands should be used to unpack
6811 @node Other Decode Variables
6812 @subsubsection Other Decode Variables
6815 @vindex gnus-uu-grabbed-file-functions
6817 @item gnus-uu-grabbed-file-functions
6818 All functions in this list will be called right each file has been
6819 successfully decoded---so that you can move or view files right away,
6820 and don't have to wait for all files to be decoded before you can do
6821 anything. Ready-made functions you can put in this list are:
6825 @item gnus-uu-grab-view
6826 @findex gnus-uu-grab-view
6829 @item gnus-uu-grab-move
6830 @findex gnus-uu-grab-move
6831 Move the file (if you're using a saving function.)
6834 @item gnus-uu-ignore-files-by-name
6835 @vindex gnus-uu-ignore-files-by-name
6836 Files with name matching this regular expression won't be viewed.
6838 @item gnus-uu-ignore-files-by-type
6839 @vindex gnus-uu-ignore-files-by-type
6840 Files with a @sc{mime} type matching this variable won't be viewed.
6841 Note that Gnus tries to guess what type the file is based on the name.
6842 @code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
6845 @item gnus-uu-tmp-dir
6846 @vindex gnus-uu-tmp-dir
6847 Where @code{gnus-uu} does its work.
6849 @item gnus-uu-do-not-unpack-archives
6850 @vindex gnus-uu-do-not-unpack-archives
6851 Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
6852 looking for files to display.
6854 @item gnus-uu-view-and-save
6855 @vindex gnus-uu-view-and-save
6856 Non-@code{nil} means that the user will always be asked to save a file
6859 @item gnus-uu-ignore-default-view-rules
6860 @vindex gnus-uu-ignore-default-view-rules
6861 Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
6864 @item gnus-uu-ignore-default-archive-rules
6865 @vindex gnus-uu-ignore-default-archive-rules
6866 Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
6869 @item gnus-uu-kill-carriage-return
6870 @vindex gnus-uu-kill-carriage-return
6871 Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
6874 @item gnus-uu-unmark-articles-not-decoded
6875 @vindex gnus-uu-unmark-articles-not-decoded
6876 Non-@code{nil} means that @code{gnus-uu} will mark articles that were
6877 unsuccessfully decoded as unread.
6879 @item gnus-uu-correct-stripped-uucode
6880 @vindex gnus-uu-correct-stripped-uucode
6881 Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
6882 uuencoded files that have had trailing spaces deleted.
6884 @item gnus-uu-view-with-metamail
6885 @vindex gnus-uu-view-with-metamail
6886 Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
6887 commands defined by the rule variables and just fudge a @sc{mime}
6888 content type based on the file name. The result will be fed to
6889 @code{metamail} for viewing.
6891 @item gnus-uu-save-in-digest
6892 @vindex gnus-uu-save-in-digest
6893 Non-@code{nil} means that @code{gnus-uu}, when asked to save without
6894 decoding, will save in digests. If this variable is @code{nil},
6895 @code{gnus-uu} will just save everything in a file without any
6896 embellishments. The digesting almost conforms to RFC1153---no easy way
6897 to specify any meaningful volume and issue numbers were found, so I
6898 simply dropped them.
6902 @node Uuencoding & Posting
6903 @subsubsection Uuencoding & Posting
6907 @item gnus-uu-post-include-before-composing
6908 @vindex gnus-uu-post-include-before-composing
6909 Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
6910 before you compose the article. If this variable is @code{t}, you can
6911 either include an encoded file with @key{C-c C-i} or have one included
6912 for you when you post the article.
6914 @item gnus-uu-post-length
6915 @vindex gnus-uu-post-length
6916 Maximum length of an article. The encoded file will be split into how
6917 many articles it takes to post the entire file.
6919 @item gnus-uu-post-threaded
6920 @vindex gnus-uu-post-threaded
6921 Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
6922 thread. This may not be smart, as no other decoder I have seen are able
6923 to follow threads when collecting uuencoded articles. (Well, I have
6924 seen one package that does that---@code{gnus-uu}, but somehow, I don't
6925 think that counts...) Default is @code{nil}.
6927 @item gnus-uu-post-separate-description
6928 @vindex gnus-uu-post-separate-description
6929 Non-@code{nil} means that the description will be posted in a separate
6930 article. The first article will typically be numbered (0/x). If this
6931 variable is @code{nil}, the description the user enters will be included
6932 at the beginning of the first article, which will be numbered (1/x).
6933 Default is @code{t}.
6938 @subsection Viewing Files
6939 @cindex viewing files
6940 @cindex pseudo-articles
6942 After decoding, if the file is some sort of archive, Gnus will attempt
6943 to unpack the archive and see if any of the files in the archive can be
6944 viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
6945 containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
6946 uncompress and detar the main file, and then view the two pictures.
6947 This unpacking process is recursive, so if the archive contains archives
6948 of archives, it'll all be unpacked.
6950 Finally, Gnus will normally insert a @dfn{pseudo-article} for each
6951 extracted file into the summary buffer. If you go to these "articles",
6952 you will be prompted for a command to run (usually Gnus will make a
6953 suggestion), and then the command will be run.
6955 @vindex gnus-view-pseudo-asynchronously
6956 If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
6957 until the viewing is done before proceeding.
6959 @vindex gnus-view-pseudos
6960 If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
6961 the pseudo-articles into the summary buffer, but view them
6962 immediately. If this variable is @code{not-confirm}, the user won't even
6963 be asked for a confirmation before viewing is done.
6965 @vindex gnus-view-pseudos-separately
6966 If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
6967 pseudo-article will be created for each file to be viewed. If
6968 @code{nil}, all files that use the same viewing command will be given as
6969 a list of parameters to that command.
6971 If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert
6972 pseudo-articles when decoding. It is @code{t} by default.
6974 So; there you are, reading your @emph{pseudo-articles} in your
6975 @emph{virtual newsgroup} from the @emph{virtual server}; and you think:
6976 Why isn't anything real anymore? How did we get here?
6979 @node Article Treatment
6980 @section Article Treatment
6982 Reading through this huge manual, you may have quite forgotten that the
6983 object of newsreaders are to actually, like, read what people have
6984 written. Reading articles. Unfortunately, people are quite bad at
6985 writing, so there are tons of functions and variables to make reading
6986 these articles easier.
6989 * Article Highlighting:: You want to make the article look like fruit salad.
6990 * Article Hiding:: You also want to make certain info go away.
6991 * Article Washing:: Lots of way-neat functions to make life better.
6992 * Article Buttons:: Clcik on URLs, Message-IDs, addresses and the like.
6993 * Article Date:: Grumble, UT!
6997 @node Article Highlighting
6998 @subsection Article Highlighting
7001 Not only do you want your article buffer to look like fruit salad, but
7002 you want it to look like technicolor fruit salad.
7007 @kindex W H a (Summary)
7008 @findex gnus-article-highlight
7009 Highlight the current article (@code{gnus-article-highlight}).
7012 @kindex W H h (Summary)
7013 @findex gnus-article-highlight-headers
7014 @vindex gnus-header-face-alist
7015 Highlight the headers (@code{gnus-article-highlight-headers}). The
7016 highlighting will be done according to the @code{gnus-header-face-alist}
7017 variable, which is a list where each element has the form @var{(regexp
7018 name content)}. @var{regexp} is a regular expression for matching the
7019 header, @var{name} is the face used for highling the header name and
7020 @var{content} is the face for highlighting the header value. The first
7021 match made will be used.
7024 @kindex W H c (Summary)
7025 @findex gnus-article-highlight-citation
7026 Highlight cited text (@code{gnus-article-highlight-citation}).
7028 Some variables to customize the citation highlights:
7031 @vindex gnus-cite-parse-max-size
7033 @item gnus-cite-parse-max-size
7034 If the article size if bigger than this variable (which is 25000 by
7035 default), no citation highlighting will be performed.
7037 @item gnus-cite-prefix-regexp
7038 @vindex gnus-cite-prefix-regexp
7039 Regexp mathcing the longest possible citation prefix on a line.
7041 @item gnus-cite-max-prefix
7042 @vindex gnus-cite-max-prefix
7043 Maximum possible length for a citation prefix (default 20).
7045 @item gnus-supercite-regexp
7046 @vindex gnus-supercite-regexp
7047 Regexp matching normal SuperCite attribution lines.
7049 @item gnus-supercite-secondary-regexp
7050 @vindex gnus-supercite-secondary-regexp
7051 Regexp matching mangled SuperCite attribution lines.
7053 @item gnus-cite-minimum-match-count
7054 @vindex gnus-cite-minimum-match-count
7055 Minimum number of identical prefixes we have to see before we believe
7056 that it's a citation.
7058 @item gnus-cite-attribution-prefix
7059 @vindex gnus-cite-attribution-prefix
7060 Regexp matching the beginning of an attribution line.
7062 @item gnus-cite-addtribution-suffix
7063 @vindex gnus-cite-addtribution-suffix
7064 Regexp matching the end of an attribution line.
7066 @item gnus-cite-attribution-face
7067 @vindex gnus-cite-attribution-face
7068 Face used for attribution lines. It is merged with the face for the
7069 cited text belonging to the attribution.
7075 @kindex W H s (Summary)
7076 @vindex gnus-signature-separator
7077 @findex gnus-article-highlight-signature
7078 Highlight the signature (@code{gnus-article-highlight-signature}).
7079 Everything after @code{gnus-signature-separator} in an article will be
7080 considered a signature.
7085 @node Article Hiding
7086 @subsection Article Hiding
7087 @cindex article hiding
7089 Or rather, hiding certain things in each article. There usually is much
7090 to much gruft in most articles.
7095 @kindex W W a (Summary)
7096 @findex gnus-article-hide
7097 Do maximum hiding on the summary buffer (@kbd{gnus-article-hide}).
7100 @kindex W W h (Summary)
7101 @findex gnus-article-hide-headers
7102 Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
7106 @kindex W W s (Summary)
7107 @findex gnus-article-hide-signature
7108 Hide signature (@code{gnus-article-hide-signature}).
7111 @kindex W W p (Summary)
7112 @findex gnus-article-hide-pgp
7113 Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}).
7116 @kindex W W c (Summary)
7117 @findex gnus-article-hide-citation
7118 Hide citation (@code{gnus-article-hide-citation}). Two variables for
7119 customizing the hiding:
7123 @item gnus-cite-hide-percentage
7124 @vindex gnus-cite-hide-percentage
7125 If the cited text is of a bigger percentage than this variable (default
7126 50), hide the cited text.
7128 @item gnus-cite-hide-absolute
7129 @vindex gnus-cite-hide-absolute
7130 The cited text must be have at least this length (default 10) before it
7136 @kindex W W C (Summary)
7137 @findex gnus-article-hide-citation-in-followups
7138 Hide cited text in articles that aren't roots
7139 (@code{gnus-article-hide-citation-in-followups}). This isn't very
7140 useful as an interactive command, but might be a handy function to stick
7141 in @code{gnus-article-display-hook} (@pxref{Customizing Articles}).
7145 All these "hide" functions take a prefix to undo the hiding. @kbd{C-u W
7146 W c} will show any hidden signatures, for instance.
7148 Also see @xref{Article Highlighting} for further variables for
7149 citation customization.
7152 @node Article Washing
7153 @subsection Article Washing
7155 @cindex article washing
7157 We call this "article washing" for a really good reason. Namely, the
7158 @kbd{A} key was taken, so we had to use the @kbd{W} key instead.
7160 @dfn{Washing} is defined by us as "changing something from something to
7161 something else", but normally results in something looking better.
7167 @kindex W l (Summary)
7168 @findex gnus-summary-stop-page-breaking
7169 Remove page breaks from the current article
7170 (@code{gnus-summary-stop-page-breaking}).
7173 @kindex W r (Summary)
7174 @findex gnus-summary-caesar-message
7175 Do a Caesar rotate (rot13) on the article buffer
7176 (@code{gnus-summary-caesar-message}).
7179 @kindex A g (Summary)
7180 @findex gnus-summary-show-article
7181 (Re)fetch the current article (@code{gnus-summary-show-article}). If
7182 given a prefix, fetch the current article, but don't run any of the
7183 article treatment functions. This will give you a "raw" article, just
7184 the way it came from the server.
7187 @kindex W t (Summary)
7188 @findex gnus-summary-toggle-header
7189 Toggle whether to display all headers in the article buffer
7190 (@code{gnus-summary-toggle-header}).
7193 @kindex W m (Summary)
7194 @findex gnus-summary-toggle-mime
7195 Toggle whether to run the article through @sc{mime} before displaying
7196 (@code{gnus-summary-toggle-mime}).
7199 @kindex W o (Summary)
7200 @findex gnus-article-treat-overstrike
7201 Treat overstrike (@code{gnus-article-treat-overstrike}).
7204 @kindex W w (Summary)
7205 @findex gnus-article-word-wrap
7206 Do word wrap (@code{gnus-article-word-wrap}).
7209 @kindex W c (Summary)
7210 @findex gnus-article-remove-cr
7211 Remove CR (@code{gnus-article-remove-cr}).
7214 @kindex W q (Summary)
7215 @findex gnus-article-de-quoted-unreadable
7216 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
7219 @kindex W f (Summary)
7221 @findex gnus-article-display-x-face
7222 @findex gnus-article-x-face-command
7223 @vindex gnus-article-x-face-command
7224 @vindex gnus-article-x-face-too-ugly
7225 Look for and display any X-Face headers
7226 (@code{gnus-article-display-x-face}). The command executed by this
7227 function is given by the @code{gnus-article-x-face-command} variable. If
7228 this variable is a string, this string will be executed in a sub-shell.
7229 If it is a function, this function will be called with the face as the
7230 argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
7231 matches the @code{From} header, the face will not be shown.
7234 @kindex W b (Summary)
7235 @findex gnus-article-add-buttons
7236 Add clickable buttons to the article (@code{gnus-article-add-buttons}).
7239 @kindex W B (Summary)
7240 @findex gnus-article-add-buttons-to-head
7241 Add clickable buttons to the article headers
7242 (@code{gnus-article-add-buttons-to-head}).
7247 @node Article Buttons
7248 @subsection Article Buttons
7251 People often include references to other stuff in articles, and it would
7252 be nice if Gnus could just fetch whatever it is that people talk about
7253 with the minimum of fuzz.
7255 Gnus adds @dfn{buttons} to certain standard references by default:
7256 Well-formed URLs, mail addresses and Message-IDs. This is controlled by
7257 two variables, one that handles article bodies and one that handles
7262 @item gnus-button-alist
7263 @vindex gnus-header-button-alist
7264 This is an alist where each entry has this form:
7267 (REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
7273 All text that match this regular expression will be considered an
7274 external reference. Here's a typical regexp that match embedded URLs:
7275 @samp{"<URL:\\([^\n\r>]*\\)>"}.
7278 Gnus has to know which parts of the match is to be highlighted. This is
7279 a number that says what sub-expression of the regexp that is to be
7280 highlighted. If you want it all highlighted, you use @samp{0} here.
7283 This form will be @code{eval}ed, and if the result is non-@code{nil},
7284 this is considered a match. This is useful if you want extra sifting to
7285 avoid false matches.
7288 This function will be called when you click on this button.
7291 As with @var{button-par}, this is a sub-expression number, but this one
7292 says which part of the match is to be sent as data to @var{function}.
7296 So the full entry for buttonizing URLs is then
7299 ("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
7302 @item gnus-header-button-alist
7303 @vindex gnus-header-button-alist
7304 This is just like the other alist, except that it is applied to the
7305 article head only, and that each entry has an additional element that is
7306 used to say what headers to apply the buttonize coding to:
7309 (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
7312 @var{header} is a regular expression.
7316 @vindex gnus-article-button-face
7317 @vindex gnus-article-mouse-face
7318 Buttons are highlighted with @code{gnus-article-button-face}, while
7319 @code{gnus-article-mouse-face} is used when the mouse cursor is over the
7324 @subsection Article Date
7326 The date is most likely generated in some obscure timezone you've never
7327 heard of, so it's quite nice to be able to find out what the time was
7328 when the article was sent.
7333 @kindex W T u (Summary)
7334 @findex gnus-article-date-ut
7335 Display the date in UT (aka. GMT, aka ZULU)
7336 (@code{gnus-article-date-ut}).
7339 @kindex W T l (Summary)
7340 @findex gnus-article-date-local
7341 Display the date in the local timezone (@code{gnus-article-date-local}).
7344 @kindex W T e (Summary)
7345 @findex gnus-article-date-lapsed
7346 Say how much time has (e)lapsed between the article was posted and now
7347 (@code{gnus-article-date-lapsed}).
7350 @kindex W T o (Summary)
7351 @findex gnus-article-date-original
7352 Display the original date (@code{gnus-article-date-original}). This can
7353 be useful if you normally use some other conversion function and is
7354 worried that it might be doing something totally wrong. Say, claiming
7355 that the article was posted in 1854. Although something like that is
7356 @emph{totally} impossible. Don't you trust me? *titter*
7361 @node Summary Sorting
7362 @section Summary Sorting
7363 @cindex summary sorting
7365 You can have the summary buffer sorted in various ways, even though I
7366 can't really see why you'd want that.
7371 @kindex C-c C-s C-n (Summary)
7372 @findex gnus-summary-sort-by-number
7373 Sort by article number (@code{gnus-summary-sort-by-number}).
7376 @kindex C-c C-s C-a (Summary)
7377 @findex gnus-summary-sort-by-author
7378 Sort by author (@code{gnus-summary-sort-by-author}).
7381 @kindex C-c C-s C-s (Summary)
7382 @findex gnus-summary-sort-by-subject
7383 Sort by subject (@code{gnus-summary-sort-by-subject}).
7386 @kindex C-c C-s C-d (Summary)
7387 @findex gnus-summary-sort-by-date
7388 Sort by date (@code{gnus-summary-sort-by-date}).
7391 @kindex C-c C-s C-i (Summary)
7392 @findex gnus-summary-sort-by-score
7393 Sort by score (@code{gnus-summary-sort-by-score}).
7396 These functions will work both when you use threading and when you don't
7397 use threading. In the latter case, all summary lines will be sorted,
7398 line by line. In the former case, sorting will be done on a
7399 root-by-root basis, which might not be what you were looking for. To
7400 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
7404 @node Finding the Parent
7405 @section Finding the Parent
7406 @cindex parent articles
7407 @cindex referring articles
7409 @findex gnus-summary-refer-parent-article
7411 If you'd like to read the parent of the current article, and it is not
7412 displayed in the article buffer, you might still be able to. That is,
7413 if the current group is fetched by @sc{nntp}, the parent hasn't expired
7414 and the @code{References} in the current article are not mangled, you
7415 can just press @kbd{^} or @kbd{A r}
7416 (@code{gnus-summary-refer-parent-article}). If everything goes well,
7417 you'll get the parent. If the parent is already displayed in the
7418 summary buffer, point will just move to this article.
7420 @findex gnus-summary-refer-references
7421 @kindex A R (Summary)
7422 You can have Gnus fetch all articles mentioned in the @code{References}
7423 header of the article by pushing @kbd{A R}
7424 (@code{gnus-summary-refer-references}).
7426 @findex gnus-summary-refer-article
7427 @kindex M-^ (Summary)
7428 You can also ask the @sc{nntp} server for an arbitrary article, no
7429 matter what group it belongs to. @kbd{M-^}
7430 (@code{gnus-summary-refer-article}) will ask you for a
7431 @code{Message-ID}, which is one of those long thingies that look
7432 something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
7433 it all exactly right. No fuzzy searches, I'm afraid.
7435 @vindex gnus-refer-article-method
7436 If the group you are reading is located on a backend that does not
7437 support fetching by @code{Message-ID} very well (like @code{nnspool}),
7438 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
7439 would, perhaps, be best if the @sc{nntp} server you consult is the same
7440 as the one that keeps the spool you are reading from updated, but that's
7441 not really necessary.
7443 Most of the mail backends support fetching by @code{Message-ID}, but do
7444 not do a particularly excellent job of it. That is, @code{nnmbox} and
7445 @code{nnbabyl} are able to locate articles from any groups, while
7446 @code{nnml} and @code{nnfolder} are only able to locate articles that
7447 have been posted to the current group. (Anything else would be too time
7448 consuming.) @code{nnmh} does not support this at all.
7451 @node Mail Group Commands
7452 @section Mail Group Commands
7453 @cindex mail group commands
7455 Some commands only make sense in mail groups. If these commands are
7456 illegal in the current group, they will raise a hell and let you know.
7458 All these commands (except the expiry and edit commands) use the
7459 process/prefix convention (@pxref{Process/Prefix}).
7464 @kindex B e (Summary)
7465 @findex gnus-summary-expire-articles
7466 Expire all expirable articles in the group
7467 (@code{gnus-summary-expire-articles}).
7470 @kindex B M-C-e (Summary)
7471 @findex gnus-summary-expire-articles-now
7472 Expunge all the expirable articles in the group
7473 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
7474 articles that are eligeble for expiry in the current group will
7475 disappear forever into that big @file{/dev/null} in the sky.
7478 @kindex B DEL (Summary)
7479 @findex gnus-summary-delete-articles
7480 Delete the mail article. This is "delete" as in "delete it from your
7481 disk forever and ever, never to return again." Use with caution.
7482 (@code{gnus-summary-delete-article}).
7485 @kindex B m (Summary)
7487 @findex gnus-summary-move-article
7488 Move the article from one mail group to another
7489 (@code{gnus-summary-move-article}).
7492 @kindex B c (Summary)
7494 @findex gnus-summary-copy-article
7495 Copy the article from one group (mail group or not) to a mail group
7496 (@code{gnus-summary-copy-article}).
7499 @kindex B i (Summary)
7500 @findex gnus-summary-import-article
7501 Import a random file into the current mail newsgroup
7502 (@code{gnus-summary-import-article}). You will be prompted for a file
7503 name, a @code{From} header and a @code{Subject} header.
7505 Something similar can be done by just starting to compose a mail
7506 message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
7507 @kbd{C-c C-p} instead. This will put the message you have just created
7508 into the current mail group.
7511 @kindex B r (Summary)
7512 @findex gnus-summary-respool-article
7513 Respool the mail article (@code{gnus-summary-move-article}).
7517 @kindex B w (Summary)
7519 @findex gnus-summary-edit-article
7520 @kindex C-c C-c (Article)
7521 Edit the current article (@code{gnus-summary-edit-article}). To finish
7522 editing and make the changes permanent, type @kbd{C-c C-c}
7523 (@kbd{gnus-summary-edit-article-done}).
7526 @kindex B q (Summary)
7527 @findex gnus-summary-respool-query
7528 If you want to respool an article, you might be curious as to what group
7529 the article will end up in before you do the respooling. This command
7530 will tell you (@code{gnus-summary-fancy-query}).
7533 If you move (or copy) articles regularly, you might wish to have Gnus
7534 suggest where to put the articles. @code{gnus-move-split-methods} is a
7535 variable that uses the same syntax as @code{gnus-split-methods}
7536 (@pxref{Saving Articles}). You may customize that variable to create
7537 suggestions you find reasonable.
7540 @node Various Summary Stuff
7541 @section Various Summary Stuff
7544 * Group Information:: Information oriented commands.
7545 * Searching for Articles:: Multiple article commands.
7546 * Really Various Summary Commands:: Those pesky non-conformant commands.
7549 @vindex gnus-summary-generate-hook
7550 @code{gnus-summary-generate-hook} is called as the last thing before
7551 doing the threading and the generation of the summary buffer. It's
7552 quite convenient for customizing the threading variables based on what
7553 data the newsgroup has. This hook is called from the summary buffer
7554 after most summary buffer variables has been set.
7556 @vindex gnus-summary-prepare-hook
7557 @code{gnus-summary-prepare-hook} is called after the summary buffer has
7558 been generated. You might use it to, for instance, highlight lines or
7559 modify the look of the buffer in some other ungodly manner. I don't
7562 @node Group Information
7563 @subsection Group Information
7568 @kindex H f (Summary)
7569 @findex gnus-summary-fetch-faq
7570 @vindex gnus-group-faq-directory
7571 Try to fetch the FAQ (list of frequently asked questions) for the
7572 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
7573 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
7574 on a remote machine. This variable can also be a list of directories.
7575 In that case, giving a prefix to this command will allow you to choose
7576 between the various sites. @code{ange-ftp} probably will be used for
7580 @kindex H d (Summary)
7581 @findex gnus-summary-describe-group
7582 Give a brief description of the current group
7583 (@code{gnus-summary-describe-group}). If given a prefix, force
7584 rereading the description from the server.
7587 @kindex H h (Summary)
7588 @findex gnus-summary-describe-briefly
7589 Give a very brief description of the most important summary keystrokes
7590 (@code{gnus-summary-describe-briefly}).
7593 @kindex H i (Summary)
7594 @findex gnus-info-find-node
7595 Go to the Gnus info node (@code{gnus-info-find-node}).
7598 @node Searching for Articles
7599 @subsection Searching for Articles
7604 @kindex M-s (Summary)
7605 @findex gnus-summary-search-article-forward
7606 Search through all subsequent articles for a regexp
7607 (@code{gnus-summary-search-article-forward}).
7610 @kindex M-r (Summary)
7611 @findex gnus-summary-search-article-backward
7612 Search through all previous articles for a regexp
7613 (@code{gnus-summary-search-article-backward}).
7617 @findex gnus-summary-execute-command
7618 This command will prompt you for a header field, a regular expression to
7619 match on this field, and a command to be executed if the match is made
7620 (@code{gnus-summary-execute-command}).
7623 @kindex M-& (Summary)
7624 @findex gnus-summary-universal-argument
7625 Perform any operation on all articles that have been marked with
7626 the process mark (@code{gnus-summary-universal-argument}).
7629 @node Really Various Summary Commands
7630 @subsection Really Various Summary Commands
7635 @kindex A D (Summary)
7636 @findex gnus-summary-enter-digest-group
7637 If the current article is a collection of other articles (for instance,
7638 a digest), you might use this command to enter a group based on the that
7639 article (@code{gnus-summary-enter-digest-group}). Gnus will try to
7640 guess what article type is currently displayed unless you give a prefix
7641 to this command, which forces a "digest" interpretation. Basically,
7642 whenever you see a message that is a collection of other messages on
7643 some format, you @kbd{A D} and read these messages in a more convenient
7647 @kindex C-t (Summary)
7648 @findex gnus-summary-toggle-truncation
7649 Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
7653 @findex gnus-summary-expand-window
7654 Expand the summary buffer window (@code{gnus-summary-expand-window}).
7655 If given a prefix, force an @code{article} window configuration.
7659 @node The Article Buffer
7660 @chapter The Article Buffer
7661 @cindex article buffer
7663 The articles are displayed in the article buffer, of which there is only
7664 one. All the summary buffer share the same article buffer.
7667 * Hiding Headers:: Deciding what headers should be displayed.
7668 * Using Mime:: Pushing articles through @sc{mime} before reading them.
7669 * Customizing Articles:: Tailoring the look of the articles.
7670 * Article Keymap:: Keystrokes available in the article buffer
7671 * Misc Article:: Other stuff.
7675 @node Hiding Headers
7676 @section Hiding Headers
7677 @cindex hiding headers
7678 @cindex deleting headers
7680 The top section of each article is the @dfn{head}. (The rest is the
7681 @dfn{body}, but you may have guessed that already.)
7683 @vindex gnus-show-all-headers
7684 There is a lot of useful information in the head: the name of the person
7685 who wrote the article, the date it was written and the subject of the
7686 article. That's well and nice, but there's also lots of information
7687 most people do not want to see---what systems the article has passed
7688 through before reaching you, the @code{Message-ID}, the
7689 @code{References}, etc. ad nauseum---and you'll probably want to get rid
7690 of some of those lines. If you want to keep all those lines in the
7691 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
7693 Gnus provides you with two variables for sifting headers:
7697 @item gnus-visible-headers
7698 @vindex gnus-visible-headers
7699 If this variable is non-@code{nil}, it should be a regular expression
7700 that says what headers you wish to keep in the article buffer. All
7701 headers that do not match this variable will be hidden.
7703 For instance, if you only want to see the name of the person who wrote
7704 the article and the subject, you'd say:
7707 (setq gnus-visible-headers "^From:\\|^Subject:")
7710 This variable can also be a list of regexps to match headers that are to
7713 @item gnus-ignored-headers
7714 @vindex gnus-ignored-headers
7715 This variable is the reverse of @code{gnus-visible-headers}. If this
7716 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
7717 should be a regular expression that matches all lines that you want to
7718 hide. All lines that do not match this variable will remain visible.
7720 For instance, if you just want to get rid of the @code{References} line
7721 and the @code{Xref} line, you might say:
7724 (setq gnus-ignored-headers "^References:\\|^Xref:")
7727 This variable can also be a list of regexps to match headers that are to
7730 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
7731 variable will have no effect.
7735 @vindex gnus-sorted-header-list
7736 Gnus can also sort the headers for you. (It does this by default.) You
7737 can control the sorting by setting the @code{gnus-sorted-header-list}
7738 variable. It is a list of regular expressions that says in what order
7739 the headers are to be displayed.
7741 For instance, if you want the name of the author of the article first,
7742 and then the subject, you might say something like:
7745 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
7748 Any headers that are to remain visible, but are not listed in this
7749 variable, will be displayed in random order after all the headers that
7750 are listed in this variable.
7756 Mime is a standard for waving your hands through the air, aimlessly,
7757 while people stand around yawning.
7759 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
7760 while all newsreaders die of fear.
7762 @sc{mime} may specify what character set the article uses, the encoding
7763 of the characters, and it also makes it possible to embed pictures and
7764 other naughty stuff in innocent-looking articles.
7766 @vindex gnus-show-mime
7767 @vindex gnus-show-mime-method
7768 Gnus handles @sc{mime} by shoving the articles through
7769 @code{gnus-show-mime-method}, which is @code{metamail-buffer} by
7770 default. If @code{gnus-strict-mime} is non-@code{nil}, the @sc{mime}
7771 method will only be used it there are @sc{mime} headers in the article.
7772 Set @code{gnus-show-mime} to @code{t} if you want to use @sc{mime} all
7773 the time; it might be best to just use the toggling functions from the
7774 summary buffer to avoid getting nasty surprises. (For instance, you
7775 enter the group @samp{alt.sing-a-long} and, before you know it,
7776 @sc{mime} has decoded the sound file in the article and some horrible
7777 sing-a-long song comes streaming out out your speakers, and you can't
7778 find the volume button, because there isn't one, and people are starting
7779 to look at you, and you try to stop the program, but you can't, and you
7780 can't find the program to control the volume, and everybody else in the
7781 room suddenly decides to look at you disdainfully, and you'll feel
7784 Any similarity to real events and people is purely coincidental. Ahem.
7787 @node Customizing Articles
7788 @section Customizing Articles
7789 @cindex article customization
7791 @vindex gnus-article-display-hook
7792 The @code{gnus-article-display-hook} is called after the article has
7793 been inserted into the article buffer. It is meant to handle all
7794 treatment of the article before it is displayed.
7796 By default it contains @code{gnus-article-hide-headers},
7797 @code{gnus-article-treat-overstrike}, and
7798 @code{gnus-article-maybe-highlight}, but there are thousands, nay
7799 millions, of functions you can put in this hook. For an overview of
7800 functions @xref{Article Highlighting}, @xref{Article Hiding},
7801 @xref{Article Washing}, @xref{Article Buttons} and @xref{Article Date}.
7803 You can, of course, write your own functions. The functions are called
7804 from the article buffer, and you can do anything you like, pretty much.
7805 There is no information that you have to keep in the buffer---you can
7806 change everything. However, you shouldn't delete any headers. Instead
7807 make them invisible if you want to make them go away.
7810 @node Article Keymap
7811 @section Article Keymap
7813 @c Most of the keystrokes in the summary buffer can also be used in the
7814 @c article buffer. They should behave as if you typed them in the summary
7815 @c buffer, which means that you don't actually have to have a summary
7816 @c buffer displayed while reading. You can do it all from the article
7819 A few additional keystrokes are available:
7824 @kindex SPACE (Article)
7825 @findex gnus-article-next-page
7826 Scroll forwards one page (@code{gnus-article-next-page}).
7829 @kindex DEL (Article)
7830 @findex gnus-article-prev-page
7831 Scroll backwards one page (@code{gnus-article-prev-page}).
7834 @kindex C-c ^ (Article)
7835 @findex gnus-article-refer-article
7836 If point is in the neighborhood of a @code{Message-ID} and you press
7837 @kbd{r}, Gnus will try to get that article from the server
7838 (@code{gnus-article-refer-article}).
7841 @kindex C-c C-m (Article)
7842 @findex gnus-article-mail
7843 Send a reply to the address near point (@code{gnus-article-mail}). If
7844 given a prefix, include the mail.
7848 @findex gnus-article-show-summary
7849 Reconfigure the buffers so that the summary buffer becomes visible
7850 (@code{gnus-article-show-summary}).
7854 @findex gnus-article-describe-briefly
7855 Give a very brief description of the available keystrokes
7856 (@code{gnus-article-describe-briefly}).
7859 @kindex TAB (Article)
7860 @findex gnus-article-next-button
7861 Go to the next button, if any (@code{gnus-article-next-button}. This
7862 only makes sense if you have buttonizing turned on.
7865 @kindex M-TAB (Article)
7866 @findex gnus-article-prev-button
7867 Go to the previous button, if any (@code{gnus-article-prev-button}.
7873 @section Misc Article
7877 @item gnus-single-article-buffer
7878 @vindex gnus-single-article-buffer
7879 If non-@code{nil}, use the same article buffer for all the groups.
7880 (This is the default.) If @code{nil}, each group will have its own
7883 @vindex gnus-article-prepare-hook
7885 @item gnus-article-prepare-hook
7886 This hook is called right after the article has been inserted into the
7887 article buffer. It is mainly intended for functions that do something
7888 depending on the contents; it should probably not be used for changing
7889 the contents of the article buffer.
7890 @vindex gnus-article-display-hook
7892 @item gnus-article-display-hook
7893 This hook is called as the last thing when displaying an article, and is
7894 intended for modifying the contents of the buffer, doing highlights,
7895 hiding headers, and the like.
7896 @vindex gnus-article-mode-line-format
7898 @item gnus-article-mode-line-format
7899 This variable is a format string along the same lines as
7900 @code{gnus-summary-mode-line-format}. It accepts exactly the same
7901 format specifications as that variable.
7902 @vindex gnus-break-pages
7904 @item gnus-break-pages
7905 Controls whether @dfn{page breaking} is to take place. If this variable
7906 is non-@code{nil}, the articles will be divided into pages whenever a
7907 page delimiter appears in the article. If this variable is @code{nil},
7908 paging will not be done.
7910 @item gnus-page-delimiter
7911 @vindex gnus-page-delimiter
7912 This is the delimiter mentioned above. By default, it is @samp{^L}
7916 @node The Server Buffer
7917 @chapter The Server Buffer
7919 Traditionally, a @dfn{server} is a machine or a piece of software that
7920 one connects to, and then requests information from. Gnus does not
7921 connect directly to any real servers, but does all transactions through
7922 one backend or other. But that's just putting one layer more between
7923 the actual media and Gnus, so we might just as well say that each
7924 backend represents a virtual server.
7926 For instance, the @code{nntp} backend may be used to connect to several
7927 different actual @sc{nntp} servers, or, perhaps, to many different ports
7928 on the same actual @sc{nntp} server. You tell Gnus which backend to
7929 use, and what parameters to set by specifying a @dfn{select method}.
7931 These select methods specifications can sometimes become quite
7932 complicated---say, for instance, that you want to read from the
7933 @sc{nntp} server @samp{news.funet.fi} on port number @samp{13}, which
7934 hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
7935 Anyways, if you had to specify that for each group that used this
7936 server, that would be too much work, so Gnus offers a way of putting
7937 names to methods, which is what you do in the server buffer.
7939 To enter the server buffer, user the @kbd{^}
7940 (@code{gnus-group-enter-server-mode}) command in the group buffer.
7943 * Server Buffer Format:: You can customize the look of this buffer.
7944 * Server Commands:: Commands to manipulate servers.
7945 * Example Methods:: Examples server specifications.
7946 * Servers & Methods:: You can use server names as select methods.
7947 * Unavailable Servers:: Some servers you try to contact may be down.
7950 @node Server Buffer Format
7951 @section Server Buffer Format
7952 @cindex server buffer format
7954 @vindex gnus-server-line-format
7955 You can change the look of the server buffer lines by changing the
7956 @code{gnus-server-line-format} variable. This is a @code{format}-like
7957 variable, with some simple extensions:
7962 How the news is fetched---the backend name.
7965 The name of this server.
7968 Where the news is to be fetched from---the address.
7971 @node Server Commands
7972 @section Server Commands
7973 @cindex server commands
7978 Browse the current server (@code{gnus-server-read-server}).
7981 Return to the group buffer (@code{gnus-server-exit}).
7984 List all servers (@code{gnus-server-list-servers}).
7987 Kill the current server (@code{gnus-server-kill-server}).
7990 Yank the previously killed server (@code{gnus-server-yank-server}).
7993 Copy the current server (@code{gnus-server-copy-server}).
7996 Add a new server (@code{gnus-server-add-server}).
7999 Edit a server (@code{gnus-server-edit-server}).
8002 @node Example Methods
8003 @section Example Methods
8005 Most select methods are pretty simple and self-explanatory:
8008 (nntp "news.funet.fi")
8011 Reading directly from the spool is even simpler:
8017 As you can see, the first element in a select method is the name of the
8018 backend, and the second is the @dfn{address}, or @dfn{name}, if you
8021 After these two elements, there may be a random number of @var{(variable
8024 To go back to the first example---imagine that you want to read from
8025 port @code{15} from that machine. This is what the select method should
8029 (nntp "news.funet.fi" (nntp-port-number 15))
8032 You should read the documentation to each backend to find out what
8033 variables are relevant, but here's an @code{nnmh} example.
8035 @code{nnmh} is a mail backend that reads a spool-like structure. Say
8036 you have two structures that you wish to access: One is your private
8037 mail spool, and the other is a public one. Here's the possible spec for
8041 (nnmh "private" (nnmh-directory "~/private/mail/"))
8044 (This server is then called @samp{private}, but you may have guessed
8047 Here's the method for the public spool:
8051 (nnmh-directory "/usr/information/spool/")
8052 (nnmh-get-new-mail nil))
8055 @node Servers & Methods
8056 @section Servers & Methods
8058 Wherever you would normally use a select method
8059 (eg. @code{gnus-secondary-select-method}, in the group select method,
8060 when browsing a foreign server) you can use a virtual server name
8061 instead. This could potentially save lots of typing. And it's nice all
8065 @node Unavailable Servers
8066 @section Unavailable Servers
8068 If a server seems to be unreachable, Gnus will mark that server as
8069 @code{denied}. That means that any subsequent attempt to make contact
8070 with that server will just be ignored. "It can't be opened," Gnus will
8071 tell you, without making the least effort to see whether that is
8072 actually the case or not.
8074 That might seem quite naughty, but it does make sense most of the time.
8075 Let's say you have 10 groups subscribed to the server
8076 @samp{nepholococcygia.com}. This server is located somewhere quite far
8077 away from you, the machine is quite, so it takes 1 minute just to find
8078 out that it refuses connection from you today. If Gnus were to attempt
8079 to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
8080 that. Once it has gotten a single "connection refused", it will regard
8081 that server as "down".
8083 So, what happens if the machine was only feeling unwell temporarily?
8084 How do you test to see whether the machine has come up again?
8086 You jump to the server buffer (@pxref{The Server Buffer}) and poke ut
8087 with the following commands:
8093 @findex gnus-server-open-server
8094 Try to establish connection to the server on the current line
8095 (@code{gnus-server-open-server}).
8099 @findex gnus-server-close-server
8100 Close the connection (if any) to the server
8101 (@code{gnus-server-close-server}).
8105 @findex gnus-server-deny-server
8106 Mark the current server as unreachable
8107 (@code{gnus-server-deny-server}).
8111 @findex gnus-server-remove-denials
8112 Remove all marks to whether Gnus was denied connection from all servers
8113 (@code{gnus-server-remove-denials}).
8122 Other people use @dfn{kill files}, but we here at Gnus Towers like
8123 scoring better than killing, so we'd rather switch than fight. They do
8124 something completely different as well, so sit up straight and pay
8127 @vindex gnus-summary-mark-below
8128 All articles have a default score (@code{gnus-summary-default-score}),
8129 which is 0 by default. This score may be raised or lowered either
8130 interactively or by score files. Articles that have a score lower than
8131 @code{gnus-summary-mark-below} are marked as read.
8133 Gnus will read any @dfn{score files} that apply to the current group
8134 before generating the summary buffer.
8136 There are several commands in the summary buffer that insert score
8137 entries based on the current article. You can, for instance, ask Gnus to
8138 lower or increase the score of all articles with a certain subject.
8140 There are two sorts of scoring entries: Permanent and temporary.
8141 Temporary score entries are self-expiring entries. Any entries that are
8142 temporary and have not been used for, say, a week, will be removed
8143 silently to help keep the sizes of the score files down.
8146 * Summary Score Commands:: Adding score entries for the current group.
8147 * Group Score Commands:: General score commands.
8148 * Score Variables:: Customize your scoring. (My, what terminology).
8149 * Score File Format:: What a score file may contain.
8150 * Score File Editing:: You can edit score files by hand as well.
8151 * Adaptive Scoring:: Big Sister Gnus *knows* what you read.
8152 * Followups To Yourself:: Having Gnus notice when people answer you.
8153 * Scoring Tips:: How to score effectively.
8154 * Reverse Scoring:: That problem child of old is not problem.
8155 * Global Score Files:: Earth-spanning, ear-splitting score files.
8156 * Kill Files:: They are still here, but they can be ignored.
8159 @node Summary Score Commands
8160 @section Summary Score Commands
8161 @cindex score commands
8163 The score commands that alter score entries do not actually modify real
8164 score files. That would be too inefficient. Gnus maintains a cache of
8165 previously loaded score files, one of which is considered the
8166 @dfn{current score file alist}. The score commands simply insert
8167 entries into this list, and upon group exit, this list is saved.
8169 The current score file is by default the group's local score file, even
8170 if no such score file actually exists. To insert score commands into
8171 some other score file (eg. @file{all.SCORE}), you must first make this
8172 score file the current one.
8174 General score commands that don't actually change the score file:
8179 @kindex V s (Summary)
8180 @findex gnus-summary-set-score
8181 Set the score of the current article (@code{gnus-summary-set-score}).
8184 @kindex V S (Summary)
8185 @findex gnus-summary-current-score
8186 Display the score of the current article
8187 (@code{gnus-summary-current-score}).
8190 @kindex V t (Summary)
8191 @findex gnus-score-find-trace
8192 Display all score rules that have been used on the current article
8193 (@code{gnus-score-find-trace}).
8197 @findex gnus-summary-rescore
8198 Run the current summary through the scoring process
8199 (@code{gnus-summary-rescore}). This might be useful if you're playing
8200 around with your score files behind Gnus' back and want to see the
8201 effect you're having.
8204 @kindex V a (Summary)
8205 @findex gnus-summary-score-entry
8206 Add a new score entry, and allow specifying all elements
8207 (@code{gnus-summary-score-entry}).
8210 @kindex V c (Summary)
8211 @findex gnus-score-change-score-file
8212 Make a different score file the current
8213 (@code{gnus-score-change-score-file}).
8216 @kindex V e (Summary)
8217 @findex gnus-score-edit-alist
8218 Edit the current score file (@code{gnus-score-edit-alist}). You will be
8219 popped into a @code{gnus-score-mode} buffer (@pxref{Score File
8223 @kindex V f (Summary)
8224 @findex gnus-score-edit-file
8225 Edit a score file and make this score file the current one
8226 (@code{gnus-score-edit-file}).
8229 @kindex V C (Summary)
8230 @findex gnus-score-customize
8231 Customize a score file in a visually pleasing manner
8232 (@code{gnus-score-customize}).
8235 @kindex I C-i (Summary)
8236 @findex gnus-summary-raise-score
8237 Increase the score of the current article
8238 (@code{gnus-summary-raise-score}).
8241 @kindex L C-l (Summary)
8242 @findex gnus-summary-lower-score
8243 Lower the score of the current article
8244 (@code{gnus-summary-lower-score}).
8247 The rest of these commands modify the local score file.
8252 @kindex V m (Summary)
8253 @findex gnus-score-set-mark-below
8254 Prompt for a score, and mark all articles with a score below this as
8255 read (@code{gnus-score-set-mark-below}).
8258 @kindex V E (Summary)
8259 @findex gnus-score-set-expunge-below
8260 Expunge all articles with a score below the default score (or the
8261 numeric prefix) (@code{gnus-score-set-expunge-below}).
8264 The keystrokes for actually making score entries follow a very regular
8265 pattern, so there's no need to list all the commands. (Hundreds of
8270 The first key is either @kbd{I} (upper case i) for increasing the score
8271 or @kbd{L} for lowering the score.
8273 The second key says what header you want to score on. The following
8278 Score on the author name.
8281 Score on the subject line.
8284 Score on the Xref line---i.e., the cross-posting line.
8287 Score on thread---the References line.
8293 Score on the number of lines.
8296 Score on the Message-ID.
8309 The third key is the match type. Which match types are legal depends on
8310 what headers you are scoring on.
8354 Greater than number.
8359 The fourth and final key says whether this is a temporary (i.e., expiring)
8360 score entry, or a permanent (i.e., non-expiring) score entry, or whether
8361 it is to be done immediately, without adding to the score file.
8365 Temporary score entry.
8368 Permanent score entry.
8371 Immediately scoring.
8376 So, let's say you want to increase the score on the current author with
8377 exact matching permanently: @kbd{I a e p}. If you want to lower the
8378 score based on the subject line, using substring matching, and make a
8379 temporary score entry: @kbd{L s s t}. Pretty easy.
8381 To make things a bit more complicated, there are shortcuts. If you use
8382 a capital letter on either the second or third keys, Gnus will use
8383 defaults for the remaining one or two keystrokes. The defaults are
8384 "substring" and "temporary". So @kbd{I A} is the same as @kbd{I a s t},
8385 and @kbd{I a R} is the same as @kbd{I a r t}.
8387 @vindex gnus-score-mimic-keymap
8388 The @code{gnus-score-mimic-keymap} says whether these commands will
8389 pretend they are keymaps or not.
8392 @node Group Score Commands
8393 @section Group Score Commands
8394 @cindex group score commands
8396 There aren't many of these as yet, I'm afraid.
8402 @findex gnus-score-flush-cache
8403 Gnus maintains a cache of score alists to avoid having to reload them
8404 all the time. This command will flush the cache
8405 (@code{gnus-score-flush-cache}).
8410 @node Score Variables
8411 @section Score Variables
8412 @cindex score variables
8416 @item gnus-use-scoring
8417 @vindex gnus-use-scoring
8418 If @code{nil}, Gnus will not check for score files, and will not, in
8419 general, do any score-related work. This is @code{t} by default.
8421 @item gnus-kill-killed
8422 @vindex gnus-kill-killed
8423 If this variable is @code{nil}, Gnus will never apply score files to
8424 articles that have already been through the kill process. While this
8425 may save you lots of time, it also means that if you apply a kill file
8426 to a group, and then change the kill file and want to run it over you
8427 group again to kill more articles, it won't work. You have to set this
8428 variable to @code{t} to do that. (It is @code{t} by default.)
8430 @item gnus-kill-files-directory
8431 @vindex gnus-kill-files-directory
8432 All kill and score files will be stored in this directory, which is
8433 initialized from the @samp{SAVEDIR} environment variable by default.
8434 This is @file{~/News/} by default.
8436 @item gnus-score-file-suffix
8437 @vindex gnus-score-file-suffix
8438 Suffix to add to the group name to arrive at the score file name
8439 (@samp{SCORE} by default.)
8441 @item gnus-score-uncacheable-files
8442 @vindex gnus-score-uncacheable-files
8444 All score files are normally cached to avoid excessive re-loading of
8445 score files. However, if this might make you Emacs grow big and
8446 bloated, so this regexp can be used to weed out score files that are
8447 unlikely to be needed again. It would be a bad idea to deny caching of
8448 @file{all.SCORE}, while it might be a good idea to not cache
8449 @file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
8450 variable is @samp{"ADAPT$"} by default, so no adaptive score files will
8453 @item gnus-save-score
8454 @vindex gnus-save-score
8455 If you have really complicated score files, and do lots of batch
8456 scoring, then you might set this variable to @code{t}. This will make
8457 Gnus save the scores into the @file{.newsrc.eld} file.
8459 @item gnus-save-score
8460 @vindex gnus-save-score
8461 If you have really complicated score files, and do lots of batch
8462 scoring, then you might set this variable to @code{t}. This will make
8463 Gnus save the scores into the @file{.newsrc.eld} file.
8465 @item gnus-score-interactive-default-score
8466 @vindex gnus-score-interactive-default-score
8467 Score used by all the interactive raise/lower commands to raise/lower
8468 score with. Default is 1000, which may seem excessive, but this is to
8469 ensure that the adaptive scoring scheme gets enough room to play with.
8470 We don't want the small changes from the adaptive scoring to overwrite
8471 manually entered data.
8473 @item gnus-summary-default-score
8474 @vindex gnus-summary-default-score
8475 Default score of an article, which is 0 by default.
8477 @item gnus-score-over-mark
8478 @vindex gnus-score-over-mark
8479 Mark (in the third column) used for articles with a score over the
8480 default. Default is @samp{+}.
8482 @item gnus-score-below-mark
8483 @vindex gnus-score-below-mark
8484 Mark (in the third column) used for articles with a score below the
8485 default. Default is @samp{-}.
8487 @item gnus-score-find-score-files-function
8488 @vindex gnus-score-find-score-files-function
8489 Function used to find score files for the current group. This function
8490 is called with the name of the group as the argument.
8492 Predefined functions available are:
8495 @item gnus-score-find-single
8496 @findex gnus-score-find-single
8497 Only apply the group's own score file.
8499 @item gnus-score-find-bnews
8500 @findex gnus-score-find-bnews
8501 Apply all score files that match, using bnews syntax. This is the
8502 default. For instance, if the current group is @samp{gnu.emacs.gnus},
8503 @samp{all.emacs.all.SCORE}, @samp{not.alt.all.SCORE} and
8504 @samp{gnu.all.SCORE} would all apply. In short, the instances of
8505 @samp{all} in the score file names are translated into @samp{.*}, and
8506 then a regexp match is done.
8508 This means that if you have some score entries that you want to apply to
8509 all groups, then you put those entries in the @file{all.SCORE} file.
8511 If @code{gnus-use-long-file-name} is non-@code{nil}, this won't work
8512 very will. It will find stuff like @file{gnu/all/SCORE}, but will not
8513 find files like @file{not/gnu/all/SCORE}.
8515 @item gnus-score-find-hierarchical
8516 @findex gnus-score-find-hierarchical
8517 Apply all score files from all the parent groups. This means that you
8518 can't have score files like @file{all.SCORE} or @file{all.emacs.SCORE},
8519 but you can have @file{SCORE}, @file{comp.SCORE} and
8520 @file{comp.emacs.SCORE}.
8523 This variable can also be a list of functions. In that case, all these
8524 functions will be called, and all the returned lists of score files will
8525 be applied. These functions can also return lists of score alists
8526 directly. In that case, the functions that return these non-file score
8527 alists should probably be placed before the "real" score file functions,
8528 to ensure that the last score file returned is the local score file.
8531 @item gnus-score-expiry-days
8532 @vindex gnus-score-expiry-days
8533 This variable says how many days should pass before an unused score file
8534 entry is expired. The default is 7.
8537 @node Score File Format
8538 @section Score File Format
8539 @cindex score file format
8541 A score file is an @code{emacs-lisp} file that normally contains just a
8542 single form. Casual users are not expected to edit these files;
8543 everything can be changed from the summary buffer.
8545 Anyway, if you'd like to dig into it yourself, here's an example:
8549 ("Lars Ingebrigtsen" -10000)
8551 ("larsi\\|lmi" -50000 nil R))
8553 ("Ding is Badd" nil 728373))
8555 ("alt.politics" -1000 728372 s))
8560 (mark-and-expunge -10)
8564 (files "/hom/larsi/News/gnu.SCORE")
8565 (exclude-files "all.SCORE")
8566 (local (gnus-newsgroup-auto-expire t)
8567 (gnus-summary-make-false-root 'empty))
8571 This example demonstrates absolutely everything about a score file.
8573 Even though this looks much like lisp code, nothing here is actually
8574 @code{eval}ed. The lisp reader is used to read this form, though, so it
8575 has to be legal syntactically, if not semantically.
8577 Six keys are supported by this alist:
8582 If the key is a string, it is the name of the header to perform the
8583 match on. Scoring can only be performed on these eight headers:
8584 @samp{From}, @samp{Subject}, @samp{References}, @samp{Message-ID},
8585 @samp{Xref}, @samp{Lines}, @samp{Chars} and @samp{Date}. In addition to
8586 these headers, there are three strings to tell Gnus to fetch the entire
8587 article and do the match on larger parts of the article: @samp{Body}
8588 will perform the match on the body of the article, @samp{Head} will
8589 perform the match on the head of the article, and @samp{All} will
8590 perform the match on the entire article. Note that using any of these
8591 last three keys will slow down group entry @emph{considerably}. The
8592 final "header" you can score on is @samp{Followup}. These score entries
8593 will result in new score entries being added for all follow-ups to
8594 articles that matches these score entries.
8596 Following this key is a random number of score entries, where each score
8597 entry has one to four elements.
8601 The first element is the @dfn{match element}. On most headers this will
8602 be a string, but on the Lines and Chars headers, this must be an
8606 If the second element is present, it should be a number---the @dfn{score
8607 element}. This number should be an integer in the neginf to posinf
8608 interval. This number is added to the score of the article if the match
8609 is successful. If this element is not present, the
8610 @code{gnus-score-interactive-default-score} number will be used
8611 instead. This is 1000 by default.
8614 If the third element is present, it should be a number---the @dfn{date
8615 element}. This date says when the last time this score entry matched,
8616 which provides a mechanism for expiring the score entries. It this
8617 element is not present, the score entry is permanent. The date is
8618 represented by the number of days since December 31, 1 ce.
8621 If the fourth element is present, it should be a symbol---the @dfn{type
8622 element}. This element specifies what function should be used to see
8623 whether this score entry matches the article. What match types that can
8624 be used depends on what header you wish to perform the match on.
8627 @item From, Subject, References, Xref, Message-ID
8628 For most header types, there are the @code{r} and @code{R} (regexp) as
8629 well as @code{s} and @code{S} (substring) types and @code{e} and
8630 @code{E} (exact match) types. If this element is not present, Gnus will
8631 assume that substring matching should be used. @code{R} and @code{S}
8632 differ from the other two in that the matches will be done in a
8633 case-sensitive manner. All these one-letter types are really just
8634 abbreviations for the @code{regexp}, @code{string} and @code{exact}
8635 types, which you can use instead, if you feel like.
8638 These two headers use different match types: @code{<}, @code{>},
8639 @code{=}, @code{>=} and @code{<=}.
8642 For the Date header we have three match types: @code{before}, @code{at}
8643 and @code{after}. I can't really imagine this ever being useful, but,
8644 like, it would feel kinda silly not to provide this function. Just in
8645 case. You never know. Better safe than sorry. Once burnt, twice shy.
8646 Don't judge a book by its cover. Never not have sex on a first date.
8648 @item Head, Body, All
8649 These three match keys use the same match types as the @code{From} (etc)
8653 This match key will add a score entry on all articles that followup to
8654 some author. Uses the same match types as the @code{From} header uses.
8659 The value of this entry should be a number. Any articles with a score
8660 lower than this number will be marked as read.
8663 The value of this entry should be a number. Any articles with a score
8664 lower than this number will be removed from the summary buffer.
8666 @item mark-and-expunge
8667 The value of this entry should be a number. Any articles with a score
8668 lower than this number will be marked as read and removed from the
8671 @item thread-mark-and-expunge
8672 The value of this entry should be a number. All articles that belong to
8673 a thread that has a total score below this number will be marked as read
8674 and removed from the summary buffer. @code{gnus-thread-score-function}
8675 says how to compute the total score for a thread.
8678 The value of this entry should be any number of file names. These files
8679 are assumed to be score files as well, and will be loaded the same way
8683 The clue of this entry should be any number of files. This files will
8684 not be loaded, even though they would normally be so, for some reason or
8688 The value of this entry will be @code{eval}el. This element will be
8689 ignored when handling global score files.
8692 Read-only score files will not be updated or saved. Global score files
8693 should feature this atom (@pxref{Global Score Files}).
8696 The value of this entry should be a number. Articles that do not have
8697 parents will get this number added to their scores.
8700 This entry controls the adaptive scoring. If it is @code{t}, the
8701 default adaptive scoring rules will be used. If it is @code{ignore}, no
8702 adaptive scoring will be performed on this group. If it is a list, this
8703 list will be used as the adaptive scoring rules. If it isn't present,
8704 or is something other than @code{t} or @code{ignore}, the default
8705 adaptive scoring rules will be used. If you want to use adaptive
8706 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
8707 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
8708 not want adaptive scoring. If you only want adaptive scoring in a few
8709 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
8710 insert @code{(adapt t)} in the score files of the groups where you want
8714 All adaptive score entries will go to the file named by this entry. It
8715 will also be applied when entering the group. This atom might be handy
8716 if you want to adapt on several groups at once, using the same adaptive
8717 file for a number of groups.
8720 @cindex local variables
8721 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
8722 Each @var{var} will be made buffer-local to the current summary buffer,
8723 and set to the value specified. This is a convenient, if somewhat
8724 strange, way of setting variables in some groups if you don't like hooks
8728 @node Score File Editing
8729 @section Score File Editing
8731 You normally enter all scoring commands from the summary buffer, but you
8732 might feel the urge to edit them by hand as well, so we've supplied you
8733 with a mode for that.
8735 It's simply a slightly customized @code{emacs-lisp} mode, with these
8736 additional commands:
8741 @kindex C-c C-c (Score)
8742 @findex gnus-score-edit-done
8743 Save the changes you have made and return to the summary buffer
8744 (@code{gnus-score-edit-done}).
8747 @kindex C-c C-d (Score)
8748 @findex gnus-score-edit-insert-date
8749 Insert the current date in numerical format
8750 (@code{gnus-score-edit-insert-date}). This is really the day number, if
8754 @node Adaptive Scoring
8755 @section Adaptive Scoring
8756 @cindex adaptive scoring
8758 If all this scoring is getting you down, Gnus has a way of making it all
8759 happen automatically---as if by magic. Or rather, as if by artificial
8760 stupidity, to be precise.
8762 @vindex gnus-use-adaptive-scoring
8763 When you read an article, or mark an article as read, or kill an
8764 article, you leave marks behind. On exit from the group, Gnus can sniff
8765 these marks and add score elements depending on what marks it finds.
8766 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
8769 @vindex gnus-default-adaptive-score-alist
8770 To give you complete control over the scoring process, you can customize
8771 the @code{gnus-default-adaptive-score-alist} variable. By default, it
8772 looks something like this:
8775 (defvar gnus-default-adaptive-score-alist
8776 '((gnus-unread-mark)
8777 (gnus-ticked-mark (from 4))
8778 (gnus-dormant-mark (from 5))
8779 (gnus-del-mark (from -4) (subject -1))
8780 (gnus-read-mark (from 4) (subject 2))
8781 (gnus-expirable-mark (from -1) (subject -1))
8782 (gnus-killed-mark (from -1) (subject -3))
8783 (gnus-kill-file-mark)
8784 (gnus-catchup-mark (from -1) (subject -1))))
8787 As you see, each element in this alist has a mark as a key (either a
8788 variable name or a "real" mark---a character). Following this key is a
8789 random number of header/score pairs.
8791 To take @code{gnus-del-mark} as an example---this alist says that all
8792 articles that have that mark (i.e., are marked with @samp{D}) will have a
8793 score entry added to lower based on the @code{From} header by -4, and
8794 lowered by @code{Subject} by -1. Change this to fit your prejudices.
8796 The headers you can score on are @code{from}, @code{subject},
8797 @code{message-id}, @code{references}, @code{xref}, @code{lines},
8798 @code{chars} and @code{date}. In addition, you can score on
8799 @code{followup}, which will create an adaptive score entry that matches
8800 on the @code{References} header using the @code{Message-ID} of the
8801 current article, thereby matching the following thread.
8803 If you use this scheme, you should set @code{mark-below} to something
8804 small---like -300, perhaps, to avoid having small random changes result
8805 in articles getting marked as read.
8807 After using adaptive scoring for a week or so, Gnus should start to
8808 become properly trained and enhance the authors you like best, and kill
8809 the authors you like least, without you having to say so explicitly.
8811 You can control what groups the adaptive scoring is to be performed on
8812 by using the score files (@pxref{Score File Format}). This will also
8813 let you use different rules in different groups.
8815 @vindex gnus-adaptive-file-suffix
8816 The adaptive score entries will be put into a file where the name is the
8817 group name with @code{gnus-adaptive-file-suffix} appended. The default
8820 @vindex gnus-score-exact-adapt-limit
8821 When doing adaptive scoring, substring or fuzzy matching would probably
8822 give you the best results in most cases. However, if the header one
8823 matches is short, the possibility for false positives is great, so if
8824 the length of the match is less than
8825 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
8826 this variable is @code{nil}, exact matching will always be used to avoid
8830 @node Followups To Yourself
8831 @section Followups To Yourself
8833 Gnus offers two commands for picking out the @code{Message-ID} header in
8834 the current buffer. Gnus will then add a score rule that scores using
8835 this @code{Message-ID} on the @code{References} header of other
8836 articles. This will, in effect, increase the score of all articles that
8837 respond to the article in the current buffer. Quite useful if you want
8838 to easily note when people answer what you've said.
8842 @item gnus-score-followup-article
8843 @findex gnus-score-followup-article
8844 This will add a score to articles that directly follow up your own
8847 @item gnus-score-followup-thread
8848 @findex gnus-score-followup-thread
8849 This will add a score to all articles that appear in a thread "below"
8853 @vindex gnus-inews-article-hook
8854 These two functions are both primarily meant to be used in hooks like
8855 @code{gnus-inews-article-hook}.
8859 @section Scoring Tips
8860 @cindex scoring tips
8865 If you want to lower the score of crossposts, the line to match on is
8866 the @code{Xref} header.
8868 ("xref" (" talk.politics.misc:" -1000))
8871 @item Multiple crossposts
8872 If you want to lower the score of articles that have been crossposted to
8873 more than, say, 3 groups:
8875 ("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
8878 @item Matching on the body
8879 This is generally not a very good idea---it takes a very long time.
8880 Gnus actually has to fetch each individual article from the server. But
8881 you might want to anyway, I guess. Even though there are three match
8882 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
8883 and stick with it in each score file. If you use any two, each article
8884 will be fetched @emph{twice}. If you want to match a bit on the
8885 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
8888 @item Marking as read
8889 You will probably want to mark articles that has a score below a certain
8890 number as read. This is most easily achieved by putting the following
8891 in your @file{all.SCORE} file:
8895 You may also consider doing something similar with @code{expunge}.
8897 @item Negated charater classes
8898 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
8899 That will match newlines, which might lead to, well, The Unknown. Say
8900 @code{[^abcd\n]*} instead.
8903 @node Reverse Scoring
8904 @section Reverse Scoring
8905 @cindex reverse scoring
8907 If you want to keep just articles that have @samp{Sex with Emacs} in the
8908 subject header, and expunge all other articles, you could put something
8909 like this in your score file:
8913 ("Sex with Emacs" 2))
8918 So, you raise all articles that match @samp{Sex with Emacs} and mark the
8919 rest as read, and expunge them to boot.
8921 @node Global Score Files
8922 @section Global Score Files
8923 @cindex global score files
8925 Sure, other newsreaders have "global kill files". These are usually
8926 nothing more than a single kill file that applies to all groups, stored
8927 in the user's home directory. Bah! Puny, weak newsreaders!
8929 What I'm talking about here are Global Score Files. Score files from
8930 all over the world, from users everywhere, uniting all nations in one
8931 big, happy score file union! Ange-score! New and untested!
8933 @vindex gnus-global-score-files
8934 All you have to do to use other people's score files is to set the
8935 @code{gnus-global-score-files} variable. One entry for each score file,
8936 or each score file directory. Gnus will decide by itself what score
8937 files are applicable to which group.
8939 Say you want to use all score files in the
8940 @file{/ftp@@ftp.some-where:/pub/score} directory and the single score
8941 file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
8944 (setq gnus-global-score-files
8945 '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
8946 "/ftp@@ftp.some-where:/pub/score/"))
8949 @findex gnus-score-search-global-directories
8950 Simple, eh? Directory names must end with a @samp{/}. These
8951 directories are typically scanned only once during each Gnus session.
8952 If you feel the need to manually re-scan the remote directories, you can
8953 use the @code{gnus-score-search-global-directories} command.
8955 Note that, at present, using this option will slow down group entry
8956 somewhat. (That is---a lot.)
8958 If you want to start maintaining score files for other people to use,
8959 just put your score file up for anonymous ftp and announce it to the
8960 world. Become a retro-moderator! Participate in the retro-moderator
8961 wars sure to ensue, where retro-moderators battle it out for the
8962 sympathy of the people, luring them to use their score files on false
8963 premises! Yay! The net is saved!
8965 Here are some tips for the would-be retro-moderator, off the top of my
8971 Articles that are heavily crossposted are probably junk.
8973 To lower a single inappropriate article, lower by @code{Message-ID}.
8975 Particularly brilliant authors can be raised on a permanent basis.
8977 Authors that repeatedly post off-charter for the group can safely be
8978 lowered out of existence.
8980 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
8981 articles completely.
8984 Use expiring score entries to keep the size of the file down. You
8985 should probably have a long expiry period, though, as some sites keep
8986 old articles for a long time.
8989 ... I wonder whether other newsreaders will support global score files
8990 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
8991 Wave, xrn and 1stReader are bound to implement scoring. Should we start
8992 holding our breath yet?
8999 Gnus still supports those pesky old kill files. In fact, the kill file
9000 entries can now be expiring, which is something I wrote before Daniel
9001 Quinlan thought of doing score files, so I've left the code in there.
9003 In short, kill processing is a lot slower (and I do mean @emph{a lot})
9004 than score processing, so it might be a good idea to rewrite your kill
9005 files into score files.
9007 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
9008 forms into this file, which means that you can use kill files as some
9009 sort of primitive hook function to be run on group entry, even though
9010 that isn't a very good idea.
9012 XCNormal kill files look like this:
9015 (gnus-kill "From" "Lars Ingebrigtsen")
9016 (gnus-kill "Subject" "ding")
9020 This will mark every article written by me as read, and remove them from
9021 the summary buffer. Very useful, you'll agree.
9023 Other programs use a totally different kill file syntax. If Gnus
9024 encounters what looks like a @code{rn} kill file, it will take a stab at
9027 Two functions for editing a GNUS kill file:
9032 @kindex M-k (Summary)
9033 @findex gnus-summary-edit-local-kill
9034 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
9037 @kindex M-K (Summary)
9038 @findex gnus-summary-edit-global-kill
9039 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
9042 @vindex gnus-kill-file-name
9043 A kill file for the group @samp{soc.motss} is normally called
9044 @file{soc.motss.KILL}. The suffix appended to the group name to get
9045 this file name is detailed by the @code{gnus-kill-file-name} variable.
9046 The "global" kill file (not in the score file sense of "global", of
9047 course) is called just @file{KILL}.
9049 @vindex gnus-kill-save-kill-file
9050 If @code{gnus-kill-save-kill-file} is non-@code{nil}, Gnus will save the
9051 kill file after processing, which is necessary if you use expiring
9061 * Interactive:: Making Gnus ask you many questions.
9062 * Formatting Variables:: How to control the look of the buffers.
9063 * Windows Configuration:: Configuring the Gnus buffer windows.
9064 * Buttons:: Get tendonitis in ten easy steps!
9065 * Compilation & Init File:: How to speed Gnus up.
9066 * Daemons:: Gnus can do things behind your back.
9067 * NoCeM:: How to avoid spam and other fatty foods.
9068 * Various Various:: Things that are really various.
9072 @section Interactive
9077 @item gnus-novice-user
9078 @vindex gnus-novice-user
9079 If this variable is non-@code{nil}, you are either a newcomer to the
9080 World of Usenet, or you are very cautious, which is a nice thing to be,
9081 really. You will be given questions of the type "Are you sure you want
9082 to do this?" before doing anything dangerous. This is @code{t} by
9085 @item gnus-expert-user
9086 @vindex gnus-expert-user
9087 If this variable is non-@code{nil}, you will never ever be asked any
9088 questions by Gnus. It will simply assume you know what your are doing,
9089 no matter how strange.
9091 @item gnus-interactive-catchup
9092 @vindex gnus-interactive-catchup
9093 Require confirmation before catching up a group if non-@code{nil}. It
9094 is @code{t} by default.
9096 @item gnus-interactive-post
9097 @vindex gnus-interactive-post
9098 If non-@code{nil}, the user will be prompted for a group name when
9099 posting an article. It is @code{t} by default.
9101 @item gnus-interactive-exit
9102 @vindex gnus-interactive-exit
9103 Require confirmation before exiting Gnus. This variable is @code{t} by
9108 @node Formatting Variables
9109 @section Formatting Variables
9110 @cindex formatting variables
9112 Throughout this manual you've probably noticed lots of variables that
9113 are called things like @code{gnus-group-line-format} and
9114 @code{gnus-summary-mode-line-format}. These control how Gnus is to
9115 output lines in the various buffers. There's quite a lot of them.
9116 Fortunately, they all use the same syntax, so there's not that much to
9119 Here's an example format spec (from the group buffer): @samp{"%M%S%5y:
9120 %(%g%)\n"}. We see that it is indeed extremely ugly, and that there are
9121 lots of percentages everywhere.
9123 Each @samp{%} element will be replaced by some string or other when the
9124 buffer in question is generated. @samp{%5y} means "insert the @samp{y}
9125 spec, and pad with spaces to get a 5-character field". Just like a
9126 normal format spec, almost.
9128 You can also say @samp{%6,4y}, which means that the field will never be
9129 more than 6 characters wide and never less than 4 characters wide.
9131 There are also specs for highlighting, and these are shared by all the
9132 format variables. Text inside the @samp{%(} and @samp{%)} specifiers
9133 will get the special @code{mouse-face} property set, which means that it
9134 will be highlighted (with @code{gnus-mouse-face}) when you put the mouse
9137 Text inside the @samp{%@{} and @samp{%@}} specifiers will have their
9138 normal faces set using @code{gnus-face-0}, which is @code{bold} by
9139 default. If you say @samp{%1@{} instead, you'll get @code{gnus-face-1}
9140 instead, and so on. Create as many faces as you wish. The same goes
9141 for the @code{mouse-face} specs---you can say @samp{%3(hello%)} to have
9142 @samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
9144 Here's an alternative recipe for the group buffer:
9147 ;; Create three face types.
9148 (setq gnus-face-1 'bold)
9149 (setq gnus-face-3 'italic)
9151 ;; We want the article count to be in
9152 ;; a bold and green face. So we create
9153 ;; a new face called `my-green-bold'.
9154 (copy-face 'bold 'my-green-bold)
9156 (set-face-foreground 'my-green-bold "ForestGreen")
9157 (setq gnus-face-2 'my-green-bold)
9159 ;; Set the new & fancy format.
9160 (setq gnus-group-line-format
9161 "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
9164 I'm sure you'll be able to use this scheme to create totally unreadable
9165 and extremely vulgar displays. Have fun!
9167 Currently Gnus uses the following formatting variables:
9168 @code{gnus-group-line-format}, @code{gnus-summary-line-format},
9169 @code{gnus-server-line-format}, @code{gnus-topic-line-format},
9170 @code{gnus-group-mode-line-format},
9171 @code{gnus-summary-mode-line-format},
9172 @code{gnus-article-mode-line-format},
9173 @code{gnus-server-mode-line-format}.
9175 Note that the @samp{%(} specs (and friends) do not make any sense on the
9176 mode-line variables.
9178 All these format variables can also be random elisp forms. In that
9179 case, they will be @code{eval}ed to insert the required lines.
9181 @kindex M-x gnus-update-format
9182 @findex gnus-update-format
9183 Gnus includes a command to help you while creating your own format
9184 specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
9185 update the spec in question and pop you to a buffer where you can
9186 examine the resulting lisp code to be run to generate the line.
9189 @node Windows Configuration
9190 @section Windows Configuration
9191 @cindex windows configuration
9193 No, there's nothing here about X, so be quiet.
9195 @vindex gnus-use-full-window
9196 If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all
9197 other windows and occupy the entire Emacs screen by itself. It is
9198 @code{t} by default.
9200 @code{gnus-buffer-configuration} describes how much space each Gnus
9201 buffer should be given. Here's an excerpt of this variable:
9204 ((group (vertical 1.0 (group 1.0 point)
9205 (if gnus-carpal (group-carpal 4))))
9206 (article (vertical 1.0 (summary 0.25 point)
9210 This is an alist. The @dfn{key} is a symbol that names some action or
9211 other. For instance, when displaying the group buffer, the window
9212 configuration function will use @code{group} as the key. A full list of
9213 possible names is listed below.
9215 The @dfn{value} (i. e., the @dfn{split}) says how much space each buffer
9216 should occupy. To take the @code{article} split as an example -
9219 (article (vertical 1.0 (summary 0.25 point)
9223 This @dfn{split} says that the summary buffer should occupy 25% of upper
9224 half of the screen, and that it is placed over the article buffer. As
9225 you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all
9226 reaching for that calculator there). However, the special number
9227 @code{1.0} is used to signal that this buffer should soak up all the
9228 rest of the space avaiable after the rest of the buffers have taken
9229 whatever they need. There should be only one buffer with the @code{1.0}
9230 size spec per split.
9232 Point will be put in the buffer that has the optional third element
9235 Here's a more complicated example:
9238 (article (vertical 1.0 (group 4)
9239 (summary 0.25 point)
9240 (if gnus-carpal (summary-carpal 4))
9244 If the size spec is an integer instead of a floating point number,
9245 then that number will be used to say how many lines a buffer should
9246 occupy, not a percentage.
9248 If the @dfn{split} looks like something that can be @code{eval}ed (to be
9249 precise---if the @code{car} of the split is a function or a subr), this
9250 split will be @code{eval}ed. If the result is non-@code{nil}, it will
9251 be used as a split. This means that there will be three buffers if
9252 @code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal}
9255 Not complicated enough for you? Well, try this on for size:
9258 (article (horizontal 1.0
9263 (summary 0.25 point)
9268 Whoops. Two buffers with the mystery 100% tag. And what's that
9269 @code{horizontal} thingie?
9271 If the first element in one of the split is @code{horizontal}, Gnus will
9272 split the window horizontally, giving you two windows side-by-side.
9273 Inside each of these strips you may carry on all you like in the normal
9274 fashion. The number following @code{horizontal} says what percentage of
9275 the screen is to be given to this strip.
9277 For each split, there @emph{must} be one element that has the 100% tag.
9278 The splitting is never accurate, and this buffer will eat any leftover
9279 lines from the splits.
9281 To be slightly more formal, here's a definition of what a legal split
9285 split = frame | horizontal | vertical | buffer | form
9286 frame = "(frame " frame-size *split ")"
9287 horizontal = "(horizontal " size *split ")"
9288 vertical = "(vertical " size *split ")"
9289 buffer = "(" buffer-name " " size *[ "point" ] ")"
9290 frame-size = "(" number " . " number ")"
9292 buffer-name = group | article | summary ...
9295 The limitations are that the @samp{frame} split can only appear as the
9296 top-level split. @samp{form} should be an Emacs Lisp form that should
9297 return a valid split. We see that each split is fully recursive, and
9298 may contain any number of @samp{vertical} and @samp{horizontal} splits.
9300 Finding the right sizes can be a bit complicated. No window may be less
9301 than 4 characters high, and all windows must be at least 10 characters
9302 wide. Gnus will try to enforce this before applying the splits.
9304 If you're not familiar with Emacs terminology, @samp{horizontal} and
9305 @samp{vertical} splits may work the opposite way of what you'd expect.
9306 Windows inside a @samp{horizontal} split are shown side-by-side, and
9307 windows within a @samp{vertical} split are shown above each other.
9309 @findex gnus-configure-frame
9310 If you want to experiment with window placement, a good tip is to call
9311 @code{gnus-configure-frame} directly with a split. This is the function
9312 that does all the real work when splitting buffers. Below is a pretty
9313 nonsensical configuration with 5 windows; two for the group buffer and
9314 three for the article buffer. (I said it was nonsensical.) If you
9315 @code{eval} the statement below, you can get an idea of how that would
9316 look straight away, without going through the normal Gnus channels.
9317 Play with it until you're satisfied, and then use
9318 @code{gnus-add-configuration} to add your new creation to the buffer
9322 (gnus-configure-frame
9326 (article 0.3 point))
9334 Here's a list of all possible keys for
9335 @code{gnus-buffer-configuaration}:
9337 @code{group}, @code{summary}, @code{article}, @code{server},
9338 @code{browse}, @code{group-mail}, @code{summary-mail},
9339 @code{summary-reply}, @code{info}, @code{summary-faq},
9340 @code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
9341 @code{followup}, @code{followup-yank}, @code{edit-score}.
9343 @findex gnus-add-configuration
9344 Since the @code{gnus-buffer-configuration} variable is so long and
9345 complicated, there's a function you can use to ease changing the config
9346 of a single setting: @code{gnus-add-configuration}. If, for instance,
9347 you want to change the @code{article} setting, you could say:
9350 (gnus-add-configuration
9351 '(article (vertical 1.0
9357 You'd typically stick these @code{gnus-add-configuration} calls in your
9358 @file{.gnus} file or in some startup hook -- they should be run after
9359 Gnus has been loaded.
9368 Those new-fangled @dfn{mouse} contraptions is very popular with the
9369 young, hep kids who don't want to learn the proper way to do things
9370 these days. Why, I remember way back in the summer of '89, when I was
9371 using Emacs on a Tops 20 system. Three hundred users on one single
9372 machine, and every user was running Simula compilers. Bah!
9377 Well, you can make Gnus display bufferfuls of buttons you can click to
9378 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
9379 really. Tell the chiropractor I sent you.
9384 @item gnus-carpal-mode-hook
9385 @vindex gnus-carpal-mode-hook
9386 Hook run in all carpal mode buffers.
9388 @item gnus-carpal-button-face
9389 @vindex gnus-carpal-button-face
9390 Face used on buttons.
9392 @item gnus-carpal-group-buffer-buttons
9393 @vindex gnus-carpal-group-buffer-buttons
9394 Buttons in the group buffer.
9396 @item gnus-carpal-summary-buffer-buttons
9397 @vindex gnus-carpal-summary-buffer-buttons
9398 Buttons in the summary buffer.
9400 @item gnus-carpal-server-buffer-buttons
9401 @vindex gnus-carpal-server-buffer-buttons
9402 Buttons in the server buffer.
9404 @item gnus-carpal-browse-buffer-buttons
9405 @vindex gnus-carpal-browse-buffer-buttons
9406 Buttons in the browse buffer.
9409 All the @code{buttons} variables are lists. The elements in these list
9410 is either a cons cell where the car contains a text to be displayed and
9411 the cdr contains a function symbol, or a simple string.
9414 @node Compilation & Init File
9415 @section Compilation & Init File
9418 @cindex byte-compilation
9420 @vindex gnus-init-file
9421 @findex gnus-compile
9422 When Gnus starts up, it will read the Gnus init file
9423 @code{gnus-init-file}, which is @file{.gnus} by default. It is
9424 recommended that you keep any Gnus-related functions that you have
9425 written in that file. If you want to byte-compile the file, Gnus offers
9426 the handy @kbd{M-x gnus-compile} function that will do that for you.
9428 That's not really why that function was written, though.
9430 Remember all those line format specification variables?
9431 @code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
9432 on. Now, Gnus will of course heed whatever these variables are, but,
9433 unfortunately, changing them will mean a quite significant slow-down.
9434 (The default values of these variables have byte-compiled functions
9435 associated with them, while the user-generated versions do not, of
9438 To help with this, you can run @code{gnus-compile} after you've fiddled
9439 around with the variables and feel that you're (kind of) satisfied.
9440 This will result in the new specs being byte-compiled, and you'll get
9443 The result of these byte-compilations will be written to
9444 @file{.gnus.elc} by default.
9446 Note that Gnus will read @file{.gnus.elc} instead of @file{.gnus} if
9447 @file{.gnus.elc} exists, so if you change @file{.gnus}, you should
9448 remove @file{.gnus.elc}.
9456 Gnus, being larger than any program ever written (allegedly), does lots
9457 of strange stuff that you may wish to have done while you're not
9458 present. For instance, you may want it to check for new mail once in a
9459 while. Or you may want it to close down all connections to all servers
9460 when you leave Emacs idle. And stuff like that.
9462 Gnus will let you do stuff like that by defining various
9463 @dfn{handlers}. Each handler consists of three elements: A
9464 @var{function}, a @var{time}, and an @var{idle} parameter.
9466 Here's an example of a handler that closes connections when Emacs has
9467 been idle for thirty minutes:
9470 (gnus-demon-close-connections nil 30)
9473 Here's a handler that scans for PGP headers every hour when Emacs is
9477 (gnus-demon-scan-pgp 60 t)
9480 This @var{time} parameter and than @var{idle} parameter works together
9481 in a strange, but wonderful fashion. Basically, if @var{idle} is
9482 @code{nil}, then the function will be called every @var{time} minutes.
9484 If @var{idle} is @code{t}, then the function will be called after
9485 @var{time} minutes only if Emacs is idle. So if Emacs is never idle,
9486 the function will never be called. But once Emacs goes idle, the
9487 function will be called every @var{time} minutes.
9489 If @var{idle} is a number and @var{time} is a number, the function will
9490 be called every @var{time} minutes only when Emacs has been idle for
9493 If @var{idle} is a number and @var{time} is @code{nil}, the function
9494 will be called once every time Emacs has been idle for @var{idle}
9497 And if @var{time} is a string, it should look like @samp{"07:31"}, and
9498 the function will then be called once every day somewhere near that
9499 time. Modified by the @var{idle} parameter, of course.
9501 @vindex gnus-demon-timestep
9502 (When I say "minute" here, I really mean @code{gnus-demon-timestep}
9503 seconds. This is @samp{60} by default. If you change that variable,
9504 all the timings in the handlers will be affected.)
9506 @vindex gnus-use-demon
9507 To set the whole thing in motion, though, you have to set
9508 @code{gnus-use-demon} to @code{t}.
9510 @vindex gnus-use-demon
9511 To set the whole thing in motion, though, you have to set
9512 @code{gnus-use-demon} to @code{t}.
9514 So, if you want to add a handler, you could put something like this in
9515 your @file{.gnus} file:
9517 @findex gnus-demon-add-handler
9519 (gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
9522 @findex gnus-demon-add-nocem
9523 @findex gnus-demon-add-scanmail
9524 @findex gnus-demon-add-disconnection
9525 Some ready-made functions to do this has been created:
9526 @code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, and
9527 @code{gnus-demon-add-scanmail}. Just put those functions in your
9528 @file{.gnus} if you want those abilities.
9530 @findex gnus-demon-init
9531 @findex gnus-demon-cancel
9532 @vindex gnus-demon-handlers
9533 If you add handlers to @code{gnus-demon-handlers} directly, you should
9534 run @code{gnus-demon-init} to make the changes take hold. To cancel all
9535 daemons, you can use the @code{gnus-demon-cancel} function.
9537 Note that adding daemons can be pretty naughty if you overdo it. Adding
9538 functions that scan all news and mail from all servers every two seconds
9539 is a sure-fire way of getting booted off any respectable system. So
9550 @node Various Various
9551 @section Various Various
9558 @vindex gnus-verbose
9559 This variable is an integer between zero and ten. The higher the value,
9560 the more messages will be displayed. If this variable is zero, Gnus
9561 will never flash any messages, if it is seven (which is the default),
9562 most important messages will be shown, and if it is ten, Gnus won't ever
9563 shut up, but will flash so many messages it will make your head swim.
9565 @item gnus-updated-mode-lines
9566 @vindex gnus-updated-mode-lines
9567 This is a list of buffers that should keep their mode lines updated.
9568 The list may contain the symbols @code{group}, @code{article} and
9569 @code{summary}. If the corresponding symbol is present, Gnus will keep
9570 that mode line updated with information that may be pertinent. If this
9571 variable is @code{nil}, screen refresh may be quicker.
9573 @cindex display-time
9575 @item gnus-mode-non-string-length
9576 @vindex gnus-mode-non-string-length
9577 By default, Gnus displays information on the current article in the mode
9578 lines of the summary and article buffers. The information Gnus wishes
9579 to display (eg. the subject of the article) is often longer than the
9580 mode lines, and therefore have to be cut off at some point. This
9581 variable says how long the other elements on the line is (i.e., the
9582 non-info part). If you put additional elements on the mode line (eg. a
9583 clock), you should modify this variable:
9585 @c Hook written by Keinonen Kari <kk85613@cs.tut.fi>.
9587 (add-hook 'display-time-hook
9589 (setq gnus-mode-non-string-length
9590 (+ 21 (length display-time-string)))))
9593 If this variable is @code{nil} (which is the default), the mode line
9594 strings won't be chopped off, and they won't be padded either.
9599 @cindex highlighting
9602 If @code{nil}, Gnus won't attempt to create menus or use fancy colors
9603 or fonts. This will also inhibit loading the @file{gnus-visual.el}
9606 This variable can also be a list of visual properties that are enabled.
9607 The following elements are legal, and are all set by default:
9611 @item summary-highlight
9612 Perform various highlighting in the summary buffer.
9614 @item article-highlight
9615 Perform various highlighting in the article buffer.
9618 Turn on highlighting in all buffers.
9621 Create menus in the group buffer.
9624 Create menus in the summary buffer.
9627 Create menus in the article buffer.
9630 Create menus in the browse buffer.
9633 Create menus in the server buffer.
9636 Create menus in all buffers.
9640 So if you only want highlighting in the article buffer and menus in all
9641 buffers, you couls say something like:
9644 (setq gnus-visual '(article-highlight menu))
9647 If you want only highlighting and no menus whatsoever, you'd say:
9650 (setq gnus-visual '(highlight))
9653 @item gnus-mouse-face
9654 @vindex gnus-mouse-face
9655 This is the face (i.e., font) used for mouse highlighting in Gnus. No
9656 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
9658 @item gnus-display-type
9659 @vindex gnus-display-type
9660 This variable is symbol indicating the display Emacs is running under.
9661 The symbol should be one of @code{color}, @code{grayscale} or
9662 @code{mono}. If Gnus guesses this display attribute wrongly, either set
9663 this variable in your @file{~/.emacs} or set the resource
9664 @code{Emacs.displayType} in your @file{~/.Xdefaults}.
9666 @item gnus-background-mode
9667 @vindex gnus-background-mode
9668 This is a symbol indicating the Emacs background brightness. The symbol
9669 should be one of @code{light} or @code{dark}. If Gnus guesses this
9670 frame attribute wrongly, either set this variable in your @file{~/.emacs} or
9671 set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
9672 `gnus-display-type'.
9674 @item nnheader-max-head-length
9675 @vindex nnheader-max-head-length
9676 When the backends read straight heads of articles, they all try to read
9677 as little as possible. This variable (default @code{4096}) specifies
9678 the absolute max length the backends will try to read before giving up
9679 on finding a separator line between the head and the body. If this
9680 variable is @code{nil}, there is no upper read bound. If it is
9681 @code{t}, the backends won't try to read the articles piece by piece,
9682 but read the entire articles. This makes sense with some versions of
9689 @chapter Customization
9690 @cindex general customization
9692 All variables are properly documented elsewhere in this manual. This
9693 section is designed to give general pointers on how to customize Gnus
9694 for some quite common situations.
9697 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
9698 * Slow Terminal Connection:: You run a remote Emacs.
9699 * Little Disk Space:: You feel that having large setup files is icky.
9700 * Slow Machine:: You feel like buying a faster machine.
9703 @node Slow/Expensive Connection
9704 @section Slow/Expensive @sc{nntp} Connection
9706 If you run Emacs on a machine locally, and get your news from a machine
9707 over some very thin strings, you want to cut down on the amount of data
9708 Gnus has to get from the @sc{nntp} server.
9712 @item gnus-read-active-file
9713 Set this to @code{nil}, which will inhibit Gnus from requesting the
9714 entire active file from the server. This file is often v. large. You
9715 also have to set @code{gnus-check-new-news} and
9716 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
9717 doesn't suddenly decide to fetch the active file anyway.
9719 @item gnus-nov-is-evil
9720 This one has to be @code{nil}. If not, grabbing article headers from
9721 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
9722 support @sc{xover}; Gnus will detect this by itself.
9725 @node Slow Terminal Connection
9726 @section Slow Terminal Connection
9728 Let's say you use your home computer for dialing up the system that
9729 runs Emacs and Gnus. If your modem is slow, you want to reduce the
9730 amount of data that is sent over the wires as much as possible.
9734 @item gnus-auto-center-summary
9735 Set this to @code{nil} to inhibit Gnus from recentering the summary
9736 buffer all the time.
9738 @item gnus-visible-headers
9739 Cut down on the headers that are included in the articles to the
9740 minimum. You can, in fact, make do without them altogether---most of the
9741 useful data is in the summary buffer, anyway. Set this variable to
9742 @samp{"^NEVVVVER"} or @samp{"From:"}, or whatever you feel you need.
9744 @item gnus-article-display-hook
9745 Set this hook to all the available hiding commands:
9747 (setq gnus-article-display-hook
9748 '(gnus-article-hide-headers gnus-article-hide-signature
9749 gnus-article-hide-citation))
9752 @item gnus-use-full-window
9753 By setting this to @code{nil}, you can make all the windows smaller.
9754 While this doesn't really cut down much generally, it means that you
9755 have to see smaller portions of articles before deciding that you didn't
9756 want to read them anyway.
9758 @item gnus-thread-hide-subtree
9759 If this is non-@code{nil}, all threads in the summary buffer will be
9762 @item gnus-updated-mode-lines
9763 If this is @code{nil}, Gnus will not put information in the buffer mode
9764 lines, which might save some time.
9767 @node Little Disk Space
9768 @section Little Disk Space
9770 The startup files can get rather large, so you may want to cut their
9771 sizes a bit if you are running out of space.
9775 @item gnus-save-newsrc-file
9776 If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
9777 only save @file{.newsrc.eld}. This means that you will not be able to
9778 use any other newsreaders than Gnus. This variable is @code{t} by
9781 @item gnus-save-killed-list
9782 If this is @code{nil}, Gnus will not save the list of dead groups. You
9783 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
9784 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
9785 variable to @code{nil}. This variable is @code{t} by default.
9791 @section Slow Machine
9793 If you have a slow machine, or are just really impatient, there are a
9794 few things you can do to make Gnus run faster.
9796 Set@code{gnus-check-new-newsgroups} and
9797 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
9799 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
9800 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
9801 summary buffer faster.
9803 Set @code{gnus-article-display-hook} to @code{nil} to make article
9804 processing a bit faster.
9807 @node Troubleshooting
9808 @chapter Troubleshooting
9809 @cindex troubleshooting
9811 Gnus works @emph{so} well straight out of the box---I can't imagine any
9819 Make sure your computer is switched on.
9822 Make sure that you really load the current Gnus version. If you have
9823 been running @sc{gnus}, you need to exit Emacs and start it up again before
9827 Try doing an @kbd{M-x gnus-version}. If you get something that looks
9828 like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
9829 on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
9830 flee}, you have some old @file{.el} files lying around. Delete these.
9833 Read the help group (@kbd{G h} in the group buffer) for a FAQ and a
9837 If all else fails, report the problem as a bug.
9840 @cindex reporting bugs
9842 @kindex M-x gnus-bug
9844 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
9845 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
9846 me the backtrace. I will fix bugs, but I can only fix them if you send
9847 me a precise description as to how to reproduce the bug.
9849 You really can never be too detailed in a bug report. Always use the
9850 @kbd{M-x gnus-bug} command when you make bug reports, even if it creates
9851 a 10Kb mail each time you use it, and even if you have sent me your
9852 environment 500 times before. I don't care. I want the full info each
9855 It is also important to remember that I have no memory whatsoever. If
9856 you send a bug report, and I send you a reply, and then you send back
9857 just "No, it's not! Moron!", I will have no idea what you are insulting
9858 me about. Always overexplain everything. It's much easier for all of
9859 us---if I don't have all the information I need, I will just mail you
9860 and ask for more info, and everything takes more time.
9862 If you just need help, you are better off asking on
9863 @samp{gnu.emacs.gnus}. I'm not very helpful.
9865 @cindex gnu.emacs.gnus
9866 @cindex ding mailing list
9867 You can also ask on the ding mailing list---@samp{ding@@ifi.uio.no}.
9868 Write to @samp{ding-request@@ifi.uio.no} to subscribe.
9874 Well, that's the manual---you can get on with your life now. Keep in
9875 touch. Say hello to your cats from me.
9877 My @strong{ghod}---I just can't stand goodbyes. Sniffle.
9879 Ol' Chuck Reznikoff said it pretty well, so I leave the floor to him:
9884 Not because of victories @*
9887 but for the common sunshine,@*
9889 the largess of the spring.
9892 but for the day's work done@*
9893 as well as I was able;@*
9894 not for a seat upon the dais@*
9895 but at the common table.@*
9902 * A Programmer@'s Guide to Gnus:: Rilly, rilly technical stuff.
9903 * Emacs for Heathens:: A short intruduction to Emacsian terms.
9904 * Frequently Asked Questions:: A question-and-answer session.
9908 @node A Programmer@'s Guide to Gnus
9909 @section A Programmer@'s Guide to Gnus
9911 It is my hope that other people will figure out smart stuff that Gnus
9912 can do, and that other people will write those smart things as well. To
9913 facilitate that I thought it would be a good idea to describe the inner
9914 workings of Gnus. And some of the not-so-inner workings, while I'm at
9917 You can never expect the internals of a program not to change, but I
9918 will be defining (in some details) the interface between Gnus and its
9919 backends (this is written in stone), the format of the score files
9920 (ditto), data structures (some are less likely to change than others)
9921 and general method of operations.
9924 * Backend Interface:: How Gnus communicates with the servers.
9925 * Score File Syntax:: A BNF definition of the score file standard.
9926 * Headers:: How Gnus stores headers internally.
9927 * Ranges:: A handy format for storing mucho numbers.
9928 * Group Info:: The group info format.
9929 * Various File Formats:: Formats of files that Gnus use.
9933 @node Backend Interface
9934 @subsection Backend Interface
9936 Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
9937 groups. It only knows how to talk to @dfn{virtual servers}. A virtual
9938 server is a @dfn{backend} and some @dfn{backend variables}. As examples
9939 of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
9940 examples of the latter we have @code{nntp-port-number} and
9941 @code{nnmbox-directory}.
9943 When Gnus asks for information from a backend---say @code{nntp}---on
9944 something, it will normally include a virtual server name in the
9945 function parameters. (If not, the backend should use the "current"
9946 virtual server.) For instance, @code{nntp-request-list} takes a virtual
9947 server as its only (optional) parameter. If this virtual server hasn't
9948 been opened, the function should fail.
9950 Note that a virtual server name has no relation to some physical server
9951 name. Take this example:
9955 (nntp-address "ifi.uio.no")
9956 (nntp-port-number 4324))
9959 Here the virtual server name is @samp{"odd-one"} while the name of
9960 the physical server is @samp{"ifi.uio.no"}.
9962 The backends should be able to switch between several virtual servers.
9963 The standard backends implement this by keeping an alist of virtual
9964 server environments that it pulls down/pushes up when needed.
9966 There are two groups of interface functions: @dfn{required functions},
9967 which must be present, and @dfn{optional functions}, which Gnus will
9968 always check whether are present before attempting to call.
9970 All these functions are expected to return data in the buffer
9971 @code{nntp-server-buffer} (@samp{" *nntpd*"}), which is somewhat
9972 unfortunately named, but we'll have to live with it. When I talk about
9973 "resulting data", I always refer to the data in that buffer. When I
9974 talk about "return value", I talk about the function value returned by
9977 Some backends could be said to be @dfn{server-forming} backends, and
9978 some might be said to not be. The latter are backends that generally
9979 only operate on one group at a time, and have no concept of "server" --
9980 they have a group, and they deliver info on that group and nothing more.
9982 In the examples and definitions I will refer to the imaginary backend
9985 @cindex @code{nnchoke}
9988 * Required Backend Functions:: Functions that must be implemented.
9989 * Optional Backend Functions:: Functions that need not be implemented.
9993 @node Required Backend Functions
9994 @subsubsection Required Backend Functions
9998 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
10000 @var{articles} is either a range of article numbers or a list of
10001 @code{Message-ID}s. Current backends do not fully support either---only
10002 sequences (lists) of article numbers, and most backends do not support
10003 retrieval of @code{Message-ID}s. But they should try for both.
10005 The result data should either be HEADs or NOV lines, and the result
10006 value should either be @code{headers} or @code{nov} to reflect this.
10007 This might later be expanded to @code{various}, which will be a mixture
10008 of HEADs and NOV lines, but this is currently not supported by Gnus.
10010 If @var{fetch-old} is non-@code{nil} it says to try to fetch "extra
10011 headers, in some meaning of the word. This is generally done by
10012 fetching (at most) @var{fetch-old} extra headers less than the smallest
10013 article number in @code{articles}, and fill in the gaps as well. The
10014 presence of this parameter can be ignored if the backend finds it
10015 cumbersome to follow the request. If this is non-@code{nil} and not a
10016 number, do maximum fetches.
10018 Here's an example HEAD:
10021 221 1056 Article retrieved.
10022 Path: ifi.uio.no!sturles
10023 From: sturles@@ifi.uio.no (Sturle Sunde)
10024 Newsgroups: ifi.discussion
10025 Subject: Re: Something very droll
10026 Date: 27 Oct 1994 14:02:57 +0100
10027 Organization: Dept. of Informatics, University of Oslo, Norway
10029 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
10030 References: <38jdmq$4qu@@visbur.ifi.uio.no>
10031 NNTP-Posting-Host: holmenkollen.ifi.uio.no
10035 So a @code{headers} return value would imply that there's a number of
10036 these in the data buffer.
10038 Here's a BNF definition of such a buffer:
10042 head = error / valid-head
10043 error-message = [ "4" / "5" ] 2number " " <error message> eol
10044 valid-head = valid-message *header "." eol
10045 valid-message = "221 " <number> " Article retrieved." eol
10046 header = <text> eol
10049 If the return value is @code{nov}, the data buffer should contain
10050 @dfn{network overview database} lines. These are basically fields
10054 nov-buffer = *nov-line
10055 nov-line = 8*9 [ field <TAB> ] eol
10056 field = <text except TAB>
10059 For a closer explanation what should be in those fields,
10063 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
10065 @var{server} is here the virtual server name. @var{definitions} is a
10066 list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
10068 If the server can't be opened, no error should be signaled. The backend
10069 may then choose to refuse further attempts at connecting to this
10070 server. In fact, it should do so.
10072 If the server is opened already, this function should return a
10073 non-@code{nil} value. There should be no data returned.
10076 @item (nnchoke-close-server &optional SERVER)
10078 Close connection to @var{server} and free all resources connected
10081 There should be no data returned.
10084 @item (nnchoke-request-close)
10086 Close connection to all servers and free all resources that the backend
10087 have reserved. All buffers that have been created by that backend
10088 should be killed. (Not the @code{nntp-server-buffer}, though.)
10090 There should be no data returned.
10093 @item (nnchoke-server-opened &optional SERVER)
10095 This function should return whether @var{server} is opened, and that the
10096 connection to it is still alive. This function should under no
10097 circumstances attempt to reconnect to a server that is has lost
10100 There should be no data returned.
10103 @item (nnchoke-status-message &optional SERVER)
10105 This function should return the last error message from @var{server}.
10107 There should be no data returned.
10110 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
10112 The result data from this function should be the article specified by
10113 @var{article}. This might either be a @code{Message-ID} or a number.
10114 It is optional whether to implement retrieval by @code{Message-ID}, but
10115 it would be nice if that were possible.
10117 If @var{to-buffer} is non-@code{nil}, the result data should be returned
10118 in this buffer instead of the normal data buffer. This is to make it
10119 possible to avoid copying large amounts of data from one buffer to
10120 another, and Gnus mainly request articles to be inserted directly into
10121 its article buffer.
10124 @item (nnchoke-open-group GROUP &optional SERVER)
10126 Make @var{group} the current group.
10128 There should be no data returned by this function.
10131 @item (nnchoke-request-group GROUP &optional SERVER)
10133 Get data on @var{group}. This function also has the side effect of
10134 making @var{group} the current group.
10136 Here's an example of some result data and a definition of the same:
10139 211 56 1000 1059 ifi.discussion
10142 The first number is the status, which should be @samp{211}. Next is the
10143 total number of articles in the group, the lowest article number, the
10144 highest article number, and finally the group name. Note that the total
10145 number of articles may be less than one might think while just
10146 considering the highest and lowest article numbers, but some articles
10147 may have been cancelled. Gnus just discards the total-number, so
10148 whether one should take the bother to generate it properly (if that is a
10149 problem) is left as an excercise to the reader.
10152 group-status = [ error / info ] eol
10153 error = [ "4" / "5" ] 2<number> " " <Error message>
10154 info = "211 " 3* [ <number> " " ] <string>
10158 @item (nnchoke-close-group GROUP &optional SERVER)
10160 Close @var{group} and free any resources connected to it. This will be
10161 a no-op on most backends.
10163 There should be no data returned.
10166 @item (nnchoke-request-list &optional SERVER)
10168 Return a list of all groups available on @var{server}. And that means
10171 Here's an example from a server that only carries two groups:
10174 ifi.test 0000002200 0000002000 y
10175 ifi.discussion 3324 3300 n
10178 On each line we have a group name, then the highest article number in
10179 that group, the lowest article number, and finally a flag.
10182 active-file = *active-line
10183 active-line = name " " <number> " " <number> " " flags eol
10185 flags = "n" / "y" / "m" / "x" / "j" / "=" name
10188 The flag says whether the group is read-only (@samp{n}), is moderated
10189 (@samp{m}), is dead (@samp{x}), is aliased to some other group
10190 (@samp{=other-group} or none of the above (@samp{y}).
10193 @item (nnchoke-request-post &optional SERVER)
10195 This function should post the current buffer. It might return whether
10196 the posting was successful or not, but that's not required. If, for
10197 instance, the posting is done asynchronously, it has generally not been
10198 completed by the time this function concludes. In that case, this
10199 function should set up some kind of sentinel to beep the user loud and
10200 clear if the posting could not be completed.
10202 There should be no result data from this function.
10205 @item (nnchoke-request-post-buffer POST GROUP SUBJECT HEADER ARTICLE-BUFFER INFO FOLLOW-TO RESPECT-POSTER)
10207 This function should return a buffer suitable for composing an article
10208 to be posted by @code{nnchoke-request-post}. If @var{post} is
10209 non-@code{nil}, this is not a followup, but a totally new article.
10210 @var{group} is the name of the group to be posted to. @var{subject} is
10211 the subject of the message. @var{article-buffer} is the buffer being
10212 followed up, if that is the case. @var{info} is the group info.
10213 @var{follow-to} is the group that one is supposed to re-direct the
10214 article ot. If @var{respect-poster} is non-@code{nil}, the special
10215 @samp{"poster"} value of a @code{Followup-To} header is to be respected.
10217 There should be no result data returned.
10221 @node Optional Backend Functions
10222 @subsubsection Optional Backend Functions
10226 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
10228 @var{groups} is a list of groups, and this function should request data
10229 on all those groups. How it does it is of no concern to Gnus, but it
10230 should attempt to do this in a speedy fashion.
10232 The return value of this function can be either @code{active} or
10233 @code{group}, which says what the format of the result data is. The
10234 former is in the same format as the data from
10235 @code{nnchoke-request-list}, while the latter is a buffer full of lines
10236 in the same format as @code{nnchoke-request-group} gives.
10239 group-buffer = *active-line / *group-status
10243 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
10245 A Gnus group info (@pxref{Group Info}) is handed to the backend for
10246 alterations. This comes in handy if the backend really carries all the
10247 information (as is the case with virtual an imap groups). This function
10248 may alter the info in any manner it sees fit, and should return the
10249 (altered) group info. This function may alter the group info
10250 destructively, so no copying is needed before boogying.
10252 There should be no result data from this function.
10255 @item (nnchoke-request-scan &optional GROUP SERVER)
10257 This function may be called at any time (by Gnus or anything else) to
10258 request that the backend check for incoming articles, in one way or
10259 another. A mail backend will typically read the spool file or query the
10260 POP server when this function is invoked. The @var{group} doesn't have
10261 to be heeded---if the backend decides that it is too much work just
10262 scanning for a single group, it may do a total scan of all groups. It
10263 would be nice, however, to keep things local if that's practical.
10265 There should be no result data from this function.
10268 @item (nnchoke-request-asynchronous GROUP &optional SERVER ARTICLES)
10270 This is a request to fetch articles asynchronously later.
10271 @var{articles} is an alist of @var{(article-number line-number)}. One
10272 would generally expect that if one later fetches article number 4, for
10273 instance, some sort of asynchronous fetching of the articles after 4
10274 (which might be 5, 6, 7 or 11, 3, 909 depending on the order in that
10275 alist) would be fetched asynchronouly, but that is left up to the
10276 backend. Gnus doesn't care.
10278 There should be no result data from this function.
10281 @item (nnchoke-request-group-description GROUP &optional SERVER)
10283 The result data from this function should be a description of
10287 description-line = name <TAB> description eol
10289 description = <text>
10292 @item (nnchoke-request-list-newsgroups &optional SERVER)
10294 The result data from this function should be the description of all
10295 groups available on the server.
10298 description-buffer = *description-line
10302 @item (nnchoke-request-newgroups DATE &optional SERVER)
10304 The result data from this function should be all groups that were
10305 created after @samp{date}, which is in normal human-readable date
10306 format. The data should be in the active buffer format.
10309 @item (nnchoke-request-create-groups GROUP &optional SERVER)
10311 This function should create an empty group with name @var{group}.
10313 There should be no return data.
10316 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
10318 This function should run the expiry process on all articles in the
10319 @var{articles} range (which is currently a simple list of article
10320 numbers.) It is left up to the backend to decide how old articles
10321 should be before they are removed by this function. If @var{force} is
10322 non-@code{nil}, all @var{articles} should be deleted, no matter how new
10325 This function should return a list of articles that it did not/was not
10328 There should be no result data returned.
10331 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
10334 This function should move @var{article} (which is a number) from
10335 @var{group} by calling @var{accept-form}.
10337 This function should ready the article in question for moving by
10338 removing any header lines it has added to the article, and generally
10339 should "tidy up" the article. Then it should @code{eval}
10340 @var{accept-form} in the buffer where the "tidy" article is. This will
10341 do the actual copying. If this @code{eval} returns a non-@code{nil}
10342 value, the article should be removed.
10344 If @var{last} is @code{nil}, that means that there is a high likelihood
10345 that there will be more requests issued shortly, so that allows some
10348 There should be no data returned.
10351 @item (nnchoke-request-accept-article GROUP &optional LAST)
10353 This function takes the current buffer and inserts it into @var{group}.
10354 If @var{last} in @code{nil}, that means that there will be more calls to
10355 this function in short order.
10357 There should be no data returned.
10360 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
10362 This function should remove @var{article} (which is a number) from
10363 @var{group} and insert @var{buffer} there instead.
10365 There should be no data returned.
10368 @item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
10370 This function should delete @var{group}. If @var{force}, it should
10371 really delete all the articles in the group, and then delete the group
10372 itself. (If there is such a thing as "the group itself".)
10374 There should be no data returned.
10377 @item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
10379 This function should rename @var{group} into @var{new-name}. All
10380 articles that are in @var{group} should move to @var{new-name}.
10382 There should be no data returned.
10388 @node Score File Syntax
10389 @subsection Score File Syntax
10391 Score files are meant to be easily parsable, but yet extremely
10392 mallable. It was decided that something that had the same read syntax
10393 as an Emacs Lisp list would fit that spec.
10395 Here's a typical score file:
10399 ("win95" -10000 nil s)
10406 BNF definition of a score file:
10409 score-file = "" / "(" *element ")"
10410 element = rule / atom
10411 rule = string-rule / number-rule / date-rule
10412 string-rule = "(" quote string-header quote space *string-match ")"
10413 number-rule = "(" quote number-header quote space *number-match ")"
10414 date-rule = "(" quote date-header quote space *date-match ")"
10416 string-header = "subject" / "from" / "references" / "message-id" /
10417 "xref" / "body" / "head" / "all" / "followup"
10418 number-header = "lines" / "chars"
10419 date-header = "date"
10420 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
10421 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
10422 score = "nil" / <integer>
10423 date = "nil" / <natural number>
10424 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
10425 "r" / "regex" / "R" / "Regex" /
10426 "e" / "exact" / "E" / "Exact" /
10427 "f" / "fuzzy" / "F" / "Fuzzy"
10428 number-match = "(" <integer> [ "" / [ space score [ "" /
10429 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
10430 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
10431 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
10432 space date [ "" / [ space date-match-t ] ] ] ] ")"
10433 date-match-t = "nil" / "at" / "before" / "after"
10434 atom = "(" [ required-atom / optional-atom ] ")"
10435 required-atom = mark / expunge / mark-and-expunge / files /
10436 exclude-files / read-only / touched
10437 optional-atom = adapt / local / eval
10438 mark = "mark" space nil-or-number
10439 nil-or-number = "nil" / <integer>
10440 expunge = "expunge" space nil-or-number
10441 mark-and-expunge = "mark-and-expunge" space nil-or-number
10442 files = "files" *[ space <string> ]
10443 exclude-files = "exclude-files" *[ space <string> ]
10444 read-only = "read-only" [ space "nil" / space "t" ]
10445 adapt = "adapt" [ space "nil" / space "t" / space adapt-rule ]
10446 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
10447 local = "local" *[ space "(" <string> space <form> ")" ]
10448 eval = "eval" space <form>
10449 space = *[ " " / <TAB> / <NEWLINE> ]
10452 Any unrecognized elements in a score file should be ignored, but not
10455 As you can see, white space is needed, but the type and amount of white
10456 space is irrelevant. This means that formatting of the score file is
10457 left up to the programmer---if it's simpler to just spew it all out on
10458 one looong line, then that's ok.
10460 The meaning of the various atoms are explained elsewhere in this
10465 @subsection Headers
10467 Gnus uses internally a format for storing article headers that
10468 corresponds to the @sc{nov} format in a mysterious fashion. One could
10469 almost suspect that the author looked at the @sc{nov} specification and
10470 just shamelessly @emph{stole} the entire thing, and one would be right.
10472 @dfn{Header} is a severly overloaded term. "Header" is used in RFC1036
10473 to talk about lines in the head of an article (eg., @code{From}). It is
10474 used by many people as a synonym for "head"---"the header and the
10475 body". (That should be avoided, in my opinion.) And Gnus uses a format
10476 interanally that it calls "header", which is what I'm talking about
10477 here. This is a 9-element vector, basically, with each header (ouch)
10480 These slots are, in order: @code{number}, @code{subject}, @code{from},
10481 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
10482 @code{xref}. There are macros for accessing and setting these slots --
10483 they all have predicatable names beginning with @code{mail-header-} and
10484 @code{mail-header-set-}, respectively.
10486 The @code{xref} slot is really a @code{misc} slot. Any extra info will
10493 @sc{gnus} introduced a concept that I found so useful that I've started
10494 using it a lot and have elaborated on it greatly.
10496 The question is simple: If you have a large amount of objects that are
10497 identified by numbers (say, articles, to take a @emph{wild} example)
10498 that you want to callify as being "included", a normal sequence isn't
10499 very useful. (A 200,000 length sequence is a bit long-winded.)
10501 The solution is as simple as the question: You just collapse the
10505 (1 2 3 4 5 6 10 11 12)
10508 is transformed into
10511 ((1 . 6) (10 . 12))
10514 To avoid having those nasty @samp{(13 . 13)} elements to denote a
10515 lonesome object, a @samp{13} is a valid element:
10518 ((1 . 6) 7 (10 . 12))
10521 This means that comparing two ranges to find out whether they are equal
10522 is slightly tricky:
10525 ((1 . 5) 7 8 (10 . 12))
10531 ((1 . 5) (7 . 8) (10 . 12))
10534 are equal. In fact, any non-descending list is a range:
10540 is a perfectly valid range, although a pretty longwinded one. This is
10547 and is equal to the previous range.
10549 Here's a BNF definition of ranges. Of course, one must remember the
10550 semantic requirement that the numbers are non-descending. (Any number
10551 of repetition of the same number is allowed, but apt to disappear in
10555 range = simple-range / normal-range
10556 simple-range = "(" number " . " number ")"
10557 normal-range = "(" start-contents ")"
10558 contents = "" / simple-range *[ " " contents ] /
10559 number *[ " " contents ]
10562 Gnus currently uses ranges to keep track of read articles and article
10563 marks. I plan on implementing a number of range operators in C if The
10564 Powers That Be are willing to let me. (I haven't asked yet, because I
10565 need to do some more thinking on what operators I need to make life
10566 totally range-based without ever having to convert back to normal
10571 @subsection Group Info
10573 Gnus stores all permanent info on groups in a @dfn{group info} list.
10574 This list is from three to six elements (or more) long and exhaustively
10575 describes the group.
10577 Here are two example group infos; one is a very simple group while the
10578 second is a more complex one:
10581 ("no.group" 5 (1 . 54324))
10583 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
10584 ((tick (15 . 19)) (replied 3 6 (19 . 3)))
10586 (auto-expire (to-address "ding@@ifi.uio.no")))
10589 The first element is the group name as Gnus knows the group; the second
10590 is the group level; the third is the read articles in range format; the
10591 fourth is a list of article marks lists; the fifth is the select method;
10592 and the sixth contains the group parameters.
10594 Here's a BNF definition of the group info format:
10597 info = "(" group space level space read
10598 [ "" / [ space marks-list [ "" / [ space method [ "" /
10599 space parameters ] ] ] ] ] ")"
10600 group = quote <string> quote
10601 level = <integer in the range of 1 to inf>
10603 marks-lists = nil / "(" *marks ")"
10604 marks = "(" <string> range ")"
10605 method = "(" <string> *elisp-forms ")"
10606 parameters = "(" *elisp-forms ")"
10609 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
10610 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
10614 @node Various File Formats
10615 @subsection Various File Formats
10618 * Active File Format:: Information on articles and groups available.
10619 * Newsgroups File Format:: Group descriptions.
10623 @node Active File Format
10624 @subsubsection Active File Format
10626 The active file lists all groups that are available on the server in
10627 question. It also lists the highest and lowest current article numbers
10630 Here's an exceprt from a typical active file:
10633 soc.motss 296030 293865 y
10634 alt.binaries.pictures.fractals 3922 3913 n
10635 comp.sources.unix 1605 1593 m
10636 comp.binaries.ibm.pc 5097 5089 y
10637 no.general 1000 900 y
10640 Here's a pseudo-BNF definition of this file:
10643 active = *group-line
10644 group-line = group space high-number space low-number space flag <NEWLINE>
10645 group = <non-white-space string>
10647 high-number = <non-negative integer>
10648 low-number = <positive integer>
10649 flag = "y" / "n" / "m" / "j" / "x" / "=" group
10653 @node Newsgroups File Format
10654 @subsubsection Newsgroups File Format
10656 The newsgroups file lists groups along with their descriptions. Not all
10657 groups on the server have to be listed, and not all groups in the file
10658 have to exist on the server. The file is meant purely as information to
10661 The format is quite simple; a group name, a tab, and the description.
10662 Here's the definition:
10666 line = group tab description <NEWLINE>
10667 group = <non-white-space string>
10669 description = <string>
10673 @node Emacs for Heathens
10674 @section Emacs for Heathens
10676 Believe it or not, but some people who use Gnus haven't really used
10677 Emacs much before they embarked on their journey on the Gnus Love Boat.
10678 If you are one of those unfortunates whom "@kbd{M-C-a}", "kill the
10679 region", and "set @code{gnus-flargblossen} to an alist where the key is
10680 a regexp that is used for matching on the group name" are magical
10681 phrases with little or no meaning, then this appendix is for you. If
10682 you are already familiar with Emacs, just ignore this and go fondle your
10686 * Keystrokes:: Entering text and executing commands.
10687 * Emacs Lisp:: The built-in Emacs programming language.
10692 @subsection Keystrokes
10696 Q: What is an experienced Emacs user?
10699 A: A person who wishes that the terminal had pedals.
10702 Yes, when you use Emacs, you are apt to use the control key, the shift
10703 key and the meta key a lot. This is very annoying to some people
10704 (notably @code{vi}le users), and the rest of us just love the hell out
10705 of it. Just give up and submit. Emacs really does stand for
10706 "Escape-Meta-Alt-Control-Shift", and not "Editin Macros", as you may
10707 have heard from other disreputable sources (like the Emacs author).
10709 The shift key is normally located near your pinky fingers, and are
10710 normally used to get capital letters and stuff. You probably use it all
10711 the time. The control key is normally marked "CTRL" or something like
10712 that. The meta key is, funnily enough, never marked as such on any
10713 keyboards. The one I'm curretly at has a key that's marked "Alt", which
10714 is the meta key on this keyboard. It's usually located somewhere to the
10715 left hand side of the keyboard, usually on the bottom row.
10717 Now, us Emacs people doesn't say "press the meta-control-m key", because
10718 that's just too inconvenient. We say "press the @kbd{M-C-m} key".
10719 @kbd{M-} is the prefix that means "meta" and "C-" is the prefix that
10720 means "control". So "press @kbd{C-k}" means "press down the control
10721 key, and hold it down while you press @kbd{k}". "Press @kbd{M-C-k}"
10722 means "press down and hold down the meta key and the control key and
10723 then press @kbd{k}". Simple, ay?
10725 This is somewhat complicated by the fact that not all keyboards have a
10726 meta key. In that case you can use the "escape" key. Then @kbd{M-k}
10727 means "press escape, release escape, press @kbd{k}". That's much more
10728 work than if you have a meta key, so if that's the case, I respectfully
10729 suggest you get a real keyboard with a meta key. You can't live without
10735 @subsection Emacs Lisp
10737 Emacs is the King of Editors because it's really a Lisp interpreter.
10738 Each and every key you tap runs some Emacs Lisp code snippet, and since
10739 Emacs Lisp is an interpreted language, that means that you can configure
10740 any key to run any random code. You just, like, do it.
10742 Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
10743 functions. (These are byte-compiled for speed, but it's still
10744 interpreted.) If you decide that you don't like the way Gnus does
10745 certain things, it's trivial to have it do something a different way.
10746 (Well, at least if you know how to write Lisp code.) However, that's
10747 beyond the scope of this manual, so we are simply going to talk about
10748 some common constructs that you normally use in your @file{.emacs} file
10751 If you want to set the variable @code{gnus-florgbnize} to four (4), you
10752 write the following:
10755 (setq gnus-florgbnize 4)
10758 This function (really "special form") @code{setq} is the one that can
10759 set a variable to some value. This is really all you need to know. Now
10760 you can go and fill your @code{.emacs} file with lots of these to change
10763 If you have put that thing in your @code{.emacs} file, it will be read
10764 and @code{eval}ed (which is lispese for "run") the next time you start
10765 Emacs. If you want to change the variable right away, simply say
10766 @kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
10767 previous "form", which here is a simple @code{setq} statement.
10769 Go ahead---just try it, if you're located at your Emacs. After you
10770 @kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
10771 is the return value of the form you @code{eval}ed.
10775 If the manual says "set @code{gnus-read-active-file} to @code{some}",
10779 (setq gnus-read-active-file 'some)
10782 On the other hand, if the manual says "set @code{gnus-nntp-server} to
10783 @samp{"nntp.ifi.uio.no"}", that means:
10786 (setq gnus-nntp-server "nntp.ifi.uio.no")
10789 So be careful not to mix up strings (the latter) with symbols (the
10790 former). The manual is unambiguous, but it can be confusing.
10793 @include gnus-faq.texi
10808 @c Local Variables:
10809 @c outline-regexp: "@chap\\|@\\(sub\\)*section\\|@appendix \\|@appendix\\(sub\\)*sec\\|\^L"