1 \input texinfo @c -*-texinfo-*-
2 @comment %**start of header (This is for running Texinfo on a region.)
4 @settitle September Gnus Manual
11 @setchapternewpage odd
13 @comment %**end of header (This is for running Texinfo on a region.)
16 %\global\baselineskip 30pt % For printing in double spaces
21 This file documents Gnus, the GNU Emacs newsreader.
23 Copyright (C) 1995 Free Software Foundation, Inc.
25 Permission is granted to make and distribute verbatim copies of
26 this manual provided the copyright notice and this permission notice
27 are preserved on all copies.
30 Permission is granted to process this file through Tex and print the
31 results, provided the printed document carries copying permission
32 notice identical to this one except for the removal of this paragraph
33 (this paragraph not being relevant to the printed manual).
36 Permission is granted to copy and distribute modified versions of this
37 manual under the conditions for verbatim copying, provided also that the
38 entire resulting derived work is distributed under the terms of a
39 permission notice identical to this one.
41 Permission is granted to copy and distribute translations of this manual
42 into another language, under the above conditions for modified versions.
48 @title September Gnus Manual
50 @author by Lars Magne Ingebrigtsen
52 @vskip 0pt plus 1filll
53 Copyright @copyright{} 1995 Free Software Foundation, Inc.
55 Permission is granted to make and distribute verbatim copies of
56 this manual provided the copyright notice and this permission notice
57 are preserved on all copies.
59 Permission is granted to copy and distribute modified versions of this
60 manual under the conditions for verbatim copying, provided that the
61 entire resulting derived work is distributed under the terms of a
62 permission notice identical to this one.
64 Permission is granted to copy and distribute translations of this manual
65 into another language, under the above conditions for modified versions.
67 Cover art by Etienne Suvasa.
74 @top The Gnus Newsreader
76 You can read news (and mail) from within Emacs by using Gnus. The news
77 can be gotten by any nefarious means you can think of---@sc{nntp}, local
78 spool or your mbox file. All at the same time, if you want to push your
82 * History:: How Gnus got where it is today.
83 * Terminology:: We use really difficult, like, words here.
84 * Starting Up:: Finding news can be a pain.
85 * The Group Buffer:: Selecting, subscribing and killing groups.
86 * The Summary Buffer:: Reading, saving and posting articles.
87 * The Article Buffer:: Displaying and handling articles.
88 * The Server Buffer:: Making and editing virtual servers.
89 * Scoring:: Assigning values to articles.
90 * Various:: General purpose settings.
91 * Customization:: Tailoring Gnus to your needs.
92 * Troubleshooting:: What you might try if things do not work.
93 * The End:: Farewell and goodbye.
94 * Appendix:: Technical stuff for technical people.
95 * Index:: Variable, function and concept index.
96 * Key Index:: Key Index.
103 @sc{gnus} was written by Masanobu UMEDA. When autumn crept up in '94,
104 Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
106 If you want to investigate the person responsible for this outrage, you
107 can point your (feh!) web browser to
108 @file{http://www.ifi.uio.no/~larsi/}. This is also the primary
109 distribution point for the new and spiffy versions of Gnus, also know as
110 The Site That Destroys Newsrcs And Drives People Mad.
112 During the first extended alpha period of develpment, the new Gnus was
113 called "(ding) Gnus". @dfn{(ding)}, is, of course, short for @dfn{ding
114 is not Gnus}, which is a total and utter lie, but who cares? (Besides,
115 the "Gnus" in this abbreviation should probably be pronounced "news" as
116 UMEDA intended, which makes it a more appropriate name, don't you
119 In any case, after spending all that energy with coming up with a new
120 and spiffy name, we decided that the name was @emph{too} spiffy, so we
121 renamamed it back again to "Gnus". But in mixed case. "Gnus" vs.
122 "@sc{gnus}". New vs. old.
124 Incidentally, the next Gnus generation will be called "September Gnus",
125 and won't be released until February. Confused? You will be.
128 * Why?:: What's the point of Gnus?
129 * Compatibility:: Just how compatible is Gnus with @sc{gnus}?
130 * Conformity:: Gnus tries to conform to all standards.
131 * Emacsen:: Gnus can be run on a few modern Emacsen.
132 * Contributors:: Oodles of people.
133 * New Features:: Pointers to some of the new stuff in Gnus.
134 * Newest Features:: Features so new that they haven't been written yet.
140 What's the point of Gnus?
142 I want to provide a "rad", "happening", "way cool" and "hep" newsreader,
143 that lets you do anything you can think of. That was my original
144 motivation, but while working on Gnus, it has become clear to me that
145 this generation of newsreaders really belong in the stone age.
146 Newsreaders haven't developed much since the infancy of the net. If the
147 volume continues to rise with the current rate of increase, all current
148 newsreaders will be pretty much useless. How do you deal with
149 newsgroups that have hundreds (or thousands) of new articles each day?
151 Gnus offer no real solutions to these questions, but I would very much
152 like to see Gnus being used as a testing ground for new methods of
153 reading and fetching news. Expanding on Umeda-san's wise decision to
154 separate the newsreader from the backends, Gnus now offers a simple
155 interface for anybody who wants to write new backends for fetching mail
156 and news from different sources. I have added hooks for customizations
157 everywhere I can imagine useful. By doing so, I'm inviting every one of
158 you to explore and invent new ways of reading news.
160 May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
163 @section Compatibility
165 @cindex compatibility
166 Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
167 bindings have been kept. More key bindings have been added, of course,
168 but only in one or two obscure cases have old bindings been changed.
173 @center In a cloud bones of steel.
177 All commands have kept their names. Some internal functions have changed
180 The @code{gnus-uu} package has changed drastically. @xref{Decoding
183 One major compatibility question if the presence of several summary
184 buffers. All variables that are relevant while reading a group are
185 buffer-local to the summary buffer they belong in. Although most
186 important variables have their values copied into their global
187 counterparts whenever a command is executed in the summary buffer, this
188 change might lead to incorrect values being used unless you are careful.
190 All code that relies on knowledge of @sc{gnus} internals will probably
191 fail. To take two examples: Sorting @code{gnus-newsrc-assoc} (or
192 changing it in any way, as a matter of fact) is strictly verboten. Gnus
193 maintains a hash table that points to the entries in this assoc (which
194 speeds up many functions), and changing the assoc directly will lead to
199 Old hilit19 code does not work at all. In fact, you should probably
200 remove all hilit code from all Gnus hooks
201 (@code{gnus-group-prepare-hook}, @code{gnus-summary-prepare-hook} and
202 @code{gnus-summary-article-hook}). (Well, at the very least the first
203 two.) Gnus provides various integrated functions for highlighting.
204 These are faster and more accurate. To make life easier for everybody,
205 Gnus will by default remove all hilit calls from all hilit hooks.
208 Packages like @code{expire-kill} will no longer work. As a matter of
209 fact, you should probably remove all old @sc{gnus} packages (and other
210 code) when you start using Gnus. More likely than not, Gnus already
211 does what you have written code to make @sc{gnus} do. (Snicker.)
213 Even though old methods of doing things are still supported, only the
214 new methods are documented in this manual. If you detect a new method of
215 doing something while reading this manual, that does not mean you have
216 to stop doing it the old way.
218 Gnus understands all @sc{gnus} startup files.
221 Overall, a casual user who hasn't written much code that depends on
222 @sc{gnus} internals should suffer no problems. If problems occur,
223 please let me know (@kbd{M-x gnus-bug}).
229 No rebels without a clue here, ma'am. We conform to all standards known
230 to (wo)man. Except for those standards and/or conventions we disagree
236 There are no known breaches of this standard.
239 There are no known breaches of this standard, either.
241 @item Usenet Seal of Approval
242 Gnus hasn't been formally through the Seal process, but I have read
243 through the Seal text and I think Gnus would pass.
245 @item Son-of-RFC 1036
246 We do have some breaches to this one.
250 Gnus does no MIME handling, and this standard-to-be seems to think that
251 MIME is the bees' knees, so we have major breakage here.
253 This is considered to be a "vanity header", while I consider it to be
254 consumer information. After seeing so many badly formatted articles
255 coming from @code{tin} and @code{Netscape} I know not to use either of
256 those for posting articles. I would not have known that if it wasn't
257 for the @code{X-Newsreader} header.
259 Gnus breaks lines if this header is long. I infer from RFC1036 that
260 being conservative in what you output is not creating 5000-character
261 lines, so it seems like a good idea to me. However, this standard-to-be
262 says that whitespace in the @code{References} header is to be preserved,
263 so... It doesn't matter one way or the other to Gnus, so if somebody
264 tells me what The Way is, I'll change it. Or not.
269 If you ever see Gnus act noncompliantly to the texts mentioned above,
270 don't hesitate to drop a note to Gnus Towers and let us know.
280 Gnus should work on :
291 Mule versions based on Emacs 19.26 and up.
295 Gnus will absolutely not work on any Emacsen older than that. Not
298 There are some vague differences in what Gnus does, though:
303 The mouse-face on Gnus lines under Emacs and Mule is delimited to
304 certain parts of the lines while they cover the entire line under
308 The same with current-article marking---XEmacs puts an underline under
309 the entire summary line while Emacs and Mule are nicer and kinder.
312 XEmacs features more graphics---a logo and a toolbar.
315 Citation highlighting us better under Emacs and Mule than under XEmacs.
318 Emacs 19.26-19.28 have tangible hidden headers, which can be a bit
325 @section Contributors
328 The new Gnus version couldn't have been done without the help of all the
329 people on the (ding) mailing list. Every day for months I have gotten
330 tens of nice bug reports from them, filling me with joy, every single
331 one of them. Smooches. The people on the list have been tried beyond
332 endurance, what with my "oh, that's a neat idea <type type>, yup, I'll
333 release it right away <ship off> no wait, that doesn't work at all <type
334 type>, yup, I'll ship that one off right away <ship off> no, wait, that
335 absolutely does not work" policy for releases. Micro$oft---bah.
336 Amateurs. I'm @emph{much} worse. (Or is that "worser"? "much worser"?
339 I would like to take this opportunity to thank the Academy for... oops,
344 Of course, GNUS was written by Masanobu UMEDA.
346 Many excellent functions, especially dealing with scoring and
347 highlighting (as well as the soon-to-come @sc{soup} support) was written
350 Innumerable bug fixes were written by Sudish Joseph.
352 @code{gnus-topic} was written by Ilja Weis.
354 The refcard was written by Vladimir Alexiev.
356 I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
358 @code{nnfolder} has been much enhanced by Scott Byer.
360 The orphan scoring was written by Peter Mutsaers.
362 GNU XEmacs support has been added by Fabrice Popineau.
364 Various bits and pieces, especially dealing with .newsrc files, were
365 suggested and added by Hallvard B Furuseth.
367 Brian Edmonds has written @code{gnus-bbdb}.
369 Ricardo Nassif did the proof-reading.
371 Kevin Davidson came up with the name @dfn{ding}, so blame him.
373 Peter Arius, Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel
374 Quinlan, Frank D. Cringle, Geoffrey T. Dairiki and Andrew Eskilsson have
375 all contributed code and suggestions.
380 @section New Features
386 The look of all buffers can be changed by setting format-like variables
387 (@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
390 Local spool and several @sc{nntp} servers can be used at once
391 (@pxref{Foreign Groups}).
394 You can combine groups into virtual groups (@pxref{nnvirtual}).
397 You can read a number of different mail formats (@pxref{Reading Mail}).
398 All the mail backends implement a convenient mail expiry scheme
399 (@pxref{Expiring Old Mail Articles}).
402 Gnus can use various strategies for gathering threads that have lost
403 their roots (thereby gathering loose sub-threads into one thread) or it
404 can go back and retrieve enough headers to build a complete thread
405 (@pxref{Customizing Threading}).
408 Killed groups can be displayed in the group buffer, and you can read
412 Gnus can do partial group updates---you do not have to retrieve the
413 entire active file just to check for new articles in a few groups
414 (@pxref{The Active File}).
417 Gnus implements a sliding scale of subscribedness to groups
418 (@pxref{Group Levels}).
421 You can score articles according to any number of criteria
422 (@pxref{Scoring}). You can even get Gnus to find out how to score
423 articles for you (@pxref{Adaptive Scoring}).
426 Gnus maintains a dribble buffer that is auto-saved the normal Emacs
427 manner, so it should be difficult to lose much data on what you have
428 read if your machine should go down (@pxref{Auto Save}).
431 Gnus now has its own startup file to avoid cluttering up the
435 You can set the process mark on both groups and articles and perform
436 operations on all the marked items (@pxref{Process/Prefix}).
439 You can grep through a subset of groups and create a group from the
440 results (@pxref{nnkiboze}).
443 You can list subsets of groups according to, well, anything
444 (@pxref{Listing Groups}).
447 You can browse foreign servers and subscribe to groups from those
448 servers (@pxref{Browse Foreign Server}).
451 Gnus can fetch articles asynchronously on a second connection to the
452 server (@pxref{Asynchronous Fetching}).
455 You can cache articles locally (@pxref{Article Caching}).
458 The uudecode functions have been expanded and generalized
459 (@pxref{Decoding Articles}).
462 You can still post uuencoded articles, which was a little-known feature
463 of @sc{gnus} past (@pxref{Uuencoding & Posting}).
466 Fetching parents (and other articles) now actually works without
467 glitches (@pxref{Finding the Parent}).
470 Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
473 Digests (and other files) can be used as the basis for groups
477 Articles can be highlighted and customized (@pxref{Customizing
481 URLs and other external references can be buttonized (@pxref{Article
485 All Gnus buffers can be customized in a difficult fashion
486 (@pxref{Windows Configuration}).
489 You can click on buttons instead of using the keyboard
494 This is, of course, just a @emph{short} overview of the @emph{most}
495 important new features. No, really. There are tons more. Yes, we have
496 feeping creaturism in full effect, but nothing too gratuitous, I would
500 @node Newest Features
501 @section Newest Features
504 Also known as the @dfn{todo list}. Sure to be implemented before the
507 Be afraid. Be very afraid.
511 Native @sc{mime} support is something that should be done.
513 @code{trn}-like trees.
515 @code{nn}-like pick-and-read summary interface.
521 Floating point group levels and group bubbling.
523 Automatic re-scan of incoming mail.
525 Buttonize more stuff in the article buffer.
527 A better and simpler method for specifying mail composing methods.
529 Marks for saved, forwarded, etc articles.
531 Speed up caching and adaptive scoring.
533 Gather thread by filling in missing Message-IDs.
537 Allow posting through mail-to-news gateways.
539 Speed up massive group massacres.
541 @code{jka-compr} isn't fully supported.
543 Create better digests.
545 Do better word-wrap on cited text.
547 Better X-Face support with X-Face databases and stuff.
549 Support SELF-DISCIPLINE pins.
551 Really do unbinhexing.
553 Listing of all active groups.
557 Do the X-Receipt-To thing.
559 Don't kill summary buffers upon exit from the groups.
561 Allow adaption on secondary marks.
564 And much, much, much more. There is more to come than has already been
565 implemented. (But that's always true, isn't it?)
567 @code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>} is where the actual
568 up-to-the-second todo list is located, so if you're really curious, you
569 could point your Web browser over that-a-way.
578 This is what you are supposed to use this thing for---reading news.
579 News is generally fetched from a nearby @sc{nntp} server, and is
580 generally publicly available to everybody. If you post news, the entire
581 world is likely to read just what you have written, and they'll all
582 snigger mischievously. Behind your back.
585 Everything that's delivered to you personally is mail. Some news/mail
586 readers (like Gnus) blur the distinction between mail and news, but
587 there is a difference. Mail is private. News is public. Mailing is
588 not posting, and replying is not following up.
590 Send a mail to the person who has written what you are reading.
592 Post an article to the current newsgroup responding to the article you
595 Gnus gets fed articles from a number of backends, both news and mail
596 backends. Gnus does not handle the underlying media, so to speak---this
597 is all done by the backends.
599 Gnus will always use one method (and backend) as the @dfn{native}, or
600 default, way of getting news.
602 You can also have any number of foreign groups at the same time. These
603 are groups that use different backends for getting news.
606 The top part of an article, where administration information (etc.) is
610 The rest of an article. Everything that is not in the head is in the
614 A line from the head of an article.
617 A collection of such lines, or a collection of heads. Or even a
618 collection of @sc{nov} lines.
621 When Gnus enters a group, it asks the backend for the headers for all
622 the unread articles in the group. Most servers support the News OverView
623 format, which is much smaller and much faster to read than the normal
627 Each group is subscribed at some @dfn{level} or other (1-9). The ones
628 that have a lower level are "more" subscribed than the groups with a
629 higher level. In fact, groups on levels 1-5 are considered
630 @dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
631 are @dfn{killed}. Commands for listing groups and scanning for new
632 articles will all use the numeric prefix as @dfn{working level}.
634 @cindex killed groups
635 No information on killed groups is stored or updated, which makes killed
636 groups much easier to handle than subscribed groups.
638 @cindex zombie groups
639 Just like killed groups, only slightly less dead.
642 The news server has to keep track of what articles it carries, and what
643 groups exist. All this information in stored in the active file, which
644 is rather large, as you might surmise.
647 A group that exists in the @file{.newsrc} file, but isn't known to the
648 server (i. e., it isn't in the active file), is a @emph{bogus group}.
649 This means that the group probably doesn't exist (any more).
653 @chapter Starting Gnus
657 If your system administrator has set things up properly, starting Gnus
658 and reading news is extremely easy---you just type @kbd{M-x gnus}.
660 If things do not go smoothly at startup, you have to twiddle some
664 * Finding the News:: Choosing a method for getting news.
665 * The First Time:: What does Gnus do the first time you start it?
666 * The Server is Down:: How can I read my mail then?
667 * Slave Gnusii:: You can have more than one Gnus active at a time.
668 * Fetching a Group:: Starting Gnus just to read a group.
669 * New Groups:: What is Gnus supposed to do with new groups?
670 * Startup Files:: Those pesky startup files---@file{.newsrc}.
671 * Auto Save:: Recovering from a crash.
672 * The Active File:: Reading the active file over a slow line Takes Time.
673 * Startup Variables:: Other variables you might change.
676 @node Finding the News
677 @section Finding the News
679 @vindex gnus-select-method
680 The @code{gnus-select-method} variable controls how Gnus finds news.
681 This variable should be a list where the first element says @dfn{how}
682 and the second element says @dfn{where}. This method is is your native
683 method. All groups that are not fetched with this method are foreign
686 For instance, if you want to get your daily dosage of news from the
687 @samp{news.somewhere.edu} @sc{nntp} server, you'd say:
690 (setq gnus-select-method '(nntp "news.somewhere.edu"))
693 If you want to read directly from the local spool, say:
696 (setq gnus-select-method '(nnspool ""))
699 If you can use a local spool, you probably should, as it will almost
700 certainly be much faster.
702 @vindex gnus-nntpserver-file
704 @cindex @sc{nntp} server
705 If this variable is not set, Gnus will take a look at the
706 @code{NNTPSERVER} environment variable. If that variable isn't set,
707 Gnus will see whether @code{gnus-nntpserver-file} (default
708 @file{/etc/nntpserver}) has any opinions in the matter. It that fails
709 as well, Gnus will will try to use the machine that is running Emacs as
710 an @sc{nntp} server. That's a longshot, though.
712 @vindex gnus-nntp-server
713 If @code{gnus-nntp-server} is set, this variable will override
714 @code{gnus-select-method}. You should therefore set
715 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
717 @vindex gnus-secondary-servers
718 You can also make Gnus prompt you interactively for the name of an
719 @sc{nntp} server. If you give a non-numerical prefix to @code{gnus}
720 (i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
721 in the @code{gnus-secondary-servers} list (if any). You can also just
722 type in the name of any server you feel like visiting.
724 However, if you use one @sc{nntp} server regularly, and are just
725 interested in a couple of groups from a different server, you would be
726 better served by using the @code{gnus-group-browse-foreign-server}
727 command from the group buffer. It will let you have a look at what
728 groups are available, and you can subscribe to any of the groups you
729 want to. This also makes @file{.newsrc} maintenance much tidier.
730 @xref{Foreign Groups}.
732 @vindex gnus-secondary-select-methods
733 A slightly different approach to foreign groups is to set the
734 @code{gnus-secondary-select-methods} variable. The select methods
735 listed in this variable are in many ways just as native as the
736 @code{gnus-select-method} server. They will also be queried for active
737 files during startup (if that's required), and new newsgroups that
738 appear on these servers will be subscribed (or not) just as native
741 For instance, if you use the @code{nnmbox} backend to read you mail, you
742 would typically set this variable to
745 (setq gnus-secondary-select-methods '((nnmbox "")))
749 @section The First Time
750 @cindex first time usage
752 If no startup files exist, Gnus will try to determine what groups should
753 be subscribed by default.
755 @vindex gnus-default-subscribed-newsgroups
756 If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
757 will subscribe you to just those groups in that list, leaving the rest
758 killed. Your system administrator should have set this variable to
761 Since she hasn't, Gnus will just subscribe you to a few randomly picked
762 groups (i.e., @samp{*.newusers}). (@dfn{Random} is here defined as
763 "whatever Lars thinks you should read".)
765 You'll also be subscribed to the Gnus documentation group, which should
766 help you with most common problems.
768 If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
769 use the normal functions for handling new groups, and not do anything
772 @node The Server is Down
773 @section The Server is Down
774 @cindex server errors
776 If the default server is down, Gnus will understandably have some
777 problems starting. However, if you have some mail groups in addition to
778 the news groups, you may want to start Gnus anyway.
780 Gnus, being the trusting sort of program, will ask whether to proceed
781 without a native select method if that server can't be contacted. This
782 will happen whether the server doesn't actually exist (i.e., you have
783 given the wrong address) or the server has just momentarily taken ill
784 for some reason or other.
786 If Gnus says "nntp server on <your server> can't be opened. Continue?",
787 you do not want to continue unless you have some foreign groups that you
788 want to read. Even if you don't, Gnus will let you continue, but you'll
789 find it difficult to actually do anything in the group buffer. But,
790 hey, that's your problem. Blllrph!
792 @findex gnus-no-server
793 If you know that the server is definitely down, or you just want to read
794 your mail without bothering with the server at all, you can use the
795 @code{gnus-no-server} command to start Gnus. That might come in handy
796 if you're in a hurry as well.
800 @section Slave Gnusii
803 You might want to run more than one Emacs with more than one Gnus at the
804 same time. If you are using different @file{.newsrc} files (eg., if you
805 are using the two different Gnusii to read from two different servers),
806 that is no problem whatsoever. You just do it.
808 The problem appears when you want to run two Gnusii that use the same
811 To work around that problem some, we here at the Think-Tank at the Gnus
812 Towers have come up with a new concept: @dfn{Masters} and
813 @dfn{servants}. (We have applied for a patent on this concept, and have
814 taken out a copyright on those words. If you wish to use those words in
815 conjunction with each other, you have to send $1 per usage instance to
816 me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
817 Applications}) will be much more expensive, of course.)
819 Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
820 however you do it). Each subsequent slave Gnusii should be started with
821 @kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
822 files, but some slave files that contains information only on what
823 groups have been read in the slave session. When a master Gnus starts,
824 it will read (and delete) these slave files, incorporating all
825 information from all of them. (The slave files will be read in the
826 sequence they were created, so the latest changes will have precedence.)
828 Information from the slave files has, of course, presedence over the
829 information in the normal (i. e., master) @code{.newsrc} file.
832 @node Fetching a Group
833 @section Fetching a Group
835 @findex gnus-fetch-group
836 It it sometime convenient to be able to just say "I want to read this
837 group and I don't care whether Gnus has been started or not". This is
838 perhaps more useful for people who write code than for users, but the
839 command @code{gnus-fetch-group} provides this functionality in any
840 case. It takes the group name as a paramenter.
847 @vindex gnus-subscribe-newsgroup-method
848 What Gnus does when it encounters a new group is determined by the
849 @code{gnus-subscribe-newsgroup-method} variable.
851 This variable should contain a function. Some handy pre-fab values
855 @item gnus-subscribe-randomly
856 @vindex gnus-subscribe-randomly
857 Subscribe all new groups randomly.
858 @item gnus-subscribe-alphabetically
859 @vindex gnus-subscribe-alphabetically
860 Subscribe all new groups alphabetically.
861 @item gnus-subscribe-hierarchically
862 @vindex gnus-subscribe-hierarchically
863 Subscribe all new groups hierarchically.
864 @item gnus-subscribe-interactively
865 @vindex gnus-subscribe-interactively
866 Subscribe new groups interactively. This means that Gnus will ask
867 you about @strong{all} new groups.
868 @item gnus-subscribe-zombies
869 @vindex gnus-subscribe-zombies
870 Make all new groups zombies. You can browse the zombies later and
871 either kill them all off properly, or subscribe to them. This is the
875 @vindex gnus-subscribe-hierarchical-interactive
876 A closely related variable is
877 @code{gnus-subscribe-hierarchical-interactive}. (That's quite a
878 mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a
879 hierarchical fashion whether to subscribe to new groups or not. Gnus
880 will ask you for each sub-hierarchy whether you want to descend the
883 One common way to control which new newsgroups should be subscribed or
884 ignored is to put an @dfn{options} line at the start of the
885 @file{.newsrc} file. Here's an example:
888 options -n !alt.all !rec.all sci.all
891 @vindex gnus-subscribe-options-newsgroup-method
892 This line obviously belongs to a serious-minded intellectual scientific
893 person (or she may just be plain old boring), because it says that all
894 groups that have names beginning with @samp{alt} and @samp{rec} should
895 be ignored, and all groups with names beginning with @samp{sci} should
896 be subscribed. Gnus will not use the normal subscription method for
897 subscribing these groups.
898 @code{gnus-subscribe-options-newsgroup-method} is used instead. This
899 variable defaults to @code{gnus-subscribe-alphabetically}.
901 @vindex gnus-options-not-subscribe
902 @vindex gnus-options-subscribe
903 If you don't want to mess with your @file{.newsrc} file, you can just
904 set the two variables @code{gnus-options-subscribe} and
905 @code{gnus-options-not-subscribe}. These two variables do exactly the
906 same as the @file{.newsrc} options -n trick. Both are regexps, and if
907 the the new group matches the first, it will be unconditionally
908 subscribed, and if it matches the latter, it will be ignored.
910 @vindex gnus-auto-subscribed-groups
911 Yet another variable that meddles here is
912 @code{gnus-auto-subscribed-groups}. It works exactly like
913 @code{gnus-options-subscribe}, and is therefore really superfluos, but I
914 thought it would be nice to have two of these. This variable is more
915 meant for setting some ground rules, while the other variable is used
916 more for user fiddling. By default this variable makes all new groups
917 that come from mail backends (@code{nnml}, @code{nnbabyl},
918 @code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you
919 don't like that, just set this variable to @code{nil}.
921 @vindex gnus-check-new-newsgroups
922 If you are satisfied that you really never want to see any new groups,
923 you could set @code{gnus-check-new-newsgroups} to @code{nil}. This will
924 also save you some time at startup. Even if this variable is
925 @code{nil}, you can always subscribe to the new groups just by pressing
926 @kbd{U} in the group buffer (@pxref{Group Maintenance}).
928 Gnus normally determines whether a group is new or not by comparing the
929 list of groups from the active file(s) with the lists of subscribed and
930 dead groups. This isn't a particularly fast method. If
931 @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
932 server for new groups since the last time. This is both faster &
933 cheaper. This also means that you can get rid of the list of killed
934 groups altogether, so you may set @code{gnus-save-killed-list} to
935 @code{nil}, which will save time both at startup, at exit, and all over.
936 Saves disk space, too. Why isn't this the default, then?
937 Unfortunately, not all servers support this function.
939 This variable can also be a list of select methods. If so, Gnus will
940 issue an @code{ask-server} command to each of the select methods, and
941 subscribe them (or not) using the normal methods. This might be handy
942 if you are monitoring a few servers for new groups. A side effect is
943 that startup will take much longer, so you can meditate while waiting.
944 Use the mantra "dingnusdingnusdingnus" to achieve permanent happiness.
947 @section Startup Files
948 @cindex startup files
951 Now, you all know about the @file{.newsrc} file. All subscription
952 information is traditionally stored in this file.
954 Things got a bit more complicated with @sc{gnus}. In addition to
955 keeping the @file{.newsrc} file updated, it also used a file called
956 @file{.newsrc.el} for storing all the information that didn't fit into
957 the @file{.newsrc} file. (Actually, it duplicated everything in the
958 @file{.newsrc} file.) @sc{gnus} would read whichever one of these files
959 that were the most recently saved, which enabled people to swap between
960 @sc{gnus} and other newsreaders.
962 That was kinda silly, so Gnus went one better: In addition to the
963 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
964 @file{.newsrc.eld}. It will read whichever of these files that are most
965 recent, but it will never write a @file{.newsrc.el} file.
967 @vindex gnus-save-newsrc-file
968 You can also turn off writing the @file{.newsrc} file by setting
969 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
970 the file and save some space, as well as making exit from Gnus faster.
971 However, this will make it impossible to use other newsreaders than
972 Gnus. But hey, who would want to, right?
974 @vindex gnus-save-killed-list
975 If @code{gnus-save-killed-list} is @code{nil}, Gnus will not save the
976 list of killed groups to the startup file. This will save both time
977 (when starting and quitting) and space (on disk). It will also means
978 that Gnus has no record of what groups are new or old, so the automatic
979 new groups subscription methods become meaningless. You should always
980 set @code{gnus-check-new-newsgroups} to @code{nil} or @code{ask-server}
981 if you set this variable to @code{nil} (@pxref{New Groups}).
983 @vindex gnus-startup-file
984 The @code{gnus-startup-file} variable says where the startup files are.
985 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
986 file being whatever that one is with a @samp{.eld} appended.
988 @vindex gnus-save-newsrc-hook
989 @vindex gnus-save-quick-newsrc-hook
990 @vindex gnus-save-standard-newsrc-hook
991 @code{gnus-save-newsrc-hook} is called before saving any of the newsrc
992 files, while @code{gnus-save-quick-newsrc-hook} is called just before
993 saving the @file{.newsrc.eld} file, and
994 @code{gnus-save-standard-newsrc-hook} is called just before saving the
995 @file{.newsrc} file. The latter two are commonly used to tern version
1000 @cindex dribble file
1003 Whenever you do something that changes the Gnus data (reading articles,
1004 catching up, killing/subscribing groups), the change is added to a
1005 special @dfn{dribble buffer}. This buffer is auto-saved the normal
1006 Emacs way. If your Emacs should crash before you have saved the
1007 @file{.newsrc} files, all changes you have made can be recovered from
1010 If Gnus detects this file at startup, it will ask the user whether to
1011 read it. The auto save file is deleted whenever the real startup file is
1014 @vindex gnus-use-dribble-file
1015 If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
1016 maintain a dribble buffer.
1018 @vindex gnus-dribble-directory
1019 Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
1020 this variable is @code{nil}, which it is by default, Gnus will dribble
1021 into the same directory as the @file{.newsrc} file is located. (This is
1022 normally the user's home directory.)
1024 @node The Active File
1025 @section The Active File
1027 @cindex ignored groups
1029 When Gnus starts, or indeed whenever it tries to determine whether new
1030 articles have arrived, it reads the active file. This is a very large
1031 file that lists all the active groups and articles on the @sc{nntp}
1034 @vindex gnus-ignored-newsgroups
1035 Before examining the active file, Gnus deletes all lines that match the
1036 regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject
1037 any groups with bogus names, but you can use this variable to make Gnus
1038 ignore hierarchies you aren't ever interested in. This variable is
1039 @code{nil} by default, and will slow down active file handling somewhat
1040 if you set it to anything else.
1042 @vindex gnus-read-active-file
1043 The active file can be rather Huge, so if you have a slow network, you
1044 can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
1045 reading the active file.
1047 Gnus will try to make do by just getting information on the groups
1048 that you actually subscribe to.
1050 Note that if you subscribe to lots and lots of groups, setting this
1051 variable to @code{nil} will probably make Gnus slower, not faster. At
1052 present, having this variable @code{nil} will slow Gnus down
1053 considerably, unless you read news over a 2400 baud modem.
1055 This variable can also have the value @code{some}. Gnus will then
1056 attempt to read active info only on the subscribed groups. On some
1057 servers this is quite fast (on sparkling, brand new INN servers that
1058 support the @samp{LIST ACTIVE group} command), on others this is not
1059 fast at all. In any case, @code{some} should be faster than @code{nil},
1060 and is certainly faster than @code{t} over slow lines.
1062 If this variable is @code{nil}, Gnus will as for group info in total
1063 lock-step, which isn't very fast. If it is @code{some} and you use an
1064 @sc{nntp} server, Gnus will pump out commands as fast as it can, and
1065 read all the replies in one swoop. This will normally result in better
1066 performance, but if the server does not support the aforementioned
1067 @samp{LIST ACTIVE group} command, this isn't very nice to the server.
1069 In any case, if you use @code{some} or @code{nil}, you should kill all
1070 groups that you aren't interested in.
1072 @node Startup Variables
1073 @section Startup Variables
1076 @item gnus-load-hook
1077 @vindex gnus-load-hook
1078 A hook that is run while Gnus is being loaded. Note that this hook will
1079 normally be run just once in each Emacs session, no matter how many
1080 times you start Gnus.
1082 @item gnus-startup-hook
1083 @vindex gnus-startup-hook
1084 A hook that is run after starting up Gnus successfully.
1086 @item gnus-check-bogus-newsgroups
1087 @vindex gnus-check-bogus-newsgroups
1088 If non-@code{nil}, Gnus will check for and delete all bogus groups at
1089 startup. A @dfn{bogus group} is a group that you have in your
1090 @file{.newsrc} file, but doesn't exist on the news server. Checking for
1091 bogus groups isn't very quick, so to save time and resources, it's best
1092 to leave this option off, and instead do the checking for bogus groups
1093 once in a while from the group buffer (@pxref{Group Maintenance}).
1095 @item gnus-inhibit-startup-message
1096 @vindex gnus-inhibit-startup-message
1097 If non-@code{nil}, the startup message won't be displayed. That way,
1098 your boss might not notice that you are reading news instead of doing
1101 @item gnus-no-groups-message
1102 @vindex gnus-no-groups-message
1103 Message displayed by Gnus when no groups are available.
1106 @node The Group Buffer
1107 @chapter The Group Buffer
1108 @cindex group buffer
1110 The @dfn{group buffer} lists all (or parts) of the available groups. It
1111 is the first buffer shown when Gnus starts, and will never be killed as
1112 long as Gnus is active.
1115 * Group Buffer Format:: Information listed and how you can change it.
1116 * Group Maneuvering:: Commands for moving in the group buffer.
1117 * Selecting a Group:: Actually reading news.
1118 * Subscription Commands:: Unsubscribing, killing, subscribing.
1119 * Group Levels:: Levels? What are those, then?
1120 * Marking Groups:: You can mark groups for later processing.
1121 * Foreign Groups:: How to create foreign groups.
1122 * Group Parameters:: Each group may have different parameters set.
1123 * Listing Groups:: Gnus can list various subsets of the groups.
1124 * Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
1125 * Browse Foreign Server:: You can browse a server. See what if has to offer.
1126 * Exiting Gnus:: Stop reading news and get some work done.
1127 * Group Topics:: A folding group mode divided into topics.
1128 * Misc Group Stuff:: Other stuff that you can to do.
1131 @node Group Buffer Format
1132 @section Group Buffer Format
1133 @cindex group buffer format
1135 The default format of the group buffer is nice and dull, but you can
1136 make it as exciting and ugly as you feel like.
1138 Here's a couple of example group lines:
1141 25: news.announce.newusers
1142 * 0: alt.fan.andrea-dworkin
1147 You can see that there are 25 unread articles in
1148 @samp{news.announce.newusers}. There are no unread articles, but some
1149 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
1150 asterisk at the beginning of the line?)
1152 @vindex gnus-group-line-format
1153 You can fuck that up to your heart's delight by fiddling with the
1154 @code{gnus-group-line-format} variable. This variable works along the
1155 lines of a @code{format} specification, which is pretty much the same as
1156 a @code{printf} specifications, for those of you who use (feh!) C.
1158 In addition to the normal "padding" specs that @code{format} supports
1159 (eg. @samp{%7d}), specifications like @samp{%7,12s} are allowed. A spec
1160 of this type means that the field will be at least 7 characters long,
1161 and never more that 12 characters long.
1163 The default value that produced those lines above is
1164 @samp{"%M%S%5y: %(%g%)\n"}.
1166 There should always be a colon on the line; the cursor always moves to
1167 the colon after performing an operation. Nothing else is required---not
1168 even the group name. All displayed text is just window dressing, and is
1169 never examined by Gnus. Gnus stores all real information it needs using
1172 (Note that if you make a really strange, wonderful, spreadsheet-like
1173 layout, everybody will believe you are hard at work with the accounting
1174 instead of wasting time reading news.)
1176 Here's a list of all available format characters:
1180 Only marked articles.
1182 Whether the group is subscribed.
1184 Level of subscribedness.
1186 Number of unread articles.
1188 Number of dormant articles.
1190 Number of ticked articles.
1192 Number of read articles.
1194 Total number of articles.
1196 Number of unread, unticked, non-dormant articles.
1198 Number of ticked and dormant articles.
1204 Newsgroup description.
1214 A string that looks like @samp{<%s:%n>} if a foreign select method is
1217 User defined specifier. The next character in the format string should
1218 be a letter. @sc{gnus} will call the function
1219 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
1220 following @samp{%u}. The function will be passed the current headers as
1221 argument. The function should return a string, which will be inserted
1222 into the buffer just like information from any other specifier.
1226 All the "number-of" specs will be filled with an asterisk (@samp{*}) if
1227 no info is available---for instance, if it is a non-activated foreign
1228 group, or a bogus (or semi-bogus) native group.
1230 @vindex gnus-group-mode-line-format
1231 The mode line can be changed by setting
1232 (@code{gnus-group-mode-line-format}). It doesn't understand that many
1237 Default news server.
1239 Default select method.
1242 @node Group Maneuvering
1243 @section Group Maneuvering
1244 @cindex group movement
1246 All movement commands understand the numeric prefix and will behave as
1247 expected, hopefully.
1252 @findex gnus-group-next-unread-group
1253 Go to the next group that has unread articles
1254 (@code{gnus-group-next-unread-group}).
1259 @findex gnus-group-prev-unread-group
1260 Go to the previous group group that has unread articles
1261 (@code{gnus-group-prev-unread-group}).
1264 @findex gnus-group-next-group
1265 Go to the next group (@code{gnus-group-next-group}).
1268 @findex gnus-group-prev-group
1269 Go to the previous group (@code{gnus-group-prev-group}).
1272 @findex gnus-group-next-unread-group-same-level
1273 Go to the next unread group on the same level (or lower)
1274 (@code{gnus-group-next-unread-group-same-level}).
1277 @findex gnus-group-prev-unread-group-same-level
1278 Go to the previous unread group on the same level (or lower)
1279 (@code{gnus-group-prev-unread-group-same-level}).
1282 Three commands for jumping to groups:
1287 @findex gnus-group-jump-to-group
1288 Jump to a group (and make it visible if it isn't already)
1289 (@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
1293 @findex gnus-group-best-unread-group
1294 Jump to the unread group with the lowest level
1295 (@code{gnus-group-best-unread-group}).
1298 @findex gnus-group-first-unread-group
1299 Jump to the first group with unread articles
1300 (@code{gnus-group-first-unread-group}).
1303 @vindex gnus-group-goto-unread
1304 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
1305 commands will move to the next group, not the next unread group. Even
1306 the commands that say they move to the next unread group.
1308 @node Selecting a Group
1309 @section Selecting a Group
1310 @cindex group selection
1315 @kindex SPACE (Group)
1316 @findex gnus-group-read-group
1317 Select the current group, switch to the summary buffer and display the
1318 first unread article (@code{gnus-group-read-group}). If there are no
1319 unread articles in the group, or if you give a non-numerical prefix to
1320 this command, Gnus will offer to fetch all the old articles in this
1321 group from the server. If you give a numerical prefix @var{N}, Gnus
1322 will fetch @var{N} number of articles. If @var{N} is positive, fetch
1323 the @var{N} newest articles, if @var{N} is negative, fetch the
1324 @var{abs(N)} oldest articles.
1328 @findex gnus-group-select-group
1329 Select the current group and switch to the summary buffer
1330 (@code{gnus-group-select-group}). Takes the same arguments as
1331 @code{gnus-group-read-group}---the only difference is that this command
1332 does not display the first unread article automatically upon group
1336 @kindex M-RET (Group)
1337 @findex gnus-group-quick-select-group
1338 This does the same as the command above, but tries to do it with the
1339 minimum amount off fuzz (@code{gnus-group-quick-select-group}). No
1340 scoring/killing will be performed, there will be no highlights and no
1341 expunging. This might be useful if you're in a real hurry and have to
1342 enter some humongous groups.
1346 @findex gnus-group-catchup-current
1347 Mark all unticked articles in this group as read
1348 (@code{gnus-group-catchup-current}).
1352 @findex gnus-group-catchup-current-all
1353 Mark all articles in this group, even the ticked ones, as read
1354 (@code{gnus-group-catchup-current-all}).
1357 @vindex gnus-large-newsgroup
1358 The @code{gnus-large-newsgroup} variable says what Gnus should consider
1359 to be a big group. If the group has more unread articles than this,
1360 Gnus will query the user before entering the group. The user can then
1361 specify how many articles should be fetched from the server. If the
1362 user specifies a negative number (@samp{-n}), the @samp{n} oldest
1363 articles will be fetched. If it is positive, the @samp{n} articles that
1364 have arrived most recently will be fetched.
1366 @vindex gnus-select-group-hook
1367 @vindex gnus-auto-select-first
1368 If @code{gnus-auto-select-first} is non-@code{nil}, the first unread
1369 article in the group will be displayed when you enter the group. If you
1370 want to prevent automatic selection in some group (say, in a binary
1371 group with Huge articles) you can set this variable to @code{nil} in
1372 @code{gnus-select-group-hook}, which is called when a group is selected.
1374 @findex gnus-thread-sort-by-total-score
1375 @findex gnus-thread-sort-by-date
1376 @findex gnus-thread-sort-by-score
1377 @findex gnus-thread-sort-by-subject
1378 @findex gnus-thread-sort-by-author
1379 @findex gnus-thread-sort-by-number
1380 @vindex gnus-thread-sort-functions
1381 If you are using a threaded summary display, you can sort the threads by
1382 setting @code{gnus-thread-sort-functions}, which is a list of functions.
1383 By default, sorting is done on article numbers. Ready-made sorting
1384 functions include @code{gnus-thread-sort-by-number},
1385 @code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
1386 @code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score},
1387 @code{gnus-thread-sort-by-total-score}.
1389 Each function takes two threads and return non-@code{nil} if the first
1390 thread should be sorted before the other. If you use more than one
1391 function, the primary sort key should be the last function in the list.
1393 If you would like to sort by score, then by subject, and finally by
1394 date, you could do something like:
1397 (setq gnus-thread-sort-functions
1398 '(gnus-thread-sort-by-date
1399 gnus-thread-sort-by-subject
1400 gnus-thread-sort-by-score))
1403 @vindex gnus-thread-score-function
1404 The function in the @code{gnus-thread-score-function} variable (default
1405 @code{+}) is used for calculating the total score of a thread. Useful
1406 functions might be @code{max}, @code{min}, or squared means, or whatever
1409 @node Subscription Commands
1410 @section Subscription Commands
1418 @findex gnus-group-unsubscribe-current-group
1419 Toggle subscription to the current group
1420 (@code{gnus-group-unsubscribe-current-group}).
1425 @findex gnus-group-unsubscribe-group
1426 Prompt for a group to subscribe, and then subscribe it. If it was
1427 subscribed already, unsubscribe it instead
1428 (@code{gnus-group-unsubscribe-group}).
1433 @findex gnus-group-kill-group
1434 Kill the current group (@code{gnus-group-kill-group}).
1439 @findex gnus-group-yank-group
1440 Yank the last killed group (@code{gnus-group-yank-group}).
1445 @findex gnus-group-kill-region
1446 Kill all groups in the region (@code{gnus-group-kill-region}).
1449 @findex gnus-group-kill-all-zombies
1450 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
1453 Also @xref{Group Levels}.
1456 @section Group Levels
1459 All groups have a level of @dfn{subscribedness}. For instance, if a
1460 group is on level 2, it is more subscribed than a group on level 5. You
1461 can ask Gnus to just list groups on a given level or lower
1462 (@pxref{Listing Groups}), or to just check for new articles in groups on
1463 a given level or lower (@pxref{Misc Group Stuff}).
1468 @findex gnus-group-set-current-level
1469 Set the level of the current group. If a numeric prefix is given, the
1470 next @var{n} groups will have their levels set. The user will be
1471 prompted for a level.
1474 @vindex gnus-level-killed
1475 @vindex gnus-level-zombie
1476 @vindex gnus-level-unsubscribed
1477 @vindex gnus-level-subscribed
1478 Gnus considers groups on between levels 1 and
1479 @code{gnus-level-subscribed} (inclusive) to be subscribed,
1480 @code{gnus-level-subscribed} (exclusive) and
1481 @code{gnus-level-unsubscribed} (inclusive) to be unsubscribed,
1482 @code{gnus-level-zombie} to be zombies (walking dead) and
1483 @code{gnus-level-killed} to be killed, completely dead. Gnus treats
1484 subscribed and unsubscribed groups exactly the same, but zombie and
1485 killed groups have no information on what articles you have read, etc,
1486 stored. This distinction between dead and living groups isn't done
1487 because it is nice or clever, it is done purely for reasons of
1490 It is recommended that you keep all your mail groups (if any) on quite
1491 low levels (eg. 1 or 2).
1493 If you want to play with the level variables, you should show some care.
1494 Set them once, and don't touch them ever again. Better yet, don't touch
1495 them at all unless you know exactly what you're doing.
1497 @vindex gnus-level-default-unsubscribed
1498 @vindex gnus-level-default-subscribed
1499 Two closely related variables are @code{gnus-level-default-subscribed}
1500 and @code{gnus-level-default-unsubscribed}, which are the levels that new
1501 groups will be put on if they are (un)subscribed. These two variables
1502 should, of course, be inside the relevant legal ranges.
1504 @vindex gnus-keep-same-level
1505 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
1506 will only move to groups that are of the same level (or lower). In
1507 particular, going from the last article in one group to the next group
1508 will go to the next group of the same level (or lower). This might be
1509 handy if you want to read the most important groups before you read the
1512 @vindex gnus-group-default-list-level
1513 All groups with a level less than or equal to
1514 @code{gnus-group-default-list-level} will be listed in the group buffer
1517 @vindex gnus-group-use-permament-levels
1518 If @code{gnus-group-use-permament-levels} is non-@code{nil}, once you
1519 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
1520 use this level as the "work" level.
1522 @node Marking Groups
1523 @section Marking Groups
1524 @cindex marking groups
1526 If you want to perform some command on several groups, and they appear
1527 subsequently in the group buffer, you would normally just give a
1528 numerical prefix to the command. Most group commands will then do your
1529 bidding on those groups.
1531 However, if the groups are not in sequential order, you can still
1532 perform a command on several groups. You simply mark the groups first
1533 with the process mark and then execute the command.
1541 @findex gnus-group-mark-group
1542 Set the mark on the current group (@code{gnus-group-mark-group}).
1548 @findex gnus-group-unmark-group
1549 Remove the mark from the current group
1550 (@code{gnus-group-unmark-group}).
1554 @findex gnus-group-mark-region
1555 Mark all groups between point and mark (@code{gnus-group-mark-region}).
1558 Also @xref{Process/Prefix}.
1561 @node Foreign Groups
1562 @section Foreign Groups
1563 @cindex foreign groups
1565 A @dfn{foreign group} is a group that is not read by the usual (or
1566 default) means. It could be, for instance, a group from a different
1567 @sc{nntp} server, it could be a virtual group, or it could be your own
1568 personal mail group.
1570 A foreign group (or any group, really) is specified by a @dfn{name} and
1571 a @dfn{select method}. To take the latter first, a select method is a
1572 list where the first element says what backend to use (eg. @code{nntp},
1573 @code{nnspool}, @code{nnml}) and the second element is the @dfn{server
1574 name}. There may be additional elements in the select method, where the
1575 value may have special meaning for the backend in question.
1577 One could say that a select method defines a @dfn{virtual server}---so
1578 we do just that (@pxref{The Server Buffer}).
1580 The @dfn{name} of the group is the name the backend will recognize the
1583 For instance, the group @samp{soc.motss} on the @sc{nntp} server
1584 @samp{some.where.edu} will have the name @samp{soc.motss} and select
1585 method @code{(nntp "some.where.edu")}. Gnus will call this group, in
1586 all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
1587 @code{nntp} backend just knows this group as @samp{soc.motss}.
1589 Here are some commands for making and editing general foreign groups,
1590 and some commands to ease the creation of some special-purpose groups:
1595 @findex gnus-group-make-group
1596 Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
1597 for a name, a method and possibly an @dfn{address}. For an easier way
1598 to subscribe to @sc{nntp} groups, @xref{Browse Foreign Server}.
1602 @findex gnus-group-rename-group
1603 Rename the current group to something else
1604 (@code{gnus-group-rename-group}). This is legal only on some groups --
1605 mail groups mostly. This command might very well be quite slow on some
1610 @findex gnus-group-edit-group-method
1611 Enter a buffer where you can edit the select method of the current
1612 group (@code{gnus-group-edit-group-method}).
1616 @findex gnus-group-edit-group-parameters
1617 Enter a buffer where you can edit the group parameters
1618 (@code{gnus-group-edit-group-parameters}).
1622 @findex gnus-group-edit-group
1623 Enter a buffer where you can edit the group info
1624 (@code{gnus-group-edit-group}).
1628 @findex gnus-group-make-directory-group
1629 Make a directory group. You will be prompted for a directory name
1630 (@code{gnus-group-make-directory-group}).
1634 @findex gnus-group-make-help-group
1635 Make the Gnus help group (@code{gnus-group-make-help-group}).
1639 @findex gnus-group-make-archive-group
1640 @vindex gnus-group-archive-directory
1641 @vindex gnus-group-recent-archive-directory
1642 Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
1643 default a group pointing to the most recent articles will be created
1644 (@code{gnus-group-recent-archibe-directory}), but given a prefix, a full
1645 group will be created from from @code{gnus-group-archive-directory}.
1649 @findex gnus-group-make-kiboze-group
1650 Make a kiboze group. You will be prompted for a name, for a regexp to
1651 match groups to be "included" in the kiboze group, and a series of
1652 strings to match on headers (@code{gnus-group-make-kiboze-group}).
1656 @findex gnus-group-enter-directory
1657 Read a random directory as if with were a newsgroup with the
1658 @code{nneething} backend (@code{gnus-group-enter-directory}).
1662 @findex gnus-group-make-doc-group
1663 Make a group based on some file or other
1664 (@code{gnus-group-make-doc-group}). You will be prompted for a file
1665 name and a file type. Currently supported types are @code{babyl},
1666 @code{mbox} and @code{digest}.
1669 @kindex G DEL (Group)
1670 @findex gnus-group-delete-group
1671 This function will delete the current group
1672 (@code{gnus-group-delete-group}). If given a prefix, this function will
1673 actually delete all the articles in the group, and forcibly remove the
1674 group itself from the face of the Earth. Use a prefix only if you are
1675 sure of what you are doing.
1679 @findex gnus-group-make-empty-virtual
1680 Make a new, fresh, empty @code{nnvirtual} group
1681 (@code{gnus-group-make-empty-virtual}).
1685 @findex gnus-group-add-to-virtual
1686 Add the current group to an @code{nnvirtual} group
1687 (@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
1690 The different methods all have their peculiarities, of course.
1693 * nntp:: Reading news from a different @sc{nntp} server.
1694 * nnspool:: Reading news from the local spool.
1695 * nnvirtual:: Combining articles from many groups.
1696 * nnkiboze:: Looking through parts of the newsfeed for articles.
1697 * nndir:: You can read a directory as if it was a newsgroup.
1698 * nneething:: Dired? Who needs dired?
1699 * nndoc:: Single files can be the basis of a group.
1700 * Reading Mail:: Reading your personal mail with Gnus.
1703 @vindex gnus-activate-foreign-newsgroups
1704 If the @code{gnus-activate-foreign-newsgroups} is a positive number,
1705 Gnus will check all foreign groups with this level or lower at startup.
1706 This might take quite a while, especially if you subscribe to lots of
1707 groups from different @sc{nntp} servers. It is @code{nil} by default,
1708 which means that you won't be told whether there are new articles in
1709 these groups. How many unread articles there are will be determined
1710 when, or if, you decide to enter them. You can also activate any group
1711 with @kbd{M-g} to see how many unread articles there are.
1717 Subscribing to a foreign group from an @sc{nntp} server is rather easy.
1718 You just specify @code{nntp} as method and the address of the @sc{nntp}
1719 server as the, uhm, address.
1721 If the @sc{nntp} server is located at a non-standard port, setting the
1722 third element of the select method to this port number should allow you
1723 to connect to the right port. You'll have to edit the group info for
1724 that (@pxref{Foreign Groups}).
1726 The name of the foreign group can be the same as a native group. In
1727 fact, you can subscribe to the same group from as many different servers
1728 you feel like. There will be no name collisions.
1730 The following variables can be used to create a virtual @code{nntp}
1734 @item nntp-server-opened-hook
1735 @vindex nntp-server-opened-hook
1736 @cindex @sc{mode reader}
1738 @cindex authentification
1739 @cindex nntp authentification
1740 @findex nntp-send-authinfo
1741 @findex nntp-send-mode-reader
1742 @code{nntp-server-opened-hook} is run after a connection has been made.
1743 It can be used to send commands to the @sc{nntp} server after it has
1744 been contacted. By default is sends the command @samp{MODE READER} to
1745 the server with the @code{nntp-send-mode-reader} function. Another
1746 popular function is @code{nntp-send-authinfo}, which will prompt you for
1747 an @sc{nntp} password and stuff.
1749 @item nntp-maximum-request
1750 @vindex nntp-maximum-request
1751 If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
1752 will collect headers by sending a series of @code{head} commands. To
1753 speed things up, the backend sends lots of these commands without
1754 waiting for reply, and then reads all the replies. This is controlled
1755 by the @code{nntp-maximum-request} variable, and is 400 by default. If
1756 your network is buggy, you should set this to 1.
1758 @item nntp-connection-timeout
1759 @vindex nntp-connection-timeout
1760 If you have lots of foreign @code{nntp} groups that you connect to
1761 regularly, you're sure to have problems with @sc{nntp} servers not
1762 responding properly, or being too loaded to reply within reasonable
1763 time. This is can lead to awkward problems, which can be helped
1764 somewhat by setting @code{nntp-connection-timeout}. This is an integer
1765 that says how many seconds the @code{nntp} backend should wait for a
1766 connection before giving up. If it is @code{nil}, which is the default,
1767 no timeouts are done.
1769 @item nntp-server-hook
1770 @vindex nntp-server-hook
1771 This hook is run as the last step when connecting to an @sc{nntp}
1774 @c @findex nntp-open-rlogin
1775 @c @findex nntp-open-network-stream
1776 @c @item nntp-open-server-function
1777 @c @vindex nntp-open-server-function
1778 @c This function is used to connect to the remote system. Two pre-made
1779 @c functions are @code{nntp-open-network-stream}, which is the default, and
1780 @c simply connects to some port or other on the remote system. The other
1781 @c is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
1782 @c and then does a telnet to the @sc{nntp} server available there.
1784 @c @item nntp-rlogin-parameters
1785 @c @vindex nntp-rlogin-parameters
1786 @c If you use @code{nntp-open-rlogin} as the
1787 @c @code{nntp-open-server-function}, this list will be used as the
1788 @c parameter list given to @code{rsh}.
1790 @c @item nntp-rlogin-user-name
1791 @c @vindex nntp-rlogin-user-name
1792 @c User name on the remote system when using the @code{rlogin} connect
1796 @vindex nntp-address
1797 The address of the remote system running the @sc{nntp} server.
1799 @item nntp-port-number
1800 @vindex nntp-port-number
1801 Port number to connect to when using the @code{nntp-open-network-stream}
1804 @item nntp-buggy-select
1805 @vindex nntp-buggy-select
1806 Set this to non-@code{nil} if your select routine is buggy.
1808 @item nntp-nov-is-evil
1809 @vindex nntp-nov-is-evil
1810 If the @sc{nntp} server does not support @sc{nov}, you could set this
1811 variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
1812 can be used automatically.
1814 @item nntp-xover-commands
1815 @vindex nntp-xover-commands
1816 List of strings that are used as commands to fetch @sc{nov} lines from a
1817 server. The default value of this variable is @code{("XOVER"
1821 @vindex nntp-nov-gap
1822 @code{nntp} normally sends just one big request for @sc{nov} lines to
1823 the server. The server responds with one huge list of lines. However,
1824 if you have read articles 2-5000 in the group, and only want to read
1825 article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
1826 lines that you do not want, and will not use. This variable says how
1827 big a gap between two consecutive articles is allowed to be before the
1828 @code{XOVER} request is split into several request. Note that if your
1829 network is fast, setting this variable to a really small number means
1830 that fetching will probably be slower. If this variable is @code{nil},
1831 @code{nntp} will never split requests.
1833 @item nntp-prepare-server-hook
1834 @vindex nntp-prepare-server-hook
1835 A hook run before attempting to connect to an @sc{nntp} server.
1837 @item nntp-async-number
1838 @vindex nntp-async-number
1839 How many articles should be pre-fetched when in asynchronous mode. If
1840 this variable is @code{t}, @code{nntp} will pre-fetch all the articles
1841 that it can without bound. If it is @code{nil}, no pre-fetching will be
1844 @item nntp-warn-about-losing-connection
1845 @vindex nntp-warn-about-losing-connection
1846 If this variable is non-@code{nil}, some noise will be made when a
1847 server closes connection.
1854 @cindex @code{nnspool}
1857 Subscribing to a foreign group from the local spool is extremely easy,
1858 and might be useful, for instance, to speed up reading groups like
1859 @samp{alt.binaries.pictures.furniture}.
1861 Anyways, you just specify @code{nnspool} as the method and @samp{""} (or
1862 anything else) as the address.
1864 If you have access to a local spool, you should probably use that as the
1865 native select method (@pxref{Finding the News}).
1868 @item nnspool-inews-program
1869 @vindex nnspool-inews-program
1870 Program used to post an article.
1872 @item nnspool-inews-switches
1873 @vindex nnspool-inews-switches
1874 Parameters given to the inews program when posting an article.
1876 @item nnspool-spool-directory
1877 @vindex nnspool-spool-directory
1878 Where @code{nnspool} looks for the articles. This is normally
1879 @file{/usr/spool/news/}.
1881 @item nnspool-nov-directory
1882 @vindex nnspool-nov-directory
1883 Where @code{nnspool} will look for @sc{nov} files. This is normally
1884 @file{/usr/spool/news/over.view/}.
1886 @item nnspool-lib-dir
1887 @vindex nnspool-lib-dir
1888 Where the news lib dir is (@file{/usr/lib/news/} by default).
1890 @item nnspool-active-file
1891 @vindex nnspool-active-file
1892 The path of the active file.
1894 @item nnspool-newsgroups-file
1895 @vindex nnspool-newsgroups-file
1896 The path of the group description file.
1898 @item nnspool-history-file
1899 @vindex nnspool-history-file
1900 The path of the news history file.
1902 @item nnspool-active-times-file
1903 @vindex nnspool-active-times-file
1904 The path of the active date file.
1906 @item nnspool-nov-is-evil
1907 @vindex nnspool-nov-is-evil
1908 If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
1911 @item nnspool-sift-nov-with-sed
1912 @vindex nnspool-sift-nov-with-sed
1913 If non-@code{nil}, which is the default, use @code{sed} to get the
1914 relevant portion from the overview file. If nil, @code{nnspool} will
1915 load the entire file into a buffer and process it there.
1920 @subsection nnvirtual
1921 @cindex @code{nnvirtual}
1922 @cindex virtual groups
1924 An @dfn{nnvirtual group} is really nothing more than a collection of
1927 For instance, if you are tired of reading many small group, you can
1928 put them all in one big group, and then grow tired of reading one
1929 big, unwieldy group. The joys of computing!
1931 You specify @code{nnvirtual} as the method. The address should be a
1932 regexp to match component groups.
1934 All marks in the virtual group will stick to the articles in the
1935 component groups. So if you tick an article in a virtual group, the
1936 article will also be ticked in the component group from whence it came.
1937 (And vice versa---marks from the component groups will also be shown in
1940 Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
1941 newsgroups into one, big, happy newsgroup:
1944 (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
1947 The component groups can be native or foreign; everything should work
1948 smoothly, but if your computer explodes, it was probably my fault.
1950 Collecting the same group from several servers might actually be a good
1951 idea if users have set the Distribution header to limit distribution.
1952 If you would like to read @samp{soc.motss} both from a server in Japan
1953 and a server in Norway, you could use the following as the group regexp:
1956 "^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
1959 This should work kinda smoothly---all articles from both groups should
1960 end up in this one, and there should be no duplicates. Threading (and
1961 the rest) will still work as usual, but there might be problems with the
1962 sequence of articles. Sorting on date might be an option here
1963 (@pxref{Selecting a Group}.
1965 One limitation, however---all groups that are included in a virtual
1966 group has to be alive (i.e., subscribed or unsubscribed). Killed or
1967 zombie groups can't be component groups for @code{nnvirtual} groups.
1970 @subsection nnkiboze
1971 @cindex @code{nnkiboze}
1974 @dfn{Kibozing} is defined by @sc{oed} as "grepping through (parts of)
1975 the news feed". @code{nnkiboze} is a backend that will do this for you. Oh
1976 joy! Now you can grind any @sc{nntp} server down to a halt with useless
1977 requests! Oh happiness!
1979 The address field of the @code{nnkiboze} method is, as with @code{nnvirtual}, a regexp
1980 to match groups to be "included" in the @code{nnkiboze} group. There most
1981 similarities between @code{nnkiboze} and @code{nnvirtual} ends.
1983 In addition to this regexp detailing component groups, an @code{nnkiboze} group
1984 must have a score file to say what articles that are to be included in
1985 the group (@pxref{Scoring}).
1987 @kindex M-x nnkiboze-generate-groups
1988 @findex nnkiboze-generate-groups
1989 You must run @kbd{M-x nnkiboze-generate-groups} after creating the
1990 @code{nnkiboze} groups you want to have. This command will take time. Lots of
1991 time. Oodles and oodles of time. Gnus has to fetch the headers from
1992 all the articles in all the components groups and run them through the
1993 scoring process to determine if there are any articles in the groups
1994 that are to be part of the @code{nnkiboze} groups.
1996 Please limit the number of component groups by using restrictive
1997 regexps. Otherwise your sysadmin may become annoyed with you, and the
1998 @sc{nntp} site may throw you off and never let you back in again.
1999 Stranger things have happened.
2001 @code{nnkiboze} component groups do not have to be alive---they can be dead,
2002 and they can be foreign. No restrictions.
2004 @vindex nnkiboze-directory
2005 The generation of an @code{nnkiboze} group means writing two files in
2006 @code{nnkiboze-directory}, which is @file{~/News/} by default. One
2007 contains the @sc{nov} header lines for all the articles in the group,
2008 and the other is an additional @file{.newsrc} file to store information
2009 on what groups that have been searched through to find component
2012 Articles that are marked as read in the @code{nnkiboze} group will have their
2013 @sc{nov} lines removed from the @sc{nov} file.
2017 @cindex @code{nndir}
2018 @cindex directory groups
2020 If you have a directory that has lots of articles in separate files in
2021 it, you might treat it as a newsgroup. The files have to have numerical
2024 This might be an opportune moment to mention @code{ange-ftp}, that most
2025 wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
2026 didn't think much about it---a backend to read directories. Big deal.
2028 @code{ange-ftp} changes that picture dramatically. For instance, if you
2029 enter @file{"/ftp@@sina.tcamc.uh.edu:/pub/emacs/ding-list/"} as the the
2030 directory name, ange-ftp will actually allow you to read this directory
2031 over at @samp{sina} as a newsgroup. Distributed news ahoy!
2033 @code{nndir} will use @sc{nov} files if they are present.
2035 @code{nndir} is a "read-only" backend---you can't delete or expire
2036 articles with this method. You can use @code{nnmh} or @code{nnml} for
2037 whatever you use @code{nndir} for, so you could switch to any of those
2038 methods if you feel the need to have a non-read-only @code{nndir}.
2041 @subsection nneething
2042 @cindex @code{nneething}
2044 From the @code{nndir} backend (which reads a single spool-like
2045 directory), it's just a hop and a skip to @code{nneething}, which
2046 pretends that any random directory is a newsgroup. Strange, but true.
2048 When @code{nneething} is presented with a directory, it will scan this
2049 directory and assign article numbers to each file. When you enter such a
2050 group, @code{nneething} must create "headers" that Gnus can use. After
2051 all, Gnus is a newsreader, in case you're forgetting. @code{nneething}
2052 does this in a two-step process. First, it snoops each file in question.
2053 If the file looks like an article (i.e., the first few lines look like
2054 headers), it will use this as the head. If this is just some random file
2055 without a head (eg. a C source file), @code{nneething} will cobble up a
2056 header out of thin air. It will use file ownership, name and date and do
2057 whatever it can with these elements.
2059 All this should happen automatically for you, and you will be presented
2060 with something that looks very much like a newsgroup. Totally like a
2061 newsgroup, to be precise. If you select an article, it will be displayed
2062 in the article buffer, just as usual.
2064 If you select a line that represents a directory, Gnus will pop you into
2065 a new summary buffer for this @code{nneething} group. And so on. You can
2066 traverse the entire disk this way, if you feel like, but remember that
2067 Gnus is not dired, really, and does not intend to be, either.
2069 There are two overall modes to this action---ephemeral or solid. When
2070 doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
2071 will not store information on what files you have read, and what files
2072 are new, and so on. If you create a solid @code{nneething} group the
2073 normal way with @kbd{G m}, Gnus will store a mapping table between
2074 article numbers and file names, and you can treat this group like any
2075 other groups. When you activate a solid @code{nneething} group, you will
2076 be told how many unread articles it contains, etc., etc.
2081 @item nneething-map-file-directory
2082 @vindex nneething-map-file-directory
2083 All the mapping files for solid @code{nneething} groups will be stored
2084 in this directory, which defaults to @file{~/.nneething/}.
2086 @item nneething-exclude-files
2087 @vindex nneething-exclude-files
2088 All files that match this regexp will be ignored. Nice to use to exclude
2089 auto-save files and the like, which is what it does by default.
2091 @item nneething-map-file
2092 @vindex nneething-map-file
2093 Name of the map files.
2099 @cindex @code{nndoc}
2100 @cindex documentation group
2103 @code{nndoc} is a cute little thing that will let you read a single file as a
2104 newsgroup. Currently supported file types are @code{babyl}, @code{mbox}
2107 @code{nndoc} will not try to change the file or insert any extra headers into
2108 it---it will simply, like, let you use the file as the basis for a
2109 group. And that's it.
2111 Virtual server variables:
2114 @item nndoc-article-type
2115 @vindex nndoc-article-type
2116 This should be one of @code{mbox}, @code{babyl} or @code{digest}.
2120 @subsection Reading Mail
2121 @cindex reading mail
2124 Reading mail with a newsreader---isn't that just plain WeIrD? But of
2127 Gnus will read the mail spool when you activate a mail group. The mail
2128 file is first copied to your home directory. What happens after that
2129 depends on what format you want to store your mail in.
2132 * Creating Mail Groups:: How to create mail groups.
2133 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
2134 * Mail & Procmail:: Reading mail groups that procmail create.
2135 * Expiring Old Mail Articles:: Getting rid of unwanted mail.
2136 * Not Reading Mail:: Using mail backends for reading other files.
2137 * nnmbox:: Using the (quite) standard Un*x mbox.
2138 * nnbabyl:: Emacs programs use the rmail babyl format.
2139 * nnml:: Store your mail in a private spool?
2140 * nnmh:: An mhspool-like backend.
2141 * nnfolder:: Having one file for each group.
2144 @vindex nnmail-read-incoming-hook
2145 The mail backends all call @code{nnmail-read-incoming-hook} after
2146 reading new mail. You can use this hook to notify any mail watch
2147 programs, if you want to.
2149 @vindex nnmail-spool-file
2150 @code{nnmail-spool-file} says where to look for new mail. If this
2151 variable is @code{nil}, the mail backends will never attempt to fetch
2152 mail by themselves. It is quite likely that Gnus supports POP-mail.
2153 Set this variable to begin with the string @samp{po:}, and everything
2154 should go smoothly, even though I have never tested this.
2156 @vindex nnmail-use-procmail
2157 If @code{nnmail-use-procmail} is non-@code{nil}, the mail backends will
2158 look in @code{nnmail-procmail-directory} for incoming mail. All the
2159 files in that directory that have names ending in
2160 @code{gnus-procmail-suffix} will be considered incoming mailboxes, and
2161 will be searched for new mail.
2163 @vindex nnmail-prepare-incoming-hook
2164 @code{nnmail-prepare-incoming-hook} is run in a buffer that holds all
2165 the new incoming mail, and can be used for, well, anything, really.
2167 @vindex nnmail-tmp-directory
2168 @code{nnmail-tmp-directory} says where to move the incoming mail to
2169 while processing it. This is usually done in the same directory that
2170 the mail backend inhabits (i.e., @file{~/Mail/}), but if this variable is
2171 non-@code{nil}, it will be used instead.
2173 @vindex nnmail-movemail-program
2174 @code{nnmail-movemail-program} is executed to move mail from the user's
2175 inbox to her home directory. The default is @samp{"movemail"}.
2177 @vindex nnmail-delete-incoming
2178 If @code{nnmail-delete-incoming} is non-@code{nil}, the mail backends
2179 will delete the temporary incoming file after splitting mail into the
2180 proper groups. This is @code{nil} by default for reasons of security.
2182 @vindex nnmail-message-id-cache-length
2183 @vindex nnmail-message-id-cache-file
2184 @vindex nnmail-delete-duplicates
2185 @cindex duplicate mails
2186 If you are a member of a couple of mailing list, you will sometime
2187 receive two copies of the same mail. This can be quite annoying, so
2188 @code{nnmail} checks for and discards any duplicates it might find. To
2189 do this, it keeps a cache of old @code{Message-ID}s -
2190 @code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
2191 default. The approximate maximum number of @code{Message-ID}s stored
2192 there is controlled by the @code{nnmail-message-id-cache-length}
2193 variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
2194 stored.) If all this sounds scary to you, you can set
2195 @code{nnmail-delete-duplicates} to @code{nil} (which is what it is by
2196 default), and @code{nnmail} won't do any duplicate checking.
2198 Here's a neat feature: If you know that the recipient reads her mail
2199 with Gnus, and that she has @code{nnmail-delete-duplicates} set to
2200 @code{t}, you can send her as many insults as you like, just by using a
2201 @code{Message-ID} of a mail that you know that she's already received.
2202 Think of all the fun! She'll never see any of it! Whee!
2204 Gnus gives you all the opportunity you could possibly want for shooting
2205 yourself in the foot. Let's say you create a group that will contain
2206 all the mail you get from your boss. And then you accidentally
2207 unsubscribe from the group. Gnus will still put all the mail from your
2208 boss in the unsubscribed group, and so, when your boss mails you "Have
2209 that report ready by Monday or you're fired!", you'll never see it and,
2210 come Tuesday, you'll still believe that you're gainfully employed while
2211 you really should be out collecting empty bottles to save up for next
2214 @node Creating Mail Groups
2215 @subsubsection Creating Mail Groups
2216 @cindex creating mail groups
2218 You can make Gnus read your personal, private, secret mail.
2220 You should first set @code{gnus-secondary-select-methods} to, for
2221 instance, @code{((nnmbox ""))}. When you start up Gnus, Gnus will ask
2222 this backend for what groups it carries (@samp{mail.misc} by default)
2223 and subscribe it the normal way. (Which means you may have to look for
2224 it among the zombie groups, I guess, all depending on your
2225 @code{gnus-subscribe-newsgroup-method} variable.)
2227 @vindex nnmail-split-methods
2228 Then you should set the variable @code{nnmail-split-methods} to specify
2229 how the incoming mail is to be split into groups.
2232 (setq nnmail-split-methods
2233 '(("mail.junk" "^From:.*Lars Ingebrigtsen")
2234 ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
2238 This variable is a list of lists, where the first element of each of
2239 these lists is the name of the mail group (they do not have to be called
2240 something beginning with @samp{mail}, by the way), and the second
2241 element is a regular expression used on the header of each mail to
2242 determine if it belongs in this mail group.
2244 The second element can also be a function. In that case, it will be
2245 called narrowed to the headers with the first element of the rule as the
2246 argument. It should return a non-@code{nil} value if it thinks that the
2247 mail belongs in that group.
2249 The last of these groups should always be a general one, and the regular
2250 expression should @emph{always} be @samp{""} so that it matches any
2251 mails that haven't been matched by any of the other regexps.
2253 If you like to tinker with this yourself, you can set this variable to a
2254 function of your choice. This function will be called without any
2255 arguments in a buffer narrowed to the headers of an incoming mail
2256 message. The function should return a list of groups names that it
2257 thinks should carry this mail message.
2259 @vindex nnmail-crosspost
2260 The mail backends all support cross-posting. If several regexps match,
2261 the mail will be "cross-posted" to all those groups.
2262 @code{nnmail-crosspost} says whether to use this mechanism or not. Note
2263 that no articles are crossposted to the general (@samp{""}) group.
2265 @node Fancy Mail Splitting
2266 @subsubsection Fancy Mail Splitting
2267 @cindex mail splitting
2268 @cindex fancy mail splitting
2270 @vindex nnmail-split-fancy
2271 @findex nnmail-split-fancy
2272 If the rather simple, standard method for specifying how to split mail
2273 doesn't allow you to do what you want, you can set
2274 @code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
2275 play with the @code{nnmail-split-fancy} variable.
2277 Let's look at an example value of this variable first:
2280 ;; Messages from the mailer daemon are not crossposted to any of
2281 ;; the ordinary groups. Warnings are put in a separate group
2282 ;; from real errors.
2283 (| ("from" mail (| ("subject" "warn.*" "mail.warning")
2285 ;; Non-error messages are crossposted to all relevant
2286 ;; groups, but we don't crosspost between the group for the
2287 ;; (ding) list and the group for other (ding) related mail.
2288 (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
2289 ("subject" "ding" "ding.misc"))
2290 ;; Other mailing lists...
2291 (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
2292 (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
2294 (any "larsi@@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
2295 ;; Unmatched mail goes to the catch all group.
2299 This variable has the format of a @dfn{split}. A split is a (possibly)
2300 recursive structure where each split may contain other splits. Here are
2301 the four possible split syntaxes:
2305 If the split is a string, that will be taken as a group name.
2306 @item (FIELD VALUE SPLIT)
2307 If the split is a list, and the first element is a string, then that
2308 means that if header FIELD (a regexp) contains VALUE (also a regexp),
2309 then store the message as specified by SPLIT.
2311 If the split is a list, and the first element is @code{|} (vertical
2312 bar), then process each SPLIT until one of them matches. A SPLIT is
2313 said to match if it will cause the mail message to be stored in one or
2316 If the split is a list, and the first element is @code{&}, then process
2317 all SPLITs in the list.
2320 In these splits, FIELD must match a complete field name. VALUE must
2321 match a complete word according to the fundamental mode syntax table.
2322 You can use @code{.*} in the regexps to match partial field names or
2325 @vindex nnmail-split-abbrev-alist
2326 FIELD and VALUE can also be lisp symbols, in that case they are expanded
2327 as specified by the variable @code{nnmail-split-abbrev-alist}. This is
2328 an alist of cons cells, where the car of the cells contains the key, and
2329 the cdr contains a string.
2331 @node Mail & Procmail
2332 @subsubsection Mail & Procmail
2335 Many people use @code{procmail} to split incoming mail into groups. If
2336 you do that, you should set @code{nnmail-spool-file} to @code{procmail}
2337 to ensure that the mail backends never ever try to fetch mail by
2340 This also means that you probably don't want to set
2341 @code{nnmail-split-methods} either, which has some, perhaps, unexpected
2344 When a mail backend is queried for what groups it carries, it replies
2345 with the contents of that variable, along with any groups it has figured
2346 out that it carries by other means. None of the backends (except
2347 @code{nnmh}) actually go out to the disk and check what groups actually
2348 exist. (It's not trivial to distinguish between what the user thinks is
2349 a basis for a newsgroup and what is just a plain old file or directory.)
2351 This means that you have to tell Gnus (and the backends) what groups
2354 Let's take the @code{nnmh} backend as an example.
2356 The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
2357 There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
2359 Go to the group buffer and type @kbd{G m}. When prompted, answer
2360 @samp{foo} for the name and @samp{nnmh} for the method. Repeat
2361 twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
2362 to include all your mail groups.
2364 That's it. You are now set to read your mail. An active file for this
2365 method will be created automatically.
2367 @vindex nnmail-procmail-suffix
2368 @vindex nnmail-procmail-directory
2369 If you use @code{nnfolder} or any other backend that store more than a
2370 single article in each file, you should never have procmail add mails to
2371 the file that Gnus sees. Instead, procmail should put all incoming mail
2372 in @code{nnmail-procmail-directory}. To arrive at the file name to put
2373 the incoming mail in, append @code{nnmail-procmail-suffix} to the group
2374 name. The mail backends will read the mail from these files.
2376 @vindex nnmail-resplit-incoming
2377 When Gnus reads a file called @file{mail.misc.spool}, this mail will be
2378 put in the @code{mail.misc}, as one would expect. However, if you want
2379 Gnus to split the mail the normal way, you could set
2380 @code{nnmail-resplit-incoming} to @code{t}.
2382 @vindex nnmail-keep-last-article
2383 If you use @code{procmail} to split things directory into an @code{nnmh}
2384 directory (which you shouldn't do), you should set
2385 @code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
2386 ever expiring the final article in a mail newsgroup. This is quite,
2390 @node Expiring Old Mail Articles
2391 @subsubsection Expiring Old Mail Articles
2392 @cindex article expiry
2394 Traditional mail readers have a tendency to remove mail articles when
2395 you mark them as read, in some way. Gnus takes a fundamentally
2396 different approach to mail reading.
2398 Gnus basically considers mail just to be news that has been received in
2399 a rather peculiar manner. It does not think that it has the power to
2400 actually change the mail, or delete any mail messages. If you enter a
2401 mail group, and mark articles as "read", or kill them in some other
2402 fashion, the mail articles will still exist on the system. I repeat:
2403 Gnus will not delete your old, read mail. Unless you ask it to, of
2406 To make Gnus get rid of your unwanted mail, you have to mark the
2407 articles as @dfn{expirable}. This does not mean that the articles will
2408 disappear right away, however. In general, a mail article will be
2409 deleted from your system if, 1) it is marked as expirable, AND 2) it is
2410 more than one week old. If you do not mark an article as expirable, it
2411 will remain on your system until hell freezes over. This bears
2412 repeating one more time, with some spurious capitalizations: IF you do
2413 NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
2415 @vindex gnus-auto-expirable-newsgroups
2416 You do not have to mark articles as expirable by hand. Groups that
2417 match the regular expression @code{gnus-auto-expirable-newsgroups} will
2418 have all articles that you read marked as expirable automatically. All
2419 articles that are marked as expirable have an @samp{E} in the first
2420 column in the summary buffer.
2422 Let's say you subscribe to a couple of mailing lists, and you want the
2423 articles you have read to disappear after a while:
2426 (setq gnus-auto-expirable-newsgroups
2427 "mail.nonsense-list\\|mail.nice-list")
2430 Another way to have auto-expiry happen is to have the element
2431 @code{auto-expire} in the select method of the group.
2433 @vindex nnmail-expiry-wait
2434 The @code{nnmail-expiry-wait} variable supplies the default time an
2435 expirable article has to live. The default is seven days.
2437 Gnus also supplies a function that lets you fine-tune how long articles
2438 are to live, based on what group they are in. Let's say you want to
2439 have one month expiry period in the @samp{mail.private} group, a one day
2440 expiry period in the @samp{mail.junk} group, and a six day expiry period
2444 (setq nnmail-expiry-wait-function
2446 (cond ((string= group "mail.private")
2448 ((string= group "mail.junk")
2454 @vindex nnmail-keep-last-article
2455 If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
2456 expire the final article in a mail newsgroup. This is to make life
2457 easier for procmail users.
2459 @vindex gnus-total-expirable-newsgroups
2460 By the way, that line up there about Gnus never expiring non-expirable
2461 articles is a lie. If you put @code{total-expire} in the group
2462 parameters, articles will not be marked as expirable, but all read
2463 articles will be put through the expiry process. Use with extreme
2464 caution. Even more dangerous is the
2465 @code{gnus-total-expirable-newsgroups} variable. All groups that match
2466 this regexp will have all read articles put through the expiry process,
2467 which means that @emph{all} old mail articles in the groups in question
2468 will be deleted after a while. Use with extreme caution, and don't come
2469 crying to me when you discover that the regexp you used matched the
2470 wrong group and all your important mail has disappeared. Be a
2471 @emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
2475 @node Not Reading Mail
2476 @subsubsection Not Reading Mail
2478 If you start using any of the mail backends, they have the annoying
2479 habit of assuming that you want to read mail with them. This might not
2480 be unreasonable, but it might not be what you want.
2482 If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
2483 will ever attempt to read incoming mail, which should help.
2485 @vindex nnbabyl-get-new-mail
2486 @vindex nnmbox-get-new-mail
2487 @vindex nnml-get-new-mail
2488 @vindex nnmh-get-new-mail
2489 @vindex nnfolder-get-new-mail
2490 This might be too much, if, for instance, you are reading mail quite
2491 happily with @code{nnml} and just want to peek at some old @sc{rmail}
2492 file you have stashed away with @code{nnbabyl}. All backends have
2493 variables called backend-@code{get-new-mail}. If you want to disable
2494 the @code{nnbabyl} mail reading, you edit the virtual server for the
2495 group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
2497 All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
2498 narrowed to the article to be saved before saving it when reading
2502 @subsubsection nnmbox
2503 @cindex @code{nnmbox}
2504 @cindex unix mail box
2506 @vindex nnmbox-active-file
2507 @vindex nnmbox-mbox-file
2508 The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
2509 mail. @code{nnmbox} will add extra headers to each mail article to say
2510 which group it belongs in.
2512 Virtual server settings:
2515 @item nnmbox-mbox-file
2516 @vindex nnmbox-mbox-file
2517 The name of the mail box in the user's home directory.
2519 @item nnmbox-active-file
2520 @vindex nnmbox-active-file
2521 The name of the active file for the mail box.
2523 @item nnmbox-get-new-mail
2524 @vindex nnmbox-get-new-mail
2525 If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
2530 @subsubsection nnbabyl
2531 @cindex @code{nnbabyl}
2534 @vindex nnbabyl-active-file
2535 @vindex nnbabyl-mbox-file
2536 The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
2537 mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
2538 article to say which group it belongs in.
2540 Virtual server settings:
2543 @item nnbabyl-mbox-file
2544 @vindex nnbabyl-mbox-file
2545 The name of the rmail mbox file.
2547 @item nnbabyl-active-file
2548 @vindex nnbabyl-active-file
2549 The name of the active file for the rmail box.
2551 @item nnbabyl-get-new-mail
2552 @vindex nnbabyl-get-new-mail
2553 If non-@code{nil}, @code{nnbabyl} will read incoming mail.
2559 @cindex mail @sc{nov} spool
2561 The @dfn{nnml} spool mail format isn't compatible with any other known
2562 format. It should be used with some caution.
2564 @vindex nnml-directory
2565 If you use this backend, Gnus will split all incoming mail into files;
2566 one file for each mail, and put the articles into the correct
2567 directories under the directory specified by the @code{nnml-directory}
2568 variable. The default value is @file{~/Mail/}.
2570 You do not have to create any directories beforehand; Gnus will take
2573 If you have a strict limit as to how many files you are allowed to store
2574 in your account, you should not use this backend. As each mail gets its
2575 own file, you might very well occupy thousands of inodes within a few
2576 weeks. If this is no problem for you, and it isn't a problem for you
2577 having your friendly systems administrator walking around, madly,
2578 shouting "Who is eating all my inodes?! Who? Who!?!", then you should
2579 know that this is probably the fastest format to use. You do not have
2580 to trudge through a big mbox file just to read your new mail.
2582 @code{nnml} is probably the slowest backend when it comes to article
2583 splitting. It has to create lots of files, and it also generates
2584 @sc{nov} databases for the incoming mails. This makes is the fastest
2585 backend when it comes to reading mail.
2587 Virtual server settings:
2590 @item nnml-directory
2591 @vindex nnml-directory
2592 All @code{nnml} directories will be placed under this directory.
2594 @item nnml-active-file
2595 @vindex nnml-active-file
2596 The active file for the @code{nnml} server.
2598 @item nnml-newsgroups-file
2599 @vindex nnml-newsgroups-file
2600 The @code{nnml} group description file.
2602 @item nnml-get-new-mail
2603 @vindex nnml-get-new-mail
2604 If non-@code{nil}, @code{nnml} will read incoming mail.
2606 @item nnml-nov-is-evil
2607 @vindex nnml-nov-is-evil
2608 If non-@code{nil}, this backend will ignore any @sc{nov} files.
2610 @item nnml-nov-file-name
2611 @vindex nnml-nov-file-name
2612 The name of the @sc{nov} files. The default is @file{.overview}.
2616 @findex nnml-generate-nov-databases
2617 If your @code{nnml} groups and @sc{nov} files get totally out of whack,
2618 you can do a complete update by typing @kbd{M-x
2619 nnml-generate-nov-databases}. This command will trawl through the
2620 entire @code{nnml} hierarchy, looking at each and every article, so it
2621 might take a while to complete.
2626 @cindex mh-e mail spool
2628 @code{nnmh} is just like @code{nnml}, except that is doesn't generate
2629 @sc{nov} databases and it doesn't keep an active file. This makes
2630 @code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
2631 makes it easier to write procmail scripts for.
2633 Virtual server settings:
2636 @item nnmh-directory
2637 @vindex nnmh-directory
2638 All @code{nnmh} directories will be located under this directory.
2640 @item nnmh-get-new-mail
2641 @vindex nnmh-get-new-mail
2642 If non-@code{nil}, @code{nnmh} will read incoming mail.
2645 @vindex nnmh-be-safe
2646 If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
2647 sure that the articles in the folder is actually what Gnus think they
2648 are. It will check date stamps, and stat everything in sight, so
2649 setting this to @code{t} will mean a serious slow-down. If you never
2650 use anything by Gnus to read the @code{nnmh} articles, you do not have to set
2651 this variable to @code{t}.
2655 @subsubsection nnfolder
2656 @cindex @code{nnfolder}
2657 @cindex mbox folders
2659 @code{nnfolder} is a backend for storing each mail group in a separate
2660 file. Each file is in the standard Un*x mbox format. @code{nnfolder}
2661 will add extra headers to keep track of article numbers and arrival
2664 Virtual server settings:
2667 @item nnfolder-directory
2668 @vindex nnfolder-directory
2669 All the @code{nnfolder} mail boxes will be stored under this directory.
2671 @item nnfolder-active-file
2672 @vindex nnfolder-active-file
2673 The name of the active file.
2675 @item nnfolder-newsgroups-file
2676 @vindex nnfolder-newsgroups-file
2677 The name of the group description file.
2679 @item nnfolder-get-new-mail
2680 @vindex nnfolder-get-new-mail
2681 If non-@code{nil}, @code{nnfolder} will read incoming mail.
2685 @node Group Parameters
2686 @section Group Parameters
2687 @cindex group parameters
2689 Gnus stores all information on a group in a list that is usually known
2690 as the @dfn{group info}. This list has from three to six elements.
2691 Here's an example info.
2694 ("nnml:mail.ding" 3 ((1 . 232) 244 (256 . 270)) ((tick 246 249))
2695 (nnml "private") ((to-address . "ding@@ifi.uio.no")))
2698 The first element is the @dfn{group name}, as Gnus knows the group,
2699 anyway. The second element is the @dfn{subscription level}, which
2700 normally is a small integer. The third element is a list of ranges of
2701 read articles. The fourth element is a list of lists of article marks
2702 of various kinds. The fifth element is the select method (or virtual
2703 server, if you like). The sixth element is a list of @dfn{group
2704 parameters}, which is what this section is about.
2706 Any of the last three elements may be missing if they are not required.
2707 In fact, the vast majority of groups will normally only have the first
2708 three elements, which saves quite a lot of cons cells.
2710 The group parameters store information local to a particular group:
2715 If the group parameter list contains an element that looks like
2716 @samp{(to-address . "some@@where.com")}, that address will be used by
2717 the backend when doing followups and posts. This is primarily useful in
2718 mail groups that represent mailing lists. You just set this address to
2719 whatever the list address is.
2721 This trick will actually work whether the group is foreign or not.
2722 Let's say there's a group on the server that is called @samp{fa.4ad-l}.
2723 This is a real newsgroup, but the server has gotten the articles from a
2724 mail-to-news gateway. Posting directly to this group is therefore
2725 impossible---you have to send mail to the mailing list address instead.
2726 Also @xref{Mail & Post}.
2730 If the group parameter list contains an element like @code{(to-group
2731 . "some.group.name")}, all posts will be sent to that group.
2735 If the group parameter list contains an element like @code{(topic
2736 . "some-topic")}, the group will become a member of the topic in
2737 question (@pxref{Group Topics}).
2741 If this symbol is present in the group parameter list, all articles that
2742 are read will be marked as expirable. For an alternative approach,
2743 @xref{Expiring Old Mail Articles}.
2746 @cindex total-expire
2747 If this symbol is present, all read articles will be put through the
2748 expiry process, even if they are not marked as expirable. Use with
2751 @item @var{(variable form)}
2752 You can use the group parameters to set variables local to the group you
2753 are entering. Say you want to turn threading off in
2754 @samp{news.answers}. You'd then put @code{(gnus-show-threads nil)} in
2755 the group parameters of that group. @code{gnus-show-threads} will be
2756 made into a local variable in the summary buffer you enter, and the form
2757 @code{nil} will be @code{eval}ed there.
2759 This can also be used as a group-specific hook function, if you'd like.
2760 If you want to hear a beep when you enter the group
2761 @samp{alt.binaries.pictures.furniture}, you could put something like
2762 @code{(dummy-variable (ding))} in the parameters of that group.
2763 @code{dummy-variable} will be set to the result of the @code{(ding)}
2764 form, but who cares?
2768 If you want to change the group info you can use the @kbd{G E} command
2769 to enter a buffer where you can edit it.
2771 You usually don't want to edit the entire group info, so you'd be better
2772 off using the @kbd{G p} command to just edit the group parameters.
2774 @node Listing Groups
2775 @section Listing Groups
2776 @cindex group listing
2778 These commands all list various slices of the groups that are available.
2786 @findex gnus-group-list-groups
2787 List all groups that have unread articles
2788 (@code{gnus-group-list-groups}). If the numeric prefix is used, this
2789 command will list only groups of level ARG and lower. By default, it
2790 only lists groups of level five or lower (i.e., just subscribed groups).
2796 @findex gnus-group-list-all-groups
2797 List all groups, whether they have unread articles or not
2798 (@code{gnus-group-list-all-groups}). If the numeric prefix is used,
2799 this command will list only groups of level ARG and lower. By default,
2800 it lists groups of level seven or lower (i.e., just subscribed and
2801 unsubscribed groups).
2805 @findex gnus-group-list-killed
2806 List all killed groups (@code{gnus-group-list-killed}).
2810 @findex gnus-group-list-zombies
2811 List all zombie groups (@code{gnus-group-list-zombies}).
2815 @findex gnus-group-list-matching
2816 List all subscribed groups with unread articles that match a regexp
2817 (@code{gnus-group-list-matching}).
2821 @findex gnus-group-list-all-matching
2822 List groups that match a regexp (@code{gnus-group-list-all-matching}).
2826 @findex gnus-group-list-active
2827 List absolutely all groups that are in the active file(s) of the
2828 server(s) you are connected to (@code{gnus-group-list-active}). This
2829 might very well take quite a while. It might actually be a better idea
2830 to do a @kbd{A m} to list all matching, and just give @samp{.} as the
2835 @node Group Maintenance
2836 @section Group Maintenance
2837 @cindex bogus groups
2842 @findex gnus-group-check-bogus-groups
2843 Find bogus groups and delete them
2844 (@code{gnus-group-check-bogus-groups}).
2847 @findex gnus-find-new-newsgroups
2848 Find new groups and process them (@code{gnus-find-new-newsgroups}).
2850 @kindex C-c C-x (Group)
2851 @findex gnus-group-expire-articles
2852 Run all expirable articles in the current group through the expiry
2853 process (if any) (@code{gnus-group-expire-articles}).
2856 @kindex C-c M-C-x (Group)
2857 @findex gnus-group-expire-all-groups
2858 Run all articles in all groups through the expiry process
2859 (@code{gnus-group-expire-all-groups}).
2862 @kindex C-c C-s (Group)
2863 @findex gnus-group-sort-groups
2864 @vindex gnus-group-sort-function
2865 Sort the groups according to the function given by the
2866 @code{gnus-group-sort-function} variable
2867 (@code{gnus-group-sort-groups}). Available sorting functions include:
2871 @item gnus-group-sort-by-alphabet
2872 @findex gnus-group-sort-by-alphabet
2873 Sort the group names alphabetically. This is the default.
2875 @item gnus-group-sort-by-level
2876 @findex gnus-group-sort-by-level
2877 Sort by group level.
2879 @item gnus-group-sort-by-unread
2880 @findex gnus-group-sort-by-unread
2881 Sort by number of unread articles.
2883 @item gnus-group-sort-by-method
2884 @findex gnus-group-sort-by-method
2885 Sort by alphabetically on the select method.
2889 @code{gnus-group-sort-function} can also be a list of sorting
2890 functions. In that case, the most significant sort key function must be
2894 @node Browse Foreign Server
2895 @section Browse Foreign Server
2896 @cindex foreign servers
2897 @cindex browsing servers
2902 @findex gnus-group-browse-foreign-server
2903 You will be queried for a select method and a server name. Gnus will
2904 then attempt to contact this server and let you browse the groups there
2905 (@code{gnus-group-browse-foreign-server}).
2908 @findex gnus-browse-server-mode
2909 A new buffer with a list of available groups will appear. This buffer
2910 will be use the @code{gnus-browse-server-mode}. This buffer looks a bit
2911 (well, a lot) like a normal group buffer, but with one major difference
2912 - you can't enter any of the groups. If you want to read any of the
2913 news available on that server, you have to subscribe to the groups you
2914 think may be interesting, and then you have to exit this buffer. The
2915 new groups will be added to the group buffer, and then you can read them
2916 as you would any other group.
2918 Future versions of Gnus may possibly permit reading groups straight from
2921 Here's a list of keystrokes available in the browse mode:
2926 @findex gnus-group-next-group
2927 Go to the next group (@code{gnus-group-next-group}).
2931 @findex gnus-group-prev-group
2932 Go to the previous group (@code{gnus-group-prev-group}).
2935 @kindex SPC (Browse)
2936 @findex gnus-browse-read-group
2937 Enter the current group and display the first article
2938 (@code{gnus-browse-read-group}).
2941 @kindex RET (Browse)
2942 @findex gnus-browse-select-group
2943 Enter the current group (@code{gnus-browse-select-group}).
2947 @findex gnus-browse-unsubscribe-current-group
2948 Unsubscribe to the current group, or, as will be the case here,
2949 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
2955 @findex gnus-browse-exit
2956 Exit browse mode (@code{gnus-browse-exit}).
2960 @findex gnus-browse-describe-briefly
2961 Describe browse mode briefly (well, there's not much to describe, is
2962 there) (@code{gnus-browse-describe-briefly}).
2966 @section Exiting Gnus
2967 @cindex exiting Gnus
2969 Yes, Gnus is ex(c)iting.
2974 @findex gnus-group-suspend
2975 Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
2976 but it kills all buffers except the Group buffer. I'm not sure why this
2977 is a gain, but then who am I to judge?
2980 @findex gnus-group-exit
2981 Quit Gnus (@code{gnus-group-exit}).
2984 @findex gnus-group-quit
2985 Quit Gnus without saving any startup files (@code{gnus-group-quit}).
2988 @vindex gnus-exit-gnus-hook
2989 @vindex gnus-suspend-gnus-hook
2990 @code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
2991 @code{gnus-exit-gnus-hook} is called when you quit Gnus.
2995 If you wish to completely unload Gnus and all its adherents, you can use
2996 the @code{gnus-unload} command. This command is also very handy when
2997 trying to custoize meta-variables.
3002 Miss Lisa Cannifax, while sitting in English class, feels her feet go
3003 numbly heavy and herself fall into a hazy trance as the boy sitting
3004 behind her drew repeated lines with his pencil across the back of her
3010 @section Group Topics
3013 If you read lots and lots of groups, it might be convenient to group
3014 them according to topics. You put your Emacs groups over here, your sex
3015 groups over there, and the rest (what, two groups or so?) you put in
3016 some misc section that you never bother with anyway.
3018 To get this @emph{fab} functionality, you set
3019 @code{gnus-group-prepare-function} to @code{gnus-group-prepare-topics}.
3020 Go ahead, just try it. I'll still be here when you get back. La de
3021 dum... Nice tune, that... la la la... What, you're back? Yes, and now
3022 press @kbd{l}. There. All your groups are now listed under
3023 @samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
3026 @vindex gnus-group-topics
3027 To get an even more exciting division, you have to fiddle with
3028 @code{gnus-group-topics}. That is an alist where each entry looks like
3035 As you've already guessed (only geniï read manuals anyway), all
3036 groups that match @var{regexp} gets put into a section called
3037 @var{topic}. If @var{show} is non-@code{nil}, it overrides
3038 @code{gnus-group-topic-topics-only}. In specific, if @var{show} is
3039 @code{t}, all groups with this topic are always shown, and if it is a
3040 number, these groups are never shown.
3042 @vindex gnus-group-topic-topics-only
3043 Whoo, this is complicated. If @code{gnus-group-topic-topics-only} is
3044 @code{nil}, all groups and topics will be listed, as you would expect.
3045 If this variable is non-@code{nil}, only the topics will be listed, and
3046 the groups will not be listed. This makes the group buffer much shorter,
3047 I'm sure you'll agree. This is all modified on a topic-by-topic basis
3048 by the @var{show} parameter. It makes perfect sense, really.
3050 @vindex gnus-group-topic-face
3051 Topics are shown with @code{gnus-group-topic-face}.
3053 @vindex gnus-topic-unique
3054 If @code{gnus-topic-unique} is non-@code{nil}, each group will be member
3055 of (tops) one topic each. If this is @code{nil}, each group might end
3056 up being a member of several topics.
3058 You can also put a @code{topic} in the group parameters (@pxref{Group
3061 Now, if you select a topic, if will fold/unfold that topic, which is
3062 really neat, I think.
3064 Here's an example @code{gnus-group-topics}:
3067 (("Emacs - the Spice of Life" "^gnu.emacs\\|comp.emacs" t)
3068 ("Alternativeness" "^alt" 0)
3069 ("Hard Stuff" "^comp" nil)
3070 ("The Rest" "." nil))
3074 @node Misc Group Stuff
3075 @section Misc Group Stuff
3081 @findex gnus-group-get-new-news
3082 Check the server(s) for new articles. If the numerical prefix is used,
3083 this command will check only groups of level @var{arg} and lower
3084 (@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
3085 command will force a total rereading of the active file(s) from the
3090 @findex gnus-group-get-new-news-this-group
3091 Check whether new articles have arrived in the current group
3092 (@code{gnus-group-get-new-news-this-group}).
3096 @findex gnus-group-enter-server-mode
3097 Enter the server buffer (@code{gnus-group-enter-server-mode}). @xref{The
3102 @findex gnus-group-fetch-faq
3103 Try to fetch the FAQ for the current group
3104 (@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
3105 @code{gnus-group-faq-directory}, which is usually a directory on a
3106 remote machine. @code{ange-ftp} will be used for fetching the file.
3109 @findex gnus-group-restart
3110 Restart Gnus (@code{gnus-group-restart}).
3113 @findex gnus-group-read-init-file
3114 @vindex gnus-init-file
3115 Read the init file (@code{gnus-init-file}, which defaults to
3116 @file{~/.gnus}) (@code{gnus-group-read-init-file}).
3119 @findex gnus-group-save-newsrc
3120 Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
3121 (@code{gnus-group-save-newsrc}).
3124 @findex gnus-group-clear-dribble
3125 Clear the dribble buffer (@code{gnus-group-clear-dribble}).
3128 @findex gnus-group-describe-group
3129 Describe the current group (@code{gnus-group-describe-group}). If given
3130 a prefix, force Gnus to re-read the description from the server.
3133 @findex gnus-group-apropos
3134 List all groups that have names that match a regexp
3135 (@code{gnus-group-apropos}).
3138 @findex gnus-group-description-apropos
3139 List all groups that have names or descriptions that match a regexp
3140 (@code{gnus-group-description-apropos}).
3143 @findex gnus-group-post-news
3144 Post an article to a group (@code{gnus-group-post-news}).
3147 @findex gnus-group-mail
3148 Mail a message somewhere (@code{gnus-group-mail}).
3150 @kindex C-x C-t (Group)
3151 @findex gnus-group-transpose-groups
3152 Transpose two groups (@code{gnus-group-transpose-groups}).
3155 @findex gnus-version
3156 Display current Gnus version numbers (@code{gnus-version}).
3159 @findex gnus-group-describe-all-groups
3160 Describe all groups (@code{gnus-group-describe-all-groups}). If given a
3161 prefix, force Gnus to re-read the description file from the server.
3164 @findex gnus-group-describe-briefly
3165 Give a very short help message (@code{gnus-group-describe-briefly}).
3167 @kindex C-c C-i (Group)
3168 @findex gnus-info-find-node
3169 Go to the Gnus info node (@code{gnus-info-find-node}).
3172 @vindex gnus-group-prepare-hook
3173 @code{gnus-group-prepare-hook} is called after the group buffer is
3174 generated. It may be used to modify the buffer in some strange,
3177 @node The Summary Buffer
3178 @chapter The Summary Buffer
3179 @cindex summary buffer
3181 A line for each article is displayed in the summary buffer. You can
3182 move around, read articles, post articles and reply to articles.
3185 * Summary Buffer Format:: Deciding how the summary buffer is to look.
3186 * Summary Maneuvering:: Moving around the summary buffer.
3187 * Choosing Articles:: Reading articles.
3188 * Paging the Article:: Scrolling the current article.
3189 * Reply Followup and Post:: Posting articles.
3190 * Canceling and Superseding:: "Whoops, I shouldn't have called him that."
3191 * Marking Articles:: Marking articles as read, expirable, etc.
3192 * Limiting:: You can limit the summary buffer.
3193 * Threading:: How threads are made.
3194 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
3195 * Article Caching:: You may store articles in a cache.
3196 * Article Backlog:: Having already read articles hang around.
3197 * Exiting the Summary Buffer:: Returning to the Group buffer.
3198 * Process/Prefix:: A convention used by many treatment commands.
3199 * Saving Articles:: Ways of customizing article saving.
3200 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
3201 * Article Treatment:: The article buffer can be mangled at will.
3202 * Summary Sorting:: You can sort the summary buffer four ways.
3203 * Finding the Parent:: No child support? Get the parent.
3204 * Mail Group Commands:: Some commands can only be used in mail groups.
3205 * Various Summary Stuff:: What didn't fit anywhere else.
3209 @node Summary Buffer Format
3210 @section Summary Buffer Format
3211 @cindex summary buffer format
3214 * Summary Buffer Lines:: You can specify how summary lines should look.
3215 * Summary Buffer Mode Line:: You can say how the mode line should look.
3218 @findex mail-extract-address-components
3219 @findex gnus-extract-address-components
3220 @vindex gnus-extract-address-components
3221 Gnus will use the value of the @code{gnus-extract-address-components}
3222 variable as a function for getting the name and address parts of a
3223 @code{From} header. Two pre-defined function exist:
3224 @code{gnus-extract-address-components}, which is the default, quite
3225 fast, and too simplistic solution, and
3226 @code{mail-extract-address-components}, which works very nicely, but is
3229 @vindex gnus-summary-same-subject
3230 @code{gnus-summary-same-subject} is a string indicating that the current
3231 article has the same subject as the previous. This string will be used
3232 with those specs that require it.
3234 @node Summary Buffer Lines
3235 @subsection Summary Buffer Lines
3237 @vindex gnus-summary-line-format
3238 You can change the format of the lines in the summary buffer by changing
3239 the @code{gnus-summary-line-format} variable. It works along the same
3240 lines a a normal @code{format} string, with some extensions.
3242 The default string is @samp{"%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n"}.
3244 The following format specification characters are understood:
3252 Subject if the article is the root, @code{gnus-summary-same-subject}
3255 Full @code{From} line.
3257 The name (from the @code{From} header).
3259 The name (from the @code{From} header). This differs from the @code{n}
3260 spec in that it uses @code{gnus-extract-address-components}, which is
3261 slower, but may be more thorough.
3263 The address (from the @code{From} header). This works the same way as
3266 Number of lines in the article.
3268 Number of characters in the article.
3270 Indentation based on thread level (@pxref{Customizing Threading}).
3272 Nothing if the article is a root and lots of spaces if it isn't (it
3273 pushes everything after it off the screen).
3275 Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
3276 for adopted articles.
3278 Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
3279 for adopted articles.
3281 One space for each thread level.
3283 Twenty minus thread level spaces.
3291 @vindex gnus-summary-zcore-fuzz
3292 Zcore, @samp{+} if above the default level and @samp{-} if below the
3293 default level. If the difference between
3294 @code{gnus-summary-default-level} and the score is less than
3295 @code{gnus-summary-zcore-fuzz}, this spec will not be used.
3305 Number of articles in the current sub-thread. Using this spec will slow
3306 down summary buffer generation somewhat.
3308 A single character will be displayed if the article has any children.
3310 User defined specifier. The next character in the format string should
3311 be a letter. @sc{gnus} will call the function
3312 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
3313 following @samp{%u}. The function will be passed the current header as
3314 argument. The function should return a string, which will be inserted
3315 into the summary just like information from any other summary specifier.
3318 Text between @samp{%(} and @samp{%)} will be highlighted with
3319 @code{gnus-mouse-face} when the mouse point is placed inside the area.
3320 There can only be one such area.
3322 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
3323 have to be handled with care. For reasons of efficiency, Gnus will
3324 compute what column these characters will end up in, and "hard-code"
3325 that. This means that it is illegal to have these specs after a
3326 variable-length spec. Well, you might not be arrested, but your summary
3327 buffer will look strange, which is bad enough.
3329 The smart choice is to have these specs as far to the left as possible.
3330 (Isn't that the case with everything, though? But I digress.)
3332 This restriction may disappear in later versions of Gnus.
3334 @node Summary Buffer Mode Line
3335 @subsection Summary Buffer Mode Line
3337 @vindex gnus-summary-mode-line-format
3338 You can also change the format of the summary mode bar. Set
3339 @code{gnus-summary-mode-line-format} to whatever you like. Here are the
3340 elements you can play with:
3346 Unprefixed group name.
3348 Current article number.
3352 Number of unread articles in this group.
3354 Number of unselected articles in this group.
3356 A string with the number of unread and unselected articles represented
3357 either as @samp{<%U(+%u) more>} if there are both unread and unselected
3358 articles, and just as @samp{<%U more>} if there are just unread articles
3359 and no unselected ones.
3361 Shortish group name. For instance, @samp{rec.arts.anime} will be
3362 shortened to @samp{r.a.anime}.
3364 Subject of the current article.
3368 Name of the current score file.
3370 Number of dormant articles.
3372 Number of ticked articles.
3374 Number of articles that have been marked as read in this session.
3376 Number of articles expunged by the score files.
3380 @node Summary Maneuvering
3381 @section Summary Maneuvering
3382 @cindex summary movement
3384 All the straight movement commands understand the numeric prefix and
3385 behave pretty much as you'd expect.
3387 None of these commands select articles.
3392 @kindex M-n (Summary)
3393 @kindex G M-n (Summary)
3394 @findex gnus-summary-next-unread-subject
3395 Go to the next summary line of an unread article
3396 (@code{gnus-summary-next-unread-subject}).
3399 @kindex M-p (Summary)
3400 @kindex G M-p (Summary)
3401 @findex gnus-summary-prev-unread-subject
3402 Go to the previous summary line of an unread article
3403 (@code{gnus-summary-prev-unread-subject}).
3407 @kindex G g (Summary)
3408 @findex gnus-summary-goto-subject
3409 Ask for an article number and then go to this summary line
3410 (@code{gnus-summary-goto-subject}).
3413 @vindex gnus-auto-select-next
3414 If you are at the end of the group and issue one of the movement
3415 commands, Gnus will offer to go to the next group. If
3416 @code{gnus-auto-select-next} is @code{t} and the next group is empty,
3417 Gnus will exit summary mode and return to the group buffer. If this
3418 variable is neither @code{t} nor @code{nil}, Gnus will select the next
3419 group, no matter whether it has any unread articles or not. As a
3420 special case, if this variable is @code{quietly}, Gnus will select the
3421 next group without asking for confirmation. If this variable is
3422 @code{almost-quietly}, the same will happen only if you are located on
3423 the last article in the group. Also @xref{Group Levels}.
3425 If Gnus asks you to press a key to confirm going to the next group, you
3426 can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
3427 buffer, searching for the next group to read without actually returning
3428 to the group buffer.
3430 @vindex gnus-auto-select-same
3431 If @code{gnus-auto-select-same} is non-@code{nil}, all the movement
3432 commands will try to go to the next article with the same subject as the
3433 current. This variable is not particularly useful if you use a threaded
3436 @vindex gnus-summary-check-current
3437 If @code{gnus-summary-check-current} is non-@code{nil}, all the "unread"
3438 movement commands will not proceed to the next (or previous) article if
3439 the current article is unread. Instead, they will choose the current
3442 @vindex gnus-auto-center-summary
3443 If @code{gnus-auto-center-summary} is non-@code{nil}, Gnus will keep the
3444 point in the summary buffer centered at all times. This makes things
3445 quite tidy, but if you have a slow network connection, or simply do not
3446 like this un-Emacsism, you can set this variable to @code{nil} to get
3447 the normal Emacs scrolling action.
3449 @node Choosing Articles
3450 @section Choosing Articles
3451 @cindex selecting articles
3453 None of the following movement commands understand the numeric prefix,
3454 and they all select and display an article.
3458 @kindex SPACE (Summary)
3459 @findex gnus-summary-next-page
3460 Select the current article, or, if that one's read already, the next
3461 unread article (@code{gnus-summary-next-page}).
3465 @kindex G n (Summary)
3466 @findex gnus-summary-next-unread-article
3467 Go to next unread article (@code{gnus-summary-next-unread-article}).
3471 @findex gnus-summary-prev-unread-article
3472 Go to previous unread article (@code{gnus-summary-prev-unread-article}).
3476 @kindex G N (Summary)
3477 @findex gnus-summary-next-article
3478 Go to the next article (@code{gnus-summary-next-article}).
3482 @kindex G P (Summary)
3483 @findex gnus-summary-prev-article
3484 Go to the previous article (@code{gnus-summary-prev-article}).
3486 @kindex G C-n (Summary)
3487 @findex gnus-summary-next-same-subject
3488 Go to the next article with the same subject
3489 (@code{gnus-summary-next-same-subject}).
3491 @kindex G C-p (Summary)
3492 @findex gnus-summary-prev-same-subject
3493 Go to the previous article with the same subject
3494 (@code{gnus-summary-prev-same-subject}).
3497 @kindex G f (Summary)
3499 @findex gnus-summary-first-unread-article
3500 Go to the first unread article
3501 (@code{gnus-summary-first-unread-article}).
3504 @kindex G b (Summary)
3506 Go to the article with the highest score
3507 (@code{gnus-summary-best-unread-article}).
3511 @kindex G l (Summary)
3512 @findex gnus-summary-goto-last-article
3513 Go to the previous article read (@code{gnus-summary-goto-last-article}).
3515 @kindex G p (Summary)
3516 @findex gnus-summary-pop-article
3517 Pop an article off the summary history and go to this article
3518 (@code{gnus-summary-pop-article}). This command differs from the
3519 command above in that you can pop as many previous articles off the
3520 history as you like.
3523 Some variables that are relevant for moving and selecting articles:
3526 @item gnus-auto-extend-newsgroup
3527 @vindex gnus-auto-extend-newsgroup
3528 All the movement commands will try to go to the previous (or next)
3529 article, even if that article isn't displayed in the Summary buffer if
3530 this variable is non-@code{nil}. Gnus will then fetch the article from
3531 the server and display it in the article buffer.
3532 @item gnus-select-article-hook
3533 @vindex gnus-select-article-hook
3534 This hook is called whenever an article is selected. By default it
3535 exposes any threads hidden under the selected article.
3536 @item gnus-mark-article-hook
3537 @vindex gnus-mark-article-hook
3538 This hook is called whenever an article is selected. It is intended to
3539 be used for marking articles as read.
3540 @item gnus-visual-mark-article-hook
3541 @vindex gnus-visual-mark-article-hook
3542 This hook is run after selecting an article. It is meant to be used for
3543 highlighting the article in some way. It is not run if
3544 @code{gnus-visual} is @code{nil}.
3545 @item gnus-summary-update-hook
3546 @vindex gnus-summary-update-hook
3547 This hook is called when a summary line is changed. It is not run if
3548 @code{gnus-visual} is @code{nil}.
3549 @item gnus-summary-selected-face
3550 @vindex gnus-summary-selected-face
3551 This is the face (or @dfn{font} as some people call it) that is used to
3552 highlight the current article in the summary buffer.
3553 @item gnus-summary-highlight
3554 @vindex gnus-summary-highlight
3555 Summary lines are highlighted according to this variable, which is a
3556 list where the elements are on the format @code{(FORM . FACE)}. If you
3557 would, for instance, like ticked articles to be italic and high-scored
3558 articles to be bold, you could set this variable to something like
3560 (((eq mark gnus-ticked-mark) . italic)
3561 ((> score default) . bold))
3563 As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
3564 @var{FACE} will be applied to the line.
3567 @node Paging the Article
3568 @section Scrolling the Article
3569 @cindex article scrolling
3574 @kindex SPACE (Summary)
3575 @findex gnus-summary-next-page
3576 Pressing @kbd{SPACE} will scroll the current article forward one page,
3577 or, if you have come to the end of the current article, will choose the
3578 next article (@code{gnus-summary-next-page}).
3581 @kindex DEL (Summary)
3582 @findex gnus-summary-prev-page
3583 Scroll the current article back one page (@code{gnus-summary-prev-page}).
3585 @kindex RET (Summary)
3586 @findex gnus-summary-scroll-up
3587 Scroll the current article one line forward
3588 (@code{gnus-summary-scroll-up}).
3593 @kindex A < (Summary)
3594 @findex gnus-summary-beginning-of-article
3595 Scroll to the beginning of the article
3596 (@code{gnus-summary-beginning-of-article}).
3601 @kindex A > (Summary)
3602 @findex gnus-summary-end-of-article
3603 Scroll to the end of the article (@code{gnus-summary-end-of-article}).
3606 @kindex A s (Summary)
3607 @findex gnus-summary-isearch-article
3608 Perform an isearch in the article buffer
3609 (@code{gnus-summary-isearch-article}).
3613 @node Reply Followup and Post
3614 @section Reply, Followup and Post
3619 @kindex C-c C-c (Post)
3620 All the commands for posting and mailing will put you in a post or mail
3621 buffer where you can edit the article all you like, before you send the
3622 article by pressing @kbd{C-c C-c}. If you are in a foreign news group,
3623 and you wish to post the article using the foreign server, you can give
3624 a prefix to @kbd{C-c C-c} to make Gnus try to post using the foreign
3628 * Mail:: Mailing & replying.
3629 * Post:: Posting and following up.
3630 * Mail & Post:: Mailing and posting at the same time.
3631 * Posting Styles:: An easier way to configure some key elements.
3632 * Drafts:: Postponing messages and rejected messages.
3633 * Rejected Articles:: What happens if the server doesn't like your article?
3639 Commands for composing a mail message:
3644 @kindex S r (Summary)
3646 @findex gnus-summary-reply
3647 Mail a reply to the author of the current article
3648 (@code{gnus-summary-reply}).
3652 @kindex S R (Summary)
3653 @findex gnus-summary-reply-with-original
3654 Mail a reply to the author of the current article and include the
3655 original message (@code{gnus-summary-reply-with-original}). This
3656 command uses the process/prefix convention.
3658 @kindex S o m (Summary)
3659 @findex gnus-summary-mail-forward
3660 Forward the current article to some other person
3661 (@code{gnus-summary-mail-forward}).
3663 @kindex S o p (Summary)
3664 @findex gnus-summary-post-forward
3665 Forward the current article to a newsgroup
3666 (@code{gnus-summary-post-forward}).
3670 @kindex S m (Summary)
3671 @findex gnus-summary-mail-other-window
3672 Send a mail to some other person
3673 (@code{gnus-summary-mail-other-window}).
3675 @kindex S D b (Summary)
3676 @findex gnus-summary-resend-bounced-mail
3677 If you have sent a mail, but the mail was bounced back to you for some
3678 reason (wrong address, transient failure), you can use this command to
3679 resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
3680 will be popped into a mail buffer where you can edit the headers before
3681 sending the mail off again. The headers that match the regexp
3682 @code{gnus-bounced-headers-junk} (default @samp{^Received:}) are
3683 automatically deleted first. If you give a prefix to this command, and
3684 the bounced mail is a reply to some other mail, Gnus will try to fetch
3685 that mail and display it for easy perusal of its headers. This might
3686 very well fail, though.
3688 @kindex S O m (Summary)
3689 @findex gnus-uu-digest-mail-forward
3690 Digest the current series and forward the result using mail
3691 (@code{gnus-uu-digest-mail-forward}). This command uses the
3692 process/prefix convention (@pxref{Process/Prefix}).
3694 @kindex S O p (Summary)
3695 @findex gnus-uu-digest-post-forward
3696 Digest the current series and forward the result to a newsgroup
3697 (@code{gnus-uu-digest-mail-forward}).
3700 Variables for customizing outgoing mail:
3703 @item gnus-reply-to-function
3704 @vindex gnus-reply-to-function
3705 Gnus uses the normal methods to determine where replies are to go, but
3706 you can change the behavior to suit your needs by fiddling with this
3709 If you want the replies to go to the @samp{Sender} instead of the
3710 @samp{From} in the group @samp{mail.stupid-list}, you could do something
3714 (setq gnus-reply-to-function
3716 (cond ((string= group "mail.stupid-list")
3717 (mail-fetch-field "sender"))
3722 This function will be called narrowed to the head of the article that is
3725 As you can see, this function should return a string if it has an
3726 opinion as to what the To header should be. If it does not, it should
3727 just return @code{nil}, and the normal methods for determining the To
3728 header will be used.
3730 This function can also return a list. In that case, each list element
3731 should be a cons, where the car should be the name of an header
3732 (eg. @samp{Cc}) and the cdr should be the header value
3733 (eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into
3734 the head of the outgoing mail.
3736 @item gnus-mail-send-method
3737 @vindex gnus-mail-send-method
3738 This variable says how a mail should be mailed. It uses the function in
3739 the @code{send-mail-function} variable as the default.
3741 @item gnus-uu-digest-headers
3742 @vindex gnus-uu-digest-headers
3743 List of regexps to match headers included in digested messages. The
3744 headers will be included in the sequence they are matched.
3746 @item gnus-mail-hook
3747 @vindex gnus-mail-hook
3748 Hook called as the last thing after setting up a mail buffer.
3750 @item gnus-required-mail-headers
3751 @vindex gnus-required-mail-headers
3752 Gnus will generate headers in all outgoing mail instead of letting
3753 @code{sendmail} do it for us. This makes it possible to do more neat
3754 stuff, like putting mail without sending it, do hairy @code{Fcc}
3755 handling, and much more. This variable controls what headers Gnus will
3756 generate, and is of the exact same form as @code{gnus-required-headers},
3757 which does the same for news articles (@pxref{Post}).
3759 The @code{Newsgroups} header is illegal in this list, while @code{To} is
3760 required, and @code{X-Mailer} can be added if you so should want.
3764 @kindex C-c C-c (Mail)
3765 @kindex C-c C-p (Mail)
3766 @findex gnus-put-message
3767 You normally send a mail message by pressing @kbd{C-c C-c}. However,
3768 you may wish to just put the mail message you have just written in your
3769 own local mail group instead of sending it. Sounds quite unlikely, but
3770 I found that useful, so you can now also press @kbd{C-c C-p} to
3771 @dfn{put} the article in the current mail group, or, if there is no such
3772 thing, you will be prompted for a mail group, and then the article will
3773 be put there. This means that the article is @dfn{not} mailed.
3775 There are three "methods" for handling all mail. The default is
3776 @code{sendmail}. Some people like what @code{mh} does better, and some
3777 people prefer @code{vm}.
3779 Three variables for customizing what to use when:
3783 @vindex gnus-mail-reply-method
3784 @item gnus-mail-reply-method
3785 This function is used to compose replies. The three functions avaibale
3788 @findex gnus-mail-reply-using-vm
3789 @findex gnus-mail-reply-using-mhe
3790 @findex gnus-mail-reply-using-mail
3793 @code{gnus-mail-reply-using-mail} (sendmail)
3795 @code{gnus-mail-reply-using-mhe} (mh)
3797 @code{gnus-mail-reply-using-vm} (vm)
3800 @vindex gnus-mail-forward-method
3801 @item gnus-mail-forward-method
3802 This function is used to forward messages. The three functions avaibale
3805 @findex gnus-mail-forward-using-vm
3806 @findex gnus-mail-forward-using-mhe
3807 @findex gnus-mail-forward-using-mail
3810 @code{gnus-mail-forward-using-mail} (sendmail)
3812 @code{gnus-mail-forward-using-mhe} (mh)
3814 @code{gnus-mail-forward-using-vm} (vm)
3817 @vindex gnus-mail-other-window-method
3818 @item gnus-mail-other-window-method
3819 This function is used to send mails. The three functions avaibale are:
3821 @findex gnus-mail-other-window-using-vm
3822 @findex gnus-mail-other-window-using-mhe
3823 @findex gnus-mail-other-window-using-mail
3826 @code{gnus-mail-other-window-using-mail} (sendmail)
3828 @code{gnus-mail-other-window-using-mhe} (mh)
3830 @code{gnus-mail-other-window-using-vm} (vm)
3839 Commands for posting an article:
3845 @kindex S p (Summary)
3846 @findex gnus-summary-post-news
3847 Post an article to the current group
3848 (@code{gnus-summary-post-news}).
3852 @kindex S f (Summary)
3853 @findex gnus-summary-followup
3854 Post a followup to the current article (@code{gnus-summary-followup}).
3857 @kindex S F (Summary)
3859 @findex gnus-summary-followup-with-original
3860 Post a followup to the current article and include the original message
3861 (@code{gnus-summary-followup-with-original}). This command uses the
3862 process/prefix convention.
3864 @kindex S u (Summary)
3865 @findex gnus-uu-post-news
3866 Uuencode a file, split it into parts, and post it as a series
3867 (@code{gnus-uu-post-news}).
3868 @c (@pxref{Uuencoding & Posting}).
3871 @vindex gnus-required-headers
3872 @code{gnus-required-headers} a list of header symbols. These headers
3873 will either be automatically generated, or, if that's impossible, they
3874 will be prompted for. The following symbols are legal:
3878 This required header will be filled out with the result of the
3879 @code{gnus-inews-user-name} function, which depends on the
3880 @code{gnus-user-from-line}, @code{gnus-user-login-name},
3881 @code{gnus-local-domain} and @code{user-mail-address} variables.
3883 This required header will be prompted for if not present already.
3885 This required header says which newsgroups the article is to be posted
3886 to. If it isn't present already, it will be prompted for.
3888 @cindex organization
3889 @vindex gnus-local-organization
3890 @vindex gnus-organization-file
3891 This optional header will be filled out depending on the
3892 @code{gnus-local-organization} variable. @code{gnus-organization-file}
3893 will be used if that variable is nil.
3895 This optional header will be computed by Gnus.
3897 This required header will be generated by Gnus. A unique ID will be
3898 created based on date, time, user name and system name.
3900 This optional header will be filled out with the Gnus version numbers.
3903 In addition, you can enter conses into this list. The car of this cons
3904 should be a symbol. This symbol's name is the name of the header, and
3905 the cdr can either be a string to be entered verbatim as the value of
3906 this header, or it can be a function to be called. This function should
3907 return a string to be inserted. For instance, if you want to insert
3908 @samp{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
3909 into the list. If you want to insert a funny quote, you could enter
3910 something like @code{(X-Yow . yow)} into the list. The function
3911 @code{yow} will then be called without any arguments.
3913 The list contains a cons where the car of the cons is @code{optional},
3914 the cdr of this cons will only be inserted if it is non-@code{nil}.
3916 Other variables for customizing outgoing articles:
3919 @item gnus-post-method
3920 @vindex gnus-post-method
3921 If non-@code{nil}, Gnus will use this method instead of the default
3922 select method when posting.
3924 @item nntp-news-default-headers
3925 @vindex nntp-news-default-headers
3926 If non-@code{nil}, this variable will override
3927 @code{mail-default-headers} when posting. This variable should then be
3928 a string. This string will be inserted, as is, in the head of all
3931 @item gnus-use-followup-to
3932 @vindex gnus-use-followup-to
3933 If @code{nil}, always ignore the Followup-To header. If it is @code{t},
3934 use its value, but ignore the special value @samp{poster}, which will
3935 send the followup as a reply mail to the person you are responding to.
3936 If it is the symbol @code{ask}, query the user before posting.
3937 If it is the symbol @code{use}, always use the value.
3939 @item gnus-followup-to-function
3940 @vindex gnus-followup-to-function
3941 This variable is most useful in mail groups, where "following up" really
3942 means sending a mail to a list address. Gnus uses the normal methods to
3943 determine where follow-ups are to go, but you can change the behavior
3944 to suit your needs by fiddling with this variable.
3946 If you want the followups to go to the @samp{Sender} instead of the
3947 @samp{From} in the group @samp{mail.stupid-list}, you could do something
3951 (setq gnus-followup-to-function
3953 (cond ((string= group "mail.stupid-list")
3954 (mail-fetch-field "sender"))
3959 This function will be called narrowed to header of the article that is
3962 @item gnus-removable-headers
3963 @vindex gnus-removable-headers
3964 Some headers that are generated are toxic to the @sc{nntp} server.
3965 These include the @code{NNTP-Posting-Host}, @code{Bcc} and @code{Xref},
3966 so these headers are deleted if they are present in this list of
3969 @item gnus-deletable-headers
3970 @vindex gnus-deletable-headers
3971 Headers in this list that were previously generated by Gnus will be
3972 deleted before posting. Let's say you post an article. Then you decide
3973 to post it again to some other group, you naughty boy, so you jump back
3974 to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
3975 ship it off again. By default, this variable makes sure that the old
3976 generated @code{Message-ID} is deleted, and a new one generated. If
3977 this isn't done, the entire empire would probably crumble, anarchy would
3978 prevail, and cats would start walking on two legs and rule the world.
3981 @item gnus-signature-function
3982 @vindex gnus-signature-function
3983 If non-@code{nil}, this variable should be a function that returns a
3984 signature file name. The function will be called with the name of the
3985 group being posted to. If the function returns a string that doesn't
3986 correspond to a file, the string itself is inserted. If the function
3987 returns @code{nil}, the @code{gnus-signature-file} variable will be used
3990 @item gnus-post-prepare-function
3991 @vindex gnus-post-prepare-function
3992 This function is called with the name of the current group after the
3993 post buffer has been initialized, and can be used for inserting a
3994 signature. Nice if you use different signatures in different groups.
3996 @item gnus-post-prepare-hook
3997 @vindex gnus-post-prepare-hook
3998 This hook is called after a post buffer has been prepared. If you want
3999 to insert a signature at this point, you could put
4000 @code{gnus-inews-insert-signature} into this hook.
4002 @item news-reply-header-hook
4003 @vindex news-reply-header-hook
4004 A related variable when following up and replying is this variable,
4005 which inserts the @dfn{quote line}. The default value is:
4008 (defvar news-reply-header-hook
4010 (insert "In article " news-reply-yank-message-id
4011 " " news-reply-yank-from " writes:\n\n")))
4014 This will create lines like:
4017 In article <zngay8jrql@@eyesore.no> Lars Mars <lars@@eyesore.no> writes:
4020 Having the @code{Message-Id} in this line is probably overkill, so I
4021 would suggest this hook instead:
4024 (setq news-reply-header-hook
4025 (lambda () (insert news-reply-yank-from " writes:\n\n")))
4028 @item gnus-prepare-article-hook
4029 @vindex gnus-prepare-article-hook
4030 This hook is called before the headers have been prepared.
4032 @item gnus-inews-article-function
4033 @vindex gnus-inews-article-function
4034 This function is used to do the actual article processing and header
4035 checking/generation.
4037 @item gnus-inews-article-hook
4038 @vindex gnus-inews-article-hook
4039 This hook is called right before the article is posted. By default it
4040 handles FCC processing (i.e., saving the article to a file.)
4042 @item gnus-inews-article-header-hook
4043 @vindex gnus-inews-article-header-hook
4044 This hook is called after inserting the required headers in an article
4045 to be posted. The hook is called from the @code{*post-news*} buffer,
4046 narrowed to the head, and is intended for people who would like to
4047 insert additional headers, or just change headers in some way or other.
4049 @item gnus-check-before-posting
4050 @vindex gnus-check-before-posting
4051 If non-@code{nil}, Gnus will attempt to check the legality of the
4052 headers, as well as some other stuff, before posting. You can control
4053 the granularity of the check by adding or removing elements from this
4054 list. Legal elemetents are:
4058 Check the subject for commands.
4060 Insert a new @code{Sender} header if the @code{From} header looks odd.
4061 @item multiple-headers
4062 Check for the existence of multiple equal headers.
4064 Check for the existence of version and sendsys commands.
4066 Check whether the @code{Message-ID} looks ok.
4068 Check whether the @code{From} header seems nice.
4070 Check for too long lines.
4072 Check for illegal characters.
4074 Check for excessive size.
4076 Check whether there is any new text in the messages.
4078 Check the length of the signature.
4080 Check whether the article has an @code{Approved} header, which is
4081 something only moderators should include.
4088 @subsection Mail & Post
4090 Commands for sending mail and post at the same time:
4094 @kindex S b (Summary)
4095 @findex gnus-summary-followup-and-reply
4096 Post a followup and send a reply to the current article
4097 (@code{gnus-summary-followup-and-reply}).
4099 @kindex S B (Summary)
4100 @findex gnus-summary-followup-and-reply-with-original
4101 Post a followup and send a reply to the current article and include the
4102 original message (@code{gnus-summary-followup-and-reply-with-original}).
4103 This command uses the process/prefix convention.
4106 Here's a list of variables that are relevant to both mailing and
4110 @item gnus-signature-file
4111 @itemx mail-signature
4112 @vindex mail-signature
4113 @vindex gnus-signature-file
4114 @cindex double signature
4116 If @code{gnus-signature-file} is non-@code{nil}, it should be the name
4117 of a file containing a signature (@samp{~/.signature} by default). This
4118 signature will be appended to all outgoing post. Most people find it
4119 more convenient to use @code{mail-signature}, which (sort of) does the
4120 same, but inserts the signature into the buffer before you start editing
4121 the post (or mail). So---if you have both of these variables set, you
4122 will get two signatures. Note that @code{mail-signature} does not work
4123 the same way as @code{gnus-signature-file}, which is a bit confusing.
4124 If @code{mail-signature} is @code{t}, it will insert
4125 @file{~/.signature}. If it is a string, this string will be inserted.
4127 Note that RFC1036 says that a signature should be preceded by the three
4128 characters @samp{-- } on a line by themselves. This is to make it
4129 easier for the recipient to automatically recognize and process the
4130 signature. So don't remove those characters, even though you might feel
4131 that they ruin you beautiful design, like, totally.
4133 Also note that no signature should be more than four lines long.
4134 Including ASCII graphics is an efficient way to get everybody to believe
4135 that you are silly and have nothing important to say.
4137 @item mail-yank-prefix
4138 @vindex mail-yank-prefix
4141 When you are replying to or following up an article, you normally want
4142 to quote the person you are answering. Inserting quoted text is done by
4143 @dfn{yanking}, and each quoted line you yank will have
4144 @code{mail-yank-prefix} prepended to it. This is @samp{ } by default,
4145 which isn't very pretty. Most everybody prefers that lines are
4146 prepended with @samp{> }, so @code{(setq mail-yank-prefix "> ")} in your
4149 @item mail-yank-ignored-headers
4150 @vindex mail-yank-ignored-headers
4151 When you yank a message, you do not want to quote any headers, so
4152 @code{(setq mail-yank-ignored-headers ":")}.
4154 @item user-mail-address
4155 @vindex user-mail-address
4156 If all of @code{gnus-user-login-name}, @code{gnus-use-generic-from} and
4157 @code{gnus-local-domain} are @code{nil}, Gnus will use
4158 @code{user-mail-address} as the address part of the @code{From} header.
4160 @item gnus-user-from-line
4161 @vindex gnus-user-from-line
4162 Your full, complete e-mail address with name. This variable overrides
4163 the other Gnus variables if it is non-@code{nil}.
4165 Here are two example values of this variable: @samp{"larsi@@ifi.uio.no
4166 (Lars Magne Ingebrigtsen)"} and @samp{"Lars Magne Ingebrigtsen
4167 <larsi@@ifi.uio.no>"}. The latter version is recommended in news (and is
4168 probably illegal in mail), but the name has to be quoted if it contains
4169 non-alpha-numerical characters---@samp{"\"Lars M. Ingebrigtsen\"
4170 <larsi@@ifi.uio.no>"}.
4172 @item mail-default-headers
4173 @vindex mail-default-headers
4174 This is a string that will be inserted into the header of all outgoing
4175 mail messages and news articles. Convenient to use to insert standard
4176 headers. If @code{nntp-news-default-headers} is non-@code{nil}, that
4177 variable will override this one when posting articles.
4179 @item gnus-auto-mail-to-author
4180 @vindex gnus-auto-mail-to-author
4181 If @code{ask}, you will be prompted for whether you want to send a mail
4182 copy to the author of the article you are following up. If
4183 non-@code{nil} and not @code{ask}, Gnus will send a mail with a copy of
4184 all follow-ups to the authors of the articles you follow up. It's nice
4185 in one way---you make sure that the person you are responding to gets
4186 your response. Other people loathe this method and will hate you dearly
4187 for it, because it means that they will first get a mail, and then have
4188 to read the same article later when they read the news. It is
4189 @code{nil} by default.
4191 @item gnus-mail-courtesy-message
4192 @vindex gnus-mail-courtesy-message
4193 This is a string that will be prepended to all mails that are the result
4194 of using the variable described above.
4196 @item gnus-outgoing-message-group
4197 @vindex gnus-outgoing-message-group
4198 All outgoing messages will be put in this group. If you want to store
4199 all your outgoing mail and articles in the group @samp{nnml:archive},
4200 you set this variable to that value. This variable can also be a list of
4203 If you want to have greater control over what group to put each
4204 message in, you can set this variable to a function that checks the
4205 current newsgroup name and then returns a suitable group name (or list
4208 @item gnus-mailing-list-groups
4209 @findex gnus-mailing-list-groups
4210 @cindex mailing lists
4212 If your newsserver offer groups that are really mailing lists that are
4213 gatewayed to the @sc{nntp} server, you can read those groups without
4214 problems, but you can't post/followup to them without some difficulty.
4215 One solution is to add a @code{to-address} to the group parameters
4216 (@pxref{Group Parameters}). An easier thing to do is set the
4217 @code{gnus-mailing-list-groups} to a regexp that match the groups that
4218 really are mailing lists. Then, at least, followups to the mailing
4219 lists will work most of the time. Posting to these groups (@kbd{a}) is
4220 still a pain, though.
4225 You may want to do spell-checking on messages that you send out. Or, if
4226 you don't want to spell-check by hand, you could add automatic
4227 spell-checking via the @code{ispell} package:
4229 @vindex news-inews-hook
4231 (add-hook 'news-inews-hook 'ispell-message) ;For news posts
4232 (add-hook 'mail-send-hook 'ispell-message) ;for mail posts via sendmail
4235 @findex gnus-inews-insert-mime-headers
4236 If you want to insert some @sc{mime} headers into the articles you post,
4237 without doing any actual encoding, you could add
4238 @code{gnus-inews-insert-mime-headers} to @code{gnus-inews-article-hook}.
4241 @node Posting Styles
4242 @subsection Posting Styles
4243 @cindex posting styles
4246 All them variables, they make my head swim.
4248 So what if you want a different @code{Organization} and signature based
4249 on what groups you post to? And you post both from your home machine
4250 and your work machine, and you want different @code{From} lines, and so
4253 @vindex gnus-posting-styles
4254 One way to do stuff like that is to write clever hooks that change the
4255 variables you need to have changed. That's a bit boring, so somebody
4256 came up with the bright idea of letting the user specify these things in
4257 a handy alist. Here's an example of a @code{gnus-posting-styles}
4261 ((".*" (signature . "Peace and happiness") (organization . "What me?"))
4262 ("^comp" (signature . "Death to everybody"))
4263 ("comp.emacs.i-love-it" (organization . "Emacs is it")))
4266 As you might surmise from this example, this alist consists of several
4267 @dfn{styles}. Each style will be applicable if the first element
4268 "matches", in some form or other. The entire alist will be iterated
4269 over, from the beginning towards the end, and each match will be
4270 applied, which means that attributes in later styles that match override
4271 the same attributes in earlier matching styles. So
4272 @samp{comp.programming.literate} will have the @samp{Death to everybody}
4273 signature and the @samp{What me?} @code{Organization} header.
4275 The first element in each style is called the @code{match}. If it's a
4276 string, then Gnus will try to regexp match it against the group name.
4277 If it's a function symbol, that function will be called with no
4278 arguments. If it's a variable symbol, then the variable will be
4279 referenced. If it's a list, then that list will be @code{eval}ed. In
4280 any case, if this returns a non-@code{nil} value, then the style is said
4283 Each style may contain a random amount of @dfn{attributes}. Each
4284 attribute consists of a @var{(name . value)} pair. The attribute name
4285 can be one of @code{signature}, @code{organization} or @code{from}.
4286 The attribute name can also be a string. In that case, this will be
4287 used as a header name, and the value will be inserted in the headers of
4290 The attribute value can be a string (used verbatim), a function (the
4291 return value will be used), a variable (its value will be used) or a
4292 list (it will be @code{eval}ed and the return value will be used).
4294 So here's a new example:
4297 (setq gnus-posting-styles
4299 (signature . "~/.signature")
4300 (from . "user@@foo (user)")
4301 ("X-Home-Page" . (getenv "WWW_HOME"))
4302 (organization . "People's Front Against MWM"))
4304 (signature . my-funny-signature-randomizer))
4305 ((equal (system-name) "gnarly")
4306 (signature . my-quote-randomizer))
4307 (posting-from-work-p
4308 (signature . "~/.work-signature")
4309 (from . "user@@bar.foo (user)")
4310 (organization . "Important Work, Inc"))
4312 (signature . "~/.mail-signature"))))
4321 If you are writing a message (mail or news) and suddenly remember that
4322 you have a steak in the oven (or pesto in the food processor, you craazy
4323 vegetarians), you'll probably wish there was a method to save the
4324 message you are writing so that you can continue editing it some other
4325 day, and send it when you feel its finished.
4327 @kindex C-c C-d (Mail)
4328 @kindex C-c C-d (Post)
4329 @findex gnus-enter-into-draft-group
4330 @vindex gnus-draft-group-directory
4331 What you then do is simply push @kbd{C-c C-d}
4332 (@code{gnus-enter-into-draft-group}). This will put the current
4333 (unfinished) message in a special draft group (which is implemented as
4334 an @code{nndir} group, if you absolutely have to know) called
4335 @samp{nndir:drafts}. The variable @code{gnus-draft-group-directory}
4336 controls both the name of the group and the location---the leaf element
4337 in the path will be used as the name of the group.
4339 If the group doesn't exist, it will be created and you'll be subscribed
4342 @findex gnus-summary-send-draft
4344 When you want to continue editing the article, you simply enter the
4345 draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
4346 that. You will be placed in a buffer where you left off.
4348 Rejected articles will also be put in this draft group (@pxref{Rejected
4351 @findex gnus-summary-send-all-drafts
4352 If you have lots of rejected messages you want to post (or mail) without
4353 doing further editing, you can use the @kbd{S D a} command
4354 (@code{gnus-summary-send-all-drafts}). This command understands the
4355 process/prefix convention (@pxref{Process/Prefix}).
4358 @node Rejected Articles
4359 @subsection Rejected Articles
4360 @cindex rejected articles
4362 Sometimes a news server will reject an article. Perhaps the server
4363 doesn't like your face. Perhaps it just feels miserable. Perhaps
4364 @emph{there be demons}. Perhaps you have included too much cited text.
4365 Perhaps the disk is full. Perhaps the server is down.
4367 These situations are, of course, totally beyond the control of Gnus.
4368 (Gnus, of course, loves the way you look, always feels great, has angels
4369 fluttering around inside of it, doesn't care about how much cited text
4370 you include, never runs full and never goes down.) So Gnus saves these
4371 articles until some later time when the server feels better.
4373 The rejected articles will automatically be put in a special draft group
4374 (@pxref{Drafts}). When the server comes back up again, you'd then
4375 typically enter that group and send all the articles off.
4378 @node Canceling and Superseding
4379 @section Canceling Articles
4380 @cindex canceling articles
4381 @cindex superseding articles
4383 Have you ever written something, and then decided that you really,
4384 really, really wish you hadn't posted that?
4386 Well, you can't cancel mail, but you can cancel posts.
4388 @findex gnus-summary-cancel-article
4390 Find the article you wish to cancel (you can only cancel your own
4391 articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
4392 c} (@code{gnus-summary-cancel-article}). Your article will be
4393 canceled---machines all over the world will be deleting your article.
4395 Be aware, however, that not all sites honor cancels, so your article may
4396 live on here and there, while most sites will delete the article in
4399 If you discover that you have made some mistakes and want to do some
4400 corrections, you can post a @dfn{superseding} article that will replace
4401 your original article.
4403 @findex gnus-summary-supersede-article
4405 Go to the original article and press @kbd{S s}
4406 (@code{gnus-summary-supersede-article}). You will be put in a buffer
4407 where you can edit the article all you want before sending it off the
4410 @vindex gnus-delete-supersedes-headers
4411 You probably want to delete some of the old headers before sending the
4412 superseding article---@code{Path} and @code{Date} are probably
4413 incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
4414 match the lines you want removed. The default is
4415 @samp{"^Path:\\|^Date"}.
4417 The same goes for superseding as for canceling, only more so: Some
4418 sites do not honor superseding. On those sites, it will appear that you
4419 have posted almost the same article twice.
4421 If you have just posted the article, and change your mind right away,
4422 there is a trick you can use to cancel/supersede the article without
4423 waiting for the article to appear on your site first. You simply return
4424 to the post buffer (which is called @code{*post-buf*}). There you will
4425 find the article you just posted, with all the headers intact. Change
4426 the @samp{Message-ID} header to a @samp{Cancel} or @samp{Supersedes}
4427 header by substituting one of those words for @samp{Message-ID}. Then
4428 just press @kbd{C-c C-c} to send the article as you would do normally.
4429 The previous article will be canceled/superseded.
4431 Just remember, kids: There is no 'c' in 'supersede'.
4433 @node Marking Articles
4434 @section Marking Articles
4435 @cindex article marking
4436 @cindex article ticking
4439 There are several marks you can set on an article.
4441 You have marks that decide the @dfn{readed-ness} (whoo, neato-keano
4442 neologism ohoy!) of the article. Alphabetic marks generally mean
4443 @dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
4445 In addition, you also have marks that do not affect readedness.
4448 * Unread Articles:: Marks for unread articles.
4449 * Read Articles:: Marks for read articles.
4450 * Other Marks:: Marks that do not affect readedness.
4454 There's a plethora of commands for manipulating these marks:
4458 * Setting Marks:: How to set and remove marks.
4459 * Setting Process Marks:: How to mark articles for later processing.
4462 @node Unread Articles
4463 @subsection Unread Articles
4465 The following marks mark articles as unread, in one form or other.
4467 @vindex gnus-dormant-mark
4468 @vindex gnus-ticked-mark
4471 @dfn{Ticked articles} are articles that will remain visible always. If
4472 you see an article that you find interesting, or you want to put off
4473 reading it, or replying to it, until sometime later, you'd typically
4474 tick it. However, articles can be expired, so if you want to keep an
4475 article forever, you'll have to save it. Ticked articles have a
4476 @samp{!} (@code{gnus-ticked-mark}) in the first column.
4478 A @dfn{dormant} article is marked with a @samp{?}
4479 (@code{gnus-dormant-mark}), and will only appear in the summary buffer
4480 if there are followups to it.
4482 An @dfn{unread} article is marked with a @samp{SPC}
4483 (@code{gnus-unread-mark}). These are articles that haven't been read at
4488 @subsection Read Articles
4489 @cindex expirable mark
4491 All the following marks mark articles as read.
4495 Articles that are marked as read. They have a @samp{r}
4496 (@code{gnus-del-mark}) in the first column. These are articles that the
4497 user has marked as read more or less manually.
4499 Articles that are actually read are marked with @samp{R}
4500 (@code{gnus-read-mark}).
4502 Articles that were marked as read in previous sessions are now
4503 @dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
4505 Marked as killed (@code{gnus-killed-mark}).
4507 Marked as killed by kill files (@code{gnus-kill-file-mark}).
4509 Marked as read by having a too low score (@code{gnus-low-score-mark}).
4511 Marked as read by a catchup (@code{gnus-catchup-mark}).
4513 Canceled article (@code{gnus-cancelled-mark})
4516 All these marks just mean that the article is marked as read, really.
4517 They are interpreted differently by the adaptive scoring scheme,
4520 One more special mark, though:
4524 You can also mark articles as @dfn{expirable} (or have them marked as
4525 such automatically). That doesn't make much sense in normal groups,
4526 because a user does not control the expiring of news articles, but in
4527 mail groups, for instance, articles that are marked as @dfn{expirable}
4528 can be deleted by Gnus at any time. Expirable articles are marked with
4529 @samp{E} (@code{gnus-expirable-mark}).
4533 @subsection Other Marks
4534 @cindex process mark
4537 There are some marks that have nothing to do with whether the article is
4540 You can set a bookmark in the current article. Say you are reading a
4541 long thesis on cat's urinary tracts, and have to go home for dinner
4542 before you've finished reading the thesis. You can then set a bookmark
4543 in the article, and Gnus will jump to this bookmark the next time it
4544 encounters the article.
4546 All articles that you have replied to or made a followup to (i.e., have
4547 answered) will be marked with an @samp{A} in the second column
4548 (@code{gnus-replied-mark}).
4550 @vindex gnus-not-empty-thread-mark
4551 @vindex gnus-empty-thread-mark
4552 It the @samp{%e} spec is used, the presence of threads or not will be
4553 marked with @code{gnus-not-empty-thread-mark} and
4554 @code{gnus-empty-thread-mark}, respectively.
4556 @vindex gnus-process-mark
4557 Finally we have the @dfn{process mark} (@code{gnus-process-mark}. A
4558 variety of commands react to the presence of the process mark. For
4559 instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
4560 all articles that have been marked with the process mark. Articles
4561 marked with the process mark have a @samp{#} in the second column.
4564 @subsection Setting Marks
4565 @cindex setting marks
4567 All the marking commands understand the numeric prefix.
4573 @kindex M t (Summary)
4574 @findex gnus-summary-tick-article-forward
4575 Tick the current article (@code{gnus-summary-tick-article-forward}).
4579 @kindex M ? (Summary)
4580 @findex gnus-summary-mark-as-dormant
4581 Mark the current article as dormant
4582 (@code{gnus-summary-mark-as-dormant}).
4585 @kindex M d (Summary)
4587 @findex gnus-summary-mark-as-read-forward
4588 Mark the current article as read
4589 (@code{gnus-summary-mark-as-read-forward}).
4593 @kindex M k (Summary)
4594 @findex gnus-summary-kill-same-subject-and-select
4595 Mark all articles that have the same subject as the current one as read,
4596 and then select the next unread article
4597 (@code{gnus-summary-kill-same-subject-and-select}).
4600 @kindex M K (Summary)
4601 @kindex C-k (Summary)
4602 @findex gnus-summary-kill-same-subject
4603 Mark all articles that have the same subject as the current one as read
4604 (@code{gnus-summary-kill-same-subject}).
4606 @kindex M C (Summary)
4607 @findex gnus-summary-catchup
4608 Mark all unread articles in the group as read
4609 (@code{gnus-summary-catchup}).
4611 @kindex M C-c (Summary)
4612 @findex gnus-summary-catchup-all
4613 Mark all articles in the group as read---even the ticked and dormant
4614 articles (@code{gnus-summary-catchup-all}).
4616 @kindex M H (Summary)
4617 @findex gnus-summary-catchup-to-here
4618 Catchup the current group to point
4619 (@code{gnus-summary-catchup-to-here}).
4621 @kindex C-w (Summary)
4622 @findex gnus-summary-mark-region-as-read
4623 Mark all articles between point and mark as read
4624 (@code{gnus-summary-mark-region-as-read}).
4626 @kindex M V k (Summary)
4627 @findex gnus-summary-kill-below
4628 Kill all articles with scores below the default score (or below the
4629 numeric prefix) (@code{gnus-summary-kill-below}).
4632 @kindex M c (Summary)
4633 @kindex M-u (Summary)
4634 @findex gnus-summary-clear-mark-forward
4635 Clear all readedness-marks from the current article
4636 (@code{gnus-summary-clear-mark-forward}).
4639 @kindex M e (Summary)
4641 @findex gnus-summary-mark-as-expirable
4642 Mark the current article as expirable
4643 (@code{gnus-summary-mark-as-expirable}).
4645 @kindex M b (Summary)
4646 @findex gnus-summary-set-bookmark
4647 Set a bookmark in the current article
4648 (@code{gnus-summary-set-bookmark}).
4650 @kindex M B (Summary)
4651 @findex gnus-summary-remove-bookmark
4652 Remove the bookmark from the current article
4653 (@code{gnus-summary-remove-bookmark}).
4655 @kindex M V c (Summary)
4656 @findex gnus-summary-clear-above
4657 Clear all marks from articles with scores over the default score (or
4658 over the numeric prefix) (@code{gnus-summary-clear-above}).
4660 @kindex M V u (Summary)
4661 @findex gnus-summary-tick-above
4662 Tick all articles with scores over the default score (or over the
4663 numeric prefix) (@code{gnus-summary-tick-above}).
4665 @kindex M V m (Summary)
4666 @findex gnus-summary-mark-above
4667 Prompt for a mark, and mark all articles with scores over the default
4668 score (or over the numeric prefix) with this mark
4669 (@code{gnus-summary-clear-above}).
4672 @code{gnus-summary-goto-unread}
4673 The @code{gnus-summary-goto-unread} variable controls what action should
4674 be taken after setting a mark. If non-@code{nil}, point will move to
4675 the next/previous unread article. If @code{nil}, point will just move
4676 one line up or down.
4679 @node Setting Process Marks
4680 @subsection Setting Process Marks
4681 @cindex setting process marks
4687 @kindex M P p (Summary)
4688 @findex gnus-summary-mark-as-processable
4689 Mark the current article with the process mark
4690 (@code{gnus-summary-mark-as-processable}).
4691 @findex gnus-summary-unmark-as-processable
4694 @kindex M P u (Summary)
4695 @kindex M-# (Summary)
4696 Remove the process mark, if any, from the current article
4697 (@code{gnus-summary-unmark-as-processable}).
4699 @kindex M P U (Summary)
4700 @findex gnus-summary-unmark-all-processable
4701 Remove the process mark from all articles
4702 (@code{gnus-summary-unmark-all-processable}).
4704 @kindex M P R (Summary)
4705 @findex gnus-uu-mark-by-regexp
4706 Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
4708 @kindex M P r (Summary)
4709 @findex gnus-uu-mark-region
4710 Mark articles in region (@code{gnus-uu-mark-region}).
4712 @kindex M P t (Summary)
4713 @findex gnus-uu-mark-thread
4714 Mark all articles in the current (sub)thread
4715 (@code{gnus-uu-mark-thread}).
4717 @kindex M P T (Summary)
4718 @findex gnus-uu-unmark-thread
4719 Unmark all articles in the current (sub)thread
4720 (@code{gnus-uu-unmark-thread}).
4722 @kindex M P s (Summary)
4723 @findex gnus-uu-mark-series
4724 Mark all articles in the current series (@code{gnus-uu-mark-series}).
4726 @kindex M P S (Summary)
4727 @findex gnus-uu-mark-sparse
4728 Mark all series that have already had some articles marked
4729 (@code{gnus-uu-mark-sparse}).
4731 @kindex M P a (Summary)
4732 @findex gnus-uu-mark-all
4733 Mark all articles in series order (@code{gnus-uu-mark-series}).
4735 @kindex M P b (Summary)
4736 @findex gnus-uu-mark-buffer
4737 Mark all articles in the buffer in the order they appear
4738 (@code{gnus-uu-mark-buffer}).
4746 It can be convenient to limit the summary buffer to just show some
4747 subset of the articles currently in the group. The effect most limit
4748 commands have is to remove a few (or many) articles from the summary
4755 @kindex M N u (Summary)
4757 @findex gnus-summary-limit-to-unread
4758 Limit the summary buffer to articles that are not marked as read
4759 (@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
4760 buffer to articles that are strictly unread. This means that ticked and
4761 dormant articles will also be excluded.
4764 @kindex M N m (Summary)
4765 @findex gnus-summary-limit-to-marks
4766 Ask for a mark and then limit to all articles that have not been marked
4767 with that mark (@code{gnus-summary-limit-to-marks}).
4770 @kindex M N n (Summary)
4772 Limit the summary buffer to the current article
4773 (@code{gnus-summary-limit-to-articles}). Uses the process/prefix
4774 convention (@pxref{Process/Prefix}).
4777 @kindex M N w (Summary)
4778 @findex gnus-summary-pop-limit
4779 Pop the previous limit off the stack and restore it
4780 (@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
4785 @kindex M N s (Summary)
4787 @findex gnus-summary-limit-to-subject
4788 Limit the summary buffer to articles that have a subject that matches a
4789 regexp (@code{gnus-summary-limit-to-subject}).
4792 @kindex M N v (Summary)
4793 @findex gnus-summary-limit-to-score
4794 Limit the summary buffer to articles that have a score at or above some
4795 score (@code{gnus-summary-limit-to-score}).
4798 @kindex M S (Summary)
4799 @findex gnus-summary-show-all-expunged
4800 Display all expunged articles (@code{gnus-summary-show-all-expunged}).
4803 @kindex M N D (Summary)
4804 @findex gnus-summary-limit-include-dormant
4805 Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
4808 @kindex M N d (Summary)
4809 @findex gnus-summary-limit-exclude-dormant
4810 Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
4813 @kindex M N c (Summary)
4814 @findex gnus-summary-limit-exclude-childless-dormant
4815 Hide all dormant articles that have no children
4816 (@code{gnus-summary-limit-exclude-childless-dormant}).
4824 @cindex article threading
4826 Gnus threads articles by default. @dfn{To thread} is to put replies to
4827 articles directly after the articles they reply to---in a hierarchical
4831 * Customizing Threading:: Variables you can change to affect the threading.
4832 * Thread Commands:: Thread based commands in the summary buffer.
4835 @node Customizing Threading
4836 @subsection Customizing Threading
4837 @cindex customizing threading
4842 @item gnus-show-threads
4843 @vindex gnus-show-threads
4844 If this variable is @code{nil}, no threading will be done, and all of
4845 the rest of the variables here will have no effect. Turning threading
4846 off will speed group selection up a bit, but it is sure to make reading
4847 slower and more awkward.
4849 @item gnus-fetch-old-headers
4850 @vindex gnus-fetch-old-headers
4851 If non-@code{nil}, Gnus will attempt to build old threads by fetching
4852 more old headers---headers to articles that are marked as read. If you
4853 would like to display as few summary lines as possible, but still
4854 connect as many loose threads as possible, you should set this variable
4855 to @code{some} or a number. If you set it to a number, no more than
4856 that number of extra old headers will be fetched. In either case,
4857 fetching old headers only works if the backend you are using carries
4858 overview files---this would normally be @code{nntp}, @code{nnspool} and
4859 @code{nnml}. Also remember that if the root of the thread has been
4860 expired by the server, there's not much Gnus can do about that.
4862 @item gnus-summary-gather-subject-limit
4863 Loose threads are gathered by comparing subjects of articles. If this
4864 variable is @code{nil}, Gnus requires an exact match between the
4865 subjects of the loose threads before gathering them into one big
4866 super-thread. This might be too strict a requirement, what with the
4867 presence of stupid newsreaders that chop off long subjects lines. If
4868 you think so, set this variable to, say, 20 to require that only the
4869 first 20 characters of the subjects have to match. If you set this
4870 variable to a real low number, you'll find that Gnus will gather
4871 everything in sight into one thread, which isn't very helpful.
4873 @cindex fuzzy article gathering
4874 If you set this variable to the special value @code{fuzzy}, Gnus will
4875 use a fuzzy string comparison algorithm on the subjects.
4877 @vindex gnus-summary-gather-exclude-subject
4878 Since loose thread gathering is done on subjects only, that might lead
4879 to many false hits, especially with certain common subjects like
4880 @samp{""} and @samp{"(none)"}. To make the situation slightly better,
4881 you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
4882 what subjects should be excluded from the gathering process. The
4883 default is @samp{"^ *$\\|^(none)$"}.
4885 @item gnus-summary-make-false-root
4886 @vindex gnus-summary-make-false-root
4887 If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
4888 and create a dummy root at the top. (Wait a minute. Root at the top?
4889 Yup.) Loose subtrees occur when the real root has expired, or you've
4890 read or killed the root in a previous session.
4892 When there is no real root of a thread, Gnus will have to fudge
4893 something. This variable says what fudging method Gnus should use.
4894 There are four possible values:
4896 @cindex adopting articles
4900 Gnus will make the first of the orphaned articles the parent. This
4901 parent will adopt all the other articles. The adopted articles will be
4902 marked as such by pointy brackets (@samp{<>}) instead of the standard
4903 square brackets (@samp{[]}). This is the default method.
4905 Gnus will create a dummy summary line that will pretend to be the
4906 parent. This dummy line does not correspond to any real article, so
4907 selecting it will just select the first real article after the dummy
4910 Gnus won't actually make any article the parent, but simply leave the
4911 subject field of all orphans except the first empty. (Actually, it will
4912 use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
4915 Don't make any article parent at all. Just gather the threads and
4916 display them after one another.
4918 Don't gather loose threads.
4921 @item gnus-thread-hide-subtree
4922 @vindex gnus-thread-hide-subtree
4923 If non-@code{nil}, all threads will be hidden when the summary buffer is
4926 @item gnus-thread-hide-killed
4927 @vindex gnus-thread-hide-killed
4928 if you kill a thread and this variable is non-@code{nil}, the subtree
4931 @item gnus-thread-ignore-subject
4932 @vindex gnus-thread-ignore-subject
4933 Sometimes somebody changes the subject in the middle of a thread. If
4934 this variable is non-@code{nil}, the subject change is ignored. If it
4935 is @code{nil}, which is the default, a change in the subject will result
4938 @item gnus-thread-indent-level
4939 @vindex gnus-thread-indent-level
4940 This is a number that says how much each sub-thread should be indented.
4941 The default is @samp{4}.
4944 @node Thread Commands
4945 @subsection Thread Commands
4946 @cindex thread commands
4952 @kindex T k (Summary)
4953 @kindex M-C-k (Summary)
4954 @findex gnus-summary-kill-thread
4955 Mark all articles in the current sub-thread as read
4956 (@code{gnus-summary-kill-thread}). If the prefix argument is positive,
4957 remove all marks instead. If the prefix argument is negative, tick
4962 @kindex T l (Summary)
4963 @kindex M-C-l (Summary)
4964 @findex gnus-summary-lower-thread
4965 Lower the score of the current thread
4966 (@code{gnus-summary-lower-thread}).
4969 @kindex T i (Summary)
4970 @findex gnus-summary-raise-thread
4971 Increase the score of the current thread
4972 (@code{gnus-summary-raise-thread}).
4975 @kindex T # (Summary)
4976 @findex gnus-uu-mark-thread
4977 Set the process mark on the current thread
4978 (@code{gnus-uu-mark-thread}).
4981 @kindex T M-# (Summary)
4982 @findex gnus-uu-unmark-thread
4983 Remove the process mark from the current thread
4984 (@code{gnus-uu-unmark-thread}).
4987 @kindex T T (Summary)
4988 @findex gnus-summary-toggle-threads
4989 Toggle threading (@code{gnus-summary-toggle-threads}).
4992 @kindex T s (Summary)
4993 @findex gnus-summary-show-thread
4994 Expose the thread hidden under the current article, if any
4995 (@code{gnus-summary-show-thread}).
4998 @kindex T h (Summary)
4999 @findex gnus-summary-hide-thread
5000 Hide the current (sub)thread (@code{gnus-summary-hide-thread}).
5003 @kindex T S (Summary)
5004 @findex gnus-summary-show-all-threads
5005 Expose all hidden threads (@code{gnus-summary-show-all-threads}).
5008 @kindex T H (Summary)
5009 @findex gnus-summary-hide-all-threads
5010 Hide all threads (@code{gnus-summary-hide-all-threads}).
5013 The following commands are thread movement commands. They all
5014 understand the numeric prefix.
5018 @kindex T n (Summary)
5019 @findex gnus-summary-next-thread
5020 Go to the next thread (@code{gnus-summary-next-thread}).
5022 @kindex T p (Summary)
5023 @findex gnus-summary-prev-thread
5024 Go to the previous thread (@code{gnus-summary-prev-thread}).
5026 @kindex T d (Summary)
5027 @findex gnus-summary-down-thread
5028 Descend the thread (@code{gnus-summary-down-thread}).
5030 @kindex T u (Summary)
5031 @findex gnus-summary-up-thread
5032 Ascend the thread (@code{gnus-summary-up-thread}).
5035 @vindex gnus-thread-operation-ignore-subject
5036 If you ignore subject while threading, you'll naturally end up with
5037 threads that have several different subjects in them. If you then issue
5038 a command like `T k' (@code{gnus-summary-kill-thread}) you might not
5039 wish to kill the entire thread, but just those parts of the thread that
5040 have the same subject as the current article. If you like this idea,
5041 you can fiddle with @code{gnus-thread-operation-ignore-subject}. If is
5042 is non-@code{nil} (which it is by default), subjects will be ignored
5043 when doing thread commands. If this variable is @code{nil}, articles in
5044 the same thread with different subjects will not be included in the
5045 operation in question. If this variable is @code{fuzzy}, only articles
5046 that have subjects that are fuzzily equal will be included.
5049 @node Asynchronous Fetching
5050 @section Asynchronous Article Fetching
5051 @cindex asynchronous article fetching
5053 If you read your news from an @sc{nntp} server that's far away, the
5054 network latencies may make reading articles a chore. You have to wait
5055 for a while after pressing @kbd{n} to go to the next article before the
5056 article appears. Why can't Gnus just go ahead and fetch the article
5057 while you are reading the previous one? Why not, indeed.
5059 First, some caveats. There are some pitfalls to using asynchronous
5060 article fetching, especially the way Gnus does it.
5062 Let's say you are reading article 1, which is short, and article 2 is
5063 quite long, and you are not interested in reading that. Gnus does not
5064 know this, so it goes ahead and fetches article 2. You decide to read
5065 article 3, but since Gnus is in the process of fetching article 2, the
5066 connection is blocked.
5068 To avoid these situations, Gnus will open two (count 'em two)
5069 connections to the server. Some people may think this isn't a very nice
5070 thing to do, but I don't see any real alternatives. Setting up that
5071 extra connection takes some time, so Gnus startup will be slower.
5073 Gnus will fetch more articles than you will read. This will mean that
5074 the link between your machine and the @sc{nntp} server will become more
5075 loaded than if you didn't use article pre-fetch. The server itself will
5076 also become more loaded---both with the extra article requests, and the
5079 Ok, so now you know that you shouldn't really use this thing... unless
5082 @vindex gnus-asynchronous
5083 Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
5084 happen automatically.
5086 @vindex nntp-async-number
5087 You can control how many articles that are to be pre-fetched by setting
5088 @code{nntp-async-number}. This is five by default, which means that when
5089 you read an article in the group, @code{nntp} will pre-fetch the next
5090 five articles. If this variable is @code{t}, @code{nntp} will pre-fetch
5091 all the articles that it can without bound. If it is @code{nil}, no
5092 pre-fetching will be made.
5094 @vindex gnus-asynchronous-article-function
5095 You may wish to create some sort of scheme for choosing which articles
5096 that @code{nntp} should consider as candidates for pre-fetching. For
5097 instance, you may wish to pre-fetch all articles with high scores, and
5098 not pre-fetch low-scored articles. You can do that by setting the
5099 @code{gnus-asynchronous-article-function}, which will be called with an
5100 alist where the keys are the article numbers. Your function should
5101 return an alist where the articles you are not interested in have been
5102 removed. You could also do sorting on article score and the like.
5104 @node Article Caching
5105 @section Article Caching
5106 @cindex article caching
5109 If you have an @emph{extremely} slow @sc{nntp} connection, you may
5110 consider turning article caching on. Each article will then be stored
5111 locally under your home directory. As you may surmise, this could
5112 potentially use @emph{huge} amounts of disk space, as well as eat up all
5113 your inodes so fast it will make your head swim. In vodka.
5115 Used carefully, though, it could be just an easier way to save articles.
5117 @vindex gnus-use-long-file-name
5118 @vindex gnus-cache-directory
5119 @vindex gnus-use-cache
5120 To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
5121 all articles that are ticked or marked as dormant will then be copied
5122 over to your local cache (@code{gnus-cache-directory}). Whether this
5123 cache is flat or hierarchal is controlled by the
5124 @code{gnus-use-long-file-name} variable, as usual.
5126 When re-select a ticked or dormant article, it will be fetched from the
5127 cache instead of from the server. As articles in your cache will never
5128 expire, this might serve as a method of saving articles while still
5129 keeping them where they belong. Just mark all articles you want to save
5130 as dormant, and don't worry.
5132 When an article is marked as read, is it removed from the cache.
5134 @vindex gnus-cache-remove-articles
5135 @vindex gnus-cache-enter-articles
5136 The entering/removal of articles from the cache is controlled by the
5137 @code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
5138 variables. Both are lists of symbols. The first is @code{(ticked
5139 dormant)} by default, meaning that ticked and dormant articles will be
5140 put in the cache. The latter is @code{(read)} by default, meaning that
5141 articles that are marked as read are removed from the cache. Possibly
5142 symbols in these two lists are @code{ticked}, @code{dormant},
5143 @code{unread} and @code{read}.
5145 @findex gnus-jog-cache
5146 So where does the massive article-fetching and storing come into the
5147 picture? The @code{gnus-jog-cache} command will go through all
5148 subscribed newsgroups, request all unread articles, and store them in
5149 the cache. You should only ever, ever ever ever, use this command if 1)
5150 your connection to the @sc{nntp} server is really, really, really slow
5151 and 2) you have a really, really, really huge disk. Seriously.
5153 @vindex gnus-uncacheable-groups
5154 It is likely that you do not want caching on some groups. For instance,
5155 if your @code{nnml} mail is located under your home directory, it makes no
5156 sense to cache it somewhere else under your home directory. Unless you
5157 feel that it's neat to use twice as much space. To limit the caching,
5158 you could set the @code{gnus-uncacheable-groups} regexp to
5159 @samp{"^nnml"}, for instance. This variable is @samp{"^nnvirtual"} by
5160 default, since caching doesn't really work in @code{nnvirtual} groups,
5161 since @code{nnvirtual} assigns random article numbers to its articles.
5164 @node Article Backlog
5165 @section Article Backlog
5167 @cindex article backlog
5169 If you have a slow connection, but the idea of using caching seems
5170 unappealing to you (and it is, really), you can help the situation some
5171 by switching on the @dfn{backlog}. This is where Gnus will buffer
5172 already read articles so that it doesn't have to re-fetch articles
5173 you've already read. This only helps if you are in the habit of
5174 re-selecting articles you've recently read, of course. If you never do
5175 that, turning the backlog on will slow Gnus down a little bit, and
5176 increase memory usage some.
5178 @vindex gnus-keep-backlog
5179 If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store
5180 at most @var{n} old articles in a buffer for later re-fetching. If this
5181 variable is non-@code{nil} and is not a number, Gnus will store
5182 @emph{all} read articles, which means that your Emacs will group without
5183 bound before exploding and taking your machine down with you. I put
5184 that in there just to keep y'all on your toes.
5186 This variable is @code{nil} by default.
5189 @node Exiting the Summary Buffer
5190 @section Exiting the Summary Buffer
5191 @cindex summary exit
5193 Exiting from the summary buffer will normally update all info on the
5194 group and return you to the group buffer.
5199 @kindex Z Z (Summary)
5201 @findex gnus-summary-exit
5202 @vindex gnus-summary-exit-hook
5203 @vindex gnus-summary-prepare-exit-hook
5204 Exit the current group and update all information on the group
5205 (@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
5206 called before doing much of the exiting, and calls
5207 @code{gnus-summary-expire-articles} by default.
5208 @code{gnus-summary-exit-hook} is called after finishing the exiting
5212 @kindex Z E (Summary)
5214 @findex gnus-summary-exit-no-update
5215 Exit the current group without updating any information on the group
5216 (@code{gnus-summary-exit-no-update}).
5219 @kindex Z c (Summary)
5221 @findex gnus-summary-catchup-and-exit
5222 Mark all unticked articles in the group as read and then exit
5223 (@code{gnus-summary-catchup-and-exit}).
5225 @kindex Z C (Summary)
5226 @findex gnus-summary-catchup-all-and-exit
5227 Mark all articles, even the ticked ones, as read and then exit
5228 (@code{gnus-summary-catchup-all-and-exit}).
5230 @kindex Z n (Summary)
5231 @findex gnus-summary-catchup-and-goto-next-group
5232 Mark all articles as read and go to the next group
5233 (@code{gnus-summary-catchup-and-goto-next-group}).
5235 @kindex Z R (Summary)
5236 @findex gnus-summary-reselect-current-group
5237 Exit this group, and then enter it again
5238 (@code{gnus-summary-reselect-current-group}). If given a prefix, select
5239 all articles, both read and unread.
5242 @kindex Z G (Summary)
5243 @kindex M-g (Summary)
5244 @findex gnus-summary-rescan-group
5245 Exit the group, check for new articles in the group, and select the
5246 group (@code{gnus-summary-rescan-group}). If given a prefix, select all
5247 articles, both read and unread.
5249 @kindex Z N (Summary)
5250 @findex gnus-summary-next-group
5251 Exit the group and go to the next group
5252 (@code{gnus-summary-next-group}).
5254 @kindex Z P (Summary)
5255 @findex gnus-summary-prev-group
5256 Exit the group and go to the previous group
5257 (@code{gnus-summary-prev-group}).
5260 @vindex gnus-exit-group-hook
5261 @code{gnus-exit-group-hook} is called when you exit the current
5264 @vindex gnus-use-cross-reference
5265 The data on the current group will be updated (which articles you have
5266 read, which articles you have replied to, etc.) when you exit the
5267 summary buffer. If the @code{gnus-use-cross-reference} variable is
5268 @code{t}, articles that are cross-referenced to this group and are
5269 marked as read, will also be marked as read in the other subscribed
5270 groups they were cross-posted to. If this variable is neither
5271 @code{nil} nor @code{t}, the article will be marked as read in both
5272 subscribed and unsubscribed groups.
5274 Marking cross-posted articles as read ensures that you'll never have to
5275 read the same article more than once. Unless, of course, somebody has
5276 posted it to several groups separately. Posting the same article to
5277 several groups (not cross-posting) is called @dfn{spamming}, and you are
5278 by law required to send nasty-grams to anyone who perpetrates such a
5281 Remember: Cross-posting is kinda ok, but posting the same article
5282 separately to several groups is not.
5284 One thing that may cause Gnus to not do the cross-posting thing
5285 correctly is if you use an @sc{nntp} server that supports @sc{xover}
5286 (which is very nice, because it speeds things up considerably) which
5287 does not include the @code{Xref} header in its @sc{nov} lines. This is
5288 Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
5289 even with @sc{xover} by registering the @code{Xref} lines of all
5290 articles you actually read, but if you kill the articles, or just mark
5291 them as read without reading them, Gnus will not get a chance to snoop
5292 the @code{Xref} lines out of these articles, and will be unable to use
5293 the cross reference mechanism.
5295 @vindex gnus-nov-is-evil
5296 If you want Gnus to get the @code{Xref}s right all the time, you have to
5297 set @code{gnus-nov-is-evil} to @code{t}, which slows things down
5302 @node Process/Prefix
5303 @section Process/Prefix
5304 @cindex process/prefix convention
5306 Many functions, among them functions for moving, decoding and saving
5307 articles, use what is known as the @dfn{Process/Prefix convention}.
5309 This is a method for figuring out what articles that the user wants the
5310 command to be performed on.
5314 If the numeric prefix is N, perform the operation on the next N
5315 articles, starting with the current one. If the numeric prefix is
5316 negative, perform the operation on the previous N articles, starting
5317 with the current one.
5319 If there is no numeric prefix, but some articles are marked with the
5320 process mark, perform the operation on the articles that are marked with
5323 If there is neither a numeric prefix nor any articles marked with the
5324 process mark, just perform the operation on the current article.
5326 Quite simple, really, but it needs to be made clear so that surprises
5329 @node Saving Articles
5330 @section Saving Articles
5331 @cindex saving articles
5333 Gnus can save articles in a number of ways. Below is the documentation
5334 for saving articles in a fairly straight-forward fashion (i.e., little
5335 processing of the article is done before it is saved). For a different
5336 approach (uudecoding, unsharing) you should use @code{gnus-uu}
5337 (@pxref{Decoding Articles}).
5339 @vindex gnus-save-all-headers
5340 If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
5341 unwanted headers before saving the article.
5343 @vindex gnus-saved-headers
5344 If the preceeding variable is @code{nil}, all headers that match the
5345 @code{gnus-saved-headers} regexp will be kept, while the rest will be
5346 deleted before saving.
5352 @kindex O o (Summary)
5354 @findex gnus-summary-save-article
5355 Save the current article using the default article saver
5356 (@code{gnus-summary-save-article}).
5359 @kindex O m (Summary)
5360 @findex gnus-summary-save-article-mail
5361 Save the current article in mail format
5362 (@code{gnus-summary-save-article-mail}).
5365 @kindex O r (Summary)
5366 @findex gnus-summary-save-article-mail
5367 Save the current article in rmail format
5368 (@code{gnus-summary-save-article-rmail}).
5371 @kindex O f (Summary)
5372 @findex gnus-summary-save-article-file
5373 Save the current article in plain file format
5374 (@code{gnus-summary-save-article-file}).
5377 @kindex O b (Summary)
5378 @findex gnus-summary-save-article-body-file
5379 Save the current article body in plain file format
5380 (@code{gnus-summary-save-article-body-file}).
5383 @kindex O h (Summary)
5384 @findex gnus-summary-save-article-folder
5385 Save the current article in mh folder format
5386 (@code{gnus-summary-save-article-folder}).
5389 @kindex O p (Summary)
5390 @findex gnus-summary-pipe-output
5391 Save the current article in a pipe. Uhm, like, what I mean is---Pipe
5392 the current article to a process (@code{gnus-summary-pipe-output}).
5395 @vindex gnus-prompt-before-saving
5396 All these commands use the process/prefix convention
5397 (@pxref{Process/Prefix}). If you save bunches of articles using these
5398 functions, you might get tired of being prompted for files to save each
5399 and every article in. The prompting action is controlled by
5400 the @code{gnus-prompt-before-saving} variable, which is @code{always} by
5401 default, giving you that excessive prompting action you know and
5402 loathe. If you set this variable to @code{t} instead, you'll be promted
5403 just once for each series of articles you save. If you like to really
5404 have Gnus do all your thinking for you, you can even set this variable
5405 to @code{nil}, which means that you will never be prompted for files to
5406 save articles in. Gnus will simply save all the articles in the default
5410 @vindex gnus-default-article-saver
5411 You can customize the @code{gnus-default-article-saver} variable to make
5412 Gnus do what you want it to. You can use any of the four ready-made
5413 functions below, or you can create your own.
5417 @item gnus-summary-save-in-rmail
5418 @findex gnus-summary-save-in-rmail
5419 This is the default format, @dfn{babyl}. Uses the function in the
5420 @code{gnus-rmail-save-name} variable to get a file name to save the
5421 article in. The default is @code{gnus-plain-save-name}.
5423 @item gnus-summary-save-in-mail
5424 @findex gnus-summary-save-in-mail
5425 Save in a Unix mail (mbox) file. Uses the function in the
5426 @code{gnus-mail-save-name} variable to get a file name to save the
5427 article in. The default is @code{gnus-plain-save-name}.
5429 @item gnus-summary-save-in-file
5430 @findex gnus-summary-save-in-file
5431 Append the article straight to an ordinary file. Uses the function in
5432 the @code{gnus-file-save-name} variable to get a file name to save the
5433 article in. The default is @code{gnus-numeric-save-name}.
5435 @item gnus-summary-save-body-in-file
5436 @findex gnus-summary-save-body-in-file
5437 Append the article body to an ordinary file. Uses the function in the
5438 @code{gnus-file-save-name} variable to get a file name to save the
5439 article in. The default is @code{gnus-numeric-save-name}.
5441 @item gnus-summary-save-in-folder
5442 @findex gnus-summary-save-in-folder
5443 Save the article to an MH folder using @code{rcvstore} from the MH
5446 @item gnus-summary-save-in-vm
5447 @findex gnus-summary-save-in-vm
5448 Save the article in a VM folder. You have to have the VM mail
5449 reader to use this setting.
5452 All of these functions, except for the last one, will save the article
5453 in the @code{gnus-article-save-directory}, which is initialized from the
5454 @samp{SAVEDIR} environment variable.
5456 As you can see above, the functions use different functions to find a
5457 suitable name of a file to save the article in. Below is a list of
5458 available functions that generate names:
5461 @item gnus-Numeric-save-name
5462 @findex gnus-Numeric-save-name
5463 Generates file names that look like @samp{~/News/Alt.andrea-dworkin/45}.
5464 @item gnus-numeric-save-name
5465 @findex gnus-numeric-save-name
5466 Generates file names that look like @samp{~/News/alt.andrea-dworkin/45}.
5467 @item gnus-Plain-save-name
5468 @findex gnus-Plain-save-name
5469 Generates file names that look like @samp{~/News/Alt.andrea-dworkin}.
5470 @item gnus-plain-save-name
5471 @findex gnus-plain-save-name
5472 Generates file names that look like @samp{~/News/alt.andrea-dworkin}.
5475 @vindex gnus-use-long-file-name
5476 Finally, you have the @code{gnus-use-long-file-name} variable. If it is
5477 @code{nil}, all the preceding functions will replace all periods
5478 (@samp{.}) in the group names with slashes (@samp{/})---which means that
5479 the functions will generate hierarchies of directories instead of having
5480 all the files in the toplevel directory
5481 (@samp{~/News/alt/andrea-dworkin} instead of
5482 @samp{~/News/alt.andrea-dworkin}.)
5484 This function also affects kill and score file names. If this variable
5485 is a list, and the list contains the element @code{not-score}, long file
5486 names will not be used for score files, if it contains the element
5487 @code{not-save}, long file names will not be used for saving, and if it
5488 contains the element @code{not-kill}, long file names will not be used
5491 If you'd like to save articles in a hierarchy that looks something like
5495 (setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
5496 (setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
5499 Then just save with @kbd{o}. You'd then read this hierarchy with
5500 ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
5501 the toplevel directory as the argument (@file{~/News/}). Then just walk
5502 around to the groups/directories with @code{nneething}.
5505 @node Decoding Articles
5506 @section Decoding Articles
5507 @cindex decoding articles
5509 Sometime users post articles (or series of articles) that have been
5510 encoded in some way or other. Gnus can decode them for you.
5513 * Uuencoded Articles:: Uudecode articles.
5514 * Shared Articles:: Unshar articles.
5515 * PostScript Files:: Split PostScript.
5516 * Decoding Variables:: Variables for a happy decoding.
5517 * Viewing Files:: You want to look at the result of the decoding?
5520 All these functions use the process/prefix convention
5521 (@pxref{Process/Prefix}) for finding out what articles to work on, with
5522 the extension that a "single article" means "a single series". Gnus can
5523 find out by itself what articles belong to a series, decode all the
5524 articles and unpack/view/save the resulting file(s).
5526 Gnus guesses what articles are in the series according to the following
5527 simplish rule: The subjects must be (nearly) identical, except for the
5528 last two numbers of the line. (Spaces are largely ignored, however.)
5530 For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus
5531 will find all the articles that match the regexp @samp{^cat.gif
5532 ([0-9]+/[0-9]+).*$}.
5534 Subjects that are nonstandard, like @samp{cat.gif (2/3) Part 6 of a
5535 series}, will not be properly recognized by any of the automatic viewing
5536 commands, and you have to mark the articles manually with @key{#}.
5538 @node Uuencoded Articles
5539 @subsection Uuencoded Articles
5541 @cindex uuencoded articles
5545 @kindex X u (Summary)
5546 @findex gnus-uu-decode-uu
5547 Uudecodes the current series (@code{gnus-uu-decode-uu}).
5549 @kindex X U (Summary)
5550 @findex gnus-uu-decode-uu-and-save
5551 Uudecodes and saves the current series
5552 (@code{gnus-uu-decode-uu-and-save}).
5554 @kindex X v u (Summary)
5555 @findex gnus-uu-decode-uu-view
5556 Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
5558 @kindex X v U (Summary)
5559 @findex gnus-uu-decode-uu-and-save-view
5560 Uudecodes, views and saves the current series
5561 (@code{gnus-uu-decode-uu-and-save-view}).
5564 Remember that these all react to the presence of articles marked with
5565 the process mark. If, for instance, you'd like to uncode and save an
5566 entire newsgroup, you'd typically do @kbd{M P a}
5567 (@code{gnus-uu-mark-all}) and then @kbd{X U}
5568 (@code{gnus-uu-decode-uu-and-save}).
5570 All this is very much different from how @code{gnus-uu} worked with
5571 @sc{gnus 4.1}, where you had explicit keystrokes for everything under
5572 the sun. This version of @code{gnus-uu} generally assumes that you mark
5573 articles in some way (@pxref{Setting Process Marks}) and then press
5576 Note: When trying to decode articles that have names matching
5577 @code{gnus-uu-notify-files}, which is hard-coded to
5578 @samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
5579 automatically post an article on @samp{comp.unix.wizards} saying that
5580 you have just viewed the file in question. This feature can't be turned
5583 @node Shared Articles
5584 @subsection Shared Articles
5586 @cindex shared articles
5590 @kindex X s (Summary)
5591 @findex gnus-uu-decode-unshar
5592 Unshars the current series (@code{gnus-uu-decode-unshar}).
5594 @kindex X S (Summary)
5595 @findex gnus-uu-decode-unshar-and-save
5596 Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
5598 @kindex X v s (Summary)
5599 @findex gnus-uu-decode-unshar-view
5600 Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
5602 @kindex X v S (Summary)
5603 @findex gnus-uu-decode-unshar-and-save-view
5604 Unshars, views and saves the current series
5605 (@code{gnus-uu-decode-unshar-and-save-view}).
5608 @node PostScript Files
5609 @subsection PostScript Files
5614 @kindex X p (Summary)
5615 @findex gnus-uu-decode-postscript
5616 Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
5618 @kindex X P (Summary)
5619 @findex gnus-uu-decode-postscript-and-save
5620 Unpack and save the current PostScript series
5621 (@code{gnus-uu-decode-postscript-and-save}).
5623 @kindex X v p (Summary)
5624 @findex gnus-uu-decode-postscript-view
5625 View the current PostScript series
5626 (@code{gnus-uu-decode-postscript-view}).
5628 @kindex X v P (Summary)
5629 @findex gnus-uu-decode-postscript-and-save-view
5630 View and save the current PostScript series
5631 (@code{gnus-uu-decode-postscript-and-save-view}).
5634 @node Decoding Variables
5635 @subsection Decoding Variables
5637 Adjective, not verb.
5640 * Rule Variables:: Variables that say how a file is to be viewed.
5641 * Other Decode Variables:: Other decode variables.
5642 * Uuencoding & Posting:: Variables for customizing uuencoding.
5645 @node Rule Variables
5646 @subsubsection Rule Variables
5647 @cindex rule variables
5649 Gnus uses @dfn{rule variables} to decide how to view a file. All these
5650 variables are on the form
5653 (list '(regexp1 command2)
5659 @item gnus-uu-user-view-rules
5660 @vindex gnus-uu-user-view-rules
5661 This variable is consulted first when viewing files. If you wish to use,
5662 for instance, @code{sox} to convert an @samp{.au} sound file, you could
5665 (setq gnus-uu-user-view-rules
5666 (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
5668 @item gnus-uu-user-view-rules-end
5669 @vindex gnus-uu-user-view-rules-end
5670 This variable is consulted if Gnus couldn't make any matches from the
5671 user and default view rules.
5672 @item gnus-uu-user-archive-rules
5673 @vindex gnus-uu-user-archive-rules
5674 This variable can be used to say what commands should be used to unpack
5678 @node Other Decode Variables
5679 @subsubsection Other Decode Variables
5682 @item gnus-uu-ignore-files-by-name
5683 @vindex gnus-uu-ignore-files-by-name
5684 Files with name matching this regular expression won't be viewed.
5686 @item gnus-uu-ignore-files-by-type
5687 @vindex gnus-uu-ignore-files-by-type
5688 Files with a @sc{mime} type matching this variable won't be viewed.
5689 Note that Gnus tries to guess what type the file is based on the name.
5690 @code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
5693 @item gnus-uu-tmp-dir
5694 @vindex gnus-uu-tmp-dir
5695 Where @code{gnus-uu} does its work.
5697 @item gnus-uu-do-not-unpack-archives
5698 @vindex gnus-uu-do-not-unpack-archives
5699 Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
5700 looking for files to display.
5702 @item gnus-uu-view-and-save
5703 @vindex gnus-uu-view-and-save
5704 Non-@code{nil} means that the user will always be asked to save a file
5707 @item gnus-uu-ignore-default-view-rules
5708 @vindex gnus-uu-ignore-default-view-rules
5709 Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
5712 @item gnus-uu-ignore-default-archive-rules
5713 @vindex gnus-uu-ignore-default-archive-rules
5714 Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
5717 @item gnus-uu-kill-carriage-return
5718 @vindex gnus-uu-kill-carriage-return
5719 Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
5722 @item gnus-uu-unmark-articles-not-decoded
5723 @vindex gnus-uu-unmark-articles-not-decoded
5724 Non-@code{nil} means that @code{gnus-uu} will mark articles that were
5725 unsuccessfully decoded as unread.
5727 @item gnus-uu-correct-stripped-uucode
5728 @vindex gnus-uu-correct-stripped-uucode
5729 Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
5730 uuencoded files that have had trailing spaces deleted.
5732 @item gnus-uu-view-with-metamail
5733 @vindex gnus-uu-view-with-metamail
5734 Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
5735 commands defined by the rule variables and just fudge a @sc{mime}
5736 content type based on the file name. The result will be fed to
5737 @code{metamail} for viewing.
5739 @item gnus-uu-save-in-digest
5740 @vindex gnus-uu-save-in-digest
5741 Non-@code{nil} means that @code{gnus-uu}, when asked to save without
5742 decoding, will save in digests. If this variable is @code{nil},
5743 @code{gnus-uu} will just save everything in a file without any
5744 embellishments. The digesting almost conforms to RFC1153---no easy way
5745 to specify any meaningful volume and issue numbers were found, so I
5746 simply dropped them.
5750 @node Uuencoding & Posting
5751 @subsubsection Uuencoding & Posting
5755 @item gnus-uu-post-include-before-composing
5756 @vindex gnus-uu-post-include-before-composing
5757 Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
5758 before you compose the article. If this variable is @code{t}, you can
5759 either include an encoded file with @key{C-c C-i} or have one included
5760 for you when you post the article.
5762 @item gnus-uu-post-length
5763 @vindex gnus-uu-post-length
5764 Maximum length of an article. The encoded file will be split into how
5765 many articles it takes to post the entire file.
5767 @item gnus-uu-post-threaded
5768 @vindex gnus-uu-post-threaded
5769 Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
5770 thread. This may not be smart, as no other decoder I have seen are able
5771 to follow threads when collecting uuencoded articles. (Well, I have
5772 seen one package that does that---@code{gnus-uu}, but somehow, I don't
5773 think that counts...) Default is @code{nil}.
5775 @item gnus-uu-post-separate-description
5776 @vindex gnus-uu-post-separate-description
5777 Non-@code{nil} means that the description will be posted in a separate
5778 article. The first article will typically be numbered (0/x). If this
5779 variable is @code{nil}, the description the user enters will be included
5780 at the beginning of the first article, which will be numbered (1/x).
5781 Default is @code{t}.
5786 @subsection Viewing Files
5787 @cindex viewing files
5788 @cindex pseudo-articles
5790 After decoding, if the file is some sort of archive, Gnus will attempt
5791 to unpack the archive and see if any of the files in the archive can be
5792 viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
5793 containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
5794 uncompress and detar the main file, and then view the two pictures.
5795 This unpacking process is recursive, so if the archive contains archives
5796 of archives, it'll all be unpacked.
5798 Finally, Gnus will normally insert a @dfn{pseudo-article} for each
5799 extracted file into the summary buffer. If you go to these "articles",
5800 you will be prompted for a command to run (usually Gnus will make a
5801 suggestion), and then the command will be run.
5803 @vindex gnus-view-pseudo-asynchronously
5804 If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
5805 until the viewing is done before proceeding.
5807 @vindex gnus-view-pseudos
5808 If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
5809 the pseudo-articles into the summary buffer, but view them
5810 immediately. If this variable is @code{not-confirm}, the user won't even
5811 be asked for a confirmation before viewing is done.
5813 @vindex gnus-view-pseudos-separately
5814 If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
5815 pseudo-article will be created for each file to be viewed. If
5816 @code{nil}, all files that use the same viewing command will be given as
5817 a list of parameters to that command.
5819 So; there you are, reading your @emph{pseudo-articles} in your
5820 @emph{virtual newsgroup} from the @emph{virtual server}; and you think:
5821 Why isn't anything real anymore? How did we get here?
5824 @node Article Treatment
5825 @section Article Treatment
5827 Reading through this huge manual, you may have quite forgotten that the
5828 object of newsreaders are to actually, like, read what people have
5829 written. Reading articles. Unfortunately, people are quite bad at
5830 writing, so there are tons of functions and variables to make reading
5831 these articles easier.
5834 * Article Highlighting:: You want to make the article look like fruit salad.
5835 * Article Hiding:: You also want to make certain info go away.
5836 * Article Washing:: Lots of way-neat functions to make life better.
5837 * Article Buttons:: Clcik on URLs, Message-IDs, addresses and the like.
5838 * Article Date:: Grumble, UT!
5842 @node Article Highlighting
5843 @subsection Article Highlighting
5846 Not only do you want your article buffer to look like fruit salad, but
5847 you want it to look like technicolor fruit salad.
5853 @findex gnus-article-highlight
5854 Highlight the current article (@code{gnus-article-highlight}).
5858 @findex gnus-article-highlight-headers
5859 @vindex gnus-header-face-alist
5860 Highlight the headers (@code{gnus-article-highlight-headers}). The
5861 highlighting will be done according to the @code{gnus-header-face-alist}
5862 variable, which is a list where each element has the form @var{(regexp
5863 name content)}. @var{regexp} is a regular expression for matching the
5864 header, @var{name} is the face used for highling the header name and
5865 @var{content} is the face for highlighting the header value. The first
5866 match made will be used.
5870 @findex gnus-article-highlight-citation
5871 Highlight cited text (@code{gnus-article-highlight-citation}).
5873 Some variables to customize the citation highlights:
5876 @vindex gnus-cite-parse-max-size
5877 @item gnus-cite-parse-max-size
5878 If the article size if bigger than this variable (which is 25000 by
5879 default), no citation highlighting will be performed.
5881 @item gnus-cite-prefix-regexp
5882 @vindex gnus-cite-prefix-regexp
5883 Regexp mathcing the longest possible citation prefix on a line.
5885 @item gnus-cite-max-prefix
5886 @vindex gnus-cite-max-prefix
5887 Maximum possible length for a citation prefix (default 20).
5889 @item gnus-supercite-regexp
5890 @vindex gnus-supercite-regexp
5891 Regexp matching normal SuperCite attribution lines.
5893 @item gnus-supercite-secondary-regexp
5894 @vindex gnus-supercite-secondary-regexp
5895 Regexp matching mangled SuperCite attribution lines.
5897 @item gnus-cite-minimum-match-count
5898 @vindex gnus-cite-minimum-match-count
5899 Minimum number of identical prefixes we have to see before we believe
5900 that it's a citation.
5902 @item gnus-cite-attribution-prefix
5903 @vindex gnus-cite-attribution-prefix
5904 Regexp matching the beginning of an attribution line.
5906 @item gnus-cite-addtribution-suffix
5907 @vindex gnus-cite-addtribution-suffix
5908 Regexp matching the end of an attribution line.
5910 @item gnus-cite-attribution-face
5911 @vindex gnus-cite-attribution-face
5912 Face used for attribution lines. It is merged with the face for the
5913 cited text belonging to the attribution.
5920 @vindex gnus-signature-separator
5921 @findex gnus-article-highlight-signature
5922 Highlight the signature (@code{gnus-article-highlight-signature}).
5923 Everything after @code{gnus-signature-separator} in an article will be
5924 considered a signature.
5929 @node Article Hiding
5930 @subsection Article Hiding
5931 @cindex article hiding
5933 Or rather, hiding certain things in each article. There usually is much
5934 to much gruft in most articles.
5939 @kindex W W a (Summary)
5940 @findex gnus-article-hide
5941 Do maximum hiding on the summary buffer (@kbd{gnus-article-hide}).
5944 @kindex W W h (Summary)
5945 @findex gnus-article-hide-headers
5946 Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
5950 @kindex W W s (Summary)
5951 @findex gnus-article-hide-signature
5952 Hide signature (@code{gnus-article-hide-signature}).
5955 @kindex W W p (Summary)
5956 @findex gnus-article-hide-pgp
5957 Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}).
5960 @kindex W W c (Summary)
5961 @findex gnus-article-hide-citation
5962 Hide citation (@code{gnus-article-hide-citation}). Two variables for
5963 customizing the hiding:
5967 @item gnus-cite-hide-percentage
5968 @vindex gnus-cite-hide-percentage
5969 If the cited text is of a bigger percentage than this variable (default
5970 50), hide the cited text.
5972 @item gnus-cite-hide-absolute
5973 @vindex gnus-cite-hide-absolute
5974 The cited text must be have at least this length (default 10) before it
5979 Also see @xref{Article Highlighting} for further variables for
5980 citation customization.
5985 @node Article Washing
5986 @subsection Article Washing
5988 @cindex article washing
5990 We call this "article washing" for a really good reason. Namely, the
5991 @kbd{A} key was taken, so we had to use the @kbd{W} key instead.
5993 @dfn{Washing} is defined by us as "changing something from something to
5994 something else", but normally results in something looking better.
6000 @kindex W l (Summary)
6001 @findex gnus-summary-stop-page-breaking
6002 Remove page breaks from the current article
6003 (@code{gnus-summary-stop-page-breaking}).
6006 @kindex W r (Summary)
6007 @findex gnus-summary-caesar-message
6008 Do a Caesar rotate (rot13) on the article buffer
6009 (@code{gnus-summary-caesar-message}).
6012 @kindex A g (Summary)
6013 @findex gnus-summary-show-article
6014 (Re)fetch the current article (@code{gnus-summary-show-article}). If
6015 given a prefix, fetch the current article, but don't run any of the
6016 article treatment functions. This will give you a "raw" article, just
6017 the way it came from the server.
6020 @kindex W t (Summary)
6021 @findex gnus-summary-toggle-header
6022 Toggle whether to display all headers in the article buffer
6023 (@code{gnus-summary-toggle-header}).
6026 @kindex W m (Summary)
6027 @findex gnus-summary-toggle-mime
6028 Toggle whether to run the article through @sc{mime} before displaying
6029 (@code{gnus-summary-toggle-mime}).
6032 @kindex W o (Summary)
6033 @findex gnus-article-treat-overstrike
6034 Treat overstrike (@code{gnus-article-treat-overstrike}).
6037 @kindex W w (Summary)
6038 @findex gnus-article-word-wrap
6039 Do word wrap (@code{gnus-article-word-wrap}).
6042 @kindex W c (Summary)
6043 @findex gnus-article-remove-cr
6044 Remove CR (@code{gnus-article-remove-cr}).
6047 @kindex W q (Summary)
6048 @findex gnus-article-de-quoted-unreadable
6049 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
6052 @kindex W f (Summary)
6054 @findex gnus-article-display-x-face
6055 @findex gnus-article-x-face-command
6056 @vindex gnus-article-x-face-command
6057 @vindex gnus-article-x-face-too-ugly
6058 Look for and display any X-Face headers
6059 (@code{gnus-article-display-x-face}). The command executed by this
6060 function is given by the @code{gnus-article-x-face-command} variable. If
6061 this variable is a string, this string will be executed in a sub-shell.
6062 If it is a function, this function will be called with the face as the
6063 argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
6064 matches the @code{From} header, the face will not be shown.
6067 @kindex W b (Summary)
6068 @findex gnus-article-add-buttons
6069 Add clickable buttons to the article (@code{gnus-article-add-buttons}).
6072 @kindex W B (Summary)
6073 @findex gnus-article-add-buttons-to-head
6074 Add clickable buttons to the article headers
6075 (@code{gnus-article-add-buttons-to-head}).
6080 @node Article Buttons
6081 @subsection Article Buttons
6084 People often include references to other stuff in articles, and it would
6085 be nice if Gnus could just fetch whatever it is that people talk about
6086 with the minimum of fuzz.
6088 Gnus adds @dfn{buttons} to certain standard references by default:
6089 Well-formed URLs, mail addresses and Message-IDs. This is controlled by
6090 two variables, one that handles article bodies and one that handles
6095 @item gnus-button-alist
6096 @vindex gnus-header-button-alist
6097 This is an alist where each entry has this form:
6100 (REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
6106 All text that match this regular expression will be considered an
6107 external reference. Here's a typical regexp that match embedded URLs:
6108 @samp{"<URL:\\([^\n\r>]*\\)>"}.
6111 Gnus has to know which parts of the match is to be highlighted. This is
6112 a number that says what sub-expression of the regexp that is to be
6113 highlighted. If you want it all highlighted, you use @samp{0} here.
6116 This form will be @code{eval}ed, and if the result is non-@code{nil},
6117 this is considered a match. This is useful if you want extra sifting to
6118 avoid false matches.
6121 This function will be called when you click on this button.
6124 As with @var{button-par}, this is a sub-expression number, but this one
6125 says which part of the match is to be sent as data to @var{function}.
6129 So the full entry for buttonizing URLs is then
6132 ("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
6135 @item gnus-header-button-alist
6136 @vindex gnus-header-button-alist
6137 This is just like the other alist, except that it is applied to the
6138 article head only, and that each entry has an additional element that is
6139 used to say what headers to apply the buttonize coding to:
6142 (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
6145 @var{header} is a regular expression.
6149 @vindex gnus-article-button-face
6150 @vindex gnus-article-mouse-face
6151 Buttons are highlighted with @code{gnus-article-button-face}, while
6152 @code{gnus-article-mouse-face} is used when the mouse cursor is over the
6157 @subsection Article Date
6159 The date is most likely generated in some obscure timezone you've never
6160 heard of, so it's quite nice to be able to find out what the time was
6161 when the article was sent.
6166 @kindex W T u (Summary)
6167 @findex gnus-article-date-ut
6168 Display the date in UT (aka. GMT, aka ZULU)
6169 (@code{gnus-article-date-ut}).
6172 @kindex W T l (Summary)
6173 @findex gnus-article-date-local
6174 Display the date in the local timezone (@code{gnus-article-date-local}).
6177 @kindex W T e (Summary)
6178 @findex gnus-article-date-lapsed
6179 Say how much time has (e)lapsed between the article was posted and now
6180 (@code{gnus-article-date-lapsed}).
6183 @kindex W T o (Summary)
6184 @findex gnus-article-date-original
6185 Display the original date (@code{gnus-article-date-original}). This can
6186 be useful if you normally use some other conversion function and is
6187 worried that it might be doing something totally wrong. Say, claiming
6188 that the article was posted in 1854. Although something like that is
6189 @emph{totally} impossible. Don't you trust me? *titter*
6194 @node Summary Sorting
6195 @section Summary Sorting
6196 @cindex summary sorting
6198 You can have the summary buffer sorted in various ways, even though I
6199 can't really see why you'd want that.
6203 @kindex C-c C-s C-n (Summary)
6204 @findex gnus-summary-sort-by-number
6205 Sort by article number (@code{gnus-summary-sort-by-number}).
6207 @kindex C-c C-s C-a (Summary)
6208 @findex gnus-summary-sort-by-author
6209 Sort by author (@code{gnus-summary-sort-by-author}).
6211 @kindex C-c C-s C-s (Summary)
6212 @findex gnus-summary-sort-by-subject
6213 Sort by subject (@code{gnus-summary-sort-by-subject}).
6215 @kindex C-c C-s C-d (Summary)
6216 @findex gnus-summary-sort-by-date
6217 Sort by date (@code{gnus-summary-sort-by-date}).
6219 @kindex C-c C-s C-i (Summary)
6220 @findex gnus-summary-sort-by-score
6221 Sort by score (@code{gnus-summary-sort-by-score}).
6224 These functions will work both when you use threading and when you don't
6225 use threading. In the latter case, all summary lines will be sorted,
6226 line by line. In the former case, sorting will be done on a
6227 root-by-root basis, which might not be what you were looking for. To
6228 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
6232 @node Finding the Parent
6233 @section Finding the Parent
6234 @cindex parent articles
6235 @cindex referring articles
6237 @findex gnus-summary-refer-parent-article
6239 If you'd like to read the parent of the current article, and it is not
6240 displayed in the article buffer, you might still be able to. That is,
6241 if the current group is fetched by @sc{nntp}, the parent hasn't expired
6242 and the @code{References} in the current article are not mangled, you
6243 can just press @kbd{^} or @kbd{A r}
6244 (@code{gnus-summary-refer-parent-article}). If everything goes well,
6245 you'll get the parent. If the parent is already displayed in the
6246 summary buffer, point will just move to this article.
6248 @findex gnus-summary-refer-references
6249 @kindex A R (Summary)
6250 You can have Gnus fetch all articles mentioned in the @code{References}
6251 header of the article by pushing @kbd{A R}
6252 (@code{gnus-summary-refer-references}).
6254 @findex gnus-summary-refer-article
6255 @kindex M-^ (Summary)
6256 You can also ask the @sc{nntp} server for an arbitrary article, no
6257 matter what group it belongs to. @kbd{M-^}
6258 (@code{gnus-summary-refer-article}) will ask you for a
6259 @code{Message-Id}, which is one of those long thingies that look
6260 something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
6261 it all exactly right. No fuzzy searches, I'm afraid.
6263 @vindex gnus-refer-article-method
6264 If the group you are reading is located on a backend that does not
6265 support fetching by @code{Message-Id} very well (like @code{nnspool}),
6266 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
6267 would, perhaps, be best if the @sc{nntp} server you consult is the same
6268 as the one that keeps the spool you are reading from updated, but that's
6269 not really necessary.
6271 Most of the mail backends support fetching by @code{Message-ID}, but do
6272 not do a particularly excellent job of it. That is, @code{nnmbox} and
6273 @code{nnbabyl} are able to locate articles from any groups, while
6274 @code{nnml} and @code{nnfolder} are only able to locate articles that
6275 have been posted to the current group. (Anything else would be too time
6276 consuming.) @code{nnmh} does not support this at all.
6279 @node Mail Group Commands
6280 @section Mail Group Commands
6281 @cindex mail group commands
6283 Some commands only make sense in mail groups. If these commands are
6284 illegal in the current group, they will raise a hell and let you know.
6286 All these commands (except the expiry and edit commands) use the
6287 process/prefix convention (@pxref{Process/Prefix}).
6291 @kindex B e (Summary)
6292 @findex gnus-summary-expire-articles
6293 Expire all expirable articles in the group
6294 (@code{gnus-summary-expire-articles}).
6297 @kindex B M-C-e (Summary)
6298 @findex gnus-summary-expire-articles-now
6299 Expunge all the expirable articles in the group
6300 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
6301 articles that are eligeble for expiry in the current group will
6302 disappear forever into that big @file{/dev/null} in the sky.
6305 @kindex B DEL (Summary)
6306 @findex gnus-summary-delete-articles
6307 Delete the mail article. This is "delete" as in "delete it from your
6308 disk forever and ever, never to return again." Use with caution.
6309 (@code{gnus-summary-delete-article}).
6312 @kindex B m (Summary)
6314 @findex gnus-summary-move-article
6315 Move the article from one mail group to another
6316 (@code{gnus-summary-move-article}).
6319 @kindex B c (Summary)
6321 @findex gnus-summary-copy-article
6322 Copy the article from one group (mail group or not) to a mail group
6323 (@code{gnus-summary-copy-article}).
6326 @kindex B i (Summary)
6327 @findex gnus-summary-import-article
6328 Import a random file into the current mail newsgroup
6329 (@code{gnus-summary-import-article}). You will be prompted for a file
6330 name, a @code{From} header and a @code{Subject} header.
6332 Something similar can be done by just starting to compose a mail
6333 message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
6334 @kbd{C-c C-p} instead. This will put the message you have just created
6335 into the current mail group.
6338 @kindex B r (Summary)
6339 @findex gnus-summary-respool-article
6340 Respool the mail article (@code{gnus-summary-move-article}).
6344 @kindex B w (Summary)
6346 @findex gnus-summary-edit-article
6347 @kindex C-c C-c (Article)
6348 Edit the current article (@code{gnus-summary-edit-article}). To finish
6349 editing and make the changes permanent, type @kbd{C-c C-c}
6350 (@kbd{gnus-summary-edit-article-done}).
6353 @kindex B q (Summary)
6354 @findex gnus-summary-respool-query
6355 If you want to respool an article, you might be curious as to what group
6356 the article will end up in before you do the respooling. This command
6357 will tell you (@code{gnus-summary-fancy-query}).
6360 @node Various Summary Stuff
6361 @section Various Summary Stuff
6364 * Group Information:: Information oriented commands.
6365 * Searching for Articles:: Multiple article commands.
6366 * Really Various Summary Commands:: Those pesky non-conformant commands.
6369 @vindex gnus-summary-prepare-hook
6370 @code{gnus-summary-prepare-hook} is called after the summary buffer has
6371 been generated. You might use it to, for instance, highlight lines or
6372 modify the look of the buffer in some other ungodly manner. I don't
6375 @node Group Information
6376 @subsection Group Information
6380 @kindex H f (Summary)
6381 @findex gnus-summary-fetch-faq
6382 @vindex gnus-group-faq-directory
6383 Try to fetch the FAQ (list of frequently asked questions) for the
6384 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
6385 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
6386 on a remote machine. This variable can also be a list of directories.
6387 In that case, giving a prefix to this command will allow you to choose
6388 between the various sites. @code{ange-ftp} probably will be used for
6391 @kindex H d (Summary)
6392 @findex gnus-summary-describe-group
6393 Give a brief description of the current group
6394 (@code{gnus-summary-describe-group}). If given a prefix, force
6395 rereading the description from the server.
6397 @kindex H h (Summary)
6398 @findex gnus-summary-describe-briefly
6399 Give a very brief description of the most important summary keystrokes
6400 (@code{gnus-summary-describe-briefly}).
6402 @kindex H i (Summary)
6403 @findex gnus-info-find-node
6404 Go to the Gnus info node (@code{gnus-info-find-node}).
6407 @node Searching for Articles
6408 @subsection Searching for Articles
6412 @kindex M-s (Summary)
6413 @findex gnus-summary-search-article-forward
6414 Search through all subsequent articles for a regexp
6415 (@code{gnus-summary-search-article-forward}).
6417 @kindex M-r (Summary)
6418 @findex gnus-summary-search-article-backward
6419 Search through all previous articles for a regexp
6420 (@code{gnus-summary-search-article-backward}).
6423 @findex gnus-summary-execute-command
6424 This command will prompt you for a header field, a regular expression to
6425 match on this field, and a command to be executed if the match is made
6426 (@code{gnus-summary-execute-command}).
6428 @kindex M-& (Summary)
6429 @findex gnus-summary-universal-argument
6430 Perform any operation on all articles that have been marked with
6431 the process mark (@code{gnus-summary-universal-argument}).
6434 @node Really Various Summary Commands
6435 @subsection Really Various Summary Commands
6439 @kindex A D (Summary)
6440 @findex gnus-summary-enter-digest-group
6441 If the current article is a digest, you might use this command to enter
6442 you into a group based on the current digest to ease reading
6443 (@code{gnus-summary-enter-digest-group}).
6445 @kindex C-t (Summary)
6446 @findex gnus-summary-toggle-truncation
6447 Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
6450 @findex gnus-summary-expand-window
6451 Expand the summary buffer window (@code{gnus-summary-expand-window}).
6452 If given a prefix, force an @code{article} window configuration.
6455 @node The Article Buffer
6456 @chapter The Article Buffer
6457 @cindex article buffer
6459 The articles are displayed in the article buffer, of which there is only
6460 one. All the summary buffer share the same article buffer.
6463 * Hiding Headers:: Deciding what headers should be displayed.
6464 * Using Mime:: Pushing articles through @sc{mime} before reading them.
6465 * Customizing Articles:: Tailoring the look of the articles.
6466 * Article Keymap:: Keystrokes available in the article buffer
6467 * Misc Article:: Other stuff.
6470 @node Hiding Headers
6471 @section Hiding Headers
6472 @cindex hiding headers
6473 @cindex deleting headers
6475 The top section of each article is the @dfn{head}. (The rest is the
6476 @dfn{body}, but you may have guessed that already.)
6478 @vindex gnus-show-all-headers
6479 There is a lot of useful information in the head: the name of the person
6480 who wrote the article, the date it was written and the subject of the
6481 article. That's well and nice, but there's also lots of information
6482 most people do not want to see---what systems the article has passed
6483 through before reaching you, the @code{Message-Id}, the
6484 @code{References}, etc. ad nauseum---and you'll probably want to get rid
6485 of some of those lines. If you want to keep all those lines in the
6486 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
6488 Gnus provides you with two variables for sifting headers:
6491 @item gnus-visible-headers
6492 @vindex gnus-visible-headers
6493 If this variable is non-@code{nil}, it should be a regular expression
6494 that says what headers you wish to keep in the article buffer. All
6495 headers that do not match this variable will be hidden.
6497 For instance, if you only want to see the name of the person who wrote
6498 the article and the subject, you'd say:
6501 (setq gnus-visible-headers "^From:\\|^Subject:")
6504 @item gnus-ignored-headers
6505 @vindex gnus-ignored-headers
6506 This variable is the reverse of @code{gnus-visible-headers}. If this
6507 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
6508 should be a regular expression that matches all lines that you want to
6509 hide. All lines that do not match this variable will remain visible.
6511 For instance, if you just want to get rid of the @code{References} line
6512 and the @code{Xref} line, you might say:
6515 (setq gnus-ignored-headers "^References:\\|^Xref:")
6518 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
6519 variable will have no effect.
6522 @vindex gnus-sorted-header-list
6523 Gnus can also sort the headers for you. (It does this by default.) You
6524 can control the sorting by setting the @code{gnus-sorted-header-list}
6525 variable. It is a list of regular expressions that says in what order
6526 the headers are to be displayed.
6528 For instance, if you want the name of the author of the article first,
6529 and then the subject, you might say something like:
6532 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
6535 Any headers that are to remain visible, but are not listed in this
6536 variable, will be displayed in random order after all the headers that
6537 are listed in this variable.
6543 Mime is a standard for waving your hands through the air, aimlessly,
6544 while people stand around yawning.
6546 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
6547 while all newsreaders die of fear.
6549 @sc{mime} may specify what character set the article uses, the encoding
6550 of the characters, and it also makes it possible to embed pictures and
6551 other naughty stuff in innocent-looking articles.
6553 @vindex gnus-show-mime
6554 @vindex gnus-show-mime-method
6555 Gnus handles @sc{mime} by shoving the articles through
6556 @code{gnus-show-mime-method}, which is @code{metamail-buffer} by
6557 default. If @code{gnus-strict-mime} is non-@code{nil}, the @sc{mime}
6558 method will only be used it there are @sc{mime} headers in the article.
6559 Set @code{gnus-show-mime} to @code{t} if you want to use @sc{mime} all
6560 the time; it might be best to just use the toggling functions from the
6561 summary buffer to avoid getting nasty surprises. (For instance, you
6562 enter the group @samp{alt.sing-a-long} and, before you know it,
6563 @sc{mime} has decoded the sound file in the article and some horrible
6564 sing-a-long song comes streaming out out your speakers, and you can't
6565 find the volume button, because there isn't one, and people are starting
6566 to look at you, and you try to stop the program, but you can't, and you
6567 can't find the program to control the volume, and everybody else in the
6568 room suddenly decides to look at you disdainfully, and you'll feel
6571 Any similarity to real events and people is purely coincidental. Ahem.
6574 @node Customizing Articles
6575 @section Customizing Articles
6576 @cindex article customization
6578 @vindex gnus-article-display-hook
6579 The @code{gnus-article-display-hook} is called after the article has
6580 been inserted into the article buffer. It is meant to handle all
6581 treatment of the article before it is displayed.
6583 By default it contains @code{gnus-article-hide-headers},
6584 @code{gnus-article-treat-overstrike}, and
6585 @code{gnus-article-maybe-highlight}, but there are thousands, nay
6586 millions, of functions you can put in this hook. For an overview of
6587 functions @xref{Article Highlighting}, @xref{Article Hiding},
6588 @xref{Article Washing}, @xref{Article Buttons} and @xref{Article Date}.
6590 You can, of course, write your own functions. The functions are called
6591 from the article buffer, and you can do anything you like, pretty much.
6592 There is no information that you have to keep in the buffer---you can
6593 change everything. However, you shouldn't delete any headers. Instead
6594 make them invisible if you want to make them go away.
6597 @node Article Keymap
6598 @section Article Keymap
6600 @c Most of the keystrokes in the summary buffer can also be used in the
6601 @c article buffer. They should behave as if you typed them in the summary
6602 @c buffer, which means that you don't actually have to have a summary
6603 @c buffer displayed while reading. You can do it all from the article
6606 A few additional keystrokes are available:
6610 @kindex SPACE (Article)
6611 @findex gnus-article-next-page
6612 Scroll forwards one page (@code{gnus-article-next-page}).
6614 @kindex DEL (Article)
6615 @findex gnus-article-prev-page
6616 Scroll backwards one page (@code{gnus-article-prev-page}).
6618 @kindex C-c ^ (Article)
6619 @findex gnus-article-refer-article
6620 If point is in the neighborhood of a @code{Message-Id} and you press
6621 @kbd{r}, Gnus will try to get that article from the server
6622 (@code{gnus-article-refer-article}).
6624 @kindex C-c C-m (Article)
6625 @findex gnus-article-mail
6626 Send a reply to the address near point (@code{gnus-article-mail}). If
6627 given a prefix, include the mail.
6630 @findex gnus-article-show-summary
6631 Reconfigure the buffers so that the summary buffer becomes visible
6632 (@code{gnus-article-show-summary}).
6635 @findex gnus-article-describe-briefly
6636 Give a very brief description of the available keystrokes
6637 (@code{gnus-article-describe-briefly}).
6641 @section Misc Article
6644 @vindex gnus-article-prepare-hook
6645 @item gnus-article-prepare-hook
6646 This hook is called right after the article has been inserted into the
6647 article buffer. It is mainly intended for functions that do something
6648 depending on the contents; it should probably not be used for changing
6649 the contents of the article buffer.
6650 @vindex gnus-article-display-hook
6651 @item gnus-article-display-hook
6652 This hook is called as the last thing when displaying an article, and is
6653 intended for modifying the contents of the buffer, doing highlights,
6654 hiding headers, and the like.
6655 @vindex gnus-article-mode-line-format
6656 @item gnus-article-mode-line-format
6657 This variable is a format string along the same lines as
6658 @code{gnus-summary-mode-line-format}. It accepts exactly the same
6659 format specifications as that variable.
6660 @vindex gnus-break-pages
6661 @item gnus-break-pages
6662 Controls whether @dfn{page breaking} is to take place. If this variable
6663 is non-@code{nil}, the articles will be divided into pages whenever a
6664 page delimiter appears in the article. If this variable is @code{nil},
6665 paging will not be done.
6666 @item gnus-page-delimiter
6667 @vindex gnus-page-delimiter
6668 This is the delimiter mentioned above. By default, it is @samp{^L}
6672 @node The Server Buffer
6673 @chapter The Server Buffer
6675 Traditionally, a @dfn{server} is a machine or a piece of software that
6676 one connects to, and then requests information from. Gnus does not
6677 connect directly to any real servers, but does all transactions through
6678 one backend or other. But that's just putting one layer more between
6679 the actual media and Gnus, so we might just as well say that each
6680 backend represents a virtual server.
6682 For instance, the @code{nntp} backend may be used to connect to several
6683 different actual @sc{nntp} servers, or, perhaps, to many different ports
6684 on the same actual @sc{nntp} server. You tell Gnus which backend to
6685 use, and what parameters to set by specifying a @dfn{select method}.
6687 These select methods specifications can sometimes become quite
6688 complicated---say, for instance, that you want to read from the
6689 @sc{nntp} server @samp{news.funet.fi} on port number @samp{13}, which
6690 hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
6691 Anyways, if you had to specify that for each group that used this
6692 server, that would be too much work, so Gnus offers a way of putting
6693 names to methods, which is what you do in the server buffer.
6695 To enter the server buffer, user the @kbd{^}
6696 (@code{gnus-group-enter-server-mode}) command in the group buffer.
6699 * Server Buffer Format:: You can customize the look of this buffer.
6700 * Server Commands:: Commands to manipulate servers.
6701 * Example Methods:: Examples server specifications.
6702 * Servers & Methods:: You can use server names as select methods.
6703 * Unavailable Servers:: Some servers you try to contact may be down.
6706 @node Server Buffer Format
6707 @section Server Buffer Format
6708 @cindex server buffer format
6710 @vindex gnus-server-line-format
6711 You can change the look of the server buffer lines by changing the
6712 @code{gnus-server-line-format} variable. This is a @code{format}-like
6713 variable, with some simple extensions:
6717 How the news is fetched---the backend name.
6719 The name of this server.
6721 Where the news is to be fetched from---the address.
6724 @node Server Commands
6725 @section Server Commands
6726 @cindex server commands
6730 Browse the current server (@code{gnus-server-read-server}).
6732 Return to the group buffer (@code{gnus-server-exit}).
6734 List all servers (@code{gnus-server-list-servers}).
6736 Kill the current server (@code{gnus-server-kill-server}).
6738 Yank the previously killed server (@code{gnus-server-yank-server}).
6740 Copy the current server (@code{gnus-server-copy-server}).
6742 Add a new server (@code{gnus-server-add-server}).
6744 Edit a server (@code{gnus-server-edit-server}).
6747 @node Example Methods
6748 @section Example Methods
6750 Most select methods are pretty simple and self-explanatory:
6753 (nntp "news.funet.fi")
6756 Reading directly from the spool is even simpler:
6762 As you can see, the first element in a select method is the name of the
6763 backend, and the second is the @dfn{address}, or @dfn{name}, if you
6766 After these two elements, there may be a random number of @var{(variable
6769 To go back to the first example---imagine that you want to read from
6770 port @code{15} from that machine. This is what the select method should
6774 (nntp "news.funet.fi" (nntp-port-number 15))
6777 You should read the documentation to each backend to find out what
6778 variables are relevant, but here's an @code{nnmh} example.
6780 @code{nnmh} is a mail backend that reads a spool-like structure. Say
6781 you have two structures that you wish to access: One is your private
6782 mail spool, and the other is a public one. Here's the possible spec for
6786 (nnmh "private" (nnmh-directory "~/private/mail/"))
6789 (This server is then called @samp{private}, but you may have guessed
6792 Here's the method for the public spool:
6796 (nnmh-directory "/usr/information/spool/")
6797 (nnmh-get-new-mail nil))
6800 @node Servers & Methods
6801 @section Servers & Methods
6803 Wherever you would normally use a select method
6804 (eg. @code{gnus-secondary-select-method}, in the group select method,
6805 when browsing a foreign server) you can use a virtual server name
6806 instead. This could potentially save lots of typing. And it's nice all
6810 @node Unavailable Servers
6811 @section Unavailable Servers
6813 If a server seems to be unreachable, Gnus will mark that server as
6814 @code{denied}. That means that any subsequent attempt to make contact
6815 with that server will just be ignored. "It can't be opened," Gnus will
6816 tell you, without making the least effort to see whether that is
6817 actually the case or not.
6819 That might seem quite naughty, but it does make sense most of the time.
6820 Let's say you have 10 groups subscribed to the server
6821 @samp{nepholococcygia.com}. This server is located somewhere quite far
6822 away from you, the machine is quite, so it takes 1 minute just to find
6823 out that it refuses connection from you today. If Gnus were to attempt
6824 to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
6825 that. Once it has gotten a single "connection refused", it will regard
6826 that server as "down".
6828 So, what happens if the machine was only feeling unwell temporarily?
6829 How do you test to see whether the machine has come up again?
6831 You jump to the server buffer (@pxref{The Server Buffer}) and poke ut
6832 with the following commands:
6838 @findex gnus-server-open-server
6839 Try to establish connection to the server on the current line
6840 (@code{gnus-server-open-server}).
6844 @findex gnus-server-close-server
6845 Close the connection (if any) to the server
6846 (@code{gnus-server-close-server}).
6850 @findex gnus-server-deny-server
6851 Mark the current server as unreachable
6852 (@code{gnus-server-deny-server}).
6856 @findex gnus-server-remove-denials
6857 Remove all marks to whether Gnus was denied connection from all servers
6858 (@code{gnus-server-remove-denials}).
6870 Other people use @dfn{kill files}, but we here at Gnus Towers like
6871 scoring better than killing, so we'd rather switch than fight. They do
6872 something completely different as well, so sit up straight and pay
6875 @vindex gnus-summary-mark-below
6876 All articles have a default score (@code{gnus-summary-default-score}).
6877 This score may be raised or lowered either interactively or by score
6878 files. Articles that have a score lower than
6879 @code{gnus-summary-mark-below} are marked as read.
6881 Gnus will read any @dfn{score files} that apply to the current group
6882 before generating the summary buffer.
6884 There are several commands in the summary buffer that insert score
6885 entries based on the current article. You can, for instance, ask Gnus to
6886 lower or increase the score of all articles with a certain subject.
6888 There are two sorts of scoring entries: Permanent and temporary.
6889 Temporary score entries are self-expiring entries. Any entries that are
6890 temporary and have not been used for, say, a week, will be removed
6891 silently to help keep the sizes of the score files down.
6894 * Summary Score Commands:: Adding score entries for the current group.
6895 * Group Score Commands:: General score commands.
6896 * Score Variables:: Customize your scoring. (My, what terminology).
6897 * Score File Format:: What a score file may contain.
6898 * Score File Editing:: You can edit score files by hand as well.
6899 * Adaptive Scoring:: Big Sister Gnus *knows* what you read.
6900 * Scoring Tips:: How to score effectively.
6901 * Reverse Scoring:: That problem child of old is not problem.
6902 * Global Score Files:: Earth-spanning, ear-splitting score files.
6903 * Kill Files:: They are still here, but they can be ignored.
6906 @node Summary Score Commands
6907 @section Summary Score Commands
6908 @cindex score commands
6910 The score commands that alter score entries do not actually modify real
6911 score files. That would be too inefficient. Gnus maintains a cache of
6912 previously loaded score files, one of which is considered the
6913 @dfn{current score file alist}. The score commands simply insert
6914 entries into this list, and upon group exit, this list is saved.
6916 The current score file is by default the group's local score file, even
6917 if no such score file actually exists. To insert score commands into
6918 some other score file (eg. @file{all.SCORE}), you must first make this
6919 score file the current one.
6921 General score commands that don't actually change the score file:
6925 @kindex V s (Summary)
6926 @findex gnus-summary-set-score
6927 Set the score of the current article (@code{gnus-summary-set-score}).
6930 @kindex V S (Summary)
6931 @findex gnus-summary-current-score
6932 Display the score of the current article
6933 (@code{gnus-summary-current-score}).
6936 @kindex V t (Summary)
6937 @findex gnus-score-find-trace
6938 Display all score rules that have been used on the current article
6939 (@code{gnus-score-find-trace}).
6942 @kindex V a (Summary)
6943 @findex gnus-summary-score-entry
6944 Add a new score entry, and allow specifying all elements
6945 (@code{gnus-summary-score-entry}).
6948 @kindex V c (Summary)
6949 @findex gnus-score-change-score-file
6950 Make a different score file the current
6951 (@code{gnus-score-change-score-file}).
6954 @kindex V e (Summary)
6955 @findex gnus-score-edit-alist
6956 Edit the current score file (@code{gnus-score-edit-alist}). You will be
6957 popped into a @code{gnus-score-mode} buffer (@pxref{Score File
6961 @kindex V f (Summary)
6962 @findex gnus-score-edit-file
6963 Edit a score file and make this score file the current one
6964 (@code{gnus-score-edit-file}).
6967 @kindex V C (Summary)
6968 @findex gnus-score-customize
6969 Customize a score file in a visually pleasing manner
6970 (@code{gnus-score-customize}).
6973 @kindex I C-i (Summary)
6974 @findex gnus-summary-raise-score
6975 Increase the score of the current article
6976 (@code{gnus-summary-raise-score}).
6979 @kindex L C-l (Summary)
6980 @findex gnus-summary-lower-score
6981 Lower the score of the current article
6982 (@code{gnus-summary-lower-score}).
6985 The rest of these commands modify the local score file.
6989 @kindex V m (Summary)
6990 @findex gnus-score-set-mark-below
6991 Prompt for a score, and mark all articles with a score below this as
6992 read (@code{gnus-score-set-mark-below}).
6994 @kindex V E (Summary)
6995 @findex gnus-score-set-expunge-below
6996 Expunge all articles with a score below the default score (or the
6997 numeric prefix) (@code{gnus-score-set-expunge-below}).
7000 The keystrokes for actually making score entries follow a very regular
7001 pattern, so there's no need to list all the commands. (Hundreds of
7006 The first key is either @kbd{I} (upper case i) for increasing the score
7007 or @kbd{L} for lowering the score.
7009 The second key says what header you want to score on. The following
7013 Score on the author name.
7015 Score on the subject line.
7017 Score on the Xref line---i.e., the cross-posting line.
7019 Score on thread---the References line.
7023 Score on the number of lines.
7025 Score on the Message-ID.
7035 The third key is the match type. Which match types are legal depends on
7036 what headers you are scoring on.
7069 Greater than number.
7074 The fourth and final key says whether this is a temporary (i.e., expiring)
7075 score entry, or a permanent (i.e., non-expiring) score entry, or whether
7076 it is to be done immediately, without adding to the score file.
7079 Temporary score entry.
7081 Permanent score entry.
7083 Immediately scoring.
7088 So, let's say you want to increase the score on the current author with
7089 exact matching permanently: @kbd{I a e p}. If you want to lower the
7090 score based on the subject line, using substring matching, and make a
7091 temporary score entry: @kbd{L s s t}. Pretty easy.
7093 To make things a bit more complicated, there are shortcuts. If you use
7094 a capital letter on either the second or third keys, Gnus will use
7095 defaults for the remaining one or two keystrokes. The defaults are
7096 "substring" and "temporary". So @kbd{I A} is the same as @kbd{I a s t},
7097 and @kbd{I a R} is the same as @kbd{I a r t}.
7099 @vindex gnus-score-mimic-keymap
7100 The @code{gnus-score-mimic-keymap} says whether these commands will
7101 pretend they are keymaps or not.
7104 @node Group Score Commands
7105 @section Group Score Commands
7106 @cindex group score commands
7108 There aren't many of these as yet, I'm afraid.
7114 @findex gnus-score-flush-cache
7115 Gnus maintains a cache of score alists to avoid having to reload them
7116 all the time. This command will flush the cache
7117 (@code{gnus-score-flush-cache}).
7122 @node Score Variables
7123 @section Score Variables
7124 @cindex score variables
7127 @item gnus-use-scoring
7128 @vindex gnus-use-scoring
7129 If @code{nil}, Gnus will not check for score files, and will not, in
7130 general, do any score-related work.
7132 @item gnus-kill-killed
7133 @vindex gnus-kill-killed
7134 If this variable is @code{nil}, Gnus will never apply score files to
7135 articles that have already been through the kill process. While this
7136 may save you lots of time, it also means that if you apply a kill file
7137 to a group, and then change the kill file and want to run it over you
7138 group again to kill more articles, it won't work. You have to set this
7139 variable to @code{t} to do that.
7141 @item gnus-kill-files-directory
7142 @vindex gnus-kill-files-directory
7143 All kill and score files will be stored in this directory, which is
7144 initialized from the @samp{SAVEDIR} environment variable by default.
7146 @item gnus-score-file-suffix
7147 @vindex gnus-score-file-suffix
7148 Suffix to add to the group name to arrive at the score file name
7149 (@samp{SCORE} by default.)
7151 @item gnus-score-uncacheable-files
7152 @vindex gnus-score-uncacheable-files
7154 All score files are normally cached to avoid excessive re-loading of
7155 score files. However, if this might make you Emacs grow big and
7156 bloated, so this regexp can be used to weed out score files that are
7157 unlikely to be needed again. It would be a bad idea to deny caching of
7158 @file{all.SCORE}, while it might be a good idea to not cache
7159 @file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
7160 variable is @samp{"ADAPT$"} by default, so no adaptive score files will
7163 @item gnus-score-interactive-default-score
7164 @vindex gnus-score-interactive-default-score
7165 Score used by all the interactive raise/lower commands to raise/lower
7166 score with. Default is 1000, which may seem excessive, but this is to
7167 ensure that the adaptive scoring scheme gets enough room to play with.
7168 We don't want the small changes from the adaptive scoring to overwrite
7169 manually entered data.
7171 @item gnus-summary-default-score
7172 @vindex gnus-summary-default-score
7173 Default score of an article, which is 0 by default.
7175 @item gnus-score-over-mark
7176 @vindex gnus-score-over-mark
7177 Mark (in the third column) used for articles with a score over the
7178 default. Default is @samp{+}.
7180 @item gnus-score-below-mark
7181 @vindex gnus-score-below-mark
7182 Mark (in the third column) used for articles with a score below the
7183 default. Default is @samp{-}.
7185 @item gnus-score-find-score-files-function
7186 @vindex gnus-score-find-score-files-function
7187 Function used to find score files for the current group. This function
7188 is called with the name of the group as the argument.
7190 Predefined functions available are:
7193 @item gnus-score-find-single
7194 @findex gnus-score-find-single
7195 Only apply the group's own score file.
7197 @item gnus-score-find-bnews
7198 @findex gnus-score-find-bnews
7199 Apply all score files that match, using bnews syntax. For instance, if
7200 the current group is @samp{gnu.emacs.gnus}, @samp{all.emacs.all.SCORE},
7201 @samp{not.alt.all.SCORE} and @samp{gnu.all.SCORE} would all apply. In
7202 short, the instances of @samp{all} in the score file names are
7203 translated into @samp{.*}, and then a regexp match is done.
7205 If @code{gnus-use-long-file-name} is non-@code{nil}, this won't work
7206 very will. It will find stuff like @file{gnu/all/SCORE}, but will not
7207 find files like @file{not/gnu/all/SCORE}.
7209 @item gnus-score-find-hierarchical
7210 @findex gnus-score-find-hierarchical
7211 Apply all score files from all the parent groups.
7213 This variable can also be a list of functions. In that case, all these
7214 functions will be called, and all the returned lists of score files will
7215 be applied. These functions can also return lists of score alists
7216 directly. In that case, the functions that return these non-file score
7217 alists should probably be placed before the "real" score file functions,
7218 to ensure that the last score file returned is the local score file.
7220 @item gnus-score-expiry-days
7221 @vindex gnus-score-expiry-days
7222 This variable says how many days should pass before an unused score file
7223 entry is expired. The default is 7.
7226 @node Score File Format
7227 @section Score File Format
7228 @cindex score file format
7230 A score file is an @code{emacs-lisp} file that normally contains just a
7231 single form. Casual users are not expected to edit these files;
7232 everything can be changed from the summary buffer.
7234 Anyway, if you'd like to dig into it yourself, here's an example:
7238 ("Lars Ingebrigtsen" -10000)
7240 ("larsi\\|lmi" -50000 nil R))
7242 ("Ding is Badd" nil 728373))
7244 ("alt.politics" -1000 728372 s))
7249 (mark-and-expunge -10)
7253 (files "/hom/larsi/News/gnu.SCORE")
7254 (exclude-files "all.SCORE")
7255 (local (gnus-newsgroup-auto-expire t)
7256 (gnus-summary-make-false-root 'empty))
7260 This example demonstrates absolutely everything about a score file.
7262 Even though this looks much like lisp code, nothing here is actually
7263 @code{eval}ed. The lisp reader is used to read this form, though, so it
7264 has to be legal syntactically, if not semantically.
7266 Six keys are supported by this alist:
7270 If the key is a string, it is the name of the header to perform the
7271 match on. Scoring can only be performed on these eight headers:
7272 @samp{From}, @samp{Subject}, @samp{References}, @samp{Message-ID},
7273 @samp{Xref}, @samp{Lines}, @samp{Chars} and @samp{Date}. In addition to
7274 these headers, there are three strings to tell Gnus to fetch the entire
7275 article and do the match on larger parts of the article: @samp{Body}
7276 will perform the match on the body of the article, @samp{Head} will
7277 perform the match on the head of the article, and @samp{All} will
7278 perform the match on the entire article. Note that using any of these
7279 last three keys will slow down group entry @emph{considerably}. The
7280 final "header" you can score on is @samp{Followup}. These score entries
7281 will result in new score entries being added for all follow-ups to
7282 articles that matches these score entries.
7284 Following this key is a random number of score entries, where each score
7285 entry has one to four elements.
7288 The first element is the @dfn{match element}. On most headers this will
7289 be a string, but on the Lines and Chars headers, this must be an
7292 If the second element is present, it should be a number---the @dfn{score
7293 element}. This number should be an integer in the neginf to posinf
7294 interval. This number is added to the score of the article if the match
7295 is successful. If this element is not present, the
7296 @code{gnus-score-interactive-default-score} number will be used instead.
7298 If the third element is present, it should be a number---the @dfn{date
7299 element}. This date says when the last time this score entry matched,
7300 which provides a mechanism for expiring the score entries. It this
7301 element is not present, the score entry is permanent. The date is
7302 represented by the number of days since December 31, 1 ce.
7304 If the fourth element is present, it should be a symbol---the @dfn{type
7305 element}. This element specifies what function should be used to see
7306 whether this score entry matches the article. What match types that can
7307 be used depends on what header you wish to perform the match on.
7309 @item From, Subject, References, Xref, Message-ID
7310 For most header types, there are the @code{r} and @code{R} (regexp) as
7311 well as @code{s} and @code{S} (substring) types and @code{e} and
7312 @code{E} (exact match) types. If this element is not present, Gnus will
7313 assume that substring matching should be used. @code{R} and @code{S}
7314 differ from the other two in that the matches will be done in a
7315 case-sensitive manner. All these one-letter types are really just
7316 abbreviations for the @code{regexp}, @code{string} and @code{exact}
7317 types, which you can use instead, if you feel like.
7319 These two headers use different match types: @code{<}, @code{>},
7320 @code{=}, @code{>=} and @code{<=}.
7322 For the Date header we have three match types: @code{before}, @code{at}
7323 and @code{after}. I can't really imagine this ever being useful, but,
7324 like, it would feel kinda silly not to provide this function. Just in
7325 case. You never know. Better safe than sorry. Once burnt, twice shy.
7326 Don't judge a book by its cover. Never not have sex on a first date.
7327 @item Head, Body, All
7328 These three match keys use the same match types as the @code{From} (etc)
7331 This match key will add a score entry on all articles that followup to
7332 some author. Uses the same match types as the @code{From} header uses.
7337 The value of this entry should be a number. Any articles with a score
7338 lower than this number will be marked as read.
7340 The value of this entry should be a number. Any articles with a score
7341 lower than this number will be removed from the summary buffer.
7342 @item mark-and-expunge
7343 The value of this entry should be a number. Any articles with a score
7344 lower than this number will be marked as read and removed from the
7347 The value of this entry should be any number of file names. These files
7348 are assumed to be score files as well, and will be loaded the same way
7351 The clue of this entry should be any number of files. This files will
7352 not be loaded, even though they would normally be so, for some reason or
7355 The value of this entry will be @code{eval}el. This element will be
7356 ignored when handling global score files.
7358 Read-only score files will not be updated or saved. Global score files
7359 should feature this atom (@pxref{Global Score Files}).
7361 The value of this entry should be a number. Articles that do not have
7362 parents will get this number added to their scores.
7364 This entry controls the adaptive scoring. If it is @code{t}, the
7365 default adaptive scoring rules will be used. If it is @code{ignore}, no
7366 adaptive scoring will be performed on this group. If it is a list, this
7367 list will be used as the adaptive scoring rules. If it isn't present,
7368 or is something other than @code{t} or @code{ignore}, the default
7369 adaptive scoring rules will be used. If you want to use adaptive
7370 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
7371 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
7372 not want adaptive scoring. If you only want adaptive scoring in a few
7373 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
7374 insert @code{(adapt t)} in the score files of the groups where you want
7377 @cindex local variables
7378 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
7379 Each @var{var} will be made buffer-local to the current summary buffer,
7380 and set to the value specified. This is a convenient, if somewhat
7381 strange, way of setting variables in some groups if you don't like hooks
7385 @node Score File Editing
7386 @section Score File Editing
7388 You normally enter all scoring commands from the summary buffer, but you
7389 might feel the urge to edit them by hand as well, so we've supplied you
7390 with a mode for that.
7392 It's simply a slightly customized @code{emacs-lisp} mode, with these
7393 additional commands:
7397 @kindex C-c C-c (Score)
7398 @findex gnus-score-edit-done
7399 Save the changes you have made and return to the summary buffer
7400 (@code{gnus-score-edit-done}).
7402 @kindex C-c C-d (Score)
7403 @findex gnus-score-edit-insert-date
7404 Insert the current date in numerical format
7405 (@code{gnus-score-edit-insert-date}). This is really the day number, if
7409 @node Adaptive Scoring
7410 @section Adaptive Scoring
7411 @cindex adaptive scoring
7413 If all this scoring is getting you down, Gnus has a way of making it all
7414 happen automatically---as if by magic. Or rather, as if by artificial
7415 stupidity, to be precise.
7417 @vindex gnus-use-adaptive-scoring
7418 When you read an article, or mark an article as read, or kill an
7419 article, you leave marks behind. On exit from the group, Gnus can sniff
7420 these marks and add score elements depending on what marks it finds.
7421 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
7424 @vindex gnus-default-adaptive-score-alist
7425 To give you complete control over the scoring process, you can customize
7426 the @code{gnus-default-adaptive-score-alist} variable. By default, it
7427 looks something like this:
7430 (defvar gnus-default-adaptive-score-alist
7431 '((gnus-unread-mark)
7432 (gnus-ticked-mark (from 4))
7433 (gnus-dormant-mark (from 5))
7434 (gnus-del-mark (from -4) (subject -1))
7435 (gnus-read-mark (from 4) (subject 2))
7436 (gnus-expirable-mark (from -1) (subject -1))
7437 (gnus-killed-mark (from -1) (subject -3))
7438 (gnus-kill-file-mark)
7439 (gnus-catchup-mark (from -1) (subject -1))))
7442 As you see, each element in this alist has a mark as a key (either a
7443 variable name or a "real" mark---a character). Following this key is a
7444 random number of header/score pairs.
7446 To take @code{gnus-del-mark} as an example---this alist says that all
7447 articles that have that mark (i.e., are marked with @samp{D}) will have a
7448 score entry added to lower based on the @code{From} header by -4, and
7449 lowered by @code{Subject} by -1. Change this to fit your prejudices.
7451 The headers you can score on are @code{from}, @code{subject},
7452 @code{message-id}, @code{references}, @code{xref}, @code{lines},
7453 @code{chars} and @code{date}. In addition, you can score on
7454 @code{followup}, which will create an adaptive score entry that matches
7455 on the @code{References} header using the @code{Message-ID} of the
7456 current article, thereby matching the following thread.
7458 If you use this scheme, you should set @code{mark-below} to something
7459 small---like -300, perhaps, to avoid having small random changes result
7460 in articles getting marked as read.
7462 After using adaptive scoring for a week or so, Gnus should start to
7463 become properly trained and enhance the authors you like best, and kill
7464 the authors you like least, without you having to say so explicitly.
7466 You can control what groups the adaptive scoring is to be performed on
7467 by using the score files (@pxref{Score File Format}). This will also
7468 let you use different rules in different groups.
7470 @vindex gnus-adaptive-file-suffix
7471 The adaptive score entries will be put into a file where the name is the
7472 group name with @code{gnus-adaptive-file-suffix} appended.
7474 @vindex gnus-score-exact-adapt-limit
7475 When doing adaptive scoring, substring or fuzzy matching would probably
7476 give you the best results in most cases. However, if the header one
7477 matches is short, the possibility for false positives is great, so if
7478 the length of the match is less than
7479 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
7480 this variable is @code{nil}, exact matching will always be used to avoid
7484 @section Scoring Tips
7485 @cindex scoring tips
7489 If you want to lower the score of crossposts, the line to match on is
7490 the @code{Xref} header.
7492 ("xref" (" talk.politics.misc:" -1000))
7494 @item Multiple crossposts
7495 If you want to lower the score of articles that have been crossposted to
7496 more than, say, 3 groups:
7498 ("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
7500 @item Matching on the body
7501 This is generally not a very good idea---it takes a very long time.
7502 Gnus actually has to fetch each individual article from the server. But
7503 you might want to anyway, I guess. Even though there are three match
7504 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
7505 and stick with it in each score file. If you use any two, each article
7506 will be fetched @emph{twice}. If you want to match a bit on the
7507 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
7509 @item Marking as read
7510 You will probably want to mark articles that has a score below a certain
7511 number as read. This is most easily achieved by putting the following
7512 in your @file{all.SCORE} file:
7516 You may also consider doing something similar with @code{expunge}.
7518 @item Negated charater classes
7519 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
7520 That will match newlines, which might lead to, well, The Unknown. Say
7521 @code{[^abcd\n]*} instead.
7524 @node Reverse Scoring
7525 @section Reverse Scoring
7526 @cindex reverse scoring
7528 If you want to keep just articles that have @samp{Sex with Emacs} in the
7529 subject header, and expunge all other articles, you could put something
7530 like this in your score file:
7534 ("Sex with Emacs" 2))
7539 So, you raise all articles that match @samp{Sex with Emacs} and mark the
7540 rest as read, and expunge them to boot.
7542 @node Global Score Files
7543 @section Global Score Files
7544 @cindex global score files
7546 Sure, other newsreaders have "global kill files". These are usually
7547 nothing more than a single kill file that applies to all groups, stored
7548 in the user's home directory. Bah! Puny, weak newsreaders!
7550 What I'm talking about here are Global Score Files. Score files from
7551 all over the world, from users everywhere, uniting all nations in one
7552 big, happy score file union! Ange-score! New and untested!
7554 @vindex gnus-global-score-files
7555 All you have to do to use other people's score files is to set the
7556 @code{gnus-global-score-files} variable. One entry for each score file,
7557 or each score file directory. Gnus will decide by itself what score
7558 files are applicable to which group.
7560 Say you want to use all score files in the
7561 @file{/ftp@@ftp.some-where:/pub/score} directory and the single score
7562 file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
7565 (setq gnus-global-score-files
7566 '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
7567 "/ftp@@ftp.some-where:/pub/score/"))
7570 @findex gnus-score-search-global-directories
7571 Simple, eh? Directory names must end with a @samp{/}. These
7572 directories are typically scanned only once during each Gnus session.
7573 If you feel the need to manually re-scan the remote directories, you can
7574 use the @code{gnus-score-search-global-directories} command.
7576 Note that, at present, using this option will slow down group entry
7577 somewhat. (That is---a lot.)
7579 If you want to start maintaining score files for other people to use,
7580 just put your score file up for anonymous ftp and announce it to the
7581 world. Become a retro-moderator! Participate in the retro-moderator
7582 wars sure to ensue, where retro-moderators battle it out for the
7583 sympathy of the people, luring them to use their score files on false
7584 premises! Yay! The net is saved!
7586 Here are some tips for the would-be retro-moderator, off the top of my
7591 Articles that are heavily crossposted are probably junk.
7593 To lower a single inappropriate article, lower by @code{Message-Id}.
7595 Particularly brilliant authors can be raised on a permanent basis.
7597 Authors that repeatedly post off-charter for the group can safely be
7598 lowered out of existence.
7600 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
7601 articles completely.
7603 Use expiring score entries to keep the size of the file down. You
7604 should probably have a long expiry period, though, as some sites keep
7605 old articles for a long time.
7608 ... I wonder whether other newsreaders will support global score files
7609 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
7610 Wave, xrn and 1stReader are bound to implement scoring. Should we start
7611 holding our breath yet?
7618 Gnus still supports those pesky old kill files. In fact, the kill file
7619 entries can now be expiring, which is something I wrote before Daniel
7620 Quinlan thought of doing score files, so I've left the code in there.
7622 In short, kill processing is a lot slower (and I do mean @emph{a lot})
7623 than score processing, so it might be a good idea to rewrite your kill
7624 files into score files.
7626 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
7627 forms into this file, which means that you can use kill files as some
7628 sort of primitive hook function to be run on group entry, even though
7629 that isn't a very good idea.
7631 XCNormal kill files look like this:
7634 (gnus-kill "From" "Lars Ingebrigtsen")
7635 (gnus-kill "Subject" "ding")
7639 This will mark every article written by me as read, and remove them from
7640 the summary buffer. Very useful, you'll agree.
7642 Other programs use a totally different kill file syntax. If Gnus
7643 encounters what looks like a @code{rn} kill file, it will take a stab at
7646 Two functions for editing a GNUS kill file:
7650 @kindex M-k (Summary)
7651 @findex gnus-summary-edit-local-kill
7652 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
7655 @kindex M-K (Summary)
7656 @findex gnus-summary-edit-global-kill
7657 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
7660 @vindex gnus-kill-file-name
7661 A kill file for the group @samp{soc.motss} is normally called
7662 @file{soc.motss.KILL}. The suffix appended to the group name to get
7663 this file name is detailed by the @code{gnus-kill-file-name} variable.
7664 The "global" kill file (not in the score file sense of "global", of
7665 course) is called just @file{KILL}.
7667 @vindex gnus-kill-save-kill-file
7668 If @code{gnus-kill-save-kill-file} is non-@code{nil}, Gnus will save the
7669 kill file after processing, which is necessary if you use expiring
7679 * Interactive:: Making Gnus ask you many questions.
7680 * Windows Configuration:: Configuring the Gnus buffer windows.
7681 * Buttons:: Get tendonitis in ten easy steps!
7682 * Compilation & Init File:: How to speed Gnus up.
7683 * Daemons:: Gnus can do things behind your back.
7684 * NoCeM:: How to avoid spam and other fatty foods.
7685 * Various Various:: Things that are really various.
7689 @section Interactive
7693 @item gnus-novice-user
7694 @vindex gnus-novice-user
7695 If this variable is non-@code{nil}, you are either a newcomer to the
7696 World of Usenet, or you are very cautious, which is a nice thing to be,
7697 really. You will be given questions of the type "Are you sure you want
7698 to do this?" before doing anything dangerous.
7699 @item gnus-expert-user
7700 @vindex gnus-expert-user
7701 If this variable is non-@code{nil}, you will never ever be asked any
7702 questions by Gnus. It will simply assume you know what your are doing,
7703 no matter how strange.
7704 @item gnus-interactive-catchup
7705 @vindex gnus-interactive-catchup
7706 Require confirmation before catching up a group if non-@code{nil}.
7707 @item gnus-interactive-post
7708 @vindex gnus-interactive-post
7709 If non-@code{nil}, the user will be prompted for a group name when
7711 @item gnus-interactive-exit
7712 @vindex gnus-interactive-exit
7713 Require confirmation before exiting Gnus.
7716 @node Windows Configuration
7717 @section Windows Configuration
7718 @cindex windows configuration
7720 No, there's nothing here about X, so be quiet.
7723 @item gnus-use-full-window
7724 @vindex gnus-use-full-window
7725 If non-@code{nil}, Gnus will delete all other windows and occupy the
7726 entire Emacs screen by itself. It is @code{t} by default.
7728 @item gnus-buffer-configuration
7729 @vindex gnus-buffer-configuration
7730 This variable describes how much space each Gnus buffer should be given.
7731 Here's an excerpt of this variable:
7734 ((group ([group 1.0 point]
7735 (if gnus-carpal [group-carpal 4])))
7736 (article ([summary 0.25 point]
7740 This is an alist. The @dfn{key} is a symbol that names some action or
7741 other. For instance, when displaying the group buffer, the window
7742 configuration function will use @code{group} as the key. A full list of
7743 possible names is listed below.
7745 The @dfn{value} is a @dfn{rule} that says how much space each buffer
7746 should occupy. To take the @code{article} rule as an example -
7749 (article ([summary 0.25 point]
7753 This rule says that the summary buffer should occupy 25% of the screen,
7754 and that it is placed over the article buffer. As you may have noticed,
7755 100% + 25% is actually 125% (yup, I saw y'all reaching for that
7756 calculator there). However, the special number @code{1.0} is used to
7757 signal that this buffer should soak up all the rest of the space
7758 avaiable after the rest of the buffers have taken whatever they need.
7759 There should be only one buffer with the @code{1.0} size spec.
7761 Point will be put in the buffer that has the optional third element
7764 Here's a more complicated example:
7768 [summary 0.25 point]
7769 (if gnus-carpal [summary-carpal 4])
7773 If the size spec is an integer instead of a floating point number,
7774 then that number will be used to say how many lines a buffer should
7775 occupy, not a percentage.
7777 If an element is a list instead of a vector, this list will be
7778 @code{eval}ed. If the result is non-@code{nil}, it will be used. This
7779 means that there will be three buffers if @code{gnus-carpal} is
7780 @code{nil}, and four buffers if @code{gnus-carpal} is non-@code{nil}.
7782 Not complicated enough for you? Well, try this on for size:
7785 (article ([group 1.0]
7788 [summary 0.25 point]
7793 Whoops. Two buffers with the mystery 100% tag. And what's that
7794 @code{horizontal} thingie?
7796 If the first element in one of the rule lists is a list with
7797 @code{horizontal} as the first element, Gnus will split the window
7798 horizontally, giving you two windows side-by-side. Inside each of these
7799 strips you may carry on all you like in the normal fashion. The number
7800 following @code{horizontal} says what percentage of the screen is to be
7801 given to this strip.
7803 For each horizontal split, there @emph{must} be one element that has the
7804 100% tag. The splitting is never accurate, and this buffer will eat any
7805 leftover lines from the splits.
7807 Here's a list of all possible keys:
7809 @code{group}, @code{summary}, @code{article}, @code{server},
7810 @code{browse}, @code{group-mail}, @code{summary-mail},
7811 @code{summary-reply}, @code{info}, @code{summary-faq},
7812 @code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
7813 @code{followup}, @code{followup-yank}, @code{edit-score}.
7815 @findex gnus-add-configuration
7816 Since this variable is so long and complicated, there's a function you
7817 can use to ease changing the config of a single setting:
7818 @code{gnus-add-configuration}. If, for instance, you want to change the
7819 @code{article} setting, you could say:
7822 (gnus-add-configuration
7823 '(article ([group 4]
7836 Those new-fangled @dfn{mouse} contraptions is very popular with the
7837 young, hep kids who don't want to learn the proper way to do things
7838 these days. Why, I remember way back in the summer of '89, when I was
7839 using Emacs on a Tops 20 system. Three hundred users on one single
7840 machine, and every user was running Simula compilers. Bah!
7845 Well, you can make Gnus display bufferfuls of buttons you can click to
7846 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
7847 really. Tell the chiropractor I sent you.
7851 @item gnus-carpal-mode-hook
7852 @vindex gnus-carpal-mode-hook
7853 Hook run in all carpal mode buffers.
7854 @item gnus-carpal-button-face
7855 @vindex gnus-carpal-button-face
7856 Face used on buttons.
7857 @item gnus-carpal-group-buffer-buttons
7858 @vindex gnus-carpal-group-buffer-buttons
7859 Buttons in the group buffer.
7860 @item gnus-carpal-summary-buffer-buttons
7861 @vindex gnus-carpal-summary-buffer-buttons
7862 Buttons in the summary buffer.
7863 @item gnus-carpal-server-buffer-buttons
7864 @vindex gnus-carpal-server-buffer-buttons
7865 Buttons in the server buffer.
7866 @item gnus-carpal-browse-buffer-buttons
7867 @vindex gnus-carpal-browse-buffer-buttons
7868 Buttons in the browse buffer.
7871 All the @code{buttons} variables are lists. The elements in these list
7872 is either a cons cell where the car contains a text to be displayed and
7873 the cdr contains a function symbol, or a simple string.
7876 @node Compilation & Init File
7877 @section Compilation & Init File
7880 @cindex byte-compilation
7882 @vindex gnus-init-file
7883 @findex gnus-compile
7884 When Gnus starts up, it will read the Gnus init file
7885 @code{gnus-init-file}, which is @file{.gnus} by default. It is
7886 recommended that you keep any Gnus-related functions that you have
7887 written in that file. If you want to byte-compile the file, Gnus offers
7888 the handy @kbd{M-x gnus-compile} function that will do that for you.
7890 That's not really why that function was written, though.
7892 Remember all those line format specification variables?
7893 @code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
7894 on. Now, Gnus will of course heed whatever these variables are, but,
7895 unfortunately, changing them will mean a quite significant slow-down.
7896 (The default values of these variables have byte-compiled functions
7897 associated with them, while the user-generated versions do not, of
7900 To help with this, you can run @code{gnus-compile} after you've fiddled
7901 around with the variables and feel that you're (kind of) satisfied.
7902 This will result in the new specs being byte-compiled, and you'll get
7905 The result of these byte-compilations will be written to
7906 @file{.gnus.elc} by default.
7908 Note that Gnus will read @file{.gnus.elc} instead of @file{.gnus} if
7909 @file{.gnus.elc} exists, so if you change @file{.gnus}, you should
7910 remove @file{.gnus.elc}.
7918 Gnus, being larger than any program ever written (allegedly), does lots
7919 of strange stuff that you may wish to have done while you're not
7920 present. For instance, you may want it to check for new mail once in a
7921 while. Or you may want it to close down all connections to all servers
7922 when you leave Emacs idle. And stuff like that.
7924 Gnus will let you do stuff like that by defining various
7925 @dfn{handlers}. Each handler consists of three elements: A
7926 @var{function}, a @var{time}, and an @var{idle} parameter.
7928 Here's an example of a handler that closes connections when Emacs has
7929 been idle for thirty minutes:
7932 (gnus-demon-close-connections nil 30)
7935 Here's a handler that scans for PGP headers every hour when Emacs is
7939 (gnus-demon-scan-pgp 60 t)
7942 This @var{time} parameter and than @var{idle} parameter works together
7943 in a strange, but wonderful fashion. Basically, if @var{idle} is
7944 @code{nil}, then the function will be called every @var{time} minutes.
7946 If @var{idle} is @code{t}, then the function will be called after
7947 @var{time} minutes only if Emacs is idle. So if Emacs is never idle,
7948 the function will never be called. But once Emacs goes idle, the
7949 function will be called every @var{time} minutes.
7951 If @var{idle} is a number and @var{time} is a number, the function will
7952 be called every @var{time} minutes only when Emacs has been idle for
7955 If @var{idle} is a number and @var{time} is @code{nil}, the function
7956 will be called once every time Emacs has been idle for @var{idle}
7959 And if @var{time} is a string, it should look like @samp{"07:31"}, and
7960 the function will then be called once every day somewhere near that
7961 time. Modified by the @var{idle} parameter, of course.
7963 @vindex gnus-demon-timestep
7964 (When I say "minute" here, I really mean @code{gnus-demon-timestep}
7965 seconds. This is @samp{60} by default. If you change that variable,
7966 all the timings in the handlers will be affected.)
7968 So, if you want to add a handler, you could put something like this in
7969 your @file{.gnus} file:
7971 @findex gnus-demon-add-handler
7973 (gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
7976 @findex gnus-demon-add-nocem
7977 @findex gnus-demon-add-scanmail
7978 @findex gnus-demon-add-disconnection
7979 Some ready-made functions to do this has been created:
7980 @code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, and
7981 @code{gnus-demon-add-scanmail}. Just put those functions in your
7982 @file{.gnus} if you want those abilities.
7984 @findex gnus-demon-init
7985 @findex gnus-demon-cancel
7986 @vindex gnus-demon-handlers
7987 If you add handlers to @code{gnus-demon-handlers} directly, you should
7988 run @code{gnus-demon-init} to make the changes take hold. To cancel all
7989 daemons, you can use the @code{gnus-demon-cancel} function.
7991 Note that adding daemons can be pretty naughty if you overdo it. Adding
7992 functions that scan all news and mail from all servers every two seconds
7993 is a sure-fire way of getting booted off any respectable system. So
8004 @node Various Various
8005 @section Various Various
8011 @vindex gnus-verbose
8012 This variable is an integer between zero and ten. The higher the value,
8013 the more messages will be displayed. If this variable is zero, Gnus
8014 will never flash any messages, if it is seven, most important messages
8015 will be shown, and if it is ten, Gnus won't ever shut up, but will flash
8016 so many messages it will make your head swim.
8017 @item gnus-updated-mode-lines
8018 @vindex gnus-updated-mode-lines
8019 This is a list of buffers that should keep their mode lines updated.
8020 The list may contain the symbols @code{group}, @code{article} and
8021 @code{summary}. If the corresponding symbol is present, Gnus will keep
8022 that mode line updated with information that may be pertinent. If this
8023 variable is @code{nil}, screen refresh may be quicker.
8025 @cindex display-time
8026 @item gnus-mode-non-string-length
8027 @vindex gnus-mode-non-string-length
8028 By default, Gnus displays information on the current article in the mode
8029 lines of the summary and article buffers. The information Gnus wishes
8030 to display (eg. the subject of the article) is often longer than the
8031 mode lines, and therefore have to be cut off at some point. This
8032 variable says how long the other elements on the line is (i.e., the
8033 non-info part). If you put additional elements on the mode line (eg. a
8034 clock), you should modify this variable:
8035 @c Hook written by Keinonen Kari <kk85613@cs.tut.fi>.
8037 (add-hook 'display-time-hook
8039 (setq gnus-mode-non-string-length
8040 (+ 21 (length display-time-string)))))
8046 @cindex highlighting
8049 If @code{nil}, Gnus won't attempt to create menus or use fancy colors
8050 or fonts. This will also inhibit loading the @file{gnus-visual.el}
8053 This variable can also be a list of visual properties that are enabled.
8054 The following elements are legal, and are all set by default:
8058 @item summary-highlight
8059 Perform various highlighting in the summary buffer.
8061 @item article-highlight
8062 Perform various highlighting in the article buffer.
8065 Turn on highlighting in all buffers.
8068 Create menus in the group buffer.
8071 Create menus in the summary buffer.
8074 Create menus in the article buffer.
8077 Create menus in the browse buffer.
8080 Create menus in the server buffer.
8083 Create menus in all buffers.
8087 So if you only want highlighting in the article buffer and menus in all
8088 buffers, you couls say something like:
8091 (setq gnus-visual '(article-highlight menu))
8094 If you want only highlighting and no menus whatsoever, you'd say:
8097 (setq gnus-visual '(highlight))
8100 @item gnus-mouse-face
8101 @vindex gnus-mouse-face
8102 This is the face (i.e., font) used for mouse highlighting in Gnus. No
8103 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
8105 @item gnus-display-type
8106 @vindex gnus-display-type
8107 This variable is symbol indicating the display Emacs is running under.
8108 The symbol should be one of @code{color}, @code{grayscale} or
8109 @code{mono}. If Gnus guesses this display attribute wrongly, either set
8110 this variable in your @file{~/.emacs} or set the resource
8111 @code{Emacs.displayType} in your @file{~/.Xdefaults}.
8113 @item gnus-background-mode
8114 @vindex gnus-background-mode
8115 This is a symbol indicating the Emacs background brightness. The symbol
8116 should be one of @code{light} or @code{dark}. If Gnus guesses this
8117 frame attribute wrongly, either set this variable in your @file{~/.emacs} or
8118 set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
8119 `gnus-display-type'.
8121 @item nnheader-max-head-length
8122 @vindex nnheader-max-head-length
8123 When the backends read straight heads of articles, they all try to read
8124 as little as possible. This variable (default @code{4096}) specifies
8125 the absolute max length the backends will try to read before giving up
8126 on finding a separator line between the head and the body. If this
8127 variable is @code{nil}, there is no upper read bound. If it is
8128 @code{t}, the backends won't try to read the articles piece by piece,
8129 but read the entire articles. This makes sense with some versions of
8136 @chapter Customization
8137 @cindex general customization
8139 All variables are properly documented elsewhere in this manual. This
8140 section is designed to give general pointers on how to customize Gnus
8141 for some quite common situations.
8144 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
8145 * Slow Terminal Connection:: You run a remote Emacs.
8146 * Little Disk Space:: You feel that having large setup files is icky.
8147 * Slow Machine:: You feel like buying a faster machine.
8150 @node Slow/Expensive Connection
8151 @section Slow/Expensive @sc{nntp} Connection
8153 If you run Emacs on a machine locally, and get your news from a machine
8154 over some very thin strings, you want to cut down on the amount of data
8155 Gnus has to get from the @sc{nntp} server.
8158 @item gnus-read-active-file
8159 Set this to @code{nil}, which will inhibit Gnus from requesting the
8160 entire active file from the server. This file is often v. large. You
8161 also have to set @code{gnus-check-new-news} and
8162 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
8163 doesn't suddenly decide to fetch the active file anyway.
8164 @item gnus-nov-is-evil
8165 This one has to be @code{nil}. If not, grabbing article headers from
8166 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
8167 support @sc{xover}; Gnus will detect this by itself.
8170 @node Slow Terminal Connection
8171 @section Slow Terminal Connection
8173 Let's say you use your home computer for dialing up the system that
8174 runs Emacs and Gnus. If your modem is slow, you want to reduce the
8175 amount of data that is sent over the wires as much as possible.
8178 @item gnus-auto-center-summary
8179 Set this to @code{nil} to inhibit Gnus from recentering the summary
8180 buffer all the time.
8181 @item gnus-visible-headers
8182 Cut down on the headers that are included in the articles to the
8183 minimum. You can, in fact, make do without them altogether---most of the
8184 useful data is in the summary buffer, anyway. Set this variable to
8185 @samp{"^NEVVVVER"} or @samp{"From:"}, or whatever you feel you need.
8186 @item gnus-article-display-hook
8187 Set this hook to all the available hiding commands:
8189 (setq gnus-article-display-hook
8190 '(gnus-article-hide-headers gnus-article-hide-signature
8191 gnus-article-hide-citation))
8193 @item gnus-use-full-window
8194 By setting this to @code{nil}, you can make all the windows smaller.
8195 While this doesn't really cut down much generally, it means that you
8196 have to see smaller portions of articles before deciding that you didn't
8197 want to read them anyway.
8198 @item gnus-thread-hide-subtree
8199 If this is non-@code{nil}, all threads in the summary buffer will be
8201 @item gnus-updated-mode-lines
8202 If this is @code{nil}, Gnus will not put information in the buffer mode
8203 lines, which might save some time.
8206 @node Little Disk Space
8207 @section Little Disk Space
8209 The startup files can get rather large, so you may want to cut their
8210 sizes a bit if you are running out of space.
8213 @item gnus-save-newsrc-file
8214 If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
8215 only save @file{.newsrc.eld}. This means that you will not be able to
8216 use any other newsreaders than Gnus.
8217 @item gnus-save-killed-list
8218 If this is @code{nil}, Gnus will not save the list of dead groups. You
8219 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
8220 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
8221 variable to @code{nil}.
8225 @section Slow Machine
8227 If you have a slow machine, or are just really impatient, there are a
8228 few things you can do to make Gnus run faster.
8230 Set@code{gnus-check-new-newsgroups} and
8231 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
8233 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
8234 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
8235 summary buffer faster.
8237 Set @code{gnus-article-display-hook} to @code{nil} to make article
8238 processing a bit faster.
8241 @node Troubleshooting
8242 @chapter Troubleshooting
8243 @cindex troubleshooting
8245 Gnus works @emph{so} well straight out of the box---I can't imagine any
8253 Make sure your computer is switched on.
8256 Make sure that you really load the current Gnus version. If you have
8257 been running @sc{gnus}, you need to exit Emacs and start it up again before
8261 Try doing an @kbd{M-x gnus-version}. If you get something that looks
8262 like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
8263 on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
8264 flee}, you have some old @file{.el} files lying around. Delete these.
8267 Read the help group (@kbd{M h} in the group buffer) for a FAQ and a
8271 If all else fails, report the problem as a bug.
8274 @cindex reporting bugs
8276 @kindex M-x gnus-bug
8278 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
8279 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
8280 me the backtrace. I will fix bugs, but I can only fix them if you send
8281 me a precise description as to how to reproduce the bug.
8283 You really can never be too detailed in a bug report. Always use the
8284 @kbd{M-x gnus-bug} command when you make bug reports, even if it creates
8285 a 10Kb mail each time you use it, and even if you have sent me your
8286 environment 500 times before. I don't care. I want the full info each
8289 It is also important to remember that I have no memory whatsoever. If
8290 you send a bug report, and I send you a reply, and then you send back
8291 just "No, it's not! Moron!", I will have no idea what you are insulting
8292 me about. Always overexplain everything. It's much easier for all of
8293 us---if I don't have all the information I need, I will just mail you
8294 and ask for more info, and everything takes more time.
8296 If you just need help, you are better off asking on
8297 @samp{gnu.emacs.gnus}. I'm not very helpful.
8303 Well, that's the manual---you can get on with your life now. Keep in
8304 touch. Say hello to your cats from me.
8306 My @strong{ghod}---I just can't stand goodbyes. Sniffle.
8308 Ol' Chuck Reznikoff said it pretty well, so I leave the floor to him:
8313 Not because of victories @*
8316 but for the common sunshine,@*
8318 the largess of the spring.
8321 but for the day's work done@*
8322 as well as I was able;@*
8323 not for a seat upon the dais@*
8324 but at the common table.@*
8328 @chapter A Programmer's Guide to Gnus
8330 It is my hope that other people will figure out smart stuff that Gnus
8331 can do, and that other people will write those smart things as well. To
8332 facilitate that I thought it would be a good idea to describe the inner
8333 workings of Gnus. And some of the not-so-inner workings, while I'm at
8336 You can never expect the internals of a program not to change, but I
8337 will be defining (in some details) the interface between Gnus and its
8338 backends (this is written in stone), the format of the score files
8339 (ditto), data structures (some are less likely to change than others)
8340 and general method of operations.
8343 * Backend Interface:: How Gnus communicates with the servers.
8344 * Score File Syntax:: A BNF definition of the score file standard.
8345 * Headers:: How Gnus stores headers internally.
8346 * Ranges:: A handy format for storing mucho numbers.
8347 * Group Info:: The group info format.
8351 @node Backend Interface
8352 @section Backend Interface
8354 Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
8355 groups. It only knows how to talk to @dfn{virtual servers}. A virtual
8356 server is a @dfn{backend} and some @dfn{backend variables}. As examples
8357 of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
8358 examples of the latter we have @code{nntp-port-number} and
8359 @code{nnmbox-directory}.
8361 When Gnus asks for information from a backend---say @code{nntp}---on
8362 something, it will normally include a virtual server name in the
8363 function parameters. (If not, the backend should use the "current"
8364 virtual server.) For instance, @code{nntp-request-list} takes a virtual
8365 server as its only (optional) parameter. If this virtual server hasn't
8366 been opened, the function should fail.
8368 Note that a virtual server name has no relation to some physical server
8369 name. Take this example:
8373 (nntp-address "ifi.uio.no")
8374 (nntp-port-number 4324))
8377 Here the virtual server name is @samp{"odd-one"} while the name of
8378 the physical server is @samp{"ifi.uio.no"}.
8380 The backends should be able to switch between several virtual servers.
8381 The standard backends implement this by keeping an alist of virtual
8382 server environments that it pulls down/pushes up when needed.
8384 There are two groups of interface functions: @dfn{required functions},
8385 which must be present, and @dfn{optional functions}, which Gnus will
8386 always check whether are present before attempting to call.
8388 All these functions are expected to return data in the buffer
8389 @code{nntp-server-buffer} (@samp{" *nntpd*"}), which is somewhat
8390 unfortunately named, but we'll have to live with it. When I talk about
8391 "resulting data", I always refer to the data in that buffer. When I
8392 talk about "return value", I talk about the function value returned by
8395 Some backends could be said to be @dfn{server-forming} backends, and
8396 some might be said to not be. The latter are backends that generally
8397 only operate on one group at a time, and have no concept of "server" --
8398 they have a group, and they deliver info on that group and nothing more.
8400 In the examples and definitions I will refer to the imaginary backend
8403 @cindex @code{nnchoke}
8406 * Required Backend Functions:: Functions that must be implemented.
8407 * Optional Backend Functions:: Functions that need not be implemented.
8411 @node Required Backend Functions
8412 @subsection Required Backend Functions
8416 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
8418 @var{articles} is either a range of article numbers or a list of
8419 @code{Message-ID}s. Current backends do not fully support either---only
8420 sequences (lists) of article numbers, and most backends do not support
8421 retrieval of @code{Message-ID}s. But they should try for both.
8423 The result data should either be HEADs or NOV lines, and the result
8424 value should either be @code{headers} or @code{nov} to reflect this.
8425 This might later be expanded to @code{various}, which will be a mixture
8426 of HEADs and NOV lines, but this is currently not supported by Gnus.
8428 If @var{fetch-old} is non-@code{nil} it says to try to fetch "extra"
8429 headers, in some meaning of the word. This is generally done by
8430 fetching (at most) @var{fetch-old} extra headers less than the smallest
8431 article number in @code{articles}, and fill in the gaps as well. The
8432 presence of this parameter can be ignored if the backend finds it
8433 cumbersome to follow the request. If this is non-@code{nil} and not a
8434 number, do maximum fetches.
8436 Here's an example HEAD:
8439 221 1056 Article retrieved.
8440 Path: ifi.uio.no!sturles
8441 From: sturles@@ifi.uio.no (Sturle Sunde)
8442 Newsgroups: ifi.discussion
8443 Subject: Re: Something very droll
8444 Date: 27 Oct 1994 14:02:57 +0100
8445 Organization: Dept. of Informatics, University of Oslo, Norway
8447 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
8448 References: <38jdmq$4qu@@visbur.ifi.uio.no>
8449 NNTP-Posting-Host: holmenkollen.ifi.uio.no
8453 So a @code{headers} return value would imply that there's a number of
8454 these in the data buffer.
8456 Here's a BNF definition of such a buffer:
8460 head = error / valid-head
8461 error-message = [ "4" / "5" ] 2number " " <error message> eol
8462 valid-head = valid-message *header "." eol
8463 valid-message = "221 " <number> " Article retrieved." eol
8467 If the return value is @code{nov}, the data buffer should contain
8468 @dfn{network overview database} lines. These are basically fields
8472 nov-buffer = *nov-line
8473 nov-line = 8*9 [ field <TAB> ] eol
8474 field = <text except TAB>
8477 For a closer explanation what should be in those fields,
8481 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
8483 @var{server} is here the virtual server name. @var{definitions} is a
8484 list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
8486 If the server can't be opened, no error should be signaled. The backend
8487 may then choose to refuse further attempts at connecting to this
8488 server. In fact, it should do so.
8490 If the server is opened already, this function should return a
8491 non-@code{nil} value. There should be no data returned.
8494 @item (nnchoke-close-server &optional SERVER)
8496 Close connection to @var{server} and free all resources connected
8499 There should be no data returned.
8502 @item (nnchoke-request-close)
8504 Close connection to all servers and free all resources that the backend
8505 have reserved. All buffers that have been created by that backend
8506 should be killed. (Not the @code{nntp-server-buffer}, though.)
8508 There should be no data returned.
8511 @item (nnchoke-server-opened &optional SERVER)
8513 This function should return whether @var{server} is opened, and that the
8514 connection to it is still alive. This function should under no
8515 circumstances attempt to reconnect to a server that is has lost
8518 There should be no data returned.
8521 @item (nnchoke-status-message &optional SERVER)
8523 This function should return the last error message from @var{server}.
8525 There should be no data returned.
8528 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
8530 The result data from this function should be the article specified by
8531 @var{article}. This might either be a @code{Message-ID} or a number.
8532 It is optional whether to implement retrieval by @code{Message-ID}, but
8533 it would be nice if that were possible.
8535 If @var{to-buffer} is non-@code{nil}, the result data should be returned
8536 in this buffer instead of the normal data buffer. This is to make it
8537 possible to avoid copying large amounts of data from one buffer to
8538 another, and Gnus mainly request articles to be inserted directly into
8542 @item (nnchoke-open-group GROUP &optional SERVER)
8544 Make @var{group} the current group.
8546 There should be no data returned by this function.
8549 @item (nnchoke-request-group GROUP &optional SERVER)
8551 Get data on @var{group}. This function also has the side effect of
8552 making @var{group} the current group.
8554 Here's an example of some result data and a definition of the same:
8557 211 56 1000 1059 ifi.discussion
8560 The first number is the status, which should be @samp{211}. Next is the
8561 total number of articles in the group, the lowest article number, the
8562 highest article number, and finally the group name. Note that the total
8563 number of articles may be less than one might think while just
8564 considering the highest and lowest article numbers, but some articles
8565 may have been cancelled. Gnus just discards the total-number, so
8566 whether one should take the bother to generate it properly (if that is a
8567 problem) is left as an excercise to the reader.
8570 group-status = [ error / info ] eol
8571 error = [ "4" / "5" ] 2<number> " " <Error message>
8572 info = "211 " 3* [ <number> " " ] <string>
8576 @item (nnchoke-close-group GROUP &optional SERVER)
8578 Close @var{group} and free any resources connected to it. This will be
8579 a no-op on most backends.
8581 There should be no data returned.
8584 @item (nnchoke-request-list &optional SERVER)
8586 Return a list of all groups available on @var{server}. And that means
8589 Here's an example from a server that only carries two groups:
8592 ifi.test 0000002200 0000002000 y
8593 ifi.discussion 3324 3300 n
8596 On each line we have a group name, then the highest article number in
8597 that group, the lowest article number, and finally a flag.
8600 active-file = *active-line
8601 active-line = name " " <number> " " <number> " " flags eol
8603 flags = "n" / "y" / "m" / "x" / "j" / "=" name
8606 The flag says whether the group is read-only (@samp{n}), is moderated
8607 (@samp{m}), is dead (@samp{x}), is aliased to some other group
8608 (@samp{=other-group} or none of the above (@samp{y}).
8611 @item (nnchoke-request-post &optional SERVER)
8613 This function should post the current buffer. It might return whether
8614 the posting was successful or not, but that's not required. If, for
8615 instance, the posting is done asynchronously, it has generally not been
8616 completed by the time this function concludes. In that case, this
8617 function should set up some kind of sentinel to beep the user loud and
8618 clear if the posting could not be completed.
8620 There should be no result data from this function.
8623 @item (nnchoke-request-post-buffer POST GROUP SUBJECT HEADER ARTICLE-BUFFER INFO FOLLOW-TO RESPECT-POSTER)
8625 This function should return a buffer suitable for composing an article
8626 to be posted by @code{nnchoke-request-post}. If @var{post} is
8627 non-@code{nil}, this is not a followup, but a totally new article.
8628 @var{group} is the name of the group to be posted to. @var{subject} is
8629 the subject of the message. @var{article-buffer} is the buffer being
8630 followed up, if that is the case. @var{info} is the group info.
8631 @var{follow-to} is the group that one is supposed to re-direct the
8632 article ot. If @var{respect-poster} is non-@code{nil}, the special
8633 @samp{"poster"} value of a @code{Followup-To} header is to be respected.
8635 There should be no result data returned.
8639 @node Optional Backend Functions
8640 @subsection Optional Backend Functions
8644 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
8646 @var{groups} is a list of groups, and this function should request data
8647 on all those groups. How it does it is of no concern to Gnus, but it
8648 should attempt to do this in a speedy fashion.
8650 The return value of this function can be either @code{active} or
8651 @code{group}, which says what the format of the result data is. The
8652 former is in the same format as the data from
8653 @code{nnchoke-request-list}, while the latter is a buffer full of lines
8654 in the same format as @code{nnchoke-request-group} gives.
8657 group-buffer = *active-line / *group-status
8661 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
8663 A Gnus group info (@pxref{Group Info}) is handed to the backend for
8664 alterations. This comes in handy if the backend really carries all the
8665 information (as is the case with virtual an imap groups). This function
8666 may alter the info in any manner it sees fit, and should return the
8667 (altered) group info. This function may alter the group info
8668 destructively, so no copying is needed before boogying.
8670 There should be no result data from this function.
8673 @item (nnchoke-request-scan &optional GROUP SERVER)
8675 This function may be called at any time (by Gnus or anything else) to
8676 request that the backend check for incoming articles, in one way or
8677 another. A mail backend will typically read the spool file or query the
8678 POP server when this function is invoked. The @var{group} doesn't have
8679 to be heeded---if the backend decides that it is too much work just
8680 scanning for a single group, it may do a total scan of all groups. It
8681 would be nice, however, to keep things local if that's practical.
8683 There should be no result data from this function.
8686 @item (nnchoke-request-asynchronous GROUP &optional SERVER ARTICLES)
8688 This is a request to fetch articles asynchronously later.
8689 @var{articles} is an alist of @var{(article-number line-number)}. One
8690 would generally expect that if one later fetches article number 4, for
8691 instance, some sort of asynchronous fetching of the articles after 4
8692 (which might be 5, 6, 7 or 11, 3, 909 depending on the order in that
8693 alist) would be fetched asynchronouly, but that is left up to the
8694 backend. Gnus doesn't care.
8696 There should be no result data from this function.
8699 @item (nnchoke-request-group-description GROUP &optional SERVER)
8701 The result data from this function should be a description of
8705 description-line = name <TAB> description eol
8707 description = <text>
8710 @item (nnchoke-request-list-newsgroups &optional SERVER)
8712 The result data from this function should be the description of all
8713 groups available on the server.
8716 description-buffer = *description-line
8720 @item (nnchoke-request-newgroups DATE &optional SERVER)
8722 The result data from this function should be all groups that were
8723 created after @samp{date}, which is in normal human-readable date
8724 format. The data should be in the active buffer format.
8727 @item (nnchoke-request-create-groups GROUP &optional SERVER)
8729 This function should create an empty group with name @var{group}.
8731 There should be no return data.
8734 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
8736 This function should run the expiry process on all articles in the
8737 @var{articles} range (which is currently a simple list of article
8738 numbers.) It is left up to the backend to decide how old articles
8739 should be before they are removed by this function. If @var{force} is
8740 non-@code{nil}, all @var{articles} should be deleted, no matter how new
8743 This function should return a list of articles that it did not/was not
8746 There should be no result data returned.
8749 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
8752 This function should move @var{article} (which is a number) from
8753 @var{group} by calling @var{accept-form}.
8755 This function should ready the article in question for moving by
8756 removing any header lines it has added to the article, and generally
8757 should "tidy up" the article. Then it should @code{eval}
8758 @var{accept-form} in the buffer where the "tidy" article is. This will
8759 do the actual copying. If this @code{eval} returns a non-@code{nil}
8760 value, the article should be removed.
8762 If @var{last} is @code{nil}, that means that there is a high likelihood
8763 that there will be more requests issued shortly, so that allows some
8766 There should be no data returned.
8769 @item (nnchoke-request-accept-article GROUP &optional LAST)
8771 This function takes the current buffer and inserts it into @var{group}.
8772 If @var{last} in @code{nil}, that means that there will be more calls to
8773 this function in short order.
8775 There should be no data returned.
8778 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
8780 This function should remove @var{article} (which is a number) from
8781 @var{group} and insert @var{buffer} there instead.
8783 There should be no data returned.
8786 @item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
8788 This function should delete @var{group}. If @var{force}, it should
8789 really delete all the articles in the group, and then delete the group
8790 itself. (If there is such a thing as "the group itself".)
8792 There should be no data returned.
8795 @item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
8797 This function should rename @var{group} into @var{new-name}. All
8798 articles that are in @var{group} should move to @var{new-name}.
8800 There should be no data returned.
8806 @node Score File Syntax
8807 @section Score File Syntax
8809 Score files are meant to be easily parsable, but yet extremely
8810 mallable. It was decided that something that had the same read syntax
8811 as an Emacs Lisp list would fit that spec.
8813 Here's a typical score file:
8817 ("win95" -10000 nil s)
8824 BNF definition of a score file:
8827 score-file = "" / "(" *element ")"
8828 element = rule / atom
8829 rule = string-rule / number-rule / date-rule
8830 string-rule = "(" quote string-header quote space *string-match ")"
8831 number-rule = "(" quote number-header quote space *number-match ")"
8832 date-rule = "(" quote date-header quote space *date-match ")"
8834 string-header = "subject" / "from" / "references" / "message-id" /
8835 "xref" / "body" / "head" / "all" / "followup"
8836 number-header = "lines" / "chars"
8837 date-header = "date"
8838 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
8839 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
8840 score = "nil" / <integer>
8841 date = "nil" / <natural number>
8842 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
8843 "r" / "regex" / "R" / "Regex" /
8844 "e" / "exact" / "E" / "Exact" /
8845 "f" / "fuzzy" / "F" / "Fuzzy"
8846 number-match = "(" <integer> [ "" / [ space score [ "" /
8847 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
8848 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
8849 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
8850 space date [ "" / [ space date-match-t ] ] ] ] ")"
8851 date-match-t = "nil" / "at" / "before" / "after"
8852 atom = "(" [ required-atom / optional-atom ] ")"
8853 required-atom = mark / expunge / mark-and-expunge / files /
8854 exclude-files / read-only / touched
8855 optional-atom = adapt / local / eval
8856 mark = "mark" space nil-or-number
8857 nil-or-number = "nil" / <integer>
8858 expunge = "expunge" space nil-or-number
8859 mark-and-expunge = "mark-and-expunge" space nil-or-number
8860 files = "files" *[ space <string> ]
8861 exclude-files = "exclude-files" *[ space <string> ]
8862 read-only = "read-only" [ space "nil" / space "t" ]
8863 adapt = "adapt" [ space "nil" / space "t" / space adapt-rule ]
8864 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
8865 local = "local" *[ space "(" <string> space <form> ")" ]
8866 eval = "eval" space <form>
8867 space = *[ " " / <TAB> / <NEWLINE> ]
8870 Any unrecognized elements in a score file should be ignored, but not
8873 As you can see, white space is needed, but the type and amount of white
8874 space is irrelevant. This means that formatting of the score file is
8875 left up to the programmer---if it's simpler to just spew it all out on
8876 one looong line, then that's ok.
8878 The meaning of the various atoms are explained elsewhere in this
8884 Gnus uses internally a format for storing article headers that
8885 corresponds to the @sc{nov} format in a mysterious fashion. One could
8886 almost suspect that the author looked at the @sc{nov} specification and
8887 just shamelessly @emph{stole} the entire thing, and one would be right.
8889 @dfn{Header} is a severly overloaded term. "Header" is used in RFC1036
8890 to talk about lines in the head of an article (eg., @code{From}). It is
8891 used by many people as a synonym for "head"---"the header and the
8892 body". (That should be avoided, in my opinion.) And Gnus uses a format
8893 interanally that it calls "header", which is what I'm talking about
8894 here. This is a 9-element vector, basically, with each header (ouch)
8897 These slots are, in order: @code{number}, @code{subject}, @code{from},
8898 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
8899 @code{xref}. There are macros for accessing and setting these slots --
8900 they all have predicatable names beginning with @code{mail-header-} and
8901 @code{mail-header-set-}, respectively.
8903 The @code{xref} slot is really a @code{misc} slot. Any extra info will
8909 @sc{gnus} introduced a concept that I found so useful that I've started
8910 using it a lot and have elaborated on it greatly.
8912 The question is simple: If you have a large amount of objects that are
8913 identified by numbers (say, articles, to take a @emph{wild} example)
8914 that you want to callify as being "included", a normal sequence isn't
8915 very useful. (A 200,000 length sequence is a bit long-winded.)
8917 The solution is as simple as the question: You just collapse the
8921 (1 2 3 4 5 6 10 11 12)
8930 To avoid having those nasty @samp{(13 . 13)} elements to denote a
8931 lonesome object, a @samp{13} is a valid element:
8934 ((1 . 6) 7 (10 . 12))
8937 This means that comparing two ranges to find out whether they are equal
8941 ((1 . 6) 7 8 (10 . 12))
8947 ((1 . 5) (7 . 8) (10 . 12))
8950 are equal. In fact, any non-descending list is a range:
8956 is a perfectly valid range, although a pretty longwinded one. This is
8963 and is equal to the previous range.
8965 Here's a BNF definition of ranges. Of course, one must remember the
8966 semantic requirement that the numbers are non-descending. (Any number
8967 of repetition of the same number is allowed, but apt to disappear in
8971 range = simple-range / normal-range
8972 simple-range = "(" number " . " number ")"
8973 normal-range = "(" start-contents ")"
8974 contents = "" / simple-range *[ " " contents ] /
8975 number *[ " " contents ]
8978 Gnus currently uses ranges to keep track of read articles and article
8979 marks. I plan on implementing a number of range operators in C if The
8980 Powers That Be are willing to let me. (I haven't asked yet, because I
8981 need to do some more thinking on what operators I need to make life
8982 totally range-based without ever having to convert back to normal
8989 Gnus stores all permanent info on groups in a @dfn{group info} list.
8990 This list is from three to six elements (or more) long and exhaustively
8991 describes the group.
8993 Here are two example group infos; one is a very simple group while the
8994 second is a more complex one:
8997 ("no.group" 5 (1 . 54324))
8999 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
9000 ((tick (15 . 19)) (replied 3 6 (19 . 23)))
9002 (auto-expire (to-address "ding@@ifi.uio.no")))
9005 The first element is the group name as Gnus knows the group; the second
9006 is the group level; the third is the read articles in range format; the
9007 fourth is a list of article marks lists; the fifth is the select method;
9008 and the sixth contains the group parameters.
9010 Here's a BNF definition of the group info format:
9013 info = "(" group space level space read
9014 [ "" / [ space marks-list [ "" / [ space method [ "" /
9015 space parameters ] ] ] ] ] ")"
9016 group = quote <string> quote
9017 level = <integer in the range of 1 to inf>
9019 marks-lists = nil / "(" *marks ")"
9020 marks = "(" <string> range ")"
9021 method = "(" <string> *elisp-forms ")"
9022 parameters = "(" *elisp-forms ")"
9025 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
9026 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
9044 @c outline-regexp: "@chap\\|@\\(sub\\)*section\\|@appendix \\|@appendix\\(sub\\)*sec\\|\^L"