1 \input texinfo @c -*-texinfo-*-
2 @comment %**start of header (This is for running Texinfo on a region.)
4 @settitle Gnus 5.0 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.
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 * Various:: General purpose settings.
90 * Customization:: Tailoring Gnus to your needs.
91 * Troubleshooting:: What you might try if things do not work.
92 * The End:: Farewell and goodbye.
93 * Appendix:: Technical stuff for technical people.
94 * Index:: Variable, function and concept index.
95 * Key Index:: Key Index.
102 @sc{gnus} was written by Masanobu UMEDA. When autumn crept up in '94,
103 Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
105 The recommended pronunciation of the name this program is "ding
106 guh-noose", with "ding" being half-sung in a loud, high-pitched voice,
107 and "guh-noose" being grumbled and a disaffected fashion. Any
108 irritation and/or damage this name may cause you is not the
109 responsibility of the author, even though you might like to strangle him
112 If you want to investigate the person responsible for this outrage, you
113 can point your (feh!) web browser to
114 @file{http://www.ifi.uio.no/~larsi/}. This is also the primary
115 distribution point for the new and spiffy versions of Gnus, also know as
116 The Site That Destroys Newsrcs And Drives People Mad.
118 During the first extended alpha period of develpment, the new Gnus was
119 called "(ding) Gnus". @dfn{(ding)}, is, of course, short for @dfn{ding
120 is not Gnus}, which is a total and utter lie, but who cares? (Besides,
121 the "Gnus" in this abbreviation should probably be pronounced "news" as
122 UMEDA intended, which makes it a more appropriate name, don't you
125 In any case, after spending all that energy with coming up with a new
126 and spiffy name, we decided that the name was @emph{too} spiffy, so we
127 renamamed it back again to "Gnus". But in mixed case. "Gnus" vs.
128 @sc{gnus}. New vs. old.
130 Incidentally, the next Gnus generation will be called "September Gnus",
131 and won't be released until February. Confused? You will be.
134 * Why?:: What's the point of Gnus?
135 * Compatibility:: Just how compatible is Gnus with @sc{gnus}?
136 * Conformity:: Gnus tries to conform to all standards.
137 * Contributors:: Oodles of people.
138 * New Features:: Pointers to some of the new stuff in Gnus.
139 * Newest Features:: Features so new that they haven't been written yet.
145 What's the point of Gnus?
147 I want to provide a "rad", "happening", "way cool" and "hep" newsreader,
148 that lets you do anything you can think of. That was my original
149 motivation, but while working on Gnus, it has become clear to me that
150 this generation of newsreaders really belong in the stone age.
151 Newsreaders haven't developed much since the infancy of the net. If the
152 volume continues to rise with the current rate of increase, all current
153 newsreaders will be pretty much useless. How do you deal with
154 newsgroups that have hundreds (or thousands) of new articles each day?
156 Gnus offer no real solutions to these questions, but I would very much
157 like to see Gnus being used as a testing ground for new methods of
158 reading and fetching news. Expanding on Umeda-san's wise decision to
159 separate the newsreader from the backends, Gnus now offers a simple
160 interface for anybody who wants to write new backends for fetching mail
161 and news from different sources. I have added hooks for customizations
162 everywhere I can imagine useful. By doing so, I'm inviting every one of
163 you to explore and invent new ways of reading news.
165 May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
168 @section Compatibility
170 @cindex compatibility
171 Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
172 bindings have been kept. More key bindings have been added, of course,
173 but only in one or two obscure cases have old bindings been changed.
178 @center In a cloud bones of steel.
182 All commands have kept their names. Some internal functions have changed
185 The @code{gnus-uu} package has changed drastically. @xref{Decoding
188 One major compatibility question if the presence of several summary
189 buffers. All variables that are relevant while reading a group are
190 buffer-local to the summary buffer they belong in. Although most
191 important variables have their values copied into their global
192 counterparts whenever a command is executed in the summary buffer, this
193 change might lead to incorrect values being used unless you are careful.
195 All code that relies on knowledge of @sc{gnus} internals will probably
196 fail. To take two examples: Sorting @code{gnus-newsrc-assoc} (or
197 changing it in any way, as a matter of fact) is strictly verboten. Gnus
198 maintains a hash table that points to the entries in this assoc (which
199 speeds up many functions), and changing the assoc directly will lead to
204 Old hilit19 code does not work at all. In fact, you should probably
205 remove all hilit code from all Gnus hooks
206 (@code{gnus-group-prepare-hook}, @code{gnus-summary-prepare-hook} and
207 @code{gnus-summary-article-hook}). (Well, at the very least the first
208 two.) Gnus provides various integrated functions for highlighting.
209 These are faster and more accurate. To make life easier for everybody,
210 Gnus will by default remove all hilit calls from all hilit hooks.
213 Packages like @code{expire-kill} will no longer work. As a matter of
214 fact, you should probably remove all old @sc{gnus} packages (and other
215 code) when you start using Gnus. More likely than not, Gnus already
216 does what you have written code to make @sc{gnus} do. (Snicker.)
218 Even though old methods of doing things are still supported, only the
219 new methods are documented in this manual. If you detect a new method of
220 doing something while reading this manual, that does not mean you have
221 to stop doing it the old way.
223 Gnus understands all @sc{gnus} startup files.
226 Overall, a casual user who hasn't written much code that depends on
227 @sc{gnus} internals should suffer no problems. If problems occur,
228 please let me know (@kbd{M-x gnus-bug}).
230 Problems specific to GNU XEmacs can be reported to popineau@@ese-metz.fr
231 (Fabrice Popineau). I will just forward any such questions to him,
232 anyway, so you might have to wait longer if you mail XEmacs questions to
239 No rebels without a clue here, ma'am. We conform to all standards known
240 to man. Except, of course, where we disagree with the standards and/or
246 There are no known breaches to this standard.
249 There are no known breaches to this standard, either.
251 @item Usenet Seal of Approval
252 Gnus hasn't been formally through the Seal process, but I have read
253 through the Seal text, and I think that Gnus would pass.
255 @item Son-of-RFC 1036
256 We do have some breaches to this one.
260 Gnus does no MIME handling, and this standard-to-be seems to think that
261 MIME is the bees' knees, so we have major breakage here.
263 This is considered to be a "vanity header", while I consider it to be
264 consumer information. After seeing so many badly formatted articles
265 coming from @code{tin} and @code{Netscape} I know not to use either of
266 those for posting articles. I would not have known that if it wasn't
267 for the @code{X-Newsreader} header.
269 Gnus does line breaking on this header. I infer from RFC1036 that being
270 conservative in what you output is not creating 5000-character lines, so
271 it seems like a good idea to me. However, this standard-to-be says that
272 whitespace in the @code{References} header is to be preserved, so... It
273 doesn't matter one way or the other to Gnus, so if somebody tells me
274 what The Way is, I'll change it. Or not.
279 If you ever see Gnus act noncompliantly to the texts mentioned above,
280 don't hesitate to drop a note to Gnus Towers and let us know.
284 @section Contributors
287 The new Gnus version couldn't have been done without the help of all the
288 people on the (ding) mailing list. Every day for months I have gotten
289 tens of nice bug reports from them, filling me with joy, every single
290 one of them. Smooches. The people on the list have been tried beyond
291 endurance, what with my "oh, that's a neat idea <type type>, yup, I'll
292 release it right away <ship off> no wait, that doesn't work at all <type
293 type>, yup, I'll ship that one off right away <ship off> no, wait, that
294 absolutely does not work" policy for releases. Microsoft - bah. I'm
297 I would like to take this opportunity to thank the Academy for... oops,
302 Of course, GNUS was written by Masanobu UMEDA.
304 Many excellent functions, especially dealing with scoring and
305 highlighting (as well as the soon-to-come @sc{soup} support) was written
308 Innumerable bug fixes were written by Sudish Joseph.
310 The refcard was written by Vladimir Alexiev.
312 I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
314 nnfolder has been much enhanced by Scott Byer.
316 The orphan scoring was written by Peter Mutsaers.
318 GNU XEmacs support has been added by Fabrice Popineau.
320 Various bits and pieces, especially dealing with .newsrc files, was
321 suggested and added by Hallvard B Furuseth.
323 Brian Edmonds has written @code{gnus-bbdb}, as well as other bits and
326 Ricardo Nassif did the proof-reading.
328 Kevin Davidson came up with the name @dfn{ding}, so blame him.
330 Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel Quinlan, Ilja
331 Weis, Frank D. Cringle, Geoffrey T. Dairiki and Andrew Eskilsson have
332 all contributed code and suggestions.
337 @section New Features
343 The look of all buffers can be changed by setting format-like variables
344 (@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
347 Local spool and several @sc{nntp} servers can be used at once
348 (@pxref{Foreign Groups}).
351 You can combine groups into virtual groups (@pxref{nnvirtual}).
354 You can read a number of different mail formats (@pxref{Reading Mail}).
355 All the mail backends implement a convenient mail expiry scheme
356 (@code{Expiring Old Mail Articles}).
359 Gnus can use various strategies for gathering threads that have lost
360 their roots (thereby gathering loose sub-threads in one thread) or it
361 can go back and retrieve enough headers to build a complete thread
362 (@pxref{Customizing Threading}).
365 Killed groups can be displayed in the group buffer, and you can read
369 Gnus can do partial group updates - you do not have to retrieve the
370 entire active file just to check for new articles in a few groups
371 (@pxref{The Active File}).
374 Gnus implements a sliding scale of subscribedness to groups
375 (@pxref{Group Levels}).
378 You can score articles according to any number of criteria (@pxref{Score
379 Files}). You can even get Gnus to score articles for you
380 (@pxref{Adaptive Scoring}).
383 Gnus maintains a dribble buffer that is auto-saved the normal Emacs
384 manner, so it should be difficult to lose much data on what you have
385 read if your machine should go down (@pxref{Auto Save}).
388 Gnus now has its own startup file to avoid cluttering up the
392 You can set the process mark on both groups and articles and perform
393 operations on all the marked items (@pxref{Process/Prefix}).
396 You can grep through a subset of groups and create a group from the
397 results (@pxref{nnkiboze}).
400 You can list subsets of groups according to, well, anything
401 (@pxref{Listing Groups}).
404 You can browse foreign servers and subscribe to groups from those
405 servers (@pxref{Browse Foreign Server}).
408 Gnus can fetch articles asynchronously on a second connection to the
409 server (@pxref{Asynchronous Fetching}).
412 You can cache articles locally (@pxref{Article Caching}).
415 The uudecode functions have been expanded and generalized
416 (@pxref{Decoding Articles}).
419 You can still post uuencoded articles, which was a little-known feature
420 of @sc{gnus} past (@pxref{Uuencoding & Posting}).
423 Fetching parents (and other articles) now actually works without
424 glitches (@pxref{Finding the Parent}).
427 Gnus can fetch FAQs to and descriptions of groups (@pxref{Group
431 Digests (and other files) can be used as the basis for groups
435 Articles can be highlighted and customized (@pxref{Customizing
439 All Gnus buffers can be customized in a difficult fashion
440 (@pxref{Windows Configuration}).
443 You can click on buttons instead of using the keyboard
448 This is, of course, just a @emph{short} overview of the @emph{most}
449 important new features. No, really. There are tons more. Yes, we have
450 feeping creaturism in full effect, but nothing too gratuitous, I would
454 @node Newest Features
455 @section Newest Features
458 Also known as the @dfn{todo list}. Sure to be implemented before the
461 Be afraid. Be very afraid.
465 Native @sc{mime} support is something that should be done. I was hoping
466 I could steal code from @code{Mew}, the @sc{mime} mail reader for Emacs,
467 but I'm not quite sure what the status of that project is. Gnus might
468 support @sc{mime} quite soon, and it might not.
471 @code{trn}-like trees.
473 @code{nn}-like pick-and-read summary interface.
479 Re-sending bounced mail and rejected articles.
481 Floating point group levels and group bubbling.
483 @file{/etc/nntpserver} usage.
485 Automatic re-scan of incoming mail.
487 Buttonize more stuff in the article buffer.
489 A better and simpler method for specifying mail composing methods.
491 Marks for saved, forwarded, etc articles.
493 Speed up caching and adaptive scoring.
495 Gather thread by filling in missing Message-IDs.
497 Slave Gnusii to enable several Gnusii to run at once.
501 Allow posting through mail-to-news gateways.
503 Allow renaming mail groups in a simple fashion.
505 Speed up massive group massacres.
507 @code{jka-compr} isn't fully supported.
509 Create better digests.
511 Do better word-wrap on cited text.
513 Better X-Face support with X-Face databases and stuff.
515 Support SELF-DISCIPLINE pins.
517 Really do unbinhexing.
519 Fetching by Message-ID should work in mail groups.
521 Listing of all active groups.
525 Do the X-Receipt-To thing.
527 Hierarchal group buffers.
529 Don't kill summary buffers upon exit from the groups.
531 Allow adaption on secondary marks.
534 And much, much, much more. There is more to come than has already been
535 implemented. (But that's always true, isn't it?)
537 You can probably sneak a look at the actual up-to-the-second todo list
538 by snooping @code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>}.
547 This is what you are supposed to use this thing for - reading news.
548 News is generally fetched from a nearby @sc{nntp} server, and is
549 generally publicly available to everybody. If you post news, the entire
550 world is likely to read just what you have written, and they'll all
551 snigger mischievously. Behind your back.
554 Everything that's delivered to you personally is mail. Some news/mail
555 readers (like Gnus) blur the distinction between mail and news, but
556 there is a difference. Mail is private. News is public. Mailing is
557 not posting, and replying is not following up.
559 Send a mail to the person who has written what you are reading.
561 Post an article to the current newsgroup responding to the article you
564 Gnus gets fed articles from a number of backends, both news and mail
565 backends. Gnus does not handle the underlying media, so to speak - this
566 is all done by the backends.
568 Gnus will always use one method (and backend) as the @dfn{native}, or
569 default, way of getting news.
571 You can also have any number of foreign groups at the same time. These
572 are groups that use different backends for getting news.
575 The top part of an article, where administration information (etc.) is
579 The rest of an article. Everything that is not in the head is in the
583 A line from the head of an article.
586 A collection of such lines, or a collection of heads. Or even a
587 collection of @sc{nov} lines.
590 When Gnus enters a group, it asks the backend for the headers for all
591 the unread articles in the group. Most servers support the News OverView
592 format, which is much smaller and much faster to read than the normal
596 Each group is subscribed at some @dfn{level} or other (1-9). The ones
597 that have a lower level are "more" subscribed than the groups with a
598 higher level. In fact, groups on levels 1-5 are considered
599 @dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
600 are @dfn{killed}. Commands for listing groups and scanning for new
601 articles will all use the numeric prefix as @dfn{working level}.
603 @cindex killed groups
604 No information on killed groups is stored or updated, which makes killed
605 groups much easier to handle than subscribed groups.
607 @cindex zombie groups
608 Just like killed groups, only slightly less dead.
611 The news server has to keep track of what articles it carries, and what
612 groups exist. All this information in stored in the active file, which
613 is rather large, as you might surmise.
616 A group that exists in the @file{.newsrc} file, but isn't known to the
617 server (i. e., it isn't in the active file), is a @emph{bogus group}.
618 This means that the group probably doesn't exist (any more).
622 @chapter Starting Gnus
626 If your system administrator has set things up properly, starting Gnus
627 and reading news is extremely easy - you just type @kbd{M-x gnus}.
629 If things do not go smoothly at startup, you have to twiddle some
633 * Finding the News:: Choosing a method for getting news.
634 * The First Time:: What does Gnus do the first time you start it?
635 * The Server is Down:: How can I read my mail then?
636 * New Groups:: What is Gnus supposed to do with new groups?
637 * Startup Files:: Those pesky startup files - @file{.newsrc}.
638 * Auto Save:: Recovering from a crash.
639 * The Active File:: Reading the active file over a slow line Takes Time.
640 * Startup Variables:: Other variables you might change.
643 @node Finding the News
644 @section Finding the News
646 @vindex gnus-select-method
647 The @code{gnus-select-method} variable controls how Gnus finds news.
648 This variable should be a list where the first element says @dfn{how}
649 and the second element says @dfn{where}. This method is is your native
650 method. All groups that are not fetched with this method are foreign
653 For instance, if you want to get your daily dosage of news from the
654 @samp{news.somewhere.edu} @sc{nntp} server, you'd say:
657 (setq gnus-select-method '(nntp "news.somewhere.edu"))
660 If you want to read directly from the local spool, say:
663 (setq gnus-select-method '(nnspool ""))
666 If you can use a local spool, you probably should, as it will almost
667 certainly be much faster.
669 If this variable is not set, Gnus will take a look at the
670 @code{NNTPSERVER} environment variable. If that isn't set either, it
671 will try to use the machine that is running Emacs as an @sc{nntp}
674 @vindex gnus-nntp-server
675 If @code{gnus-nntp-server} is set, this variable will override
676 @code{gnus-select-method}. You should therefore set
677 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
679 @vindex gnus-secondary-servers
680 You can also make Gnus prompt you interactively for the name of an
681 @sc{nntp} server. If you give a non-numerical prefix to @code{gnus}
682 (i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
683 in the @code{gnus-secondary-servers} list (if any). You can also just
684 type in the name of any server you feel like visiting.
686 However, if you use one @sc{nntp} server regularly, and are just
687 interested in a couple of groups from a different server, you would be
688 better served by using the @code{gnus-group-browse-foreign-server}
689 command from the group buffer. It will let you have a look at what
690 groups are available, and you can subscribe to any of the groups you
691 want to. This also makes @file{.newsrc} maintenance much tidier.
692 @xref{Foreign Groups}.
694 @vindex gnus-secondary-select-methods
695 A slightly different approach to foreign groups is to set the
696 @code{gnus-secondary-select-methods} variable. The select methods
697 listed in this variable are in many ways just as native as the
698 @code{gnus-select-method} server. They will also be queried for active
699 files during startup (if that's required), and new newsgroups that
700 appear on these servers will be subscribed (or not) just as native
703 For instance, if you use the @code{nnmbox} backend to read you mail, you
704 would typically set this variable to
707 (setq gnus-secondary-select-methods '((nnmbox "")))
711 @section The First Time
712 @cindex first time usage
714 If no startup files exist, Gnus will try to determine what groups should
715 be subscribed by default.
717 @vindex gnus-default-subscribed-newsgroups
718 If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
719 will subscribe you to just those groups in that list, leaving the rest
720 killed. Your system administrator should have set this variable to
723 Since she hasn't, Gnus will just subscribe you to a few randomly picked
724 groups (i.e., @samp{*.newusers}). (@dfn{Random} is here defined as
725 "whatever Lars thinks you should read".)
727 You'll also be subscribed to the Gnus documentation group, which should
728 help you with most common problems.
730 If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
731 use the normal functions for handling new groups, and not do anything
734 @node The Server is Down
735 @section The Server is Down
736 @cindex server errors
738 If the default server is down, Gnus will understandably have some
739 problems starting. However, if you have some mail groups in addition to
740 the news groups, you may want to start Gnus anyway.
742 Gnus, being the trusting sort of program, will ask whether to proceed
743 without a native select method if that server can't be contacted. This
744 will happen whether the server doesn't actually exist (i.e., you have
745 given the wrong address) or the server has just momentarily taken ill
746 for some reason or other.
748 If Gnus says "nntp server on <your server> can't be opened. Continue?",
749 you do not want to continue unless you have some foreign groups that you
750 want to read. Even if you don't, Gnus will let you continue, but you'll
751 find it difficult to actually do anything in the group buffer. But,
752 hey, that's your problem. Blllrph!
758 @vindex gnus-subscribe-newsgroup-method
759 What Gnus does when it encounters a new group is determined by the
760 @code{gnus-subscribe-newsgroup-method} variable.
762 This variable should contain a function. Some handy pre-fab values
766 @item gnus-subscribe-randomly
767 @vindex gnus-subscribe-randomly
768 Subscribe all new groups randomly.
769 @item gnus-subscribe-alphabetically
770 @vindex gnus-subscribe-alphabetically
771 Subscribe all new groups alphabetically.
772 @item gnus-subscribe-hierarchically
773 @vindex gnus-subscribe-hierarchically
774 Subscribe all new groups hierarchically.
775 @item gnus-subscribe-interactively
776 @vindex gnus-subscribe-interactively
777 Subscribe new groups interactively. This means that Gnus will ask
778 you about @strong{all} new groups.
779 @item gnus-subscribe-zombies
780 @vindex gnus-subscribe-zombies
781 Make all new groups zombies. You can browse the zombies later and
782 either kill them all off properly, or subscribe to them. This is the
786 @vindex gnus-subscribe-hierarchical-interactive
787 A closely related variable is
788 @code{gnus-subscribe-hierarchical-interactive}. (That's quite a
789 mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a
790 hierarchical fashion whether to subscribe to new groups or not. Gnus
791 will ask you for each sub-hierarchy whether you want to descend the
794 One common way to control which new newsgroups should be subscribed or
795 ignored is to put an @dfn{options} line at the start of the
796 @file{.newsrc} file. Here's an example:
799 options -n !alt.all !rec.all sci.all
802 @vindex gnus-subscribe-options-newsgroup-method
803 This line obviously belongs to a serious-minded intellectual scientific
804 person (or she may just be plain old boring), because it says that all
805 groups that have names beginning with @samp{alt} and @samp{rec} should
806 be ignored, and all groups with names beginning with @samp{sci} should
807 be subscribed. Gnus will not use the normal subscription method for
808 subscribing these groups.
809 @code{gnus-subscribe-options-newsgroup-method} is used instead. This
810 variable defaults to @code{gnus-subscribe-alphabetically}.
812 @vindex gnus-options-not-subscribe
813 @vindex gnus-options-subscribe
814 If you don't want to mess with your @file{.newsrc} file, you can just
815 set the two variables @code{gnus-options-subscribe} and
816 @code{gnus-options-not-subscribe}. These two variables do exactly the
817 same as the @file{.newsrc} options -n trick. Both are regexps, and if
818 the the new group matches the first, it will be unconditionally
819 subscribed, and if it matches the latter, it will be ignored.
821 @vindex gnus-check-new-newsgroups
822 If you are satisfied that you really never want to see any new groups,
823 you could set @code{gnus-check-new-newsgroups} to @code{nil}. This will
824 also save you some time at startup. Even if this variable is
825 @code{nil}, you can always subscribe to the new groups just by pressing
826 @kbd{U} in the group buffer (@pxref{Group Maintenance}).
828 Gnus normally determines whether a group is new or not by comparing the
829 list of groups from the active file(s) with the lists of subscribed and
830 dead groups. This isn't a particularly fast method. If
831 @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
832 server for new groups since the last time. This is both faster &
833 cheaper. This also means that you can get rid of the list of killed
834 groups altogether, so you may set @code{gnus-save-killed-list} to
835 @code{nil}, which will save time both at startup, at exit, and all over.
836 Saves disk space, too. Why isn't this the default, then?
837 Unfortunately, not all servers support this function.
839 This variable can also be a list of select methods. If so, Gnus will
840 issue an @code{ask-server} command to each of the select methods, and
841 subscribe them (or not) using the normal methods. This might be handy
842 if you are monitoring a few servers for new groups. A side effect is
843 that startup will take much longer, so you can meditate while waiting.
844 Use the mantra "dingnusdingnusdingnus" to achieve permanent happiness.
847 @section Startup Files
848 @cindex startup files
851 Now, you all know about the @file{.newsrc} file. All subscription
852 information is traditionally stored in this file.
854 Things got a bit more complicated with @sc{gnus}. In addition to
855 keeping the @file{.newsrc} file updated, it also used a file called
856 @file{.newsrc.el} for storing all the information that didn't fit into
857 the @file{.newsrc} file. (Actually, it duplicated everything in the
858 @file{.newsrc} file.) @sc{gnus} would read whichever one of these files
859 that were the most recently saved, which enabled people to swap between
860 @sc{gnus} and other newsreaders.
862 That was kinda silly, so Gnus went one better: In addition to the
863 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
864 @file{.newsrc.eld}. It will read whichever of these files that are most
865 recent, but it will never write a @file{.newsrc.el} file.
867 @vindex gnus-save-newsrc-file
868 You can also turn off writing the @file{.newsrc} file by setting
869 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
870 the file and save some space, as well as making exit from Gnus faster.
871 However, this will make it impossible to use other newsreaders than
872 Gnus. But hey, who would want to, right?
874 @vindex gnus-save-killed-list
875 If @code{gnus-save-killed-list} is @code{nil}, Gnus will not save the
876 list of killed groups to the startup file. This will save both time
877 (when starting and quitting) and space (on disk). It will also means
878 that Gnus has no record of what groups are new or old, so the automatic
879 new groups subscription methods become meaningless. You should always
880 set @code{gnus-check-new-newsgroups} to @code{nil} or @code{ask-server}
881 if you set this variable to @code{nil} (@pxref{New Groups}).
883 @vindex gnus-startup-file
884 The @code{gnus-startup-file} variable says where the startup files are.
885 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
886 file being whatever that one is with a @samp{.eld} appended.
888 @vindex gnus-save-newsrc-hook
889 @code{gnus-save-newsrc-hook} is called before saving the @file{.newsrc}
897 Whenever you do something that changes the Gnus data (reading articles,
898 catching up, killing/subscribing groups), the change is added to a
899 special @dfn{dribble buffer}. This buffer is auto-saved the normal
900 Emacs way. If your Emacs should crash before you have saved the
901 @file{.newsrc} files, all changes you have made can be recovered from
904 If Gnus detects this file at startup, it will ask the user whether to
905 read it. The auto save file is deleted whenever the real startup file is
908 @vindex gnus-use-dribble-file
909 If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
910 maintain a dribble buffer.
912 @node The Active File
913 @section The Active File
915 @cindex ignored groups
917 When Gnus starts, or indeed whenever it tries to determine whether new
918 articles have arrived, it reads the active file. This is a very large
919 file that lists all the active groups and articles on the @sc{nntp}
922 @vindex gnus-ignored-newsgroups
923 Before examining the active file, Gnus deletes all lines that match the
924 regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject
925 any groups with bogus names, but you can use this variable to make Gnus
926 ignore hierarchies you aren't ever interested in. This variable is
927 @code{nil} by default, and will slow down active file handling somewhat
928 if you set it to anything else.
930 @vindex gnus-read-active-file
931 The active file can be rather Huge, so if you have a slow network, you
932 can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
933 reading the active file.
935 Gnus will try to make do by just getting information on the groups
936 that you actually subscribe to.
938 Note that if you subscribe to lots and lots of groups, setting this
939 variable to @code{nil} will probably make Gnus slower, not faster. At
940 present, having this variable @code{nil} will slow Gnus down
941 considerably, unless you read news over a 2400 baud modem.
943 This variable can also have the value @code{some}. Gnus will then
944 attempt to read active info only on the subscribed groups. On some
945 servers this is quite fast (on sparkling, brand new INN servers that
946 support the @samp{LIST ACTIVE group} command), on others this is not
947 fast at all. In any case, @code{some} should be faster than @code{nil},
948 and is certainly faster than @code{t} over slow lines.
950 If this variable is @code{nil}, Gnus will as for group info in total
951 lock-step, which isn't very fast. If it is @code{some} and you use an
952 NNTP server, Gnus will pump out commands as fast as it can, and read all
953 the replies in one swoop. This will normally result in better
954 performance, but if the server does not support the aforementioned
955 @samp{LIST ACTIVE group} command, this isn't very nice to the server.
957 In any case, if you use @code{some} or @code{nil}, you should kill all
958 groups that you aren't interested in.
960 @node Startup Variables
961 @section Startup Variables
965 @vindex gnus-load-hook
966 A hook that is run while Gnus is being loaded. Note that this hook will
967 normally be run just once in a single Emacs session, no matter how many
968 times you start Gnus.
970 @item gnus-startup-hook
971 @vindex gnus-startup-hook
972 A hook that is run after starting up Gnus successfully.
974 @item gnus-check-bogus-newsgroups
975 @vindex gnus-check-bogus-newsgroups
976 If non-@code{nil}, Gnus will check for and delete all bogus groups at
977 startup. A @dfn{bogus group} is a group that you have in your
978 @file{.newsrc} file, but doesn't exist on the news server. Checking for
979 bogus groups isn't very quick, so to save time and resources, it's best
980 to leave this option off, and instead do the checking for bogus groups
981 once in a while from the group buffer (@pxref{Group Maintenance}).
983 @item gnus-inhibit-startup-message
984 @vindex gnus-inhibit-startup-message
985 If non-@code{nil}, the startup message won't be displayed. That way,
986 your boss might not notice that you are reading news instead of doing
989 @item gnus-no-groups-message
990 @vindex gnus-no-groups-message
991 Message displayed by Gnus when no groups are available.
994 @node The Group Buffer
995 @chapter The Group Buffer
998 The @dfn{group buffer} lists all (or parts) of the available groups. It
999 is the first buffer shown when Gnus starts, and will never be killed as
1000 long as Gnus is active.
1003 * Group Buffer Format:: Information listed and how you can change it.
1004 * Group Maneuvering:: Commands for moving in the group buffer.
1005 * Selecting a Group:: Actually reading news.
1006 * Group Subscribing:: Unsubscribing, killing, subscribing.
1007 * Group Levels:: Levels? What are those, then?
1008 * Marking Groups:: You can mark groups for later processing.
1009 * Foreign Groups:: How to create foreign groups.
1010 * Group Parameters:: Each group may have different parameters set.
1011 * Listing Groups:: Gnus can list various subsets of the groups.
1012 * Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
1013 * Browse Foreign Server:: You can browse a server. See what if has to offer.
1014 * Exiting Gnus:: Stop reading news and get some work done.
1015 * Misc Group Stuff:: Other stuff that you can to do.
1018 @node Group Buffer Format
1019 @section Group Buffer Format
1020 @cindex group buffer format
1022 The default format of the group buffer is nice and dull, but you can
1023 make it as exciting and ugly as you feel like.
1025 Here's a couple of example group lines:
1028 25: news.announce.newusers
1029 * 0: alt.fan.andrea-dworkin
1034 You can see that there are 25 unread articles in
1035 @samp{news.announce.newusers}. There are no unread articles, but some
1036 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
1037 asterisk at the beginning of the line?)
1039 @vindex gnus-group-line-format
1040 You can fuck that up to your heart's delight by fiddling with the
1041 @code{gnus-group-line-format} variable. This variable works along the
1042 lines of a @code{format} specification, which is pretty much the same as
1043 a @code{printf} specifications, for those of you who use (feh!) C.
1045 In addition to the normal "padding" specs that @code{format} supports
1046 (eg. @samp{%7d}), specifications like @samp{%7,12s} are allowed. A spec
1047 of this type means that the field will be at least 7 characters long,
1048 and never more that 12 characters long.
1050 The default value that produced those lines above is
1051 @samp{"%M%S%5y: %(%g%)\n"}.
1053 There should always be a colon on the line; the cursor always moves to
1054 the colon after performing an operation. Nothing else is required - not
1055 even the group name. All displayed text is just window dressing, and is
1056 never examined by Gnus. Gnus stores all real information it needs using
1059 (Note that if you make a really strange, wonderful, spreadsheet-like
1060 layout, everybody will believe you are hard at work with the accounting
1061 instead of wasting time reading news.)
1063 Here's a list of all available format characters:
1067 Only marked articles.
1069 Whether the group is subscribed.
1071 Level of subscribedness.
1073 Number of unread articles.
1075 Number of dormant articles.
1077 Number of ticked articles.
1079 Number of read articles.
1081 Total number of articles.
1083 Number of unread, unticked, non-dormant articles.
1085 Number of ticked and dormant articles.
1091 Newsgroup description.
1101 A string that looks like @samp{<%s:%n>} if a foreign select method is
1104 User defined specifier. The next character in the format string should
1105 be a letter. @sc{gnus} will call the function
1106 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
1107 following @samp{%u}. The function will be passed the current headers as
1108 argument. The function should return a string, which will be inserted
1109 into the buffer just like information from any other specifier.
1113 All the "number-of" specs will be filled with an asterisk (@samp{*}) if
1114 no info is available - for instance, if it is a non-activated foreign
1115 group, or a bogus (or semi-bogus) native group.
1117 @vindex gnus-group-mode-line-format
1118 The mode line can be changed by setting
1119 (@code{gnus-group-mode-line-format}). It doesn't understand that many
1124 Default news server.
1126 Default select method.
1129 @node Group Maneuvering
1130 @section Group Maneuvering
1131 @cindex group movement
1133 All movement commands understand the numeric prefix and will behave as
1134 expected, hopefully.
1139 @findex gnus-group-next-unread-group
1140 Go to the next group that has unread articles
1141 (@code{gnus-group-next-unread-group}).
1146 @findex gnus-group-prev-unread-group
1147 Go to the previous group group that has unread articles
1148 (@code{gnus-group-prev-unread-group}).
1151 @findex gnus-group-next-group
1152 Go to the next group (@code{gnus-group-next-group}).
1155 @findex gnus-group-prev-group
1156 Go to the previous group (@code{gnus-group-prev-group}).
1159 @findex gnus-group-next-unread-group-same-level
1160 Go to the next unread group on the same level (or lower)
1161 (@code{gnus-group-next-unread-group-same-level}).
1164 @findex gnus-group-prev-unread-group-same-level
1165 Go to the previous unread group on the same level (or lower)
1166 (@code{gnus-group-prev-unread-group-same-level}).
1169 Three commands for jumping to groups:
1174 @findex gnus-group-jump-to-group
1175 Jump to a group (and make it visible if it isn't already)
1176 (@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
1180 @findex gnus-group-best-unread-group
1181 Jump to the unread group with the lowest level
1182 (@code{gnus-group-best-unread-group}).
1185 @findex gnus-group-first-unread-group
1186 Jump to the first group with unread articles
1187 (@code{gnus-group-first-unread-group}).
1190 @vindex gnus-group-goto-unread
1191 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
1192 commands will move to the next group, not the next unread group. Even
1193 the commands that say they move to the next unread group.
1195 @node Selecting a Group
1196 @section Selecting a Group
1197 @cindex group selection
1201 @kindex SPACE (Group)
1202 @findex gnus-group-read-group
1203 Select the current group, switch to the summary buffer and display the
1204 first unread article (@code{gnus-group-read-group}). If there are no
1205 unread articles in the group, or if you give a non-numerical prefix to
1206 this command, Gnus will offer to fetch all the old articles in this
1207 group from the server. If you give a numerical prefix @var{N}, Gnus
1208 will fetch @var{N} number of articles. If @var{N} is positive, fetch
1209 the @var{N} newest articles, if @var{N} is negative, fetch the
1210 @var{abs(N)} oldest articles.
1213 @findex gnus-group-select-group
1214 Select the current group and switch to the summary buffer
1215 (@code{gnus-group-select-group}). Takes the same arguments as
1216 @code{gnus-group-read-group} - the only difference is that this command
1217 does not display the first unread article automatically upon group
1221 @findex gnus-group-catchup-current
1222 Mark all unticked articles in this group as read
1223 (@code{gnus-group-catchup-current}).
1226 @findex gnus-group-catchup-current-all
1227 Mark all articles in this group, even the ticked ones, as read
1228 (@code{gnus-group-catchup-current-all}).
1231 @vindex gnus-large-newsgroup
1232 The @code{gnus-large-newsgroup} variable says what Gnus should consider
1233 to be a big group. If the group has more unread articles than this,
1234 Gnus will query the user before entering the group. The user can then
1235 specify how many articles should be fetched from the server. If the
1236 user specifies a negative number (@samp{-n}), the @samp{n} oldest
1237 articles will be fetched. If it is positive, the @samp{n} articles that
1238 have arrived most recently will be fetched.
1240 @vindex gnus-select-group-hook
1241 @vindex gnus-auto-select-first
1242 If @code{gnus-auto-select-first} is non-@code{nil}, the first unread
1243 article in the group will be displayed when you enter the group. If you
1244 want to prevent automatic selection in some group (say, in a binary
1245 group with Huge articles) you can set this variable to @code{nil} in
1246 @code{gnus-select-group-hook}, which is called when a group is selected.
1248 @findex gnus-thread-sort-by-total-score
1249 @findex gnus-thread-sort-by-date
1250 @findex gnus-thread-sort-by-score
1251 @findex gnus-thread-sort-by-subject
1252 @findex gnus-thread-sort-by-author
1253 @findex gnus-thread-sort-by-number
1254 @vindex gnus-thread-sort-functions
1255 If you are using a threaded summary display, you can sort the threads by
1256 setting @code{gnus-thread-sort-functions}, which is a list of functions.
1257 By default, sorting is done on article numbers. Ready-made sorting
1258 functions include @code{gnus-thread-sort-by-number},
1259 @code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
1260 @code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score},
1261 @code{gnus-thread-sort-by-total-score}.
1263 Each function takes two threads and return non-@code{nil} if the first
1264 thread should be sorted before the other. If you use more than one
1265 function, the primary sort key should be the last function in the list.
1267 If you would like to sort by score, then by subject, and finally by
1268 date, you could do something like:
1271 (setq gnus-thread-sort-functions
1272 '(gnus-thread-sort-by-date
1273 gnus-thread-sort-by-subject
1274 gnus-thread-sort-by-score))
1277 @vindex gnus-thread-score-function
1278 The function in the @code{gnus-thread-score-function} variable (default
1279 @code{+}) is used for calculating the total score of a thread. Useful
1280 functions might be @code{max}, @code{min}, or squared means, or whatever
1283 @node Group Subscribing
1284 @section Group Subscribing
1292 @findex gnus-group-unsubscribe-current-group
1293 Toggle subscription to the current group
1294 (@code{gnus-group-unsubscribe-current-group}).
1299 @findex gnus-group-unsubscribe-group
1300 Prompt for a group to subscribe, and then subscribe it. If it was
1301 subscribed already, unsubscribe it instead
1302 (@code{gnus-group-unsubscribe-group}).
1307 @findex gnus-group-kill-group
1308 Kill the current group (@code{gnus-group-kill-group}).
1313 @findex gnus-group-yank-group
1314 Yank the last killed group (@code{gnus-group-yank-group}).
1319 @findex gnus-group-kill-region
1320 Kill all groups in the region (@code{gnus-group-kill-region}).
1323 @findex gnus-group-kill-all-zombies
1324 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
1328 @section Group Levels
1331 All groups have a level of @dfn{subscribedness}. For instance, if a
1332 group is on level 2, it is more subscribed than a group on level 5. You
1333 can ask Gnus to just list groups on a given level or lower
1334 (@pxref{Listing Groups}), or to just check for new articles in groups on
1335 a given level or lower (@pxref{Misc Group Stuff}).
1340 @findex gnus-group-set-current-level
1341 Set the level of the current group. If a numeric prefix is given, the
1342 next @var{n} groups will have their levels set. The user will be
1343 prompted for a level.
1346 @vindex gnus-level-killed
1347 @vindex gnus-level-zombie
1348 @vindex gnus-level-unsubscribed
1349 @vindex gnus-level-subscribed
1350 Gnus considers groups on between levels 1 and
1351 @code{gnus-level-subscribed} (inclusive) to be subscribed,
1352 @code{gnus-level-subscribed} (exclusive) and
1353 @code{gnus-level-unsubscribed} (inclusive) to be unsubscribed,
1354 @code{gnus-level-zombie} to be zombies (walking dead) and
1355 @code{gnus-level-killed} to be killed, completely dead. Gnus treats
1356 subscribed and unsubscribed groups exactly the same, but zombie and
1357 killed groups have no information on what articles you have read, etc,
1358 stored. This distinction between dead and living groups isn't done
1359 because it is nice or clever, it is done purely for reasons of
1362 It is recommended that you keep all your mail groups (if any) on quite
1363 low levels (eg. 1 or 2).
1365 If you want to play with the level variables, you should show some care.
1366 Set them once, and don't touch them ever again. Better yet, don't touch
1367 them at all unless you know exactly what you're doing.
1369 @vindex gnus-level-default-unsubscribed
1370 @vindex gnus-level-default-subscribed
1371 Two closely related variables are @code{gnus-level-default-subscribed}
1372 and @code{gnus-level-default-unsubscribed}, which are the levels that new
1373 groups will be put on if they are (un)subscribed. These two variables
1374 should, of course, be inside the relevant legal ranges.
1376 @vindex gnus-keep-same-level
1377 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
1378 will only move to groups that are of the same level (or lower). In
1379 particular, going from the last article in one group to the next group
1380 will go to the next group of the same level (or lower). This might be
1381 handy if you want to read the most important groups before you read the
1384 @vindex gnus-group-default-list-level
1385 All groups with a level less than or equal to
1386 @code{gnus-group-default-list-level} will be listed in the group buffer
1389 @vindex gnus-group-use-permament-levels
1390 If @code{gnus-group-use-permament-levels} is non-@code{nil}, once you
1391 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
1392 use this level as the "work" level.
1394 @node Marking Groups
1395 @section Marking Groups
1396 @cindex marking groups
1398 If you want to perform some action on several groups, and they appear
1399 subsequently in the group buffer, you would normally just give a
1400 numerical prefix to the command. Most group commands will then do your
1401 bidding on those groups.
1403 However, if the groups are not in sequential order, you can still
1404 perform an action on several groups. You simply mark the groups first,
1405 and then execute the command.
1412 @findex gnus-group-mark-group
1413 Set the mark on the current group (@code{gnus-group-mark-group}).
1418 @findex gnus-group-unmark-group
1419 Remove the mark from the current group
1420 (@code{gnus-group-unmark-group}).
1423 @findex gnus-group-mark-region
1424 Mark all groups between point and mark (@code{gnus-group-mark-region}).
1427 @node Foreign Groups
1428 @section Foreign Groups
1429 @cindex foreign groups
1431 A @dfn{foreign group} is a group that is not read by the usual (or
1432 default) means. It could be, for instance, a group from a different
1433 @sc{nntp} server, it could be a virtual group, or it could be your own
1434 personal mail group.
1436 A foreign group (or any group, really) is specified by a @dfn{name} and
1437 a @dfn{select method}. To take the latter first, a select method is a
1438 list where the first element says what backend to use (eg. @code{nntp},
1439 @code{nnspool}, @code{nnml}) and the second element is the @dfn{server
1440 name}. There may be additional elements in the select method, where the
1441 value may have special meaning for the backend in question.
1443 One could say that a select method defines a @dfn{virtual server} - so
1444 we do just that (@pxref{The Server Buffer}).
1446 The @dfn{name} of the group is the name the backend will recognize the
1449 For instance, the group @samp{soc.motss} on the @sc{nntp} server
1450 @samp{some.where.edu} will have the name @samp{soc.motss} and select
1451 method @code{(nntp "some.where.edu")}. Gnus will call this group, in
1452 all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
1453 nntp backend just knows this group as @samp{soc.motss}.
1455 Here are some commands for making and editing general foreign groups,
1456 and some commands to ease the creation of some special-purpose groups:
1461 @findex gnus-group-make-group
1462 Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
1463 for a name, a method and possibly an @dfn{address}. For an easier way
1464 to subscribe to @sc{nntp} groups, @xref{Browse Foreign Server}.
1468 @findex gnus-group-edit-group-method
1469 Enter a buffer where you can edit the select method of the current
1470 group (@code{gnus-group-edit-group-method}).
1474 @findex gnus-group-edit-group-parameters
1475 Enter a buffer where you can edit the group parameters
1476 (@code{gnus-group-edit-group-parameters}).
1480 @findex gnus-group-edit-group
1481 Enter a buffer where you can edit the group info
1482 (@code{gnus-group-edit-group}).
1486 @findex gnus-group-make-directory-group
1487 Make a directory group. You will be prompted for a directory name
1488 (@code{gnus-group-make-directory-group}).
1492 @findex gnus-group-make-help-group
1493 Make the Gnus help group (@code{gnus-group-make-help-group}).
1497 @findex gnus-group-make-archive-group
1498 @vindex gnus-group-archive-directory
1499 @vindex gnus-group-recent-archive-directory
1500 Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
1501 default a group pointing to the most recent articles will be created
1502 (@code{gnus-group-recent-archibe-directory}), but given a prefix, a full
1503 group will be created from from @code{gnus-group-archive-directory}.
1507 @findex gnus-group-make-kiboze-group
1508 Make a kiboze group. You will be prompted for a name, for a regexp to
1509 match groups to be "included" in the kiboze group, and a series of
1510 strings to match on headers (@code{gnus-group-make-kiboze-group}).
1514 @findex gnus-group-enter-directory
1515 Read a random directory as if with were a newsgroup with the
1516 @code{nneething} backend (@code{gnus-group-enter-directory}).
1520 @findex gnus-group-make-doc-group
1521 Make a group based on some file or other
1522 (@code{gnus-group-make-doc-group}). You will be prompted for a file
1523 name and a file type. Currently supported types are @code{babyl},
1524 @code{mbox} and @code{digest}.
1528 @findex gnus-group-make-empty-virtual
1529 Make a new, fresh, empty @code{nnvirtual} group
1530 (@code{gnus-group-make-empty-virtual}).
1534 @findex gnus-group-add-to-virtual
1535 Add the current group to an @code{nnvirtual} group
1536 (@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
1539 The different methods all have their peculiarities, of course.
1542 * nntp:: Reading news from a different @sc{nntp} server.
1543 * nnspool:: Reading news from the local spool.
1544 * nnvirtual:: Combining articles from many groups.
1545 * nnkiboze:: Looking through parts of the newsfeed for articles.
1546 * nndir:: You can read a directory as if it was a newsgroup.
1547 * nneething:: Dired? Who needs dired?
1548 * nndoc:: Single files can be the basis of a group.
1549 * Reading Mail:: Reading your personal mail with Gnus.
1552 @vindex gnus-activate-foreign-newsgroups
1553 If the @code{gnus-activate-foreign-newsgroups} is a positive number,
1554 Gnus will check all foreign groups with this level or lower at startup.
1555 This might take quite a while, especially if you subscribe to lots of
1556 groups from different @sc{nntp} servers. It is @code{nil} by default,
1557 which means that you won't be told whether there are new articles in
1558 these groups. How many unread articles there are will be determined
1559 when, or if, you decide to enter them. You can also activate any group
1560 with @kbd{M-g} to see how many unread articles there are.
1566 Subscribing to a foreign group from an @sc{nntp} server is rather easy.
1567 You just specify @code{nntp} as method and the address of the @sc{nntp}
1568 server as the, uhm, address.
1570 If the @sc{nntp} server is located at a non-standard port, setting the
1571 third element of the select method to this port number should allow you
1572 to connect to the right port. You'll have to edit the group info for
1573 that (@pxref{Foreign Groups}).
1575 The name of the foreign group can be the same as a native group. In
1576 fact, you can subscribe to the same group from as many different servers
1577 you feel like. There will be no name collisions.
1579 The following variables can be used to create a virtual @code{nntp}
1583 @item nntp-server-opened-hook
1584 @vindex nntp-server-opened-hook
1585 @cindex @sc{mode reader}
1587 @findex nntp-send-authinfo
1588 @findex nntp-send-mode-reader
1589 @code{nntp-server-opened-hook} is run after a connection has been made.
1590 It can be used to send commands to the @sc{nntp} server after it has
1591 been contacted. By default is sends the command @samp{MODE READER} to
1592 the server with the @code{nntp-send-mode-reader} function. Another
1593 popular function is @code{nntp-send-authinfo}, which will prompt you for
1594 an @sc{nntp} password and stuff.
1596 @item nntp-maximum-request
1597 @vindex nntp-maximum-request
1598 If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
1599 will collect headers by sending a series of @code{head} commands. To
1600 speed things up, the backend sends lots of these commands without
1601 waiting for reply, and then reads all the replies. This is controlled
1602 by the @code{nntp-maximum-request} variable, and is 400 by default. If
1603 your network is buggy, you should set this to 1.
1605 @item nntp-connection-timeout
1606 @vindex nntp-connection-timeout
1607 If you have lots of foreign @code{nntp} groups that you connect to
1608 regularly, you're sure to have problems with @sc{nntp} servers not
1609 responding properly, or being too loaded to reply within reasonable
1610 time. This is can lead to awkward problems, which can be helped
1611 somewhat by setting @code{nntp-connection-timeout}. This is an integer
1612 that says how many seconds the @code{nntp} backend should wait for a
1613 connection before giving up. If it is @code{nil}, which is the default,
1614 no timeouts are done.
1616 @item nntp-server-hook
1617 @vindex nntp-server-hook
1618 This hook is run as the last step when connecting to an @sc{nntp}
1621 @c @findex nntp-open-rlogin
1622 @c @findex nntp-open-network-stream
1623 @c @item nntp-open-server-function
1624 @c @vindex nntp-open-server-function
1625 @c This function is used to connect to the remote system. Two pre-made
1626 @c functions are @code{nntp-open-network-stream}, which is the default, and
1627 @c simply connects to some port or other on the remote system. The other
1628 @c is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
1629 @c and then does a telnet to the @sc{nntp} server available there.
1631 @c @item nntp-rlogin-parameters
1632 @c @vindex nntp-rlogin-parameters
1633 @c If you use @code{nntp-open-rlogin} as the
1634 @c @code{nntp-open-server-function}, this list will be used as the
1635 @c parameter list given to @code{rsh}.
1637 @c @item nntp-rlogin-user-name
1638 @c @vindex nntp-rlogin-user-name
1639 @c User name on the remote system when using the @code{rlogin} connect
1643 @vindex nntp-address
1644 The address of the remote system running the @sc{nntp} server.
1646 @item nntp-port-number
1647 @vindex nntp-port-number
1648 Port number to connect to when using the @code{nntp-open-network-stream}
1651 @item nntp-buggy-select
1652 @vindex nntp-buggy-select
1653 Set this to non-@code{nil} if your select routine is buggy.
1655 @item nntp-nov-is-evil
1656 @vindex nntp-nov-is-evil
1657 If the @sc{nntp} server does not support @sc{nov}, you could set this
1658 variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
1659 can be used automatically.
1661 @item nntp-xover-commands
1662 @vindex nntp-xover-commands
1663 List of strings that are used as commands to fetch @sc{nov} lines from a
1664 server. The default value of this variable is @code{("XOVER"
1668 @vindex nntp-nov-gap
1669 @code{nntp} normally sends just one big request for @sc{nov} lines to
1670 the server. The server responds with one huge list of lines. However,
1671 if you have read articles 2-5000 in the group, and only want to read
1672 article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
1673 lines that you do not want, and will not use. This variable says how
1674 big a gap between two consecutive articles is allowed to be before the
1675 @code{XOVER} request is split into several request. Note that if your
1676 network is fast, setting this variable to a really small number means
1677 that fetching will probably be slower. If this variable is @code{nil},
1678 @code{nntp} will never split requests.
1680 @item nntp-prepare-server-hook
1681 @vindex nntp-prepare-server-hook
1682 A hook run before attempting to connect to an @sc{nntp} server.
1684 @item nntp-async-number
1685 @vindex nntp-async-number
1686 How many articles should be pre-fetched when in asynchronous mode. If
1687 this variable is @code{t}, @code{nntp} will pre-fetch all the articles
1688 that it can without bound. If it is @code{nil}, no pre-fetching will be
1698 Subscribing to a foreign group from the local spool is extremely easy,
1699 and might be useful, for instance, to speed up reading groups like
1700 @samp{alt.binaries.pictures.furniture}.
1702 Anyways, you just specify @code{nnspool} as the method and @samp{""} (or
1703 anything else) as the address.
1705 If you have access to a local spool, you should probably use that as the
1706 native select method (@pxref{Finding the News}).
1709 @item nnspool-inews-program
1710 @vindex nnspool-inews-program
1711 Program used to post an article.
1713 @item nnspool-inews-switches
1714 @vindex nnspool-inews-switches
1715 Parameters given to the inews program when posting an article.
1717 @item nnspool-spool-directory
1718 @vindex nnspool-spool-directory
1719 Where nnspool looks for the articles. This is normally
1720 @file{/usr/spool/news/}.
1722 @item nnspool-nov-directory
1723 @vindex nnspool-nov-directory
1724 Where nnspool will look for @sc{nov} files. This is normally
1725 @file{/usr/spool/news/over.view/}.
1727 @item nnspool-lib-dir
1728 @vindex nnspool-lib-dir
1729 Where the news lib dir is (@file{/usr/lib/news/} by default).
1731 @item nnspool-active-file
1732 @vindex nnspool-active-file
1733 The path of the active file.
1735 @item nnspool-newsgroups-file
1736 @vindex nnspool-newsgroups-file
1737 The path of the group description file.
1739 @item nnspool-history-file
1740 @vindex nnspool-history-file
1741 The path of the news history file.
1743 @item nnspool-active-times-file
1744 @vindex nnspool-active-times-file
1745 The path of the active date file.
1747 @item nnspool-nov-is-evil
1748 @vindex nnspool-nov-is-evil
1749 If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
1752 @item nnspool-sift-nov-with-sed
1753 @vindex nnspool-sift-nov-with-sed
1754 If non-@code{nil}, which is the default, use @code{sed} to get the
1755 relevant portion from the overview file. If nil, @code{nnspool} will
1756 load the entire file into a buffer and process it there.
1761 @subsection nnvirtual
1763 @cindex virtual groups
1765 An @dfn{nnvirtual group} is really nothing more than a collection of
1768 For instance, if you are tired of reading many small group, you can
1769 put them all in one big group, and then grow tired of reading one
1770 big, unwieldy group. The joys of computing!
1772 You specify @code{nnvirtual} as the method. The address should be a
1773 regexp to match component groups.
1775 All marks in the virtual group will stick to the articles in the
1776 component groups. So if you tick an article in a virtual group, the
1777 article will also be ticked in the component group from whence it came.
1778 (And vice versa - marks from the component groups will also be shown in
1781 Here's an example nnvirtual method that collects all Andrea Dworkin
1782 newsgroups into one, big, happy newsgroup:
1785 (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
1788 The component groups can be native or foreign; everything should work
1789 smoothly, but if your computer explodes, it was probably my fault.
1791 Collecting the same group from several servers might actually be a good
1792 idea if users have set the Distribution header to limit distribution.
1793 If you would like to read @samp{soc.motss} both from a server in Japan
1794 and a server in Norway, you could use the following as the group regexp:
1797 "^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
1800 This should work kinda smoothly - all articles from both groups should
1801 end up in this one, and there should be no duplicates. Threading (and
1802 the rest) will still work as usual, but there might be problems with the
1803 sequence of articles. Sorting on date might be an option here
1804 (@pxref{Selecting a Group}.
1806 One limitation, however - all groups that are included in a virtual
1807 group has to be alive (i.e., subscribed or unsubscribed). Killed or
1808 zombie groups can't be component groups for nnvirtual groups.
1811 @subsection nnkiboze
1815 @dfn{Kibozing} is defined by OED as "grepping through (parts of) the
1816 news feed". nnkiboze is a backend that will do this for you. Oh joy!
1817 Now you can grind any @sc{nntp} server down to a halt with useless
1818 requests! Oh happiness!
1820 The address field of the nnkiboze method is, as with nnvirtual, a regexp
1821 to match groups to be "included" in the nnkiboze group. There most
1822 similarities between nnkiboze and nnvirtual ends.
1824 In addition to this regexp detailing component groups, an nnkiboze group
1825 must have a score file to say what articles that are to be included in
1826 the group (@pxref{Score Files}).
1828 @kindex M-x nnkiboze-generate-groups
1829 @findex nnkiboze-generate-groups
1830 You must run @kbd{M-x nnkiboze-generate-groups} after creating the
1831 nnkiboze groups you want to have. This command will take time. Lots of
1832 time. Oodles and oodles of time. Gnus has to fetch the headers from
1833 all the articles in all the components groups and run them through the
1834 scoring process to determine if there are any articles in the groups
1835 that are to be part of the nnkiboze groups.
1837 Please limit the number of component groups by using restrictive
1838 regexps. Otherwise your sysadmin may become annoyed with you, and the
1839 @sc{nntp} site may throw you off and never let you back in again.
1840 Stranger things have happened.
1842 nnkiboze component groups do not have to be alive - they can be dead,
1843 and they can be foreign. No restrictions.
1845 @vindex nnkiboze-directory
1846 The generation of an nnkiboze group means writing two files in
1847 @code{nnkiboze-directory}, which is @file{~/News/} by default. One
1848 contains the @sc{nov} header lines for all the articles in the group,
1849 and the other is an additional @file{.newsrc} file to store information
1850 on what groups that have been searched through to find component
1853 Articles that are marked as read in the nnkiboze group will have their
1854 @sc{nov} lines removed from the @sc{nov} file.
1859 @cindex directory groups
1861 If you have a directory that has lots of articles in separate files in
1862 it, you might treat it as a newsgroup. The files have to have numerical
1865 This might be an opportune moment to mention @code{ange-ftp}, that most
1866 wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
1867 didn't think much about it - a backend to read directories. Big deal.
1869 @code{ange-ftp} changes that picture dramatically. For instance, if you
1870 enter @file{"/ftp@@sina.tcamc.uh.edu:/pub/emacs/ding-list/"} as the the
1871 directory name, ange-ftp will actually allow you to read this directory
1872 over at @samp{sina} as a newsgroup. Distributed news ahoy!
1874 @code{nndir} will use @sc{nov} files if they are present.
1876 @code{nndir} is a "read-only" backend - you can't delete or expire
1877 articles with this method. You can use @code{nnmh} or @code{nnml} for
1878 whatever you use @code{nndir} for, so you could switch to any of those
1879 methods if you feel the need to have a non-read-only @code{nndir}.
1882 @subsection nneething
1885 From the @code{nndir} backend (which reads a single spool-like
1886 directory), it's just a hop and a skip to @code{nneething}, which
1887 pretends that any random directory is a newsgroup. Strange, but true.
1889 When @code{nneething} is presented with a directory, it will scan this
1890 directory and assign article numbers to each file. When you enter such a
1891 group, @code{nneething} must create "headers" that Gnus can use. After
1892 all, Gnus is a newsreader, in case you're forgetting. @code{nneething}
1893 does this in a two-step process. First, it snoops each file in question.
1894 If the file looks like an article (i.e., the first few lines look like
1895 headers), it will use this as the head. If this is just some random file
1896 without a head (eg. a C source file), @code{nneething} will cobble up a
1897 header out of thin air. It will use file ownership, name and date and do
1898 whatever it can with these elements.
1900 All this should happen automatically for you, and you will be presented
1901 with something that looks very much like a newsgroup. Totally like a
1902 newsgroup, to be precise. If you select an article, it will be displayed
1903 in the article buffer, just as usual.
1905 If you select a line that represents a directory, Gnus will pop you into
1906 a new summary buffer for this @code{nneething} group. And so on. You can
1907 traverse the entire disk this way, if you feel like, but remember that
1908 Gnus is not dired, really, and does not intend to be, either.
1910 There are two overall modes to this action - ephemeral or solid. When
1911 doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
1912 will not store information on what files you have read, and what files
1913 are new, and so on. If you create a solid @code{nneething} group the
1914 normal way with @kbd{G m}, Gnus will store a mapping table between
1915 article numbers and file names, and you can treat this group like any
1916 other groups. When you activate a solid @code{nneething} group, you will
1917 be told how many unread articles it contains, etc., etc.
1922 @item nneething-map-file-directory
1923 @vindex nneething-map-file-directory
1924 All the mapping files for solid @code{nneething} groups will be stored
1925 in this directory, which defaults to @file{~/.nneething/}.
1927 @item nneething-exclude-files
1928 @vindex nneething-exclude-files
1929 All files that match this regexp will be ignored. Nice to use to exclude
1930 auto-save files and the like, which is what it does by default.
1932 @item nneething-map-file
1933 @vindex nneething-map-file
1934 Name of the map files.
1941 @cindex documentation group
1944 nndoc is a cute little thing that will let you read a single file as a
1945 newsgroup. Currently supported file types are @code{babyl}, @code{mbox}
1948 nndoc will not try to change the file or insert any extra headers into
1949 it - it will simply, like, let you use the file as the basis for a
1950 group. And that's it.
1952 Virtual server variables:
1955 @item nndoc-article-type
1956 @vindex nndoc-article-type
1957 This should be one of @code{mbox}, @code{babyl} or @code{digest}.
1961 @subsection Reading Mail
1962 @cindex reading mail
1965 Reading mail with a newsreader - isn't that just plain WeIrD? But of
1968 Gnus will read the mail spool when you activate a mail group. The mail
1969 file is first copied to your home directory. What happens after that
1970 depends on what format you want to store your mail in.
1973 * Creating Mail Groups:: How to create mail groups.
1974 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
1975 * Mail & Procmail:: Reading mail groups that procmail create.
1976 * Expiring Old Mail Articles:: Getting rid of unwanted mail.
1977 * Not Reading Mail:: Using mail backends for reading other files.
1978 * nnmbox:: Using the (quite) standard Un*x mbox.
1979 * nnbabyl:: Emacs programs use the rmail babyl format.
1980 * nnml:: Store your mail in a private spool?
1981 * nnmh:: An mhspool-like backend.
1982 * nnfolder:: Having one file for each group.
1985 @vindex nnmail-read-incoming-hook
1986 The mail backends all call @code{nnmail-read-incoming-hook} after
1987 reading new mail. You can use this hook to notify any mail watch
1988 programs, if you want to.
1990 @vindex nnmail-spool-file
1991 @code{nnmail-spool-file} says where to look for new mail. If this
1992 variable is @code{nil}, the mail backends will never attempt to fetch
1993 mail by themselves. It is quite likely that Gnus supports POP-mail.
1994 Set this variable to begin with the string @samp{po:}, and everything
1995 should go smoothly, even though I have never tested this.
1997 @vindex nnmail-use-procmail
1998 If @code{nnmail-use-procmail} is non-@code{nil}, the mail backends will
1999 look in @code{nnmail-procmail-directory} for incoming mail. All the
2000 files in that directory that have names ending in
2001 @code{gnus-procmail-suffix} will be considered incoming mailboxes, and
2002 will be searched for new mail.
2004 @vindex nnmail-prepare-incoming-hook
2005 @code{nnmail-prepare-incoming-hook} is run in a buffer that holds all
2006 the new incoming mail, and can be used for, well, anything, really.
2008 @vindex nnmail-tmp-directory
2009 @code{nnmail-tmp-directory} says where to move the incoming mail to
2010 while processing it. This is usually done in the same directory that
2011 the mail backend inhabits (i.e., @file{~/Mail/}), but if this variable is
2012 non-@code{nil}, it will be used instead.
2014 @vindex nnmail-movemail-program
2015 @code{nnmail-movemail-program} is executed to move mail from the user's
2016 inbox to her home directory. The default is @samp{"movemail"}.
2018 @vindex nnmail-delete-incoming
2019 If @code{nnmail-delete-incoming} is non-@code{nil}, the mail backends
2020 will delete the temporary incoming file after splitting mail into the
2021 proper groups. This is @code{nil} by default for reasons of security.
2023 @vindex nnmail-message-id-cache-length
2024 @vindex nnmail-message-id-cache-file
2025 @vindex nnmail-delete-duplicates
2026 @cindex duplicate mails
2027 If you are a member of a couple of mailing list, you will sometime
2028 receive two copies of the same mail. This can be quite annoying, so
2029 @code{nnmail} checks for and discards any duplicates it might find. To
2030 do this, it keeps a cache of old @code{Message-ID}s -
2031 @code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
2032 default. The approximate maximum number of @code{Message-ID}s stored
2033 there is controlled by the @code{nnmail-message-id-cache-length}
2034 variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
2035 stored.) If all this sounds scary to you, you can set
2036 @code{nnmail-delete-duplicates} to @code{nil} (which is what it is by
2037 default), and @code{nnmail} won't do any duplicate checking.
2039 Here's a neat feature: If you know that the recipient reads her mail
2040 with Gnus, and that she has @code{nnmail-delete-duplicates} set to
2041 @code{t}, you can send her as many insults as you like, just by using a
2042 @code{Message-ID} of a mail that you know that she's already received.
2043 Think of all the fun! She'll never see any of it! Whee!
2045 Gnus gives you all the opportunity you could possibly want for shooting
2046 yourself in the foot. Let's say you create a group that will contain
2047 all the mail you get from your boss. And then you accidentally
2048 unsubscribe from the group. Gnus will still put all the mail from your
2049 boss in the unsubscribed group, and so, when your boss mails you "Have
2050 that report ready by Monday or you're fired!", you'll never see it and,
2051 come Tuesday, you'll still believe that you're gainfully employed while
2052 you really should be out collecting empty bottles to save up for next
2055 @node Creating Mail Groups
2056 @subsubsection Creating Mail Groups
2057 @cindex creating mail groups
2059 You can make Gnus read your personal, private, secret mail.
2061 You should first set @code{gnus-secondary-select-methods} to, for
2062 instance, @code{((nnmbox ""))}. When you start up Gnus, Gnus will ask
2063 this backend for what groups it carries (@samp{mail.misc} by default)
2064 and subscribe it the normal way. (Which means you may have to look for
2065 it among the zombie groups, I guess, all depending on your
2066 @code{gnus-subscribe-newsgroup-method} variable.)
2068 @vindex nnmail-split-methods
2069 Then you should set the variable @code{nnmail-split-methods} to specify
2070 how the incoming mail is to be split into groups.
2073 (setq nnmail-split-methods
2074 '(("mail.junk" "^From:.*Lars Ingebrigtsen")
2075 ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
2079 This variable is a list of lists, where the first element of each of
2080 these lists is the name of the mail group (they do not have to be called
2081 something beginning with @samp{mail}, by the way), and the second
2082 element is a regular expression used on the header of each mail to
2083 determine if it belongs in this mail group.
2085 The second element can also be a function. In that case, it will be
2086 called narrowed to the headers with the first element of the rule as the
2087 argument. It should return a non-@code{nil} value if it thinks that the
2088 mail belongs in that group.
2090 The last of these groups should always be a general one, and the regular
2091 expression should @emph{always} be @samp{""} so that it matches any
2092 mails that haven't been matched by any of the other regexps.
2094 If you like to tinker with this yourself, you can set this variable to a
2095 function of your choice. This function will be called without any
2096 arguments in a buffer narrowed to the headers of an incoming mail
2097 message. The function should return a list of groups names that it
2098 thinks should carry this mail message.
2100 @vindex nnmail-crosspost
2101 The mail backends all support cross-posting. If several regexps match,
2102 the mail will be "cross-posted" to all those groups.
2103 @code{nnmail-crosspost} says whether to use this mechanism or not. Note
2104 that no articles are crossposted to the general (@samp{""}) group.
2106 @node Fancy Mail Splitting
2107 @subsubsection Fancy Mail Splitting
2108 @cindex mail splitting
2109 @cindex fancy mail splitting
2111 @vindex nnmail-split-fancy
2112 @findex nnmail-split-fancy
2113 If the rather simple, standard method for specifying how to split mail
2114 doesn't allow you to do what you want, you can set
2115 @code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
2116 play with the @code{nnmail-split-fancy} variable.
2118 Let's look at an example value of this variable first:
2121 ;; Messages from the mailer daemon are not crossposted to any of
2122 ;; the ordinary groups. Warnings are put in a separate group
2123 ;; from real errors.
2124 (| ("from" mail (| ("subject" "warn.*" "mail.warning")
2126 ;; Non-error messages are crossposted to all relevant
2127 ;; groups, but we don't crosspost between the group for the
2128 ;; (ding) list and the group for other (ding) related mail.
2129 (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
2130 ("subject" "ding" "ding.misc"))
2131 ;; Other mailing lists...
2132 (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
2133 (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
2135 (any "larsi@@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
2136 ;; Unmatched mail goes to the catch all group.
2140 This variable has the format of a @dfn{split}. A split is a (possibly)
2141 recursive structure where each split may contain other splits. Here are
2142 the four possible split syntaxes:
2146 If the split is a string, that will be taken as a group name.
2147 @item (FIELD VALUE SPLIT)
2148 If the split is a list, and the first element is a string, then that
2149 means that if header FIELD (a regexp) contains VALUE (also a regexp),
2150 then store the message as specified by SPLIT.
2152 If the split is a list, and the first element is @code{|} (vertical
2153 bar), then process each SPLIT until one of them matches. A SPLIT is
2154 said to match if it will cause the mail message to be stored in one or
2157 If the split is a list, and the first element is @code{&}, then process
2158 all SPLITs in the list.
2161 In these splits, FIELD must match a complete field name. VALUE must
2162 match a complete word according to the fundamental mode syntax table.
2163 You can use @code{.*} in the regexps to match partial field names or
2166 @vindex nnmail-split-abbrev-alist
2167 FIELD and VALUE can also be lisp symbols, in that case they are expanded
2168 as specified by the variable @code{nnmail-split-abbrev-alist}. This is
2169 an alist of cons cells, where the car of the cells contains the key, and
2170 the cdr contains a string.
2172 @node Mail & Procmail
2173 @subsubsection Mail & Procmail
2176 Many people use @code{procmail} to split incoming mail into groups. If
2177 you do that, you should set @code{nnmail-spool-file} to @code{procmail}
2178 to ensure that the mail backends never ever try to fetch mail by
2181 This also means that you probably don't want to set
2182 @code{nnmail-split-methods} either, which has some, perhaps, unexpected
2185 When a mail backend is queried for what groups it carries, it replies
2186 with the contents of that variable, along with any groups it has figured
2187 out that it carries by other means. None of the backends (except
2188 @code{nnmh}) actually go out to the disk and check what groups actually
2189 exist. (It's not trivial to distinguish between what the user thinks is
2190 a basis for a newsgroup and what is just a plain old file or directory.)
2192 This means that you have to tell Gnus (and the backends) what groups
2195 Let's take the @code{nnmh} backend as an example.
2197 The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
2198 There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
2200 Go to the group buffer and type @kbd{G m}. When prompted, answer
2201 @samp{foo} for the name and @samp{nnmh} for the method. Repeat
2202 twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
2203 to include all your mail groups.
2205 That's it. You are now set to read your mail. An active file for this
2206 method will be created automatically.
2208 @vindex nnmail-procmail-suffix
2209 @vindex nnmail-procmail-directory
2210 If you use @code{nnfolder} or any other backend that store more than a
2211 single article in each file, you should never have procmail add mails to
2212 the file that Gnus sees. Instead, procmail should put all incoming mail
2213 in @code{nnmail-procmail-directory}. To arrive at the file name to put
2214 the incoming mail in, append @code{nnmail-procmail-suffix} to the group
2215 name. The mail backends will read the mail from these files.
2217 @vindex nnmail-resplit-incoming
2218 When Gnus reads a file called @file{mail.misc.spool}, this mail will be
2219 put in the @code{mail.misc}, as one would expect. However, if you want
2220 Gnus to split the mail the normal way, you could set
2221 @code{nnmail-resplit-incoming} to @code{t}.
2223 @vindex nnmail-keep-last-article
2224 If you use @code{procmail} to split things directory into an nnmh
2225 directory (which you shouldn't do), you should set
2226 @code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
2227 ever expiring the final article in a mail newsgroup. This is quite,
2231 @node Expiring Old Mail Articles
2232 @subsubsection Expiring Old Mail Articles
2233 @cindex article expiry
2235 Traditional mail readers have a tendency to remove mail articles when
2236 you mark them as read, in some way. Gnus takes a fundamentally
2237 different approach to mail reading.
2239 Gnus basically considers mail just to be news that has been received in
2240 a rather peculiar manner. It does not think that it has the power to
2241 actually change the mail, or delete any mail messages. If you enter a
2242 mail group, and mark articles as "read", or kill them in some other
2243 fashion, the mail articles will still exist on the system. I repeat:
2244 Gnus will not delete your old, read mail. Unless you ask it to, of
2247 To make Gnus get rid of your unwanted mail, you have to mark the
2248 articles as @dfn{expirable}. This does not mean that the articles will
2249 disappear right away, however. In general, a mail article will be
2250 deleted from your system if, 1) it is marked as expirable, AND 2) it is
2251 more than one week old. If you do not mark an article as expirable, it
2252 will remain on your system until hell freezes over. This bears
2253 repeating one more time, with some spurious capitalizations: IF you do
2254 NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
2256 @vindex gnus-auto-expirable-newsgroups
2257 You do not have to mark articles as expirable by hand. Groups that
2258 match the regular expression @code{gnus-auto-expirable-newsgroups} will
2259 have all articles that you read marked as expirable automatically. All
2260 articles that are marked as expirable have an @samp{E} in the first
2261 column in the summary buffer.
2263 Let's say you subscribe to a couple of mailing lists, and you want the
2264 articles you have read to disappear after a while:
2267 (setq gnus-auto-expirable-newsgroups
2268 "mail.nonsense-list\\|mail.nice-list")
2271 Another way to have auto-expiry happen is to have the element
2272 @code{auto-expire} in the select method of the group.
2274 @vindex nnmail-expiry-wait
2275 The @code{nnmail-expiry-wait} variable supplies the default time an
2276 expirable article has to live. The default is seven days.
2278 Gnus also supplies a function that lets you fine-tune how long articles
2279 are to live, based on what group they are in. Let's say you want to
2280 have one month expiry period in the @samp{mail.private} group, a one day
2281 expiry period in the @samp{mail.junk} group, and a six day expiry period
2285 (setq nnmail-expiry-wait-function
2287 (cond ((string= group "mail.private")
2289 ((string= group "mail.junk")
2295 @vindex nnmail-keep-last-article
2296 If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
2297 expire the final article in a mail newsgroup. This is to make life
2298 easier for procmail users.
2300 By the way, that line up there about Gnus never expiring non-expirable
2301 articles is a lie. If you put @code{total-expire} in the group
2302 parameters, articles will not be marked as expirable, but all read
2303 articles will be put through the expiry process. Use with extreme
2306 Note that at present, Gnus will not actually delete any expirable
2307 articles automatically. You have to enter one of the expiry functions
2308 (eg. `C-c M-c-x' in the group buffer) to actually run articles through
2309 the expiry process. Or you can add a call to the expiry function in the
2310 group exit hook. Gnus will probably do all this automatically in the
2313 @node Not Reading Mail
2314 @subsubsection Not Reading Mail
2316 If you start using any of the mail backends, they have the annoying
2317 habit of assuming that you want to read mail with them. This might not
2318 be unreasonable, but it might not be what you want.
2320 If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
2321 will ever attempt to read incoming mail, which should help.
2323 @vindex nnbabyl-get-new-mail
2324 @vindex nnmbox-get-new-mail
2325 @vindex nnml-get-new-mail
2326 @vindex nnmh-get-new-mail
2327 @vindex nnfolder-get-new-mail
2328 This might be too much, if, for instance, you are reading mail quite
2329 happily with @code{nnml} and just want to peek at some old @sc{rmail}
2330 file you have stashed away with @code{nnbabyl}. All backends have
2331 variables called backend-@code{get-new-mail}. If you want to disable
2332 the @code{nnbabyl} mail reading, you edit the virtual server for the
2333 group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
2335 All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
2336 narrowed to the article to be saved before saving it when reading
2340 @subsubsection nnmbox
2342 @cindex unix mail box
2344 @vindex nnmbox-active-file
2345 @vindex nnmbox-mbox-file
2346 The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
2347 mail. @code{nnmbox} will add extra headers to each mail article to say
2348 which group it belongs in.
2350 Virtual server settings:
2353 @item nnmbox-mbox-file
2354 @vindex nnmbox-mbox-file
2355 The name of the mail box in the user's home directory.
2357 @item nnmbox-active-file
2358 @vindex nnmbox-active-file
2359 The name of the active file for the mail box.
2361 @item nnmbox-get-new-mail
2362 @vindex nnmbox-get-new-mail
2363 If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
2368 @subsubsection nnbabyl
2372 @vindex nnbabyl-active-file
2373 @vindex nnbabyl-mbox-file
2374 The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
2375 mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
2376 article to say which group it belongs in.
2378 Virtual server settings:
2381 @item nnbabyl-mbox-file
2382 @vindex nnbabyl-mbox-file
2383 The name of the rmail mbox file.
2385 @item nnbabyl-active-file
2386 @vindex nnbabyl-active-file
2387 The name of the active file for the rmail box.
2389 @item nnbabyl-get-new-mail
2390 @vindex nnbabyl-get-new-mail
2391 If non-@code{nil}, @code{nnbabyl} will read incoming mail.
2397 @cindex mail @sc{nov} spool
2399 The @dfn{nnml} spool mail format isn't compatible with any other known
2400 format. It should be used with some caution.
2402 @vindex nnml-directory
2403 If you use this backend, Gnus will split all incoming mail into files;
2404 one file for each mail, and put the articles into the correct
2405 directories under the directory specified by the @code{nnml-directory}
2406 variable. The default value is @file{~/Mail/}.
2408 You do not have to create any directories beforehand; Gnus will take
2411 If you have a strict limit as to how many files you are allowed to store
2412 in your account, you should not use this backend. As each mail gets its
2413 own file, you might very well occupy thousands of inodes within a few
2414 weeks. If this is no problem for you, and it isn't a problem for you
2415 having your friendly systems administrator walking around, madly,
2416 shouting "Who is eating all my inodes?! Who? Who!?!", then you should
2417 know that this is probably the fastest format to use. You do not have
2418 to trudge through a big mbox file just to read your new mail.
2420 @code{nnml} is probably the slowest backend when it comes to article
2421 splitting. It has to create lots of files, and it also generates
2422 @sc{nov} databases for the incoming mails. This makes is the fastest
2423 backend when it comes to reading mail.
2425 Virtual server settings:
2428 @item nnml-directory
2429 @vindex nnml-directory
2430 All @code{nnml} directories will be placed under this directory.
2432 @item nnml-active-file
2433 @vindex nnml-active-file
2434 The active file for the @code{nnml} server.
2436 @item nnml-newsgroups-file
2437 @vindex nnml-newsgroups-file
2438 The @code{nnml} group description file.
2440 @item nnml-get-new-mail
2441 @vindex nnml-get-new-mail
2442 If non-@code{nil}, @code{nnml} will read incoming mail.
2444 @item nnml-nov-is-evil
2445 @vindex nnml-nov-is-evil
2446 If non-@code{nil}, this backend will ignore any @sc{nov} files.
2448 @item nnml-nov-file-name
2449 @vindex nnml-nov-file-name
2450 The name of the @sc{nov} files. The default is @file{.overview}.
2454 @findex nnml-generate-nov-databases
2455 If your @code{nnml} groups and @sc{nov} files get totally out of whack,
2456 you can do a complete update by typing @kbd{M-x
2457 nnml-generate-nov-databases}. This command will trawl through the
2458 entire @code{nnml} hierarchy, looking at each and every article, so it
2459 might take a while to complete.
2464 @cindex mh-e mail spool
2466 @code{nnmh} is just like @code{nnml}, except that is doesn't generate
2467 @sc{nov} databases and it doesn't keep an active file. This makes
2468 @code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
2469 makes it easier to write procmail scripts for.
2471 Virtual server settings:
2474 @item nnmh-directory
2475 @vindex nnmh-directory
2476 All @code{nnmh} directories will be located under this directory.
2478 @item nnmh-get-new-mail
2479 @vindex nnmh-get-new-mail
2480 If non-@code{nil}, @code{nnmh} will read incoming mail.
2483 @vindex nnmh-be-safe
2484 If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
2485 sure that the articles in the folder is actually what Gnus think they
2486 are. It will check date stamps, and stat everything in sight, so
2487 setting this to @code{t} will mean a serious slow-down. If you never
2488 use anything by Gnus to read the nnmh articles, you do not have to set
2489 this variable to @code{t}.
2493 @subsubsection nnfolder
2495 @cindex mbox folders
2497 @code{nnfolder} is a backend for storing each mail group in a separate
2498 file. Each file is in the standard Un*x mbox format. @code{nnfolder}
2499 will add extra headers to keep track of article numbers and arrival
2502 Virtual server settings:
2505 @item nnfolder-directory
2506 @vindex nnfolder-directory
2507 All the @code{nnfolder} mail boxes will be stored under this directory.
2509 @item nnfolder-active-file
2510 @vindex nnfolder-active-file
2511 The name of the active file.
2513 @item nnfolder-newsgroups-file
2514 @vindex nnfolder-newsgroups-file
2515 The name of the group description file.
2517 @item nnfolder-get-new-mail
2518 @vindex nnfolder-get-new-mail
2519 If non-@code{nil}, @code{nnfolder} will read incoming mail.
2522 @node Group Parameters
2523 @section Group Parameters
2524 @cindex group parameters
2526 Gnus stores all information on a group in a list that is usually known
2527 as the @dfn{group info}. This list has from three to six elements.
2528 Here's an example info.
2531 ("nnml:mail.ding" 3 ((1 . 232) 244 (256 . 270)) ((tick 246 249))
2532 (nnml "private") ((to-address . "ding@@ifi.uio.no")))
2535 The first element is the @dfn{group name}, as Gnus knows the group,
2536 anyway. The second element is the @dfn{subscription level}, which
2537 normally is a small integer. The third element is a list of ranges of
2538 read articles. The fourth element is a list of lists of article marks
2539 of various kinds. The fifth element is the select method (or virtual
2540 server, if you like). The sixth element is a list of @dfn{group
2541 parameters}, which is what this section is about.
2543 Any of the last three elements may be missing if they are not required.
2544 In fact, the vast majority of groups will normally only have the first
2545 three elements, which saves quite a lot of cons cells.
2547 At present, there's not much you can put in the group parameters list:
2552 If the group parameter list contains an element that looks like
2553 @samp{(to-address . "some@@where.com")}, that address will be used by
2554 the backend when doing followups and posts. This is primarily useful in
2555 mail groups that represent mailing lists. You just set this address to
2556 whatever the list address is.
2558 This trick will actually work whether the group is foreign or not.
2559 Let's say there's a group on the server that is called @samp{fa.4ad-l}.
2560 This is a real newsgroup, but the server has gotten the articles from a
2561 mail-to-news gateway. Posting directly to this group is therefore
2562 impossible - you have to send mail to the mailing list address instead.
2566 IF the group parameter list contains an element like @code{(to-group
2567 . "some.group.name")}, all posts will be sent to that groups.
2571 If this symbol is present in the group parameter list, all articles that
2572 are read will be marked as expirable. For an alternative approach,
2573 @xref{Expiring Old Mail Articles}.
2576 @cindex total-expire
2577 If this symbol is present, all read articles will be put through the
2578 expiry process, even if they are not marked as expirable. Use with
2582 If you want to change the group parameters (or anything else of the
2583 group info) you can use the @kbd{G E} to edit enter a buffer where you
2584 can edit the group info.
2586 You usually don't want to edit the entire group info, so you'd be better
2587 off using the @kbd{G p} command to just edit the group parameters.
2589 @node Listing Groups
2590 @section Listing Groups
2591 @cindex group listing
2593 These commands all list various slices of the groups that are available.
2600 @findex gnus-group-list-groups
2601 List all groups that have unread articles
2602 (@code{gnus-group-list-groups}). If the numeric prefix is used, this
2603 command will list only groups of level ARG and lower. By default, it
2604 only lists groups of level five or lower (i.e., just subscribed groups).
2609 @findex gnus-group-list-all-groups
2610 List all groups, whether they have unread articles or not
2611 (@code{gnus-group-list-all-groups}). If the numeric prefix is used,
2612 this command will list only groups of level ARG and lower. By default,
2613 it lists groups of level seven or lower (i.e., just subscribed and
2614 unsubscribed groups).
2617 @findex gnus-group-list-killed
2618 List all killed groups (@code{gnus-group-list-killed}).
2621 @findex gnus-group-list-zombies
2622 List all zombie groups (@code{gnus-group-list-zombies}).
2625 @findex gnus-group-list-matching
2626 List all subscribed groups with unread articles that match a regexp
2627 (@code{gnus-group-list-matching}).
2630 @findex gnus-group-list-all-matching
2631 List groups that match a regexp (@code{gnus-group-list-all-matching}).
2634 @node Group Maintenance
2635 @section Group Maintenance
2636 @cindex bogus groups
2641 @findex gnus-group-check-bogus-groups
2642 Find bogus groups and delete them
2643 (@code{gnus-group-check-bogus-groups}).
2646 @findex gnus-find-new-newsgroups
2647 Find new groups and process them (@code{gnus-find-new-newsgroups}).
2649 @kindex C-c C-x (Group)
2650 @findex gnus-group-expire-articles
2651 Run all expirable articles in the current group through the expiry
2652 process (if any) (@code{gnus-group-expire-articles}).
2654 @kindex C-c M-C-x (Group)
2655 @findex gnus-group-expire-all-groups
2656 Run all articles in all groups through the expiry process
2657 (@code{gnus-group-expire-all-groups}).
2659 @kindex C-c C-s (Group)
2660 @findex gnus-group-sort-groups
2661 @findex gnus-group-sort-by-level
2662 @findex gnus-group-sort-by-unread
2663 @findex gnus-group-sort-by-alphabet
2664 @vindex gnus-group-sort-function
2665 Sort the groups according to the function given by the
2666 @code{gnus-group-sort-function} variable
2667 (@code{gnus-group-sort-groups}). Available sorting functions include
2668 @code{gnus-group-sort-by-alphabet} (the default),
2669 @code{gnus-group-sort-by-unread} and @code{gnus-group-sort-by-level}.
2672 @node Browse Foreign Server
2673 @section Browse Foreign Server
2674 @cindex foreign servers
2675 @cindex browsing servers
2680 @findex gnus-group-browse-foreign-server
2681 You will be queried for a select method and a server name. Gnus will
2682 then attempt to contact this server and let you browse the groups there
2683 (@code{gnus-group-browse-foreign-server}).
2686 @findex gnus-browse-server-mode
2687 A new buffer with a list of available groups will appear. This buffer
2688 will be use the @code{gnus-browse-server-mode}. This buffer looks a bit
2689 (well, a lot) like a normal group buffer, but with one major difference
2690 - you can't enter any of the groups. If you want to read any of the
2691 news available on that server, you have to subscribe to the groups you
2692 think may be interesting, and then you have to exit this buffer. The
2693 new groups will be added to the group buffer, and then you can read them
2694 as you would any other group.
2696 Future versions of Gnus may possibly permit reading groups straight from
2699 Here's a list of keystrokes available in the browse mode:
2704 @findex gnus-group-next-group
2705 Go to the next group (@code{gnus-group-next-group}).
2709 @findex gnus-group-prev-group
2710 Go to the previous group (@code{gnus-group-prev-group}).
2713 @kindex SPC (Browse)
2714 @findex gnus-browse-read-group
2715 Enter the current group and display the first article
2716 (@code{gnus-browse-read-group}).
2719 @kindex RET (Browse)
2720 @findex gnus-browse-select-group
2721 Enter the current group (@code{gnus-browse-select-group}).
2725 @findex gnus-browse-unsubscribe-current-group
2726 Unsubscribe to the current group, or, as will be the case here,
2727 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
2733 @findex gnus-browse-exit
2734 Exit browse mode (@code{gnus-browse-exit}).
2738 @findex gnus-browse-describe-briefly
2739 Describe browse mode briefly (well, there's not much to describe, is
2740 there) (@code{gnus-browse-describe-briefly}).
2744 @section Exiting Gnus
2745 @cindex exiting Gnus
2747 Yes, Gnus is ex(c)iting.
2752 @findex gnus-group-suspend
2753 Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
2754 but it kills all buffers except the Group buffer. I'm not sure why this
2755 is a gain, but then who am I to judge?
2758 @findex gnus-group-exit
2759 Quit Gnus (@code{gnus-group-exit}).
2762 @findex gnus-group-quit
2763 Quit Gnus without saving any startup files (@code{gnus-group-quit}).
2766 @vindex gnus-exit-gnus-hook
2767 @vindex gnus-suspend-gnus-hook
2768 @code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
2769 @code{gnus-exit-gnus-hook} is called when you quit Gnus.
2773 If you wish to completely unload Gnus and all its adherents, you can use
2774 the @code{gnus-unload} command. This command is also very handy when
2775 trying to custoize meta-variables.
2780 Miss Lisa Cannifax, while sitting in English class, feels her feet go
2781 numbly heavy and herself fall into a hazy trance as the boy sitting
2782 behind her drew repeated lines with his pencil across the back of her
2786 @node Misc Group Stuff
2787 @section Misc Group Stuff
2792 @findex gnus-group-get-new-news
2793 Check server for new articles. If the numeric prefix is used, this
2794 command will check only groups of level ARG and lower
2795 (@code{gnus-group-get-new-news}).
2798 @findex gnus-group-get-new-news-this-group
2799 Check whether new articles have arrived in the current group
2800 (@code{gnus-group-get-new-news-this-group}).
2804 @findex gnus-group-enter-server-mode
2805 Enter the server buffer (@code{gnus-group-enter-server-mode}). @xref{The
2810 @findex gnus-group-fetch-faq
2811 Try to fetch the FAQ for the current group
2812 (@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
2813 @code{gnus-group-faq-directory}, which is usually a directory on a
2814 remote machine. ange-ftp will be used for fetching the file.
2817 @findex gnus-group-restart
2818 Restart Gnus (@code{gnus-group-restart}).
2821 @findex gnus-group-read-init-file
2822 @vindex gnus-init-file
2823 Read the init file (@code{gnus-init-file}, which defaults to
2824 @file{~/.gnus}) (@code{gnus-group-read-init-file}).
2827 @findex gnus-group-save-newsrc
2828 Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
2829 (@code{gnus-group-save-newsrc}).
2832 @findex gnus-group-clear-dribble
2833 Clear the dribble buffer (@code{gnus-group-clear-dribble}).
2836 @findex gnus-group-describe-group
2837 Describe the current group (@code{gnus-group-describe-group}). If given
2838 a prefix, force Gnus to re-read the description from the server.
2841 @findex gnus-group-apropos
2842 List all groups that have names that match a regexp
2843 (@code{gnus-group-apropos}).
2846 @findex gnus-group-description-apropos
2847 List all groups that have names or descriptions that match a regexp
2848 (@code{gnus-group-description-apropos}).
2851 @findex gnus-group-post-news
2852 Post an article to a group (@code{gnus-group-post-news}).
2855 @findex gnus-group-mail
2856 Mail a message somewhere (@code{gnus-group-mail}).
2858 @kindex C-x C-t (Group)
2859 @findex gnus-group-transpose-groups
2860 Transpose two groups (@code{gnus-group-transpose-groups}).
2863 @findex gnus-version
2864 Display current Gnus version numbers (@code{gnus-version}).
2867 @findex gnus-group-describe-all-groups
2868 Describe all groups (@code{gnus-group-describe-all-groups}). If given a
2869 prefix, force Gnus to re-read the description file from the server.
2872 @findex gnus-group-describe-briefly
2873 Give a very short help message (@code{gnus-group-describe-briefly}).
2875 @kindex C-c C-i (Group)
2876 @findex gnus-info-find-node
2877 Go to the Gnus info node (@code{gnus-info-find-node}).
2880 @vindex gnus-group-prepare-hook
2881 @code{gnus-group-prepare-hook} is called after the group buffer is
2882 generated. It may be used to modify the buffer in some strange,
2885 @node The Summary Buffer
2886 @chapter The Summary Buffer
2887 @cindex summary buffer
2889 A line for each article is displayed in the summary buffer. You can
2890 move around, read articles, post articles and reply to articles.
2893 * Summary Buffer Format:: Deciding how the summary buffer is to look.
2894 * Summary Maneuvering:: Moving around the summary buffer.
2895 * Choosing Articles:: Reading articles.
2896 * Paging the Article:: Scrolling the current article.
2897 * Reply Followup and Post:: Posting articles.
2898 * Canceling and Superseding:: "Whoops, I shouldn't have called him that."
2899 * Marking Articles:: Marking articles as read, expirable, etc.
2900 * Threading:: How threads are made.
2901 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
2902 * Article Caching:: You may store articles in a cache.
2903 * Exiting the Summary Buffer:: Returning to the Group buffer.
2904 * Process/Prefix:: A convention used by many treatment commands.
2905 * Saving Articles:: Ways of customizing article saving.
2906 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
2907 * Various Article Stuff:: Various stuff dealing with articles.
2908 * Summary Sorting:: You can sort the summary buffer four ways.
2909 * Finding the Parent:: No child support? Get the parent.
2910 * Score Files:: Maintaining a score file.
2911 * Mail Group Commands:: Some commands can only be used in mail groups.
2912 * Various Summary Stuff:: What didn't fit anywhere else.
2915 @node Summary Buffer Format
2916 @section Summary Buffer Format
2917 @cindex summary buffer format
2920 * Summary Buffer Lines:: You can specify how summary lines should look.
2921 * Summary Buffer Mode Line:: You can say how the mode line should look.
2924 @findex mail-extract-address-components
2925 @findex gnus-extract-address-components
2926 @vindex gnus-extract-address-components
2927 Gnus will use the value of the @code{gnus-extract-address-components}
2928 variable as a function for getting the name and address parts of a
2929 @code{From} header. Two pre-defined function exist:
2930 @code{gnus-extract-address-components}, which is the default, quite
2931 fast, and too simplistic solution, and
2932 @code{mail-extract-address-components}, which works very nicely, but is
2935 @vindex gnus-summary-same-subject
2936 @code{gnus-summary-same-subject} is a string indicating that the current
2937 article has the same subject as the previous. This string will be used
2938 with those specs that require it.
2940 @node Summary Buffer Lines
2941 @subsection Summary Buffer Lines
2943 @vindex gnus-summary-line-format
2944 You can change the format of the lines in the summary buffer by changing
2945 the @code{gnus-summary-line-format} variable. It works along the same
2946 lines a a normal @code{format} string, with some extensions.
2948 The default string is @samp{"%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n"}.
2950 The following format specification characters are understood:
2958 Subject if the article is the root, @code{gnus-summary-same-subject}
2961 Full @code{From} line.
2963 The name (from the @code{From} header).
2965 The name (from the @code{From} header). This differs from the @code{n}
2966 spec in that it uses @code{gnus-extract-address-components}, which is
2967 slower, but may be more thorough.
2969 The address (from the @code{From} header). This works the same way as
2972 Number of lines in the article.
2974 Number of characters in the article.
2976 Indentation based on thread level (@pxref{Customizing Threading}).
2978 Nothing if the article is a root and lots of spaces if it isn't (it
2979 pushes everything after it off the screen).
2981 Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
2982 for adopted articles.
2984 Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
2985 for adopted articles.
2987 One space for each thread level.
2989 Twenty minus thread level spaces.
2997 @vindex gnus-summary-zcore-fuzz
2998 Zcore, @samp{+} if above the default level and @samp{-} if below the
2999 default level. If the difference between
3000 @code{gnus-summary-default-level} and the score is less than
3001 @code{gnus-summary-zcore-fuzz}, this spec will not be used.
3011 Number of articles in the current sub-thread. Using this spec will slow
3012 down summary buffer generation somewhat.
3014 A single character will be displayed if the article has any children.
3016 User defined specifier. The next character in the format string should
3017 be a letter. @sc{gnus} will call the function
3018 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
3019 following @samp{%u}. The function will be passed the current header as
3020 argument. The function should return a string, which will be inserted
3021 into the summary just like information from any other summary specifier.
3024 Text between @samp{%(} and @samp{%)} will be highlighted with
3025 @code{gnus-mouse-face} when the mouse point is placed inside the area.
3026 There can only be one such area.
3028 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
3029 have to be handled with care. For reasons of efficiency, Gnus will
3030 compute what column these characters will end up in, and "hard-code"
3031 that. This means that it is illegal to have these specs after a
3032 variable-length spec. Well, you might not be arrested, but your summary
3033 buffer will look strange, which is bad enough.
3035 The smart choice is to have these specs as far to the left as possible.
3036 (Isn't that the case with everything, though? But I digress.)
3038 This restriction may disappear in later versions of Gnus.
3040 @node Summary Buffer Mode Line
3041 @subsection Summary Buffer Mode Line
3043 @vindex gnus-summary-mode-line-format
3044 You can also change the format of the summary mode bar. Set
3045 @code{gnus-summary-mode-line-format} to whatever you like. Here are the
3046 elements you can play with:
3052 Current article number.
3056 Number of unread articles in this group.
3058 Number of unselected articles in this group.
3060 A string with the number of unread and unselected articles represented
3061 either as @samp{<%U(+%u) more>} if there are both unread and unselected
3062 articles, and just as @samp{<%U more>} if there are just unread articles
3063 and no unselected ones.
3065 Shortish group name. For instance, @samp{rec.arts.anime} will be
3066 shortened to @samp{r.a.anime}.
3068 Subject of the current article.
3072 Name of the current score file.
3076 @node Summary Maneuvering
3077 @section Summary Maneuvering
3078 @cindex summary movement
3080 All the straight movement commands understand the numeric prefix and
3081 behave pretty much as you'd expect.
3083 None of these commands select articles.
3088 @kindex M-n (Summary)
3089 @kindex G M-n (Summary)
3090 @findex gnus-summary-next-unread-subject
3091 Go to the next summary line of an unread article
3092 (@code{gnus-summary-next-unread-subject}).
3095 @kindex M-p (Summary)
3096 @kindex G M-p (Summary)
3097 @findex gnus-summary-prev-unread-subject
3098 Go to the previous summary line of an unread article
3099 (@code{gnus-summary-prev-unread-subject}).
3103 @kindex G g (Summary)
3104 @findex gnus-summary-goto-subject
3105 Ask for an article number and then go to this summary line
3106 (@code{gnus-summary-goto-subject}).
3109 @vindex gnus-auto-select-next
3110 If you are at the end of the group and issue one of the movement
3111 commands, Gnus will offer to go to the next group. If
3112 @code{gnus-auto-select-next} is @code{t} and the next group is empty,
3113 Gnus will exit summary mode and return to the group buffer. If this
3114 variable is neither @code{t} nor @code{nil}, Gnus will select the next
3115 group, no matter whether it has any unread articles or not. As a
3116 special case, if this variable is @code{quietly}, Gnus will select the
3117 next group without asking for confirmation. Also @xref{Group Levels}.
3119 If Gnus asks you to press a key to confirm going to the next group, you
3120 can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
3121 buffer, searching for the next group to read without actually returning
3122 to the group buffer.
3124 @vindex gnus-auto-select-same
3125 If @code{gnus-auto-select-same} is non-@code{nil}, all the movement
3126 commands will try to go to the next article with the same subject as the
3127 current. This variable is not particularly useful if you use a threaded
3130 @vindex gnus-summary-check-current
3131 If @code{gnus-summary-check-current} is non-@code{nil}, all the "unread"
3132 movement commands will not proceed to the next (or previous) article if
3133 the current article is unread. Instead, they will choose the current
3136 @vindex gnus-auto-center-summary
3137 If @code{gnus-auto-center-summary} is non-@code{nil}, Gnus will keep the
3138 point in the summary buffer centered at all times. This makes things
3139 quite tidy, but if you have a slow network connection, or simply do not
3140 like this un-Emacsism, you can set this variable to @code{nil} to get
3141 the normal Emacs scrolling action.
3143 @node Choosing Articles
3144 @section Choosing Articles
3145 @cindex selecting articles
3147 None of the following movement commands understand the numeric prefix,
3148 and they all select and display an article.
3152 @kindex SPACE (Summary)
3153 @findex gnus-summary-next-page
3154 Select the current article, or, if that one's read already, the next
3155 unread article (@code{gnus-summary-next-page}).
3159 @kindex G n (Summary)
3160 @findex gnus-summary-next-unread-article
3161 Go to next unread article (@code{gnus-summary-next-unread-article}).
3165 @findex gnus-summary-prev-unread-article
3166 Go to previous unread article (@code{gnus-summary-prev-unread-article}).
3170 @kindex G N (Summary)
3171 @findex gnus-summary-next-article
3172 Go to the next article (@code{gnus-summary-next-article}).
3176 @kindex G P (Summary)
3177 @findex gnus-summary-prev-article
3178 Go to the previous article (@code{gnus-summary-prev-article}).
3180 @kindex G C-n (Summary)
3181 @findex gnus-summary-next-same-subject
3182 Go to the next article with the same subject
3183 (@code{gnus-summary-next-same-subject}).
3185 @kindex G C-p (Summary)
3186 @findex gnus-summary-prev-same-subject
3187 Go to the previous article with the same subject
3188 (@code{gnus-summary-prev-same-subject}).
3191 @kindex G f (Summary)
3193 @findex gnus-summary-first-unread-article
3194 Go to the first unread article
3195 (@code{gnus-summary-first-unread-article}).
3198 @kindex G b (Summary)
3200 Go to the article with the highest score
3201 (@code{gnus-summary-best-unread-article}).
3205 @kindex G l (Summary)
3206 @findex gnus-summary-goto-last-article
3207 Go to the previous article read (@code{gnus-summary-goto-last-article}).
3209 @kindex G p (Summary)
3210 @findex gnus-summary-pop-article
3211 Pop an article off the summary history and go to this article
3212 (@code{gnus-summary-pop-article}). This command differs from the
3213 command above in that you can pop as many previous articles off the
3214 history as you like.
3217 Some variables that are relevant for moving and selecting articles:
3220 @item gnus-auto-extend-newsgroup
3221 @vindex gnus-auto-extend-newsgroup
3222 All the movement commands will try to go to the previous (or next)
3223 article, even if that article isn't displayed in the Summary buffer if
3224 this variable is non-@code{nil}. Gnus will then fetch the article from
3225 the server and display it in the article buffer.
3226 @item gnus-select-article-hook
3227 @vindex gnus-select-article-hook
3228 This hook is called whenever an article is selected. By default it
3229 exposes any threads hidden under the selected article.
3230 @item gnus-mark-article-hook
3231 @vindex gnus-mark-article-hook
3232 This hook is called whenever an article is selected. It is intended to
3233 be used for marking articles as read.
3234 @item gnus-visual-mark-article-hook
3235 @vindex gnus-visual-mark-article-hook
3236 This hook is run after selecting an article. It is meant to be used for
3237 highlighting the article in some way. It is not run if
3238 @code{gnus-visual} is @code{nil}.
3239 @item gnus-summary-update-hook
3240 @vindex gnus-summary-update-hook
3241 This hook is called when a summary line is changed. It is not run if
3242 @code{gnus-visual} is @code{nil}.
3243 @item gnus-summary-selected-face
3244 @vindex gnus-summary-selected-face
3245 This is the face (or @dfn{font} as some people call it) that is used to
3246 highlight the current article in the summary buffer.
3247 @item gnus-summary-highlight
3248 @vindex gnus-summary-highlight
3249 Summary lines are highlighted according to this variable, which is a
3250 list where the elements are on the format @code{(FORM . FACE)}. If you
3251 would, for instance, like ticked articles to be italic and high-scored
3252 articles to be bold, you could set this variable to something like
3254 (((eq mark gnus-ticked-mark) . italic)
3255 ((> score default) . bold))
3257 As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
3258 @var{FACE} will be applied to the line.
3261 @node Paging the Article
3262 @section Scrolling the Article
3263 @cindex article scrolling
3267 @kindex SPACE (Summary)
3268 @findex gnus-summary-next-page
3269 Pressing @kbd{SPACE} will scroll the current article forward one page,
3270 or, if you have come to the end of the current article, will choose the
3271 next article (@code{gnus-summary-next-page}).
3273 @kindex DEL (Summary)
3274 @findex gnus-summary-prev-page
3275 Scroll the current article back one page (@code{gnus-summary-prev-page}).
3277 @kindex RET (Summary)
3278 @findex gnus-summary-scroll-up
3279 Scroll the current article one line forward
3280 (@code{gnus-summary-scroll-up}).
3284 @kindex A < (Summary)
3285 @findex gnus-summary-beginning-of-article
3286 Scroll to the beginning of the article
3287 (@code{gnus-summary-beginning-of-article}).
3291 @kindex A > (Summary)
3292 @findex gnus-summary-end-of-article
3293 Scroll to the end of the article (@code{gnus-summary-end-of-article}).
3296 @node Reply Followup and Post
3297 @section Reply, Followup and Post
3302 @kindex C-c C-c (Post)
3303 All the commands for posting and mailing will put you in a post or mail
3304 buffer where you can edit the article all you like, before you send the
3305 article by pressing @kbd{C-c C-c}. If you are in a foreign news group,
3306 and you wish to post the article using the foreign server, you can give
3307 a prefix to @kbd{C-c C-c} to make Gnus try to post using the foreign
3311 * Mail:: Mailing & replying.
3312 * Post:: Posting and following up.
3313 * Mail & Post:: Mailing and posting at the same time.
3319 Commands for composing a mail message:
3324 @kindex S r (Summary)
3326 @findex gnus-summary-reply
3327 Mail a reply to the author of the current article
3328 (@code{gnus-summary-reply}).
3332 @kindex S R (Summary)
3333 @findex gnus-summary-reply-with-original
3334 Mail a reply to the author of the current article and include the
3335 original message (@code{gnus-summary-reply-with-original}). This
3336 command uses the process/prefix convention.
3338 @kindex S o m (Summary)
3339 @findex gnus-summary-mail-forward
3340 Forward the current article to some other person
3341 (@code{gnus-summary-mail-forward}).
3343 @kindex S o p (Summary)
3344 @findex gnus-summary-post-forward
3345 Forward the current article to a newsgroup
3346 (@code{gnus-summary-post-forward}).
3350 @kindex S m (Summary)
3351 @findex gnus-summary-mail-other-window
3352 Send a mail to some other person
3353 (@code{gnus-summary-mail-other-window}).
3355 @kindex S O m (Summary)
3356 @findex gnus-uu-digest-mail-forward
3357 Digest the current series and forward the result using mail
3358 (@code{gnus-uu-digest-mail-forward}). This command uses the
3359 process/prefix convention (@pxref{Process/Prefix}).
3361 @kindex S O p (Summary)
3362 @findex gnus-uu-digest-post-forward
3363 Digest the current series and forward the result to a newsgroup
3364 (@code{gnus-uu-digest-mail-forward}).
3367 Variables for customizing outgoing mail:
3370 @item gnus-reply-to-function
3371 @vindex gnus-reply-to-function
3372 Gnus uses the normal methods to determine where replies are to go, but
3373 you can change the behavior to suit your needs by fiddling with this
3376 If you want the replies to go to the @samp{Sender} instead of the
3377 @samp{From} in the group @samp{mail.stupid-list}, you could do something
3381 (setq gnus-reply-to-function
3383 (cond ((string= group "mail.stupid-list")
3384 (mail-fetch-field "sender"))
3389 This function will be called narrowed to the head of the article that is
3392 As you can see, this function should return a string if it has an
3393 opinion as to what the To header should be. If it does not, it should
3394 just return @code{nil}, and the normal methods for determining the To
3395 header will be used.
3397 This function can also return a list. In that case, each list element
3398 should be a cons, where the car should be the name of an header
3399 (eg. @samp{Cc}) and the cdr should be the header value
3400 (eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into
3401 the head of the outgoing mail.
3403 @item gnus-mail-send-method
3404 @vindex gnus-mail-send-method
3405 This variable says how a mail should be mailed. It uses the function in
3406 the @code{send-mail-function} variable as the default.
3408 @item gnus-uu-digest-headers
3409 @vindex gnus-uu-digest-headers
3410 List of regexps to match headers included in digested messages. The
3411 headers will be included in the sequence they are matched.
3413 @item gnus-mail-hook
3414 Hook called as the last thing after setting up a mail buffer.
3418 There are three "methods" for handling all mail. The default is
3419 @code{sendmail}. Some people like what @code{mh} does better, and some
3420 people prefer @code{vm}.
3422 Three variables for customizing what to use when:
3426 @vindex gnus-mail-reply-method
3427 @item gnus-mail-reply-method
3428 This function is used to compose replies. The three functions avaibale
3431 @findex gnus-mail-reply-using-vm
3432 @findex gnus-mail-reply-using-mhe
3433 @findex gnus-mail-reply-using-mail
3436 @code{gnus-mail-reply-using-mail} (sendmail)
3438 @code{gnus-mail-reply-using-mhe} (mh)
3440 @code{gnus-mail-reply-using-vm} (vm)
3443 @vindex gnus-mail-forward-method
3444 @item gnus-mail-forward-method
3445 This function is used to forward messages. The three functions avaibale
3448 @findex gnus-mail-forward-using-vm
3449 @findex gnus-mail-forward-using-mhe
3450 @findex gnus-mail-forward-using-mail
3453 @code{gnus-mail-forward-using-mail} (sendmail)
3455 @code{gnus-mail-forward-using-mhe} (mh)
3457 @code{gnus-mail-forward-using-vm} (vm)
3460 @vindex gnus-mail-other-window-method
3461 @item gnus-mail-other-window-method
3462 This function is used to send mails. The three functions avaibale are:
3464 @findex gnus-mail-other-window-using-vm
3465 @findex gnus-mail-other-window-using-mhe
3466 @findex gnus-mail-other-window-using-mail
3469 @code{gnus-mail-other-window-using-mail} (sendmail)
3471 @code{gnus-mail-other-window-using-mhe} (mh)
3473 @code{gnus-mail-other-window-using-vm} (vm)
3482 Commands for posting an article:
3488 @kindex S p (Summary)
3489 @findex gnus-summary-post-news
3490 Post an article to the current group
3491 (@code{gnus-summary-post-news}).
3495 @kindex S f (Summary)
3496 @findex gnus-summary-followup
3497 Post a followup to the current article (@code{gnus-summary-followup}).
3500 @kindex S F (Summary)
3502 @findex gnus-summary-followup-with-original
3503 Post a followup to the current article and include the original message
3504 (@code{gnus-summary-followup-with-original}). This command uses the
3505 process/prefix convention.
3507 @kindex S u (Summary)
3508 @findex gnus-uu-post-news
3509 Uuencode a file, split it into parts, and post it as a series
3510 (@code{gnus-uu-post-news}).
3511 @c (@pxref{Uuencoding & Posting}).
3514 @vindex gnus-required-headers
3515 @code{gnus-required-headers} a list of header symbols. These headers
3516 will either be automatically generated, or, if that's impossible, they
3517 will be prompted for. The following symbols are legal:
3521 This required header will be filled out with the result of the
3522 @code{gnus-inews-user-name} function, which depends on the
3523 @code{gnus-user-from-line}, @code{gnus-user-login-name},
3524 @code{gnus-local-domain} and @code{user-mail-address} variables.
3526 This required header will be prompted for if not present already.
3528 This required header says which newsgroups the article is to be posted
3529 to. If it isn't present already, it will be prompted for.
3531 @cindex organization
3532 @vindex gnus-local-organization
3533 @vindex gnus-organization-file
3534 This optional header will be filled out depending on the
3535 @code{gnus-local-organization} variable. @code{gnus-organization-file}
3536 will be used if that variable is nil.
3538 This optional header will be computed by Gnus.
3540 This required header will be generated by Gnus. A unique ID will be
3541 created based on date, time, user name and system name.
3543 This optional header will be filled out with the Gnus version numbers.
3546 In addition, you can enter conses into this list. The car of this cons
3547 should be a symbol who's name is the name of the header, and the cdr can
3548 either a string to be entered verbatim as the value of this header, or
3549 it can be a function to be called. This function should return a string
3550 to be inserted. For instance, if you want to insert @samp{Mime-Version:
3551 1.0}, you should enter @code{(Mime-Version . "1.0")} into the list. If
3552 you want to insert a funny quote, you could enter something like
3553 @code{(X-Yow . yow)} into the list. The function @code{yow} will then
3554 be called without any arguments.
3556 Other variables for customizing outgoing articles:
3559 @item gnus-post-method
3560 @vindex gnus-post-method
3561 If non-@code{nil}, Gnus will use this method instead of the default
3562 select method when posting.
3564 @item nntp-news-default-headers
3565 @vindex nntp-news-default-headers
3566 If non-@code{nil}, this variable will override
3567 @code{mail-default-headers} when posting. This variable should then be
3568 a string. This string will be inserted, as is, in the head of all
3571 @item gnus-use-followup-to
3572 @vindex gnus-use-followup-to
3573 If @code{nil}, always ignore the Followup-To header. If it is @code{t},
3574 use its value, but ignore the special value @samp{poster}, which will
3575 send the followup as a reply mail to the person you are responding to.
3576 If it is the symbol @code{ask}, query the user before posting.
3577 If it is the symbol @code{use}, always use the value.
3579 @item gnus-followup-to-function
3580 @vindex gnus-followup-to-function
3581 This variable is most useful in mail groups, where "following up" really
3582 means sending a mail to a list address. Gnus uses the normal methods to
3583 determine where follow-ups are to go, but you can change the behavior
3584 to suit your needs by fiddling with this variable.
3586 If you want the followups to go to the @samp{Sender} instead of the
3587 @samp{From} in the group @samp{mail.stupid-list}, you could do something
3591 (setq gnus-followup-to-function
3593 (cond ((string= group "mail.stupid-list")
3594 (mail-fetch-field "sender"))
3599 This function will be called narrowed to header of the article that is
3602 @item gnus-removable-headers
3603 @vindex gnus-removable-headers
3604 Some headers that are generated are toxic to the @sc{nntp} server.
3605 These include the @code{NNTP-Posting-Host}, @code{Bcc} and @code{Xref},
3606 so these headers are deleted if they are present in this list of
3609 @item gnus-deletable-headers
3610 @vindex gnus-deletable-headers
3611 Headers in this list that were previously generated by Gnus will be
3612 deleted before posting. Let's say you post an article. Then you decide
3613 to post it again to some other group, you naughty boy, so you jump back
3614 to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
3615 ship it off again. By default, this variable makes sure that the old
3616 generated @code{Message-ID} is deleted, and a new one generated. If
3617 this isn't done, the entire empire would probably crumble, anarchy would
3618 prevail, and cats would start walking on two legs and rule the world.
3621 @item gnus-signature-function
3622 @vindex gnus-signature-function
3623 If non-@code{nil}, this variable should be a function that returns a
3624 signature file name. The function will be called with the name of the
3625 group being posted to. If the function returns a string that doesn't
3626 correspond to a file, the string itself is inserted. If the function
3627 returns @code{nil}, the @code{gnus-signature-file} variable will be used
3630 @item gnus-post-prepare-function
3631 @vindex gnus-post-prepare-function
3632 This function is called with the name of the current group after the
3633 post buffer has been initialized, and can be used for inserting a
3634 signature. Nice if you use different signatures in different groups.
3636 @item gnus-post-prepapare-hook
3637 @vindex gnus-post-prepapare-hook
3638 This hook is called after a post buffer has been prepared. If you want
3639 to insert a signature at this point, you could put
3640 @code{gnus-inews-insert-signature} into this hook.
3642 @item news-reply-header-hook
3643 @vindex news-reply-header-hook
3644 A related variable when following up and replying is this variable,
3645 which inserts the @dfn{quote line}. The default value is:
3648 (defvar news-reply-header-hook
3650 (insert "In article " news-reply-yank-message-id
3651 " " news-reply-yank-from " writes:\n\n")))
3654 This will create lines like:
3657 In article <zngay8jrql@@eyesore.no> Lars Mars <lars@@eyesore.no> writes:
3660 Having the @code{Message-Id} in this line is probably overkill, so I
3661 would suggest this hook instead:
3664 (setq news-reply-header-hook
3665 (lambda () (insert news-reply-yank-from " writes:\n\n")))
3668 @item gnus-prepare-article-hook
3669 @vindex gnus-prepare-article-hook
3670 This hook is called before the headers have been prepared. By default
3671 it inserts the signature specified by @code{gnus-signature-file}.
3673 @item gnus-inews-article-function
3674 @vindex gnus-inews-article-function
3675 This function is used to do the actual article processing and header
3676 checking/generation.
3678 @item gnus-inews-article-hook
3679 @vindex gnus-inews-article-hook
3680 This hook is called right before the article is posted. By default it
3681 handles FCC processing (i.e., saving the article to a file.)
3683 @item gnus-inews-article-header-hook
3684 @vindex gnus-inews-article-header-hook
3685 This hook is called after inserting the required headers in an article
3686 to be posted. The hook is called from the @code{*post-news*} buffer,
3687 narrowed to the head, and is intended for people who would like to
3688 insert additional headers, or just change headers in some way or other.
3690 @item gnus-check-before-posting
3691 @vindex gnus-check-before-posting
3692 If non-@code{nil}, Gnus will attempt to check the legality of the
3693 headers, as well as some other stuff, before posting. You can control
3694 the granularity of the check by adding or removing elements from this
3695 list. Legal elemetents are:
3699 Check the subject for commands.
3700 @item multiple-headers
3701 Check for the existence of multiple equal headers.
3703 Check for the existence of version and sendsys commands.
3705 Check whether the @code{Message-ID} looks ok.
3707 Check whether the @code{From} header seems nice.
3709 Check for too long lines.
3711 Check for illegal characters.
3713 Check for excessive size.
3715 Check whether there is any new text in the messages.
3717 Check the length of the signature
3724 @subsection Mail & Post
3726 Commands for sending mail and post at the same time:
3730 @kindex S b (Summary)
3731 @findex gnus-summary-followup-and-reply
3732 Post a followup and send a reply to the current article
3733 (@code{gnus-summary-followup-and-reply}).
3735 @kindex S B (Summary)
3736 @findex gnus-summary-followup-and-reply-with-original
3737 Post a followup and send a reply to the current article and include the
3738 original message (@code{gnus-summary-followup-and-reply-with-original}).
3739 This command uses the process/prefix convention.
3742 Here's a list of variables that are relevant to both mailing and
3746 @item gnus-signature-file
3747 @itemx mail-signature
3748 @vindex mail-signature
3749 @vindex gnus-signature-file
3750 @cindex double signature
3752 If @code{gnus-signature-file} is non-@code{nil}, it should be the name
3753 of a file containing a signature (@samp{~/.signature} by default). This
3754 signature will be appended to all outgoing post. Most people find it
3755 more convenient to use @code{mail-signature}, which (sort of) does the
3756 same, but inserts the signature into the buffer before you start editing
3757 the post (or mail). So - if you have both of these variables set, you
3758 will get two signatures. Note that @code{mail-signature} does not work
3759 the same way as @code{gnus-signature-file}, which is a bit confusing.
3760 If @code{mail-signature} is @code{t}, it will insert
3761 @file{~/.signature}. If it is a string, this string will be inserted.
3763 Note that RFC1036 says that a signature should be preceded by the three
3764 characters @samp{-- } on a line by themselves. This is to make it
3765 easier for the recipient to automatically recognize and process the
3766 signature. So don't remove those characters, even though you might feel
3767 that they ruin you beautiful design, like, totally.
3769 Also note that no signature should be more than four lines long.
3770 Including ASCII graphics is an efficient way to get everybody to believe
3771 that you are silly and have nothing important to say.
3773 @item mail-yank-prefix
3774 @vindex mail-yank-prefix
3777 When you are replying to or following up an article, you normally want
3778 to quote the person you are answering. Inserting quoted text is done by
3779 @dfn{yanking}, and each quoted line you yank will have
3780 @code{mail-yank-prefix} prepended to it. This is @samp{ } by default,
3781 which isn't very pretty. Most everybody prefers that lines are
3782 prepended with @samp{> }, so @code{(setq mail-yank-prefix "> ")} in your
3785 @item mail-yank-ignored-headers
3786 @vindex mail-yank-ignored-headers
3787 When you yank a message, you do not want to quote any headers, so
3788 @code{(setq mail-yank-ignored-headers ":")}.
3790 @item user-mail-address
3791 @vindex user-mail-address
3792 If all of @code{gnus-user-login-name}, @code{gnus-use-generic-from} and
3793 @code{gnus-local-domain} are @code{nil}, Gnus will use
3794 @code{user-mail-address} as the address part of the @code{From} header.
3796 @item gnus-user-from-line
3797 @vindex gnus-user-from-line
3798 Your full, complete e-mail address. This variable overrides the other
3799 Gnus variables if it is non-@code{nil}.
3801 Here are two example values of this variable: @samp{"larsi@@ifi.uio.no
3802 (Lars Magne Ingebrigtsen)"} and @samp{"Lars Magne Ingebrigtsen
3803 <larsi@@ifi.uio.no>"}. The latter version is recommended, but the name
3804 has to be quoted if it contains non-alpha-numerical characters -
3805 @samp{"\"Lars M. Ingebrigtsen\" <larsi@@ifi.uio.no>"}.
3807 @item mail-default-headers
3808 @vindex mail-default-headers
3809 This is a string that will be inserted into the header of all outgoing
3810 mail messages and news articles. Convenient to use to insert standard
3811 headers. If @code{nntp-news-default-headers} is non-@code{nil}, that
3812 variable will override this one when posting articles.
3814 @item gnus-auto-mail-to-author
3815 @vindex gnus-auto-mail-to-author
3816 If @code{ask}, you will be prompted for whether you want to send a mail
3817 copy to the author of the article you are following up. If
3818 non-@code{nil} and not @code{ask}, Gnus will send a mail with a copy of
3819 all follow-ups to the authors of the articles you follow up. It's nice
3820 in one way - you make sure that the person you are responding to gets
3821 your response. Other people loathe this method and will hate you dearly
3822 for it, because it means that they will first get a mail, and then have
3823 to read the same article later when they read the news. It is
3824 @code{nil} by default.
3826 @item gnus-mail-courtesy-message
3827 @vindex gnus-mail-courtesy-message
3828 This is a string that will be prepended to all mails that are the result
3829 of using the variable described above.
3833 You may want to do spell-checking on messages that you send out. Or, if
3834 you don't want to spell-check by hand, you could add automatic
3835 spell-checking via the @code{ispell} package:
3837 @vindex news-inews-hook
3839 (add-hook 'news-inews-hook 'ispell-message) ;For news posts
3840 (add-hook 'mail-send-hook 'ispell-message) ;for mail posts via sendmail
3843 @findex gnus-inews-insert-mime-headers
3844 If you want to insert some @sc{mime} headers into the articles you post,
3845 without doing any actual encoding, you could add
3846 @code{gnus-inews-insert-mime-headers} to @code{gnus-inews-article-hook}.
3849 @node Canceling and Superseding
3850 @section Canceling Articles
3851 @cindex canceling articles
3852 @cindex superseding articles
3854 Have you ever written something, and then decided that you really,
3855 really, really wish you hadn't posted that?
3857 Well, you can't cancel mail, but you can cancel posts.
3859 @findex gnus-summary-cancel-article
3861 Find the article you wish to cancel (you can only cancel your own
3862 articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
3863 c} (@code{gnus-summary-cancel-article}). Your article will be
3864 canceled - machines all over the world will be deleting your article.
3866 Be aware, however, that not all sites honor cancels, so your article may
3867 live on here and there, while most sites will delete the article in
3870 If you discover that you have made some mistakes and want to do some
3871 corrections, you can post a @dfn{superseding} article that will replace
3872 your original article.
3874 @findex gnus-summary-supersede-article
3876 Go to the original article and press @kbd{S s}
3877 (@code{gnus-summary-supersede-article}). You will be put in a buffer
3878 where you can edit the article all you want before sending it off the
3881 @vindex gnus-delete-supersedes-headers
3882 You probably want to delete some of the old headers before sending the
3883 superseding article - @code{Path} and @code{Date} are probably
3884 incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
3885 match the lines you want removed. The default is
3886 @samp{"^Path:\\|^Date"}.
3888 The same goes for superseding as for canceling, only more so: Some
3889 sites do not honor superseding. On those sites, it will appear that you
3890 have posted almost the same article twice.
3892 If you have just posted the article, and change your mind right away,
3893 there is a trick you can use to cancel/supersede the article without
3894 waiting for the article to appear on your site first. You simply return
3895 to the post buffer (which is called @code{*post-buf*}). There you will
3896 find the article you just posted, with all the headers intact. Change
3897 the @samp{Message-ID} header to a @samp{Cancel} or @samp{Supersedes}
3898 header by substituting one of those words for @samp{Message-ID}. Then
3899 just press @kbd{C-c C-c} to send the article as you would do normally.
3900 The previous article will be canceled/superseded.
3902 Just remember, kids: There is no 'c' in 'supersede'.
3904 @node Marking Articles
3905 @section Marking Articles
3906 @cindex article marking
3907 @cindex article ticking
3910 There are several marks you can set on an article.
3912 You have marks that decide the @dfn{readed-ness} (whoo, neato-keano
3913 neologism ohoy!) of the article. Alphabetic marks generally mean
3914 @dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
3916 In addition, you also have marks that do not affect readedness.
3919 * Unread Articles:: Marks for unread articles.
3920 * Read Articles:: Marks for read articles.
3921 * Other Marks:: Marks that do not affect readedness.
3925 There's a plethora of commands for manipulating these marks:
3929 * Setting Marks:: How to set and remove marks.
3930 * Setting Process Marks:: How to mark articles for later processing.
3933 @node Unread Articles
3934 @subsection Unread Articles
3936 The following marks mark articles as unread, in one form or other.
3938 @vindex gnus-dormant-mark
3939 @vindex gnus-ticked-mark
3942 @dfn{Ticked articles} are articles that will remain visible always. If
3943 you see an article that you find interesting, or you want to put off
3944 reading it, or replying to it, until sometime later, you'd typically
3945 tick it. However, articles can be expired, so if you want to keep an
3946 article forever, you'll have to save it. Ticked articles have a
3947 @samp{!} (@code{gnus-ticked-mark}) in the first column.
3949 A @dfn{dormant} article is marked with a @samp{?}
3950 (@code{gnus-dormant-mark}), and will only appear in the summary buffer
3951 if there are followups to it.
3953 An @dfn{unread} article is marked with a @samp{SPC}
3954 (@code{gnus-unread-mark}). These are articles that haven't been read at
3959 @subsection Read Articles
3960 @cindex expirable mark
3962 All the following marks mark articles as read.
3966 Articles that are marked as read. They have a @samp{r}
3967 (@code{gnus-del-mark}) in the first column. These are articles that the
3968 user has marked as read more or less manually.
3970 Articles that are actually read are marked with @samp{R}
3971 (@code{gnus-read-mark}).
3973 Articles that were marked as read in previous sessions are now
3974 @dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
3976 Marked as killed (@code{gnus-killed-mark}).
3978 Marked as killed by kill files (@code{gnus-kill-file-mark}).
3980 Marked as read by having a too low score (@code{gnus-low-score-mark}).
3982 Marked as read by a catchup (@code{gnus-catchup-mark}).
3984 Canceled article (@code{gnus-cancelled-mark})
3987 All these marks just mean that the article is marked as read, really.
3988 They are interpreted differently by the adaptive scoring scheme,
3991 One more special mark, though:
3995 You can also mark articles as @dfn{expirable} (or have them marked as
3996 such automatically). That doesn't make much sense in normal groups,
3997 because a user does not control the expiring of news articles, but in
3998 mail groups, for instance, articles that are marked as @dfn{expirable}
3999 can be deleted by Gnus at any time. Expirable articles are marked with
4000 @samp{E} (@code{gnus-expirable-mark}).
4004 @subsection Other Marks
4005 @cindex process mark
4008 There are some marks that have nothing to do with whether the article is
4011 You can set a bookmark in the current article. Say you are reading a
4012 long thesis on cat's urinary tracts, and have to go home for dinner
4013 before you've finished reading the thesis. You can then set a bookmark
4014 in the article, and Gnus will jump to this bookmark the next time it
4015 encounters the article.
4017 All articles that you have replied to or made a followup to (i.e., have
4018 answered) will be marked with an @samp{A} in the second column
4019 (@code{gnus-replied-mark}).
4021 @vindex gnus-not-empty-thread-mark
4022 @vindex gnus-empty-thread-mark
4023 It the @samp{%e} spec is used, the presence of threads or not will be
4024 marked with @code{gnus-not-empty-thread-mark} and
4025 @code{gnus-empty-thread-mark}, respectively.
4027 @vindex gnus-process-mark
4028 Finally we have the @dfn{process mark} (@code{gnus-process-mark}. A
4029 variety of commands react to the presence of the process mark. For
4030 instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
4031 all articles that have been marked with the process mark. Articles
4032 marked with the process mark have a @samp{#} in the second column.
4035 @subsection Setting Marks
4036 @cindex setting marks
4038 All the marking commands understand the numeric prefix.
4044 @kindex M t (Summary)
4045 @findex gnus-summary-tick-article-forward
4046 Tick the current article (@code{gnus-summary-tick-article-forward}).
4050 @kindex M ? (Summary)
4051 @findex gnus-summary-mark-as-dormant
4052 Mark the current article as dormant
4053 (@code{gnus-summary-mark-as-dormant}).
4056 @kindex M d (Summary)
4058 @findex gnus-summary-mark-as-read-forward
4059 Mark the current article as read
4060 (@code{gnus-summary-mark-as-read-forward}).
4064 @kindex M k (Summary)
4065 @findex gnus-summary-kill-same-subject-and-select
4066 Mark all articles that have the same subject as the current one as read,
4067 and then select the next unread article
4068 (@code{gnus-summary-kill-same-subject-and-select}).
4071 @kindex M K (Summary)
4072 @kindex C-k (Summary)
4073 @findex gnus-summary-kill-same-subject
4074 Mark all articles that have the same subject as the current one as read
4075 (@code{gnus-summary-kill-same-subject}).
4077 @kindex M C (Summary)
4078 @findex gnus-summary-catchup
4079 Catchup the current group (@code{gnus-summary-catchup}).
4081 @kindex M C-c (Summary)
4082 @findex gnus-summary-catchup-all
4083 Catchup all articles in the current group (@code{gnus-summary-catchup-all}).
4085 @kindex M H (Summary)
4086 @findex gnus-summary-catchup-to-here
4087 Catchup the current group to point
4088 (@code{gnus-summary-catchup-to-here}).
4090 @kindex C-w (Summary)
4091 @findex gnus-summary-mark-region-as-read
4092 Mark all articles between point and mark as read
4093 (@code{gnus-summary-mark-region-as-read}).
4096 @kindex M c (Summary)
4097 @kindex M-u (Summary)
4098 @findex gnus-summary-clear-mark-forward
4099 Clear all readedness-marks from the current article
4100 (@code{gnus-summary-clear-mark-forward}).
4103 @kindex M e (Summary)
4105 @findex gnus-summary-mark-as-expirable
4106 Mark the current article as expirable
4107 (@code{gnus-summary-mark-as-expirable}).
4109 @kindex M b (Summary)
4110 @findex gnus-summary-set-bookmark
4111 Set a bookmark in the current article
4112 (@code{gnus-summary-set-bookmark}).
4114 @kindex M B (Summary)
4115 @findex gnus-summary-remove-bookmark
4116 Remove the bookmark from the current article
4117 (@code{gnus-summary-remove-bookmark}).
4120 @kindex M M-r (Summary)
4121 @kindex M-d (Summary)
4122 @findex gnus-summary-remove-lines-marked-as-read
4123 Expunge all deleted articles from the summary buffer
4124 (@code{gnus-summary-remove-lines-marked-as-read}).
4126 @kindex M M-C-r (Summary)
4127 @findex gnus-summary-remove-lines-marked-with
4128 Ask for a mark and then expunge all articles that have been marked with
4129 that mark (@code{gnus-summary-remove-lines-marked-with}).
4131 @kindex M S (Summary)
4132 @findex gnus-summary-show-all-expunged
4133 Display all expunged articles (@code{gnus-summary-show-all-expunged}).
4135 @kindex M D (Summary)
4136 @findex gnus-summary-show-all-dormant
4137 Display all dormant articles (@code{gnus-summary-show-all-dormant}).
4139 @kindex M M-D (Summary)
4140 @findex gnus-summary-hide-all-dormant
4141 Hide all dormant articles (@code{gnus-summary-hide-all-dormant}).
4143 @kindex M V k (Summary)
4144 @findex gnus-summary-kill-below
4145 Kill all articles with scores below the default score (or below the
4146 numeric prefix) (@code{gnus-summary-kill-below}).
4148 @kindex M V c (Summary)
4149 @findex gnus-summary-clear-above
4150 Clear all marks from articles with scores over the default score (or
4151 over the numeric prefix) (@code{gnus-summary-clear-above}).
4153 @kindex M V u (Summary)
4154 @findex gnus-summary-tick-above
4155 Tick all articles with scores over the default score (or over the
4156 numeric prefix) (@code{gnus-summary-tick-above}).
4158 @kindex M V m (Summary)
4159 @findex gnus-summary-mark-above
4160 Prompt for a mark, and mark all articles with scores over the default
4161 score (or over the numeric prefix) with this mark
4162 (@code{gnus-summary-clear-above}).
4165 @code{gnus-summary-goto-unread}
4166 The @code{gnus-summary-goto-unread} variable controls what action should
4167 be taken after setting a mark. If non-@code{nil}, point will move to
4168 the next/previous unread article. If @code{nil}, point will just move
4169 one line up or down.
4171 @node Setting Process Marks
4172 @subsection Setting Process Marks
4173 @cindex setting process marks
4179 @kindex M P p (Summary)
4180 @findex gnus-summary-mark-as-processable
4181 Mark the current article with the process mark
4182 (@code{gnus-summary-mark-as-processable}).
4183 @findex gnus-summary-unmark-as-processable
4186 @kindex M P u (Summary)
4187 @kindex M-# (Summary)
4188 Remove the process mark, if any, from the current article
4189 (@code{gnus-summary-unmark-as-processable}).
4191 @kindex M P U (Summary)
4192 @findex gnus-summary-unmark-all-processable
4193 Remove the process mark from all articles
4194 (@code{gnus-summary-unmark-all-processable}).
4196 @kindex M P R (Summary)
4197 @findex gnus-uu-mark-by-regexp
4198 Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
4200 @kindex M P r (Summary)
4201 @findex gnus-uu-mark-region
4202 Mark articles in region (@code{gnus-uu-mark-region}).
4204 @kindex M P t (Summary)
4205 @findex gnus-uu-mark-thread
4206 Mark all articles in the current (sub)thread
4207 (@code{gnus-uu-mark-thread}).
4209 @kindex M P s (Summary)
4210 @findex gnus-uu-mark-series
4211 Mark all articles in the current series (@code{gnus-uu-mark-series}).
4213 @kindex M P S (Summary)
4214 @findex gnus-uu-mark-sparse
4215 Mark all series that have already had some articles marked
4216 (@code{gnus-uu-mark-sparse}).
4218 @kindex M P a (Summary)
4219 @findex gnus-uu-mark-all
4220 Mark all articles in series order (@code{gnus-uu-mark-series}).
4226 @cindex article threading
4228 Gnus threads articles by default. @dfn{To thread} is to put replies to
4229 articles directly after the articles they reply to - in a hierarchical
4233 * Customizing Threading:: Variables you can change to affect the threading.
4234 * Thread Commands:: Thread based commands in the summary buffer.
4237 @node Customizing Threading
4238 @subsection Customizing Threading
4239 @cindex customizing threading
4244 @item gnus-show-threads
4245 @vindex gnus-show-threads
4246 If this variable is @code{nil}, no threading will be done, and all of
4247 the rest of the variables here will have no effect. Turning threading
4248 off will speed group selection up a bit, but it is sure to make reading
4249 slower and more awkward.
4250 @item gnus-fetch-old-headers
4251 @vindex gnus-fetch-old-headers
4252 If non-@code{nil}, Gnus will attempt to build old threads by fetching
4253 more old headers - headers to articles that are marked as read. If you
4254 would like to display as few summary lines as possible, but still
4255 connect as many loose threads as possible, you should set this variable
4256 to @code{some}. In either case, fetching old headers only works if the
4257 backend you are using carries overview files -- this would normally be
4258 @code{nntp}, @code{nnspool} and @code{nnml}. Also remember that if the
4259 root of the thread has been expired by the server, there's not much Gnus
4262 @item gnus-summary-gather-subject-limit
4263 Loose threads are gathered by comparing subjects of articles. If this
4264 variable is @code{nil}, Gnus requires an exact match between the
4265 subjects of the loose threads before gathering them into one big
4266 super-thread. This might be too strict a requirement, what with the
4267 presence of stupid newsreaders that chop off long subjects lines. If
4268 you think so, set this variable to, say, 20 to require that only the
4269 first 20 characters of the subjects have to match. If you set this
4270 variable to a real low number, you'll find that Gnus will gather
4271 everything in sight into one thread, which isn't very helpful.
4273 @cindex fuzzy article gathering
4274 If you set this variable to the special value @code{fuzzy}, Gnus will
4275 use a fuzzy string comparison algorithm on the subjects.
4277 @item gnus-summary-make-false-root
4278 @vindex gnus-summary-make-false-root
4279 If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
4280 and create a dummy root at the top. (Wait a minute. Root at the top?
4281 Yup.) Loose subtrees occur when the real root has expired, or you've
4282 read or killed the root in a previous session.
4284 When there is no real root of a thread, Gnus will have to fudge
4285 something. This variable says what fudging method Gnus should use.
4286 There are four possible values:
4288 @cindex adopting articles
4292 Gnus will make the first of the orphaned articles the parent. This
4293 parent will adopt all the other articles. The adopted articles will be
4294 marked as such by pointy brackets (@samp{<>}) instead of the standard
4295 square brackets (@samp{[]}). This is the default method.
4297 Gnus will create a dummy summary line that will pretend to be the
4298 parent. This dummy line does not correspond to any real article, so
4299 selecting it will just select the first real article after the dummy
4302 Gnus won't actually make any article the parent, but simply leave the
4303 subject field of all orphans except the first empty. (Actually, it will
4304 use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
4307 Don't make any article parent at all. Just gather the threads and
4308 display them after one another.
4310 Don't gather loose threads.
4313 @item gnus-thread-hide-subtree
4314 @vindex gnus-thread-hide-subtree
4315 If non-@code{nil}, all threads will be hidden when the summary buffer is
4317 @item gnus-thread-hide-killed
4318 @vindex gnus-thread-hide-killed
4319 if you kill a thread and this variable is non-@code{nil}, the subtree
4321 @item gnus-thread-ignore-subject
4322 @vindex gnus-thread-ignore-subject
4323 Sometimes somebody changes the subject in the middle of a thread. If
4324 this variable is non-@code{nil}, the subject change is ignored. If it
4325 is @code{nil}, which is the default, a change in the subject will result
4327 @item gnus-thread-indent-level
4328 @vindex gnus-thread-indent-level
4329 This is a number that says how much each sub-thread should be indented.
4330 The default is @samp{4}.
4333 @node Thread Commands
4334 @subsection Thread Commands
4335 @cindex thread commands
4340 @kindex T k (Summary)
4341 @kindex M-C-k (Summary)
4342 @findex gnus-summary-kill-thread
4343 Mark all articles in the current sub-thread as read
4344 (@code{gnus-summary-kill-thread}). If the prefix argument is positive,
4345 remove all marks instead. If the prefix argument is negative, tick
4349 @kindex T l (Summary)
4350 @kindex M-C-l (Summary)
4351 @findex gnus-summary-lower-thread
4352 Lower the score of the current thread
4353 (@code{gnus-summary-lower-thread}).
4355 @kindex T i (Summary)
4356 @findex gnus-summary-raise-thread
4357 Increase the score of the current thread
4358 (@code{gnus-summary-raise-thread}).
4360 @kindex T # (Summary)
4361 @findex gnus-uu-mark-thread
4362 Mark the current thread with the process mark
4363 (@code{gnus-uu-mark-thread}).
4365 @kindex T T (Summary)
4366 @findex gnus-summary-toggle-threads
4367 Toggle threading (@code{gnus-summary-toggle-threads}).
4369 @kindex T s (Summary)
4370 @findex gnus-summary-show-thread
4371 Expose the thread hidden under the current article, if any
4372 (@code{gnus-summary-show-thread}).
4374 @kindex T h (Summary)
4375 @findex gnus-summary-hide-thread
4376 Hide the current (sub)thread (@code{gnus-summary-hide-thread}).
4378 @kindex T S (Summary)
4379 @findex gnus-summary-show-all-threads
4380 Expose all hidden threads (@code{gnus-summary-show-all-threads}).
4382 @kindex T H (Summary)
4383 @findex gnus-summary-hide-all-threads
4384 Hide all threads (@code{gnus-summary-hide-all-threads}).
4387 The following commands are thread movement commands. They all
4388 understand the numeric prefix.
4392 @kindex T n (Summary)
4393 @findex gnus-summary-next-thread
4394 Go to the next thread (@code{gnus-summary-next-thread}).
4396 @kindex T p (Summary)
4397 @findex gnus-summary-prev-thread
4398 Go to the previous thread (@code{gnus-summary-prev-thread}).
4400 @kindex T d (Summary)
4401 @findex gnus-summary-down-thread
4402 Descend the thread (@code{gnus-summary-down-thread}).
4404 @kindex T u (Summary)
4405 @findex gnus-summary-up-thread
4406 Ascend the thread (@code{gnus-summary-up-thread}).
4409 @node Asynchronous Fetching
4410 @section Asynchronous Article Fetching
4411 @cindex asynchronous article fetching
4413 If you read your news from an @sc{nntp} server that's far away, the
4414 network latencies may make reading articles a chore. You have to wait
4415 for a while after pressing @kbd{n} to go to the next article before the
4416 article appears. Why can't Gnus just go ahead and fetch the article
4417 while you are reading the previous one? Why not, indeed.
4419 First, some caveats. There are some pitfalls to using asynchronous
4420 article fetching, especially the way Gnus does it.
4422 Let's say you are reading article 1, which is short, and article 2 is
4423 quite long, and you are not interested in reading that. Gnus does not
4424 know this, so it goes ahead and fetches article 2. You decide to read
4425 article 3, but since Gnus is in the process of fetching article 2, the
4426 connection is blocked.
4428 To avoid these situations, Gnus will open two (count 'em two)
4429 connections to the server. Some people may think this isn't a very nice
4430 thing to do, but I don't see any real alternatives. Setting up that
4431 extra connection takes some time, so Gnus startup will be slower.
4433 Gnus will fetch more articles than you will read. This will mean that
4434 the link between your machine and the @sc{nntp} server will become more
4435 loaded than if you didn't use article pre-fetch. The server itself will
4436 also become more loaded - both with the extra article requests, and the
4439 Ok, so now you know that you shouldn't really use this thing... unless
4442 @vindex gnus-asynchronous
4443 Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
4444 happen automatically.
4446 @vindex nntp-async-number
4447 You can control how many articles that are to be pre-fetched by setting
4448 @code{nntp-async-number}. This is five by default, which means that when
4449 you read an article in the group, @code{nntp} will pre-fetch the next
4450 five articles. If this variable is @code{t}, @code{nntp} will pre-fetch
4451 all the articles that it can without bound. If it is @code{nil}, no
4452 pre-fetching will be made.
4454 @vindex gnus-asynchronous-article-function
4455 You may wish to create some sort of scheme for choosing which articles
4456 that @code{nntp} should consider as candidates for pre-fetching. For
4457 instance, you may wish to pre-fetch all articles with high scores, and
4458 not pre-fetch low-scored articles. You can do that by setting the
4459 @code{gnus-asynchronous-article-function}, which will be called with an
4460 alist where the keys are the article numbers. Your function should
4461 return an alist where the articles you are not interested in have been
4462 removed. You could also do sorting on article score and the like.
4464 @node Article Caching
4465 @section Article Caching
4466 @cindex article caching
4469 If you have an @emph{extremely} slow @sc{nntp} connection, you may
4470 consider turning article caching on. Each article will then be stored
4471 locally under your home directory. As you may surmise, this could
4472 potentially use @emph{huge} amounts of disk space, as well as eat up all
4473 your inodes so fast it will make your head swim. In vodka.
4475 Used carefully, though, it could be just an easier way to save articles.
4477 @vindex gnus-use-long-file-name
4478 @vindex gnus-cache-directory
4479 @vindex gnus-use-cache
4480 To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
4481 all articles that are ticked or marked as dormant will then be copied
4482 over to your local cache (@code{gnus-cache-directory}). Whether this
4483 cache is flat or hierarchal is controlled by the
4484 @code{gnus-use-long-file-name} variable, as usual.
4486 When re-select a ticked or dormant article, it will be fetched from the
4487 cache instead of from the server. As articles in your cache will never
4488 expire, this might serve as a method of saving articles while still
4489 keeping them where they belong. Just mark all articles you want to save
4490 as dormant, and don't worry.
4492 When an article is marked as read, is it removed from the cache.
4494 @vindex gnus-cache-remove-articles
4495 @vindex gnus-cache-enter-articles
4496 The entering/removal of articles from the cache is controlled by the
4497 @code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
4498 variables. Both are lists of symbols. The first is @code{(ticked
4499 dormant)} by default, meaning that ticked and dormant articles will be
4500 put in the cache. The latter is @code{(read)} by default, meaning that
4501 articles that are marked as read are removed from the cache. Possibly
4502 symbols in these two lists are @code{ticked}, @code{dormant},
4503 @code{unread} and @code{read}.
4505 @findex gnus-jog-cache
4506 So where does the massive article-fetching and storing come into the
4507 picture? The @code{gnus-jog-cache} command will go through all
4508 subscribed newsgroups, request all unread articles, and store them in
4509 the cache. You should only ever, ever ever ever, use this command if 1)
4510 your connection to the @sc{nntp} server is really, really, really slow
4511 and 2) you have a really, really, really huge disk. Seriously.
4514 @node Exiting the Summary Buffer
4515 @section Exiting the Summary Buffer
4516 @cindex summary exit
4518 Exiting from the summary buffer will normally update all info on the
4519 group and return you to the group buffer.
4524 @kindex Z Z (Summary)
4526 @findex gnus-summary-exit
4527 @vindex gnus-summary-exit-hook
4528 @vindex gnus-summary-prepare-exit-hook
4529 Exit the current group and update all information on the group
4530 (@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
4531 called before doing much of the exiting, and calls
4532 @code{gnus-summary-expire-articles} by default.
4533 @code{gnus-summary-exit-hook} is called after finishing the exiting
4537 @kindex Z E (Summary)
4539 @findex gnus-summary-exit-no-update
4540 Exit the current group without updating any information on the group
4541 (@code{gnus-summary-exit-no-update}).
4544 @kindex Z c (Summary)
4546 @findex gnus-summary-catchup-and-exit
4547 Mark all unticked articles in the group as read and then exit
4548 (@code{gnus-summary-catchup-and-exit}).
4550 @kindex Z C (Summary)
4551 @findex gnus-summary-catchup-all-and-exit
4552 Mark all articles, even the ticked ones, as read and then exit
4553 (@code{gnus-summary-catchup-all-and-exit}).
4555 @kindex Z n (Summary)
4556 @findex gnus-summary-catchup-and-goto-next-group
4557 Mark all articles as read and go to the next group
4558 (@code{gnus-summary-catchup-and-goto-next-group}).
4560 @kindex Z R (Summary)
4561 @findex gnus-summary-reselect-current-group
4562 Exit this group, and then enter it again
4563 (@code{gnus-summary-reselect-current-group}). If given a prefix, select
4564 all articles, both read and unread.
4567 @kindex Z G (Summary)
4568 @kindex M-g (Summary)
4569 @findex gnus-summary-rescan-group
4570 Exit the group, check for new articles in the group, and select the
4571 group (@code{gnus-summary-rescan-group}). If given a prefix, select all
4572 articles, both read and unread.
4574 @kindex Z N (Summary)
4575 @findex gnus-summary-next-group
4576 Exit the group and go to the next group
4577 (@code{gnus-summary-next-group}).
4579 @kindex Z P (Summary)
4580 @findex gnus-summary-prev-group
4581 Exit the group and go to the previous group
4582 (@code{gnus-summary-prev-group}).
4585 @vindex gnus-exit-group-hook
4586 @code{gnus-exit-group-hook} is called when you exit the current
4589 @vindex gnus-use-cross-reference
4590 The data on the current group will be updated (which articles you have
4591 read, which articles you have replied to, etc.) when you exit the
4592 summary buffer. If the @code{gnus-use-cross-reference} variable is
4593 @code{t}, articles that are cross-referenced to this group and are
4594 marked as read, will also be marked as read in the other subscribed
4595 groups they were cross-posted to. If this variable is neither
4596 @code{nil} nor @code{t}, the article will be marked as read in both
4597 subscribed and unsubscribed groups.
4599 Marking cross-posted articles as read ensures that you'll never have to
4600 read the same article more than once. Unless, of course, somebody has
4601 posted it to several groups separately. Posting the same article to
4602 several groups (not cross-posting) is called @dfn{spamming}, and you are
4603 by law required to send nasty-grams to anyone who perpetrates such a
4606 Remember: Cross-posting is kinda ok, but posting the same article
4607 separately to several groups is not.
4609 One thing that may cause Gnus to not do the cross-posting thing
4610 correctly is if you use an @sc{nntp} server that supports @sc{xover}
4611 (which is very nice, because it speeds things up considerably) which
4612 does not include the @code{Xref} header in its @sc{nov} lines. This is
4613 Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
4614 even with @sc{xover} by registering the @code{Xref} lines of all
4615 articles you actually read, but if you kill the articles, or just mark
4616 them as read without reading them, Gnus will not get a chance to snoop
4617 the @code{Xref} lines out of these articles, and will be unable to use
4618 the cross reference mechanism.
4620 @vindex gnus-nov-is-evil
4621 If you want Gnus to get the @code{Xref}s right all the time, you have to
4622 set @code{gnus-nov-is-evil} to @code{t}, which slows things down
4627 @node Process/Prefix
4628 @section Process/Prefix
4629 @cindex process/prefix convention
4631 Many functions, among them functions for moving, decoding and saving
4632 articles, use what is known as the @dfn{Process/Prefix convention}.
4634 This is a method for figuring out what articles that the user wants the
4635 command to be performed on.
4639 If the numeric prefix is N, perform the operation on the next N
4640 articles, starting with the current one. If the numeric prefix is
4641 negative, perform the operation on the previous N articles, starting
4642 with the current one.
4644 If there is no numeric prefix, but some articles are marked with the
4645 process mark, perform the operation on the articles that are marked with
4648 If there is neither a numeric prefix nor any articles marked with the
4649 process mark, just perform the operation on the current article.
4651 Quite simple, really, but it needs to be made clear so that surprises
4654 @node Saving Articles
4655 @section Saving Articles
4656 @cindex saving articles
4658 Gnus can save articles in a number of ways. Below is the documentation
4659 for saving articles in a fairly straight-forward fashion (i.e., little
4660 processing of the article is done before it is saved). For a different
4661 approach (uudecoding, unsharing) you should use @code{gnus-uu}
4662 (@pxref{Decoding Articles}).
4664 @vindex gnus-save-all-headers
4665 If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
4666 unwanted headers before saving the article.
4671 @kindex O o (Summary)
4673 @findex gnus-summary-save-article
4674 Save the current article using the default article saver
4675 (@code{gnus-summary-save-article}).
4677 @kindex O m (Summary)
4678 @findex gnus-summary-save-article-mail
4679 Save the current article in mail format
4680 (@code{gnus-summary-save-article-mail}).
4682 @kindex O r (Summary)
4683 @findex gnus-summary-save-article-mail
4684 Save the current article in rmail format
4685 (@code{gnus-summary-save-article-rmail}).
4687 @kindex O f (Summary)
4688 @findex gnus-summary-save-article-file
4689 Save the current article in plain file format
4690 (@code{gnus-summary-save-article-file}).
4692 @kindex O h (Summary)
4693 @findex gnus-summary-save-article-folder
4694 Save the current article in mh folder format
4695 (@code{gnus-summary-save-article-folder}).
4697 @kindex O p (Summary)
4698 @findex gnus-summary-pipe-output
4699 Save the current article in a pipe. Uhm, like, what I mean is - Pipe
4700 the current article to a process (@code{gnus-summary-pipe-output}).
4703 All these commands use the process/prefix convention
4704 (@pxref{Process/Prefix}).
4706 @vindex gnus-default-article-saver
4707 You can customize the @code{gnus-default-article-saver} variable to make
4708 Gnus do what you want it to. You can use any of the four ready-made
4709 functions below, or you can create your own.
4712 @item gnus-summary-save-in-rmail
4713 @vindex gnus-summary-save-in-rmail
4714 This is the default format, @dfn{babyl}. Uses the function in the
4715 @code{gnus-rmail-save-name} variable to get a file name to save the
4716 article in. The default is @code{gnus-plain-save-name}.
4717 @item gnus-summary-save-in-mail
4718 @vindex gnus-summary-save-in-mail
4719 Save in a Unix mail (mbox) file. Uses the function in the
4720 @code{gnus-mail-save-name} variable to get a file name to save the
4721 article in. The default is @code{gnus-plain-save-name}.
4722 @item gnus-summary-save-in-file
4723 @vindex gnus-summary-save-in-file
4724 Append the article straight to an ordinary file. Uses the function in
4725 the @code{gnus-file-save-name} variable to get a file name to save the
4726 article in. The default is @code{gnus-numeric-save-name}.
4727 @item gnus-summary-save-in-folder
4728 @vindex gnus-summary-save-in-folder
4729 Save the article to an MH folder using @code{rcvstore} from the MH
4731 @item gnus-summary-save-in-vm
4732 @vindex gnus-summary-save-in-vm
4733 Save the article in a VM folder. You have to have the VM mail
4734 reader to use this setting.
4737 All of these functions, except for the last one, will save the article
4738 in the @code{gnus-article-save-directory}, which is initialized from the
4739 @samp{SAVEDIR} environment variable.
4741 As you can see above, the functions use different functions to find a
4742 suitable name of a file to save the article in. Below is a list of
4743 available functions that generate names:
4746 @item gnus-Numeric-save-name
4747 @findex gnus-Numeric-save-name
4748 Generates file names that look like @samp{~/News/Alt.andrea-dworkin/45}.
4749 @item gnus-numeric-save-name
4750 @findex gnus-numeric-save-name
4751 Generates file names that look like @samp{~/News/alt.andrea-dworkin/45}.
4752 @item gnus-Plain-save-name
4753 @findex gnus-Plain-save-name
4754 Generates file names that look like @samp{~/News/Alt.andrea-dworkin}.
4755 @item gnus-plain-save-name
4756 @findex gnus-plain-save-name
4757 Generates file names that look like @samp{~/News/alt.andrea-dworkin}.
4760 @vindex gnus-use-long-file-name
4761 Finally, you have the @code{gnus-use-long-file-name} variable. If it is
4762 @code{nil}, all the preceding functions will replace all periods
4763 (@samp{.}) in the group names with slashes (@samp{/}) - which means that
4764 the functions will generate hierarchies of directories instead of having
4765 all the files in the toplevel directory
4766 (@samp{~/News/alt/andrea-dworkin} instead of
4767 @samp{~/News/alt.andrea-dworkin}.)
4769 This function also affects kill and score file names. If this variable
4770 is a list, and the list contains the element @code{not-score}, long file
4771 names will not be used for score files, if it contains the element
4772 @code{not-save}, long file names will not be used for saving, and if it
4773 contains the element @code{not-kill}, long file names will not be used
4776 If you'd like to save articles in a hierarchy that looks something like
4780 (setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
4781 (setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
4784 Then just save with @kbd{o}. You'd then read this hierarchy with
4785 ephemeral @code{nneething} groups - @kbd{G D} in the group buffer, and
4786 the toplevel directory as the argument (@file{~/News/}). Then just walk
4787 around to the groups/directories with @code{nneething}.
4790 @node Decoding Articles
4791 @section Decoding Articles
4792 @cindex decoding articles
4794 Sometime users post articles (or series of articles) that have been
4795 encoded in some way or other. Gnus can decode them for you.
4798 * Uuencoded Articles:: Uudecode articles.
4799 * Shared Articles:: Unshar articles.
4800 * PostScript Files:: Split PostScript.
4801 * Decoding Variables:: Variables for a happy decoding.
4802 * Viewing Files:: You want to look at the result of the decoding?
4805 All these functions use the process/prefix convention
4806 (@pxref{Process/Prefix}) for finding out what articles to work on, with
4807 the extension that a "single article" means "a single series". Gnus can
4808 find out by itself what articles belong to a series, decode all the
4809 articles and unpack/view/save the resulting file(s).
4811 Gnus guesses what articles are in the series according to the following
4812 simplish rule: The subjects must be (nearly) identical, except for the
4813 last two numbers of the line. (Spaces are largely ignored, however.)
4815 For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus
4816 will find all the articles that match the regexp @samp{^cat.gif
4817 ([0-9]+/[0-9]+).*$}.
4819 Subjects that are nonstandard, like @samp{cat.gif (2/3) Part 6 of a
4820 series}, will not be properly recognized by any of the automatic viewing
4821 commands, and you have to mark the articles manually with @key{#}.
4823 @node Uuencoded Articles
4824 @subsection Uuencoded Articles
4826 @cindex uuencoded articles
4830 @kindex X u (Summary)
4831 @findex gnus-uu-decode-uu
4832 Uudecodes the current series (@code{gnus-uu-decode-uu}).
4834 @kindex X U (Summary)
4835 @findex gnus-uu-decode-uu-and-save
4836 Uudecodes and saves the current series
4837 (@code{gnus-uu-decode-uu-and-save}).
4839 @kindex X v u (Summary)
4840 @findex gnus-uu-decode-uu-view
4841 Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
4843 @kindex X v U (Summary)
4844 @findex gnus-uu-decode-uu-and-save-view
4845 Uudecodes, views and saves the current series
4846 (@code{gnus-uu-decode-uu-and-save-view}).
4849 Remember that these all react to the presence of articles marked with
4850 the process mark. If, for instance, you'd like to uncode and save an
4851 entire newsgroup, you'd typically do @kbd{M P a}
4852 (@code{gnus-uu-mark-all}) and then @kbd{X U}
4853 (@code{gnus-uu-decode-uu-and-save}).
4855 All this is very much different from how @code{gnus-uu} worked with
4856 @sc{gnus 4.1}, where you had explicit keystrokes for everything under
4857 the sun. This version of @code{gnus-uu} generally assumes that you mark
4858 articles in some way (@pxref{Setting Process Marks}) and then press
4861 Note: When trying to decode articles that have names matching
4862 @code{gnus-uu-notify-files}, which is hard-coded to
4863 @samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
4864 automatically post an article on @samp{comp.unix.wizards} saying that
4865 you have just viewed the file in question. This feature can't be turned
4868 @node Shared Articles
4869 @subsection Shared Articles
4871 @cindex shared articles
4875 @kindex X s (Summary)
4876 @findex gnus-uu-decode-unshar
4877 Unshars the current series (@code{gnus-uu-decode-unshar}).
4879 @kindex X S (Summary)
4880 @findex gnus-uu-decode-unshar-and-save
4881 Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
4883 @kindex X v s (Summary)
4884 @findex gnus-uu-decode-unshar-view
4885 Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
4887 @kindex X v S (Summary)
4888 @findex gnus-uu-decode-unshar-and-save-view
4889 Unshars, views and saves the current series
4890 (@code{gnus-uu-decode-unshar-and-save-view}).
4893 @node PostScript Files
4894 @subsection PostScript Files
4899 @kindex X p (Summary)
4900 @findex gnus-uu-decode-postscript
4901 Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
4903 @kindex X P (Summary)
4904 @findex gnus-uu-decode-postscript-and-save
4905 Unpack and save the current PostScript series
4906 (@code{gnus-uu-decode-postscript-and-save}).
4908 @kindex X v p (Summary)
4909 @findex gnus-uu-decode-postscript-view
4910 View the current PostScript series
4911 (@code{gnus-uu-decode-postscript-view}).
4913 @kindex X v P (Summary)
4914 @findex gnus-uu-decode-postscript-and-save-view
4915 View and save the current PostScript series
4916 (@code{gnus-uu-decode-postscript-and-save-view}).
4919 @node Decoding Variables
4920 @subsection Decoding Variables
4922 Adjective, not verb.
4925 * Rule Variables:: Variables that say how a file is to be viewed.
4926 * Other Decode Variables:: Other decode variables.
4927 * Uuencoding & Posting:: Variables for customizing uuencoding.
4930 @node Rule Variables
4931 @subsubsection Rule Variables
4932 @cindex rule variables
4934 Gnus uses @dfn{rule variables} to decide how to view a file. All these
4935 variables are on the form
4938 (list '(regexp1 command2)
4944 @item gnus-uu-user-view-rules
4945 @vindex gnus-uu-user-view-rules
4946 This variable is consulted first when viewing files. If you wish to use,
4947 for instance, @code{sox} to convert an @samp{.au} sound file, you could
4950 (setq gnus-uu-user-view-rules
4951 (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
4953 @item gnus-uu-user-view-rules-end
4954 @vindex gnus-uu-user-view-rules-end
4955 This variable is consulted if Gnus couldn't make any matches from the
4956 user and default view rules.
4957 @item gnus-uu-user-archive-rules
4958 @vindex gnus-uu-user-archive-rules
4959 This variable can be used to say what commands should be used to unpack
4963 @node Other Decode Variables
4964 @subsubsection Other Decode Variables
4967 @item gnus-uu-ignore-files-by-name
4968 @vindex gnus-uu-ignore-files-by-name
4969 Files with name matching this regular expression won't be viewed.
4971 @item gnus-uu-ignore-files-by-type
4972 @vindex gnus-uu-ignore-files-by-type
4973 Files with a @sc{mime} type matching this variable won't be viewed.
4974 Note that Gnus tries to guess what type the file is based on the name.
4975 @code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
4978 @item gnus-uu-tmp-dir
4979 @vindex gnus-uu-tmp-dir
4980 Where @code{gnus-uu} does its work.
4982 @item gnus-uu-do-not-unpack-archives
4983 @vindex gnus-uu-do-not-unpack-archives
4984 Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
4985 looking for files to display.
4987 @item gnus-uu-view-and-save
4988 @vindex gnus-uu-view-and-save
4989 Non-@code{nil} means that the user will always be asked to save a file
4992 @item gnus-uu-ignore-default-view-rules
4993 @vindex gnus-uu-ignore-default-view-rules
4994 Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
4997 @item gnus-uu-ignore-default-archive-rules
4998 @vindex gnus-uu-ignore-default-archive-rules
4999 Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
5002 @item gnus-uu-kill-carriage-return
5003 @vindex gnus-uu-kill-carriage-return
5004 Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
5007 @item gnus-uu-unmark-articles-not-decoded
5008 @vindex gnus-uu-unmark-articles-not-decoded
5009 Non-@code{nil} means that @code{gnus-uu} will mark articles that were
5010 unsuccessfully decoded as unread.
5012 @item gnus-uu-correct-stripped-uucode
5013 @vindex gnus-uu-correct-stripped-uucode
5014 Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
5015 uuencoded files that have had trailing spaces deleted.
5017 @item gnus-uu-view-with-metamail
5018 @vindex gnus-uu-view-with-metamail
5019 Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
5020 commands defined by the rule variables and just fudge a @sc{mime}
5021 content type based on the file name. The result will be fed to
5022 @code{metamail} for viewing.
5024 @item gnus-uu-save-in-digest
5025 @vindex gnus-uu-save-in-digest
5026 Non-@code{nil} means that @code{gnus-uu}, when asked to save without
5027 decoding, will save in digests. If this variable is @code{nil},
5028 @code{gnus-uu} will just save everything in a file without any
5029 embellishments. The digesting almost conforms to RFC1153 - no easy way
5030 to specify any meaningful volume and issue numbers were found, so I
5031 simply dropped them.
5035 @node Uuencoding & Posting
5036 @subsubsection Uuencoding & Posting
5040 @item gnus-uu-post-include-before-composing
5041 @vindex gnus-uu-post-include-before-composing
5042 Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
5043 before you compose the article. If this variable is @code{t}, you can
5044 either include an encoded file with @key{C-c C-i} or have one included
5045 for you when you post the article.
5047 @item gnus-uu-post-length
5048 @vindex gnus-uu-post-length
5049 Maximum length of an article. The encoded file will be split into how
5050 many articles it takes to post the entire file.
5052 @item gnus-uu-post-threaded
5053 @vindex gnus-uu-post-threaded
5054 Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
5055 thread. This may not be smart, as no other decoder I have seen are able
5056 to follow threads when collecting uuencoded articles. (Well, I have
5057 seen one package that does that - @code{gnus-uu}, but somehow, I don't
5058 think that counts...) Default is @code{nil}.
5060 @item gnus-uu-post-separate-description
5061 @vindex gnus-uu-post-separate-description
5062 Non-@code{nil} means that the description will be posted in a separate
5063 article. The first article will typically be numbered (0/x). If this
5064 variable is @code{nil}, the description the user enters will be included
5065 at the beginning of the first article, which will be numbered (1/x).
5066 Default is @code{t}.
5071 @subsection Viewing Files
5072 @cindex viewing files
5073 @cindex pseudo-articles
5075 After decoding, if the file is some sort of archive, Gnus will attempt
5076 to unpack the archive and see if any of the files in the archive can be
5077 viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
5078 containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
5079 uncompress and detar the main file, and then view the two pictures.
5080 This unpacking process is recursive, so if the archive contains archives
5081 of archives, it'll all be unpacked.
5083 Finally, Gnus will normally insert a @dfn{pseudo-article} for each
5084 extracted file into the summary buffer. If you go to these "articles",
5085 you will be prompted for a command to run (usually Gnus will make a
5086 suggestion), and then the command will be run.
5088 @vindex gnus-view-pseudo-asynchronously
5089 If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
5090 until the viewing is done before proceeding.
5092 @vindex gnus-view-pseudos
5093 If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
5094 the pseudo-articles into the summary buffer, but view them
5095 immediately. If this variable is @code{not-confirm}, the user won't even
5096 be asked for a confirmation before viewing is done.
5098 @vindex gnus-view-pseudos-separately
5099 If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
5100 pseudo-article will be created for each file to be viewed. If
5101 @code{nil}, all files that use the same viewing command will be given as
5102 a list of parameters to that command.
5104 So; there you are, reading your @emph{pseudo-articles} in your
5105 @emph{virtual newsgroup} from the @emph{virtual server}; and you think:
5106 Why isn't anything real anymore? How did we get here?
5108 @node Various Article Stuff
5109 @section Various Article Stuff
5113 @kindex W l (Summary)
5114 @findex gnus-summary-stop-page-breaking
5115 Remove page breaks from the current article
5116 (@code{gnus-summary-stop-page-breaking}).
5118 @kindex A s (Summary)
5119 @findex gnus-summary-isearch-article
5120 Perform an isearch in the article buffer
5121 (@code{gnus-summary-isearch-article}).
5123 @kindex W r (Summary)
5124 @findex gnus-summary-caesar-message
5125 Do a Caesar rotate (rot13) on the article buffer
5126 (@code{gnus-summary-caesar-message}).
5128 @kindex A g (Summary)
5129 @findex gnus-summary-show-article
5130 (Re)fetch the current article (@code{gnus-summary-show-article}). If
5131 given a prefix, don't actually refetch any articles, just jump to the
5132 current article and configure the windows to display the current
5135 @kindex W t (Summary)
5136 @findex gnus-summary-toggle-header
5137 Toggle whether to display all headers in the article buffer
5138 (@code{gnus-summary-toggle-header}).
5140 @kindex W m (Summary)
5141 @findex gnus-summary-toggle-mime
5142 Toggle whether to run the article through @sc{mime} before displaying
5143 (@code{gnus-summary-toggle-mime}).
5146 There's a battery of commands for washing the article buffer:
5150 @kindex W W h (Summary)
5151 @findex gnus-article-hide-headers
5152 Hide headers (@code{gnus-article-hide-headers}).
5154 @kindex W W s (Summary)
5155 @findex gnus-article-hide-signature
5156 Hide signature (@code{gnus-article-hide-signature}).
5158 @kindex W W c (Summary)
5159 @findex gnus-article-hide-citation
5160 Hide citation (@code{gnus-article-hide-citation}).
5162 @kindex W o (Summary)
5163 @findex gnus-article-treat-overstrike
5164 Treat overstrike (@code{gnus-article-treat-overstrike}).
5166 @kindex W w (Summary)
5167 @findex gnus-article-word-wrap
5168 Do word wrap (@code{gnus-article-word-wrap}).
5170 @kindex W c (Summary)
5171 @findex gnus-article-remove-cr
5172 Remove CR (@code{gnus-article-remove-cr}).
5174 @kindex W q (Summary)
5175 @findex gnus-article-de-quoted-unreadable
5176 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
5178 @kindex W f (Summary)
5180 @findex gnus-article-display-x-face
5181 @findex gnus-article-x-face-command
5182 @vindex gnus-article-x-face-command
5183 @vindex gnus-article-x-face-too-ugly
5184 Look for and display any X-Face headers
5185 (@code{gnus-article-display-x-face}). The command executed by this
5186 function is given by the @code{gnus-article-x-face-command} variable. If
5187 this variable is a string, this string will be executed in a sub-shell.
5188 If it is a function, this function will be called with the face as the
5189 argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
5190 matches the @code{From} header, the face will not be shown.
5194 @findex gnus-article-highlight
5195 Highlight the current article (@code{gnus-article-highlight}).
5199 @findex gnus-article-highlight-headers
5200 Highlight the headers (@code{gnus-article-highlight-headers}).
5204 @findex gnus-article-highlight-citation
5205 Highlight cited text (@code{gnus-article-highlight-citation}).
5209 @findex gnus-article-highlight-signature
5210 Highlight the signature (@code{gnus-article-highlight-signature}).
5214 @findex gnus-article-date-ut
5215 Display the date in UT (aka. GMT, aka ZULU)
5216 (@code{gnus-article-date-ut}).
5220 @findex gnus-article-date-local
5221 Display the date in the local timezone (@code{gnus-article-date-local}).
5225 @findex gnus-article-date-lapsed
5226 Say how much time has (e)lapsed between the article was posted and now
5227 (@code{gnus-article-date-lapsed}).
5232 @node Summary Sorting
5233 @section Summary Sorting
5234 @cindex summary sorting
5236 You can have the summary buffer sorted in various ways, even though I
5237 can't really see why you'd want that.
5241 @kindex C-c C-s C-n (Summary)
5242 @findex gnus-summary-sort-by-number
5243 Sort by article number (@code{gnus-summary-sort-by-number}).
5245 @kindex C-c C-s C-a (Summary)
5246 @findex gnus-summary-sort-by-author
5247 Sort by author (@code{gnus-summary-sort-by-author}).
5249 @kindex C-c C-s C-s (Summary)
5250 @findex gnus-summary-sort-by-subject
5251 Sort by subject (@code{gnus-summary-sort-by-subject}).
5253 @kindex C-c C-s C-d (Summary)
5254 @findex gnus-summary-sort-by-date
5255 Sort by date (@code{gnus-summary-sort-by-date}).
5257 @kindex C-c C-s C-i (Summary)
5258 @findex gnus-summary-sort-by-score
5259 Sort by score (@code{gnus-summary-sort-by-score}).
5262 These functions will work both when you use threading and when you don't
5263 use threading. In the latter case, all summary lines will be sorted,
5264 line by line. In the former case, sorting will be done on a
5265 root-by-root basis, which might not be what you were looking for. To
5266 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
5269 @node Finding the Parent
5270 @section Finding the Parent
5271 @cindex parent articles
5272 @cindex referring articles
5274 @findex gnus-summary-refer-parent-article
5276 If you'd like to read the parent of the current article, and it is not
5277 displayed in the article buffer, you might still be able to. That is,
5278 if the current group is fetched by @sc{nntp}, the parent hasn't expired
5279 and the @code{References} in the current article are not mangled, you
5280 can just press @kbd{^} or @kbd{A r}
5281 (@code{gnus-summary-refer-parent-article}). If everything goes well,
5282 you'll get the parent. If the parent is already displayed in the
5283 summary buffer, point will just move to this article.
5285 @findex gnus-summary-refer-article
5286 @kindex M-^ (Summary)
5287 You can also ask the @sc{nntp} server for an arbitrary article, no
5288 matter what group it belongs to. @kbd{M-^}
5289 (@code{gnus-summary-refer-article}) will ask you for a
5290 @code{Message-Id}, which is one of those long thingies that look
5291 something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
5292 it all exactly right. No fuzzy searches, I'm afraid.
5294 @vindex gnus-refer-article-method
5295 If the group you are reading is located on a backend that does not
5296 support fetching by @code{Message-Id} very well (like @code{nnspool}),
5297 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
5298 would, perhaps, be best if the @sc{nntp} server you consult is the same
5299 as the one that keeps the spool you are reading from updated, but that's
5300 not really necessary.
5303 @section Score Files
5306 Other people use @dfn{kill files}, but we here at Gnus Towers like
5307 scoring better than killing, so we'd rather switch than fight. They do
5308 something completely different as well, so sit up straight and pay
5311 @vindex gnus-summary-mark-below
5312 All articles have a default score (@code{gnus-summary-default-score}).
5313 This score may be raised or lowered either interactively or by score
5314 files. Articles that have a score lower than
5315 @code{gnus-summary-mark-below} are marked as read.
5317 Gnus will read any @dfn{score files} that apply to the current group
5318 before generating the summary buffer.
5320 There are several commands in the summary buffer that insert score
5321 entries based on the current article. You can, for instance, ask Gnus to
5322 lower or increase the score of all articles with a certain subject.
5324 There are two sorts of scoring entries: Permanent and temporary.
5325 Temporary score entries are self-expiring entries. Any entries that are
5326 temporary and have not been used for, say, a week, will be removed
5327 silently to help keep the sizes of the score files down.
5330 * Summary Score Commands:: Adding score commands to the score file.
5331 * Score Variables:: Customize your scoring. (My, what terminology).
5332 * Score File Format:: What a score file may contain.
5333 * Score File Editing:: You can edit score files by hand as well.
5334 * Adaptive Scoring:: Big Sister Gnus *knows* what you read.
5335 * Scoring Tips:: How to score effectively.
5336 * Reverse Scoring:: That problem child of old is not problem.
5337 * Global Score Files:: Earth-spanning, ear-splitting score files.
5338 * Kill Files:: They are still here, but they can be ignored.
5341 @node Summary Score Commands
5342 @subsection Summary Score Commands
5343 @cindex score commands
5345 The score commands that alter score entries do not actually modify real
5346 score files. That would be too inefficient. Gnus maintains a cache of
5347 previously loaded score files, one of which is considered the
5348 @dfn{current score file alist}. The score commands simply insert
5349 entries into this list, and upon group exit, this list is saved.
5351 The current score file is by default the group's local score file, even
5352 if no such score file actually exists. To insert score commands into
5353 some other score file (eg. @file{all.SCORE}), you must first make this
5354 score file the current one.
5356 General score commands that don't actually change the score file:
5360 @kindex V s (Summary)
5361 @findex gnus-summary-set-score
5362 Set the score of the current article (@code{gnus-summary-set-score}).
5364 @kindex V S (Summary)
5365 @findex gnus-summary-current-score
5366 Display the score of the current article
5367 (@code{gnus-summary-current-score}).
5369 @kindex V t (Summary)
5370 @findex gnus-score-find-trace
5371 Display all score rules that have been used on the current article
5372 (@code{gnus-score-find-trace}).
5374 @kindex V a (Summary)
5375 @findex gnus-summary-score-entry
5376 Add a new score entry, and allow specifying all elements
5377 (@code{gnus-summary-score-entry}).
5379 @kindex V c (Summary)
5380 @findex gnus-score-change-score-file
5381 Make a different score file the current
5382 (@code{gnus-score-change-score-file}).
5384 @kindex V e (Summary)
5385 @findex gnus-score-edit-alist
5386 Edit the current score file (@code{gnus-score-edit-alist}). You will be
5387 popped into a @code{gnus-score-mode} buffer (@pxref{Score File
5390 @kindex V f (Summary)
5391 @findex gnus-score-edit-file
5392 Edit a score file and make this score file the current one
5393 (@code{gnus-score-edit-file}).
5395 @kindex I C-i (Summary)
5396 @findex gnus-summary-raise-score
5397 Increase the score of the current article
5398 (@code{gnus-summary-raise-score}).
5400 @kindex L C-l (Summary)
5401 @findex gnus-summary-lower-score
5402 Lower the score of the current article
5403 (@code{gnus-summary-lower-score}).
5406 The rest of these commands modify the local score file.
5410 @kindex V m (Summary)
5411 @findex gnus-score-set-mark-below
5412 Prompt for a score, and mark all articles with a score below this as
5413 read (@code{gnus-score-set-mark-below}).
5415 @kindex V E (Summary)
5416 @findex gnus-score-set-expunge-below
5417 Expunge all articles with a score below the default score (or the
5418 numeric prefix) (@code{gnus-score-set-expunge-below}).
5421 The keystrokes for actually making score entries follow a very regular
5422 pattern, so there's no need to list all the commands. (Hundreds of
5427 The first key is either @kbd{I} (upper case i) for increasing the score
5428 or @kbd{L} for lowering the score.
5430 The second key says what header you want to score on. The following
5434 Score on the author name.
5436 Score on the subject line.
5438 Score on the Xref line - i.e., the cross-posting line.
5440 Score on thread - the References line.
5444 Score on the number of lines.
5446 Score on the Message-ID.
5456 The third key is the match type. Which match types are legal depends on
5457 what headers you are scoring on.
5490 Greater than number.
5495 The fourth and final key says whether this is a temporary (i.e., expiring)
5496 score entry, or a permanent (i.e., non-expiring) score entry, or whether
5497 it is to be done immediately, without adding to the score file.
5500 Temporary score entry.
5502 Permanent score entry.
5504 Immediately scoring.
5509 So, let's say you want to increase the score on the current author with
5510 exact matching permanently: @kbd{I a e p}. If you want to lower the
5511 score based on the subject line, using substring matching, and make a
5512 temporary score entry: @kbd{L s s t}. Pretty easy.
5514 To make things a bit more complicated, there are shortcuts. If you use
5515 a capital letter on either the second or third keys, Gnus will use
5516 defaults for the remaining one or two keystrokes. The defaults are
5517 "substring" and "temporary". So @kbd{I A} is the same as @kbd{I a s t},
5518 and @kbd{I a R} is the same as @kbd{I a r t}.
5520 @vindex gnus-score-mimic-keymap
5521 The @code{gnus-score-mimic-keymap} says whether these commands will
5522 pretend they are keymaps or not.
5524 @node Score Variables
5525 @subsection Score Variables
5526 @cindex score variables
5529 @item gnus-use-scoring
5530 @vindex gnus-use-scoring
5531 If @code{nil}, Gnus will not check for score files, and will not, in
5532 general, do any score-related work.
5533 @item gnus-kill-killed
5534 @vindex gnus-kill-killed
5535 If this variable is @code{nil}, Gnus will never apply score files to
5536 articles that have already been through the kill process. While this
5537 may save you lots of time, it also means that if you apply a kill file
5538 to a group, and then change the kill file and want to run it over you
5539 group again to kill more articles, it won't work. You have to set this
5540 variable to @code{t} to do that.
5541 @item gnus-kill-files-directory
5542 @vindex gnus-kill-files-directory
5543 All kill and score files will be stored in this directory, which is
5544 initialized from the @samp{SAVEDIR} environment variable by default.
5545 @item gnus-score-file-suffix
5546 @vindex gnus-score-file-suffix
5547 Suffix to add to the group name to arrive at the score file name
5548 (@samp{SCORE} by default.)
5549 @item gnus-score-interactive-default-score
5550 @vindex gnus-score-interactive-default-score
5551 Score used by all the interactive raise/lower commands to raise/lower
5552 score with. Default is 1000, which may seem excessive, but this is to
5553 ensure that the adaptive scoring scheme gets enough room to play with.
5554 We don't want the small changes from the adaptive scoring to overwrite
5555 manually entered data.
5556 @item gnus-summary-default-score
5557 @vindex gnus-summary-default-score
5558 Default score of an article, which is 0 by default.
5559 @item gnus-score-over-mark
5560 @vindex gnus-score-over-mark
5561 Mark (in the third column) used for articles with a score over the
5562 default. Default is @samp{+}.
5563 @item gnus-score-below-mark
5564 @vindex gnus-score-below-mark
5565 Mark (in the third column) used for articles with a score below the
5566 default. Default is @samp{-}.
5567 @item gnus-score-find-score-files-function
5568 @vindex gnus-score-find-score-files-function
5569 Function used to find score files for the current group. This function
5570 is called with the name of the group as the argument.
5572 Predefined functions available are:
5575 @item gnus-score-find-single
5576 @findex gnus-score-find-single
5577 Only apply the group's own score file.
5579 @item gnus-score-find-bnews
5580 @findex gnus-score-find-bnews
5581 Apply all score files that match, using bnews syntax. For instance, if
5582 the current group is @samp{gnu.emacs.gnus}, @samp{all.emacs.all.SCORE},
5583 @samp{not.alt.all.SCORE} and @samp{gnu.all.SCORE} would all apply. In
5584 short, the instances of @samp{all} in the score file names are
5585 translated into @samp{.*}, and then a regexp match is done.
5587 If @code{gnus-use-long-file-name} is non-@code{nil}, this won't work
5588 very will. It will find stuff like @file{gnu/all/SCORE}, but will not
5589 find files like @file{not/gnu/all/SCORE}.
5591 @item gnus-score-find-hierarchical
5592 @findex gnus-score-find-hierarchical
5593 Apply all score files from all the parent groups.
5595 This variable can also be a list of functions. In that case, all these
5596 functions will be called, and all the returned lists of score files will
5597 be applied. These functions can also return lists of score alists
5598 directly. In that case, the functions that return these non-file score
5599 alists should probably be placed before the "real" score file functions,
5600 to ensure that the last score file returned is the local score file.
5602 @item gnus-score-expiry-days
5603 @vindex gnus-score-expiry-days
5604 This variable says how many days should pass before an unused score file
5605 entry is expired. The default is 7.
5608 @node Score File Format
5609 @subsection Score File Format
5610 @cindex score file format
5612 A score file is an @code{emacs-lisp} file that normally contains just a
5613 single form. Casual users are not expected to edit these files;
5614 everything can be changed from the summary buffer.
5616 Anyway, if you'd like to dig into it yourself, here's an example:
5620 ("Lars Ingebrigtsen" -10000)
5622 ("larsi\\|lmi" -50000 nil R))
5624 ("Ding is Badd" nil 728373))
5626 ("alt.politics" -1000 728372 s))
5631 (mark-and-expunge -10)
5635 (files "/hom/larsi/News/gnu.SCORE")
5636 (local (gnus-newsgroup-auto-expire t)
5637 (gnus-summary-make-false-root 'empty))
5641 This example demonstrates absolutely everything about a score file.
5643 Even though this looks much like lisp code, nothing here is actually
5644 @code{eval}ed. The lisp reader is used to read this form, though, so it
5645 has to be legal syntactically, if not semantically.
5647 Six keys are supported by this alist:
5651 If the key is a string, it is the name of the header to perform the
5652 match on. Scoring can only be performed on these eight headers:
5653 @samp{From}, @samp{Subject}, @samp{References}, @samp{Message-ID},
5654 @samp{Xref}, @samp{Lines}, @samp{Chars} and @samp{Date}. In addition to
5655 these headers, there are three strings to tell Gnus to fetch the entire
5656 article and do the match on larger parts of the article: @samp{Body}
5657 will perform the match on the body of the article, @samp{Head} will
5658 perform the match on the head of the article, and @samp{All} will
5659 perform the match on the entire article. Note that using any of these
5660 last three keys will slow down group entry @emph{considerably}.
5662 Following this key is a random number of score entries, where each score
5663 entry has one to four elements.
5666 The first element is the @dfn{match element}. On most headers this will
5667 be a string, but on the Lines and Chars headers, this must be an
5670 If the second element is present, it should be a number - the @dfn{score
5671 element}. This number should be an integer in the neginf to posinf
5672 interval. This number is added to the score of the article if the match
5673 is successful. If this element is not present, the
5674 @code{gnus-score-interactive-default-score} number will be used instead.
5676 If the third element is present, it should be a number - the @dfn{date
5677 element}. This date says when the last time this score entry matched,
5678 which provides a mechanism for expiring the score entries. It this
5679 element is not present, the score entry is permanent. The date is
5680 represented by the number of days since December 31, 1 ce.
5682 If the fourth element is present, it should be a symbol - the @dfn{type
5683 element}. This element specifies what function should be used to see
5684 whether this score entry matches the article. What match types that can
5685 be used depends on what header you wish to perform the match on.
5687 @item From, Subject, References, Xref, Message-ID
5688 For most header types, there are the @code{r} and @code{R} (regexp) as
5689 well as @code{s} and @code{S} (substring) types and @code{e} and
5690 @code{E} (exact match) types. If this element is not present, Gnus will
5691 assume that substring matching should be used. @code{R} and @code{S}
5692 differ from the other two in that the matches will be done in a
5693 case-sensitive manner. All these one-letter types are really just
5694 abbreviations for the @code{regexp}, @code{string} and @code{exact}
5695 types, which you can use instead, if you feel like.
5697 These two headers use different match types: @code{<}, @code{>},
5698 @code{=}, @code{>=} and @code{<=}.
5700 For the Date header we have three match types: @code{before}, @code{at}
5701 and @code{after}. I can't really imagine this ever being useful, but,
5702 like, it would feel kinda silly not to provide this function. Just in
5703 case. You never know. Better safe than sorry. Once burnt, twice shy.
5704 Don't judge a book by its cover. Never not have sex on a first date.
5705 @item Head, Body, All
5706 These three match keys use the same match types as the @code{From} (etc)
5709 This match key will add a score entry on all articles that followup to
5710 some author. Uses the same match types as the @code{From} header uses.
5715 The value of this entry should be a number. Any articles with a score
5716 lower than this number will be marked as read.
5718 The value of this entry should be a number. Any articles with a score
5719 lower than this number will be removed from the summary buffer.
5720 @item mark-and-expunge
5721 The value of this entry should be a number. Any articles with a score
5722 lower than this number will be marked as read and removed from the
5725 The value of this entry should be any number of file names. These files
5726 are assumed to be score files as well, and will be loaded the same way
5729 The clue of this entry should be any number of files. This files will
5730 not be loaded, even though they would normally be so, for some reason or
5733 The value of this entry will be @code{eval}el. This element will be
5734 ignored when handling global score files.
5736 Read-only score files will not be updated or saved. Global score files
5737 should feature this atom (@pxref{Global Score Files}).
5739 The value of this entry should be a number. Articles that do not have
5740 parents will get this number added to their scores.
5742 This entry controls the adaptive scoring. If it is @code{t}, the
5743 default adaptive scoring rules will be used. If it is @code{ignore}, no
5744 adaptive scoring will be performed on this group. If it is a list, this
5745 list will be used as the adaptive scoring rules. If it isn't present,
5746 or is something other than @code{t} or @code{ignore}, the default
5747 adaptive scoring rules will be used. If you want to use adaptive
5748 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
5749 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
5750 not want adaptive scoring. If you only want adaptive scoring in a few
5751 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
5752 insert @code{(adapt t)} in the score files of the groups where you want
5755 @cindex local variables
5756 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
5757 Each @var{var} will be made buffer-local to the current summary buffer,
5758 and set to the value specified. This is a convenient, if somewhat
5759 strange, way of setting variables in some groups if you don't like hooks
5763 @node Score File Editing
5764 @subsection Score File Editing
5766 You normally enter all scoring commands from the summary buffer, but you
5767 might feel the urge to edit them by hand as well, so we've supplied you
5768 with a mode for that.
5770 It's simply a slightly customized @code{emacs-lisp} mode, with these
5771 additional commands:
5775 @kindex C-c C-c (Score)
5776 @findex gnus-score-edit-done
5777 Save the changes you have made and return to the summary buffer
5778 (@code{gnus-score-edit-done}).
5780 @kindex C-c C-d (Score)
5781 @findex gnus-score-edit-insert-date
5782 Insert the current date in numerical format
5783 (@code{gnus-score-edit-insert-date}). This is really the day number, if
5787 @node Adaptive Scoring
5788 @subsection Adaptive Scoring
5789 @cindex adaptive scoring
5791 If all this scoring is getting you down, Gnus has a way of making it all
5792 happen automatically - as if by magic. Or rather, as if by artificial
5793 stupidity, to be precise.
5795 @vindex gnus-use-adaptive-scoring
5796 When you read an article, or mark an article as read, or kill an
5797 article, you leave marks behind. On exit from the group, Gnus can sniff
5798 these marks and add score elements depending on what marks it finds.
5799 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
5802 @vindex gnus-default-adaptive-score-alist
5803 To give you complete control over the scoring process, you can customize
5804 the @code{gnus-default-adaptive-score-alist} variable. By default, it
5805 looks something like this:
5808 (defvar gnus-default-adaptive-score-alist
5809 '((gnus-unread-mark)
5810 (gnus-ticked-mark (from 4))
5811 (gnus-dormant-mark (from 5))
5812 (gnus-del-mark (from -4) (subject -1))
5813 (gnus-read-mark (from 4) (subject 2))
5814 (gnus-expirable-mark (from -1) (subject -1))
5815 (gnus-killed-mark (from -1) (subject -3))
5816 (gnus-kill-file-mark)
5817 (gnus-catchup-mark (from -1) (subject -1))))
5820 As you see, each element in this alist has a mark as a key (either a
5821 variable name or a "real" mark - a character). Following this key is a
5822 random number of header/score pairs.
5824 To take @code{gnus-del-mark} as an example - this alist says that all
5825 articles that have that mark (i.e., are marked with @samp{D}) will have a
5826 score entry added to lower based on the @code{From} header by -4, and
5827 lowered by @code{Subject} by -1. Change this to fit your prejudices.
5829 If you use this scheme, you should set @code{mark-below} to something
5830 small - like -300, perhaps, to avoid having small random changes result
5831 in articles getting marked as read.
5833 After using adaptive scoring for a week or so, Gnus should start to
5834 become properly trained and enhance the authors you like best, and kill
5835 the authors you like least, without you having to say so explicitly.
5837 You can control what groups the adaptive scoring is to be performed on
5838 by using the score files (@pxref{Score File Format}). This will also
5839 let you use different rules in different groups.
5841 @vindex gnus-adaptive-file-suffix
5842 The adaptive score entries will be put into a file where the name is the
5843 group name with @code{gnus-adaptive-file-suffix} appended.
5845 @vindex gnus-score-exact-adapt-limit
5846 When doing adaptive scoring, substring or fuzzy matching would probably
5847 give you the best results in most cases. However, if the header one
5848 matches is short, the possibility for false positives is great, so if
5849 the length of the match is less than
5850 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
5851 this variable is @code{nil}, exact matching will always be used to avoid
5855 @subsection Scoring Tips
5856 @cindex scoring tips
5860 If you want to lower the score of crossposts, the line to match on is
5861 the @code{Xref} header.
5863 ("xref" (" talk.politics.misc:" -1000))
5865 @item Multiple crossposts
5866 If you want to lower the score of articles that have been crossposted to
5867 more than, say, 3 groups:
5869 ("xref" (" +[^ ]+:[0-9]+ +[^ ]+:[0-9]+ +[^ ]+:[0-9]+" -1000 nil r))
5871 @item Matching on the body
5872 This is generally not a very good idea - it takes a very long time.
5873 Gnus actually has to fetch each individual article from the server. But
5874 you might want to anyway, I guess. Even though there are three match
5875 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
5876 and stick with it in each score file. If you use any two, each article
5877 will be fetched @emph{twice}. If you want to match a bit on the
5878 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
5880 @item Marking as read
5881 You will probably want to mark articles that has a score below a certain
5882 number as read. This is most easily achieved by putting the following
5883 in your @file{all.SCORE} file:
5887 You may also consider doing something similar with @code{expunge}.
5889 @item Negated charater classes
5890 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
5891 That will match newlines, which might lead to, well, The Unknown. Say
5892 @code{[^abcd\n]*} instead.
5895 @node Reverse Scoring
5896 @subsection Reverse Scoring
5897 @cindex reverse scoring
5899 If you want to keep just articles that have @samp{Sex with Emacs} in the
5900 subject header, and expunge all other articles, you could put something
5901 like this in your score file:
5905 ("Sex with Emacs" 2))
5910 So, you raise all articles that match @samp{Sex with Emacs} and mark the
5911 rest as read, and expunge them to boot.
5913 @node Global Score Files
5914 @subsection Global Score Files
5915 @cindex global score files
5917 Sure, other newsreaders have "global kill files". These are usually
5918 nothing more than a single kill file that applies to all groups, stored
5919 in the user's home directory. Bah! Puny, weak newsreaders!
5921 What I'm talking about here are Global Score Files. Score files from
5922 all over the world, from users everywhere, uniting all nations in one
5923 big, happy score file union! Ange-score! New and untested!
5925 @vindex gnus-global-score-files
5926 All you have to do to use other people's score files is to set the
5927 @code{gnus-global-score-files} variable. One entry for each score file,
5928 or each score file directory. Gnus will decide by itself what score
5929 files are applicable to which group.
5931 Say you want to use all score files in the
5932 @file{/ftp@@ftp.some-where:/pub/score} directory and the single score
5933 file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
5936 (setq gnus-global-score-files
5937 '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
5938 "/ftp@@ftp.some-where:/pub/score/"))
5941 @findex gnus-score-search-global-directories
5942 Simple, eh? Directory names must end with a @samp{/}. These
5943 directories are typically scanned only once during each Gnus session.
5944 If you feel the need to manually re-scan the remote directories, you can
5945 use the @code{gnus-score-search-global-directories} command.
5947 Note that, at present, using this option will slow down group entry
5948 somewhat. (That is - a lot.)
5950 If you want to start maintaining score files for other people to use,
5951 just put your score file up for anonymous ftp and announce it to the
5952 world. Become a retro-moderator! Participate in the retro-moderator
5953 wars sure to ensue, where retro-moderators battle it out for the
5954 sympathy of the people, luring them to use their score files on false
5955 premises! Yay! The net is saved!
5957 Here are some tips for the would-be retro-moderator, off the top of my
5962 Articles that are heavily crossposted are probably junk.
5964 To lower a single inappropriate article, lower by @code{Message-Id}.
5966 Particularly brilliant authors can be raised on a permanent basis.
5968 Authors that repeatedly post off-charter for the group can safely be
5969 lowered out of existence.
5971 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
5972 articles completely.
5974 Use expiring score entries to keep the size of the file down. You
5975 should probably have a long expiry period, though, as some sites keep
5976 old articles for a long time.
5979 ... I wonder whether other newsreaders will support global score files
5980 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
5981 Wave, xrn and 1stReader are bound to implement scoring. Should we start
5982 holding our breath yet?
5985 @subsection Kill Files
5988 Gnus still supports those pesky old kill files. In fact, the kill file
5989 entries can now be expiring, which is something I wrote before Per
5990 thought of doing score files, so I've left the code in there.
5992 In short, kill processing is a lot slower (and I do mean @emph{a lot})
5993 than score processing, so it might be a good idea to rewrite your kill
5994 files into score files.
5996 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
5997 forms into this file, which means that you can use kill files as some
5998 sort of primitive hook function to be run on group entry, even though
5999 that isn't a very good idea.
6001 XCNormal kill files look like this:
6004 (gnus-kill "From" "Lars Ingebrigtsen")
6005 (gnus-kill "Subject" "ding")
6009 This will mark every article written by me as read, and remove them from
6010 the summary buffer. Very useful, you'll agree.
6012 Other programs use a totally different kill file syntax. If Gnus
6013 encounters what looks like a @code{rn} kill file, it will take a stab at
6016 Two functions for editing a GNUS kill file:
6020 @kindex M-k (Summary)
6021 @findex gnus-summary-edit-local-kill
6022 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
6025 @kindex M-K (Summary)
6026 @findex gnus-summary-edit-global-kill
6027 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
6030 @vindex gnus-kill-file-name
6031 A kill file for the group @samp{soc.motss} is normally called
6032 @file{soc.motss.KILL}. The suffix appended to the group name to get
6033 this file name is detailed by the @code{gnus-kill-file-name} variable.
6034 The "global" kill file (not in the score file sense of "global", of
6035 course) is called just @file{KILL}.
6037 @vindex gnus-kill-save-kill-file
6038 If @code{gnus-kill-save-kill-file} is non-@code{nil}, Gnus will save the
6039 kill file after processing, which is necessary if you use expiring
6043 @node Mail Group Commands
6044 @section Mail Group Commands
6045 @cindex mail group commands
6047 Some commands only make sense in mail groups. If these commands are
6048 illegal in the current group, they will raise a hell and let you know.
6050 All these commands (except the expiry and edit commands) use the
6051 process/prefix convention (@pxref{Process/Prefix}).
6055 @kindex B e (Summary)
6056 @findex gnus-summary-expire-articles
6057 Expire all expirable articles in the group
6058 (@code{gnus-summary-expire-articles}).
6061 @kindex B M-C-e (Summary)
6062 @findex gnus-summary-expire-articles-now
6063 Expunge all the expirable articles in the group
6064 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
6065 articles that are eligeble for expiry in the current group will
6066 disappear forever into that big @file{/dev/null} in the sky.
6069 @kindex B DEL (Summary)
6070 @findex gnus-summary-delete-articles
6071 Delete the mail article. This is "delete" as in "delete it from your
6072 disk forever and ever, never to return again." Use with caution.
6073 (@code{gnus-summary-delete-article}).
6076 @kindex B m (Summary)
6078 @findex gnus-summary-move-article
6079 Move the article from one mail group to another
6080 (@code{gnus-summary-move-article}).
6083 @kindex B c (Summary)
6085 @findex gnus-summary-copy-article
6086 Copy the article from one group (mail group or not) to a mail group
6087 (@code{gnus-summary-copy-article}).
6090 @kindex B i (Summary)
6091 @findex gnus-summary-import-article
6092 Import a random file into the current mail newsgroup
6093 (@code{gnus-summary-import-article}). You will be prompted for a file
6094 name, a @code{From} header and a @code{Subject} header.
6097 @kindex B r (Summary)
6098 @findex gnus-summary-respool-article
6099 Respool the mail article (@code{gnus-summary-move-article}).
6103 @kindex B w (Summary)
6105 @findex gnus-summary-edit-article
6106 @kindex C-c C-c (Article)
6107 Edit the current article (@code{gnus-summary-edit-article}). To finish
6108 editing and make the changes permanent, type @kbd{C-c C-c}
6109 (@kbd{gnus-summary-edit-article-done}).
6112 @kindex B q (Summary)
6113 @findex gnus-summary-fancy-query
6114 If you are using fancy splitting, this command will tell you where an
6115 article would go (@code{gnus-summary-fancy-query}).
6118 @node Various Summary Stuff
6119 @section Various Summary Stuff
6122 * Group Information:: Information oriented commands.
6123 * Searching for Articles:: Multiple article commands.
6124 * Really Various Summary Commands:: Those pesky non-conformant commands.
6127 @vindex gnus-summary-prepare-hook
6128 @code{gnus-summary-prepare-hook} is called after the summary buffer has
6129 been generated. You might use it to, for instance, highlight lines or
6130 modify the look of the buffer in some other ungodly manner. I don't
6133 @node Group Information
6134 @subsection Group Information
6138 @kindex H f (Summary)
6139 @findex gnus-summary-fetch-faq
6140 @vindex gnus-group-faq-directory
6141 Try to fetch the FAQ (list of frequently asked questions) for the
6142 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
6143 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
6144 on a remote machine. @code{ange-ftp} will be used for fetching the file.
6146 @kindex H d (Summary)
6147 @findex gnus-summary-describe-group
6148 Give a brief description of the current group
6149 (@code{gnus-summary-describe-group}). If given a prefix, force
6150 rereading the description from the server.
6152 @kindex H h (Summary)
6153 @findex gnus-summary-describe-briefly
6154 Give a very brief description of the most important summary keystrokes
6155 (@code{gnus-summary-describe-briefly}).
6157 @kindex H i (Summary)
6158 @findex gnus-info-find-node
6159 Go to the Gnus info node (@code{gnus-info-find-node}).
6162 @node Searching for Articles
6163 @subsection Searching for Articles
6167 @kindex M-s (Summary)
6168 @findex gnus-summary-search-article-forward
6169 Search through all subsequent articles for a regexp
6170 (@code{gnus-summary-search-article-forward}).
6172 @kindex M-r (Summary)
6173 @findex gnus-summary-search-article-backward
6174 Search through all previous articles for a regexp
6175 (@code{gnus-summary-search-article-backward}).
6178 @findex gnus-summary-execute-command
6179 This command will prompt you for a header field, a regular expression to
6180 match on this field, and a command to be executed if the match is made
6181 (@code{gnus-summary-execute-command}).
6183 @kindex M-& (Summary)
6184 @findex gnus-summary-universal-argument
6185 Perform any operation on all articles that have been marked with
6186 the process mark (@code{gnus-summary-universal-argument}).
6189 @node Really Various Summary Commands
6190 @subsection Really Various Summary Commands
6194 @kindex A D (Summary)
6195 @findex gnus-summary-enter-digest-group
6196 If the current article is a digest, you might use this command to enter
6197 you into a group based on the current digest to ease reading
6198 (@code{gnus-summary-enter-digest-group}).
6200 @kindex C-t (Summary)
6201 @findex gnus-summary-toggle-truncation
6202 Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
6205 @findex gnus-summary-expand-window
6206 Expand the summary buffer window (@code{gnus-summary-expand-window}).
6207 If given a prefix, force an @code{article} window configuration.
6210 @node The Article Buffer
6211 @chapter The Article Buffer
6212 @cindex article buffer
6214 The articles are displayed in the article buffer, of which there is only
6215 one. All the summary buffer share the same article buffer.
6218 * Hiding Headers:: Deciding what headers should be displayed.
6219 * Using Mime:: Pushing articles through @sc{mime} before reading them.
6220 * Customizing Articles:: Tailoring the look of the articles.
6221 * Article Keymap:: Keystrokes available in the article buffer
6222 * Misc Article:: Other stuff.
6225 @node Hiding Headers
6226 @section Hiding Headers
6227 @cindex hiding headers
6228 @cindex deleting headers
6230 The top section of each article is the @dfn{head}. (The rest is the
6231 @dfn{body}, but you may have guessed that already.)
6233 @vindex gnus-show-all-headers
6234 There is a lot of useful information in the head: the name of the person
6235 who wrote the article, the date it was written and the subject of the
6236 article. That's well and nice, but there's also lots of information
6237 most people do not want to see - what systems the article has passed
6238 through before reaching you, the @code{Message-Id}, the
6239 @code{References}, etc. ad nauseum - and you'll probably want to get rid
6240 of some of those lines. If you want to keep all those lines in the
6241 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
6243 Gnus provides you with two variables for sifting headers:
6246 @item gnus-visible-headers
6247 @vindex gnus-visible-headers
6248 If this variable is non-@code{nil}, it should be a regular expression
6249 that says what headers you wish to keep in the article buffer. All
6250 headers that do not match this variable will be hidden.
6252 For instance, if you only want to see the name of the person who wrote
6253 the article and the subject, you'd say:
6256 (setq gnus-visible-headers "^From:\\|^Subject:")
6259 @item gnus-ignored-headers
6260 @vindex gnus-ignored-headers
6261 This variable is the reverse of @code{gnus-visible-headers}. If this
6262 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
6263 should be a regular expression that matches all lines that you want to
6264 hide. All lines that do not match this variable will remain visible.
6266 For instance, if you just want to get rid of the @code{References} line
6267 and the @code{Xref} line, you might say:
6270 (setq gnus-ignored-headers "^References:\\|^Xref:")
6273 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
6274 variable will have no effect.
6277 @vindex gnus-sorted-header-list
6278 Gnus can also sort the headers for you. (It does this by default.) You
6279 can control the sorting by setting the @code{gnus-sorted-header-list}
6280 variable. It is a list of regular expressions that says in what order
6281 the headers are to be displayed.
6283 For instance, if you want the name of the author of the article first,
6284 and then the subject, you might say something like:
6287 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
6290 Any headers that are to remain visible, but are not listed in this
6291 variable, will be displayed in random order after all the headers that
6292 are listed in this variable.
6298 Mime is a standard for waving your hands through the air, aimlessly,
6299 while people stand around yawning.
6301 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
6302 while all newsreaders die of fear.
6304 @sc{mime} may specify what character set the article uses, the encoding
6305 of the characters, and it also makes it possible to embed pictures and
6306 other naughty stuff in innocent-looking articles.
6308 @vindex gnus-show-mime
6309 @vindex gnus-show-mime-method
6310 Gnus handles @sc{mime} by shoving the articles through
6311 @code{gnus-show-mime-method}, which is @code{metamail-buffer} by
6312 default. If @code{gnus-strict-mime} is non-@code{nil}, the @sc{mime}
6313 method will only be used it there are @sc{mime} headers in the article.
6314 Set @code{gnus-show-mime} to @code{t} if you want to use @sc{mime} all
6315 the time; it might be best to just use the toggling functions from the
6316 summary buffer to avoid getting nasty surprises. (For instance, you
6317 enter the group @samp{alt.sing-a-long} and, before you know it,
6318 @sc{mime} has decoded the sound file in the article and some horrible
6319 sing-a-long song comes streaming out out your speakers, and you can't
6320 find the volume button, because there isn't one, and people are starting
6321 to look at you, and you try to stop the program, but you can't, and you
6322 can't find the program to control the volume, and everybody else in the
6323 room suddenly decides to look at you disdainfully, and you'll feel
6326 Any similarity to real events and people is purely coincidental. Ahem.
6328 @node Customizing Articles
6329 @section Customizing Articles
6330 @cindex article customization
6332 @vindex gnus-article-display-hook
6333 The @code{gnus-article-display-hook} is called after the article has
6334 been inserted into the article buffer. It is meant to handle all
6335 treatment of the article before it is displayed. By default it contains
6336 @code{gnus-article-hide-headers}, which hides unwanted headers.
6338 @findex gnus-article-subcite
6339 @findex gnus-article-hide-signature
6340 @findex gnus-article-hide-citation
6341 Other useful functions you might add to this hook is:
6344 @item gnus-article-hide-citation
6345 Hide all cited text.
6346 @item gnus-article-hide-signature
6347 Umn, hides the signature.
6348 @item gnus-article-treat-overstrike
6349 Treat @samp{^H_} in a reasonable manner.
6350 @item gnus-article-maybe-highlight
6351 Do fancy article highlighting.
6352 @item gnus-article-remove-cr
6353 Removes trailing carriage returns.
6354 @item gnus-article-de-quoted-unreadable
6355 Do naive decoding of articles encoded with Quoted-Printable.
6356 @item gnus-article-display-x-face
6357 Displays any X-Face headers.
6360 You can, of course, write your own functions. The functions are called
6361 from the article buffer, and you can do anything you like, pretty much.
6362 There is no information that you have to keep in the buffer - you can
6363 change everything. However, you shouldn't delete any headers. Instead
6364 make them invisible if you want to make them go away.
6366 @node Article Keymap
6367 @section Article Keymap
6369 @c Most of the keystrokes in the summary buffer can also be used in the
6370 @c article buffer. They should behave as if you typed them in the summary
6371 @c buffer, which means that you don't actually have to have a summary
6372 @c buffer displayed while reading. You can do it all from the article
6375 A few additional keystrokes are available:
6379 @kindex SPACE (Article)
6380 @findex gnus-article-next-page
6381 Scroll forwards one page (@code{gnus-article-next-page}).
6383 @kindex DEL (Article)
6384 @findex gnus-article-prev-page
6385 Scroll backwards one page (@code{gnus-article-prev-page}).
6387 @kindex C-c ^ (Article)
6388 @findex gnus-article-refer-article
6389 If point is in the neighborhood of a @code{Message-Id} and you press
6390 @kbd{r}, Gnus will try to get that article from the server
6391 (@code{gnus-article-refer-article}).
6393 @kindex C-c C-m (Article)
6394 @findex gnus-article-mail
6395 Send a reply to the address near point (@code{gnus-article-mail}). If
6396 given a prefix, include the mail.
6399 @findex gnus-article-show-summary
6400 Reconfigure the buffers so that the summary buffer becomes visible
6401 (@code{gnus-article-show-summary}).
6404 @findex gnus-article-describe-briefly
6405 Give a very brief description of the available keystrokes
6406 (@code{gnus-article-describe-briefly}).
6410 @section Misc Article
6413 @vindex gnus-article-prepare-hook
6414 @item gnus-article-prepare-hook
6415 This hook is called right after the article has been inserted into the
6416 article buffer. It is mainly intended for functions that do something
6417 depending on the contents; it should probably not be used for changing
6418 the contents of the article buffer.
6419 @vindex gnus-article-display-hook
6420 @item gnus-article-display-hook
6421 This hook is called as the last thing when displaying an article, and is
6422 intended for modifying the contents of the buffer, doing highlights,
6423 hiding headers, and the like.
6424 @vindex gnus-article-mode-line-format
6425 @item gnus-article-mode-line-format
6426 This variable is a format string along the same lines as
6427 @code{gnus-summary-mode-line-format}. It accepts exactly the same
6428 format specifications as that variable.
6429 @vindex gnus-break-pages
6430 @item gnus-break-pages
6431 Controls whether @dfn{page breaking} is to take place. If this variable
6432 is non-@code{nil}, the articles will be divided into pages whenever a
6433 page delimiter appears in the article. If this variable is @code{nil},
6434 paging will not be done.
6435 @item gnus-page-delimiter
6436 @vindex gnus-page-delimiter
6437 This is the delimiter mentioned above. By default, it is @samp{^L}
6441 @node The Server Buffer
6442 @chapter The Server Buffer
6444 Traditionally, a @dfn{server} is a machine or a piece of software that
6445 one connects to, and then requests information from. Gnus does not
6446 connect directly to any real servers, but does all transactions through
6447 one backend or other. But that's just putting one layer more between
6448 the actual media and Gnus, so we might just as well say that each
6449 backend represents a virtual server.
6451 For instance, the @code{nntp} backend may be used to connect to several
6452 different actual nntp servers, or, perhaps, to many different ports on
6453 the same actual nntp server. You tell Gnus which backend to use, and
6454 what parameters to set by specifying a @dfn{select method}.
6456 These select methods specifications can sometimes become quite
6457 complicated - say, for instance, that you want to read from the nntp
6458 server @samp{news.funet.fi} on port number @samp{13}, which hangs if
6459 queried for @sc{nov} headers and has a buggy select. Ahem. Anyways, if
6460 you had to specify that for each group that used this server, that would
6461 be too much work, so Gnus offers a way of putting names to methods,
6462 which is what you do in the server buffer.
6465 * Server Buffer Format:: You can customize the look of this buffer.
6466 * Server Commands:: Commands to manipulate servers.
6467 * Example Methods:: Examples server specifications.
6468 * Servers & Methods:: You can use server names as select methods.
6471 @node Server Buffer Format
6472 @section Server Buffer Format
6473 @cindex server buffer format
6475 @vindex gnus-server-line-format
6476 You can change the look of the server buffer lines by changing the
6477 @code{gnus-server-line-format} variable. This is a @code{format}-like
6478 variable, with some simple extensions:
6482 How the news is fetched - the backend name.
6484 The name of this server.
6486 Where the news is to be fetched from - the address.
6489 @node Server Commands
6490 @section Server Commands
6491 @cindex server commands
6495 Browse the current server (@code{gnus-server-read-server}).
6497 Return to the group buffer (@code{gnus-server-exit}).
6499 List all servers (@code{gnus-server-list-servers}).
6501 Kill the current server (@code{gnus-server-kill-server}).
6503 Yank the previously killed server (@code{gnus-server-yank-server}).
6505 Copy the current server (@code{gnus-server-copy-server}).
6507 Add a new server (@code{gnus-server-add-server}).
6509 Edit a server (@code{gnus-server-edit-server}).
6512 @node Example Methods
6513 @section Example Methods
6515 Most select methods are pretty simple and self-explanatory:
6518 (nntp "news.funet.fi")
6521 Reading directly from the spool is even simpler:
6527 As you can see, the first element in a select method is the name of the
6528 backend, and the second is the @dfn{address}, or @dfn{name}, if you
6531 After these two elements, there may be a random number of @var{(variable
6534 To go back to the first example - imagine that you want to read from
6535 port @code{15} from that machine. This is what the select method should
6539 (nntp "news.funet.fi" (nntp-port-number 15))
6542 You should read the documentation to each backend to find out what
6543 variables are relevant, but here's an @code{nnmh} example.
6545 @code{nnmh} is a mail backend that reads a spool-like structure. Say
6546 you have two structures that you wish to access: One is your private
6547 mail spool, and the other is a public one. Here's the possible spec for
6551 (nnmh "private" (nnmh-directory "~/private/mail/"))
6554 (This server is then called @samp{private}, but you may have guessed
6557 Here's the method for the public spool:
6561 (nnmh-directory "/usr/information/spool/")
6562 (nnmh-get-new-mail nil))
6565 @node Servers & Methods
6566 @section Servers & Methods
6568 Wherever you would normally use a select method
6569 (eg. @code{gnus-secondary-select-method}, in the group select method,
6570 when browsing a foreign server) you can use a virtual server name
6571 instead. This could potentially save lots of typing. And it's nice all
6579 * Interactive:: Making Gnus ask you many questions.
6580 * Windows Configuration:: Configuring the Gnus buffer windows.
6581 * Buttons:: Get tendonitis in ten easy steps!
6582 * Various Various:: Things that are really various.
6586 @section Interactive
6590 @item gnus-novice-user
6591 @vindex gnus-novice-user
6592 If this variable is non-@code{nil}, you are either a newcomer to the
6593 World of Usenet, or you are very cautious, which is a nice thing to be,
6594 really. You will be given questions of the type "Are you sure you want
6595 to do this?" before doing anything dangerous.
6596 @item gnus-expert-user
6597 @vindex gnus-expert-user
6598 If this variable is non-@code{nil}, you will never ever be asked any
6599 questions by Gnus. It will simply assume you know what your are doing,
6600 no matter how strange.
6601 @item gnus-interactive-catchup
6602 @vindex gnus-interactive-catchup
6603 Require confirmation before catching up a group if non-@code{nil}.
6604 @item gnus-interactive-post
6605 @vindex gnus-interactive-post
6606 If non-@code{nil}, the user will be prompted for a group name when
6608 @item gnus-interactive-exit
6609 @vindex gnus-interactive-exit
6610 Require confirmation before exiting Gnus.
6613 @node Windows Configuration
6614 @section Windows Configuration
6615 @cindex windows configuration
6617 No, there's nothing here about X, so be quiet.
6620 @item gnus-use-full-window
6621 @vindex gnus-use-full-window
6622 If non-@code{nil}, Gnus will delete all other windows and occupy the
6623 entire Emacs screen by itself. It is @code{t} by default.
6625 @item gnus-buffer-configuration
6626 @vindex gnus-buffer-configuration
6627 This variable describes how much space each Gnus buffer should be given.
6628 Here's an excerpt of this variable:
6631 ((group ([group 1.0 point]
6632 (if gnus-carpal [group-carpal 4])))
6633 (article ([summary 0.25 point]
6637 This is an alist. The @dfn{key} is a symbol that names some action or
6638 other. For instance, when displaying the group buffer, the window
6639 configuration function will use @code{group} as the key. A full list of
6640 possible names is listed below.
6642 The @dfn{value} is a @dfn{rule} that says how much space each buffer
6643 should occupy. To take the @code{article} rule as an example -
6646 (article ([summary 0.25 point]
6650 This rule says that the summary buffer should occupy 25% of the screen,
6651 and that it is placed over the article buffer. As you may have noticed,
6652 100% + 25% is actually 125% (yup, I saw y'all reaching for that
6653 calculator there). However, the special number @code{1.0} is used to
6654 signal that this buffer should soak up all the rest of the space
6655 avaiable after the rest of the buffers have taken whatever they need.
6656 There should be only one buffer with the @code{1.0} size spec.
6658 Point will be put in the buffer that has the optional third element
6661 Here's a more complicated example:
6665 [summary 0.25 point]
6666 (if gnus-carpal [summary-carpal 4])
6670 If the size spec is an integer instead of a floating point number,
6671 then that number will be used to say how many lines a buffer should
6672 occupy, not a percentage.
6674 If an element is a list instead of a vector, this list will be
6675 @code{eval}ed. If the result is non-@code{nil}, it will be used. This
6676 means that there will be three buffers if @code{gnus-carpal} is
6677 @code{nil}, and four buffers if @code{gnus-carpal} is non-@code{nil}.
6679 Not complicated enough for you? Well, try this on for size:
6682 (article ([group 1.0]
6685 [summary 0.25 point]
6690 Whoops. Two buffers with the mystery 100% tag. And what's that
6691 @code{horizontal} thingie?
6693 If the first element in one of the rule lists is a list with
6694 @code{horizontal} as the first element, Gnus will split the window
6695 horizontally, giving you two windows side-by-side. Inside each of these
6696 strips you may carry on all you like in the normal fashion. The number
6697 following @code{horizontal} says what percentage of the screen is to be
6698 given to this strip.
6700 For each horizontal split, there @emph{must} be one element that has the
6701 100% tag. The splitting is never accurate, and this buffer will eat any
6702 leftover lines from the splits.
6704 Here's a list of all possible keys:
6706 @code{group}, @code{summary}, @code{article}, @code{server},
6707 @code{browse}, @code{group-mail}, @code{summary-mail},
6708 @code{summary-reply}, @code{info}, @code{summary-faq},
6709 @code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
6710 @code{followup}, @code{followup-yank}, @code{edit-score}.
6712 @findex gnus-add-configuration
6713 Since this variable is so long and complicated, there's a function you
6714 can use to ease changing the config of a single setting:
6715 @code{gnus-add-configuration}. If, for instance, you want to change the
6716 @code{article} setting, you could say:
6719 (gnus-add-configuration
6720 '(article ([group 4]
6733 Those new-fangled @dfn{mouse} contraptions is very popular with the
6734 young, hep kids who don't want to learn the proper way to do things
6735 these days. Why, I remember way back in the summer of '89, when I was
6736 using Emacs on a Tops 20 system. Three hundred users on one single
6737 machine, and every user was running Simula compilers. Bah!
6742 Well, you can make Gnus display bufferfuls of buttons you can click to
6743 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
6744 really. Tell the chiropractor I sent you.
6748 @item gnus-carpal-mode-hook
6749 @vindex gnus-carpal-mode-hook
6750 Hook run in all carpal mode buffers.
6751 @item gnus-carpal-button-face
6752 @vindex gnus-carpal-button-face
6753 Face used on buttons.
6754 @item gnus-carpal-group-buffer-buttons
6755 @vindex gnus-carpal-group-buffer-buttons
6756 Buttons in the group buffer.
6757 @item gnus-carpal-summary-buffer-buttons
6758 @vindex gnus-carpal-summary-buffer-buttons
6759 Buttons in the summary buffer.
6760 @item gnus-carpal-server-buffer-buttons
6761 @vindex gnus-carpal-server-buffer-buttons
6762 Buttons in the server buffer.
6763 @item gnus-carpal-browse-buffer-buttons
6764 @vindex gnus-carpal-browse-buffer-buttons
6765 Buttons in the browse buffer.
6768 All the @code{buttons} variables are lists. The elements in these list
6769 is either a cons cell where the car contains a text to be displayed and
6770 the cdr contains a function symbol, or a simple string.
6772 @node Various Various
6773 @section Various Various
6779 @vindex gnus-verbose
6780 This variable is an integer between zero and ten. The higher the value,
6781 the more messages will be displayed. If this variable is zero, Gnus
6782 will never flash any messages, if it is seven, most important messages
6783 will be shown, and if it is ten, Gnus won't ever shut up, but will flash
6784 so many messages it will make your head swim.
6785 @item gnus-updated-mode-lines
6786 @vindex gnus-updated-mode-lines
6787 This is a list of buffers that should keep their mode lines updated.
6788 The list may contain the symbols @code{group}, @code{article} and
6789 @code{summary}. If the corresponding symbol is present, Gnus will keep
6790 that mode line updated with information that may be pertinent. If this
6791 variable is @code{nil}, screen refresh may be quicker.
6793 @cindex display-time
6794 @item gnus-mode-non-string-length
6795 @vindex gnus-mode-non-string-length
6796 By default, Gnus displays information on the current article in the mode
6797 lines of the summary and article buffers. The information Gnus wishes
6798 to display (eg. the subject of the article) is often longer than the
6799 mode lines, and therefore have to be cut off at some point. This
6800 variable says how long the other elements on the line is (i.e., the
6801 non-info part). If you put additional elements on the mode line (eg. a
6802 clock), you should modify this variable:
6803 @c Hook written by Keinonen Kari <kk85613@cs.tut.fi>.
6805 (add-hook 'display-time-hook
6807 (setq gnus-mode-non-string-length
6808 (+ 21 (length display-time-string)))))
6813 If @code{nil}, Gnus won't attempt to create menus or use fancy colors
6814 or fonts. This will also inhibit loading the @file{gnus-visual.el}
6816 @item gnus-mouse-face
6817 @vindex gnus-mouse-face
6818 This is the face (i.e., font) used for mouse highlighting in Gnus. No
6819 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
6821 @item gnus-display-type
6822 @vindex gnus-display-type
6823 This variable is symbol indicating the display Emacs is running under.
6824 The symbol should be one of @code{color}, @code{grayscale} or
6825 @code{mono}. If Gnus guesses this display attribute wrongly, either set
6826 this variable in your @file{~/.emacs} or set the resource
6827 @code{Emacs.displayType} in your @file{~/.Xdefaults}.
6829 @item gnus-background-mode
6830 @vindex gnus-background-mode
6831 This is a symbol indicating the Emacs background brightness. The symbol
6832 should be one of @code{light} or @code{dark}. If Gnus guesses this
6833 frame attribute wrongly, either set this variable in your @file{~/.emacs} or
6834 set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
6835 `gnus-display-type'.
6840 @chapter Customization
6841 @cindex general customization
6843 All variables are properly documented elsewhere in this manual. This
6844 section is designed to give general pointers on how to customize Gnus
6845 for some quite common situations.
6848 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
6849 * Slow Terminal Connection:: You run a remote Emacs.
6850 * Little Disk Space:: You feel that having large setup files is icky.
6851 * Slow Machine:: You feel like buying a faster machine.
6854 @node Slow/Expensive Connection
6855 @section Slow/Expensive @sc{nntp} Connection
6857 If you run Emacs on a machine locally, and get your news from a machine
6858 over some very thin strings, you want to cut down on the amount of data
6859 Gnus has to get from the @sc{nntp} server.
6862 @item gnus-read-active-file
6863 Set this to @code{nil}, which will inhibit Gnus from requesting the
6864 entire active file from the server. This file is often v. large. You
6865 also have to set @code{gnus-check-new-news} and
6866 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
6867 doesn't suddenly decide to fetch the active file anyway.
6868 @item gnus-nov-is-evil
6869 This one has to be @code{nil}. If not, grabbing article headers from
6870 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
6871 support @sc{xover}; Gnus will detect this by itself.
6874 @node Slow Terminal Connection
6875 @section Slow Terminal Connection
6877 Let's say you use your home computer for dialing up the system that
6878 runs Emacs and Gnus. If your modem is slow, you want to reduce the
6879 amount of data that is sent over the wires as much as possible.
6882 @item gnus-auto-center-summary
6883 Set this to @code{nil} to inhibit Gnus from recentering the summary
6884 buffer all the time.
6885 @item gnus-visible-headers
6886 Cut down on the headers that are included in the articles to the
6887 minimum. You can, in fact, make do without them altogether - most of the
6888 useful data is in the summary buffer, anyway. Set this variable to
6889 @samp{"^NEVVVVER"} or @samp{"From:"}, or whatever you feel you need.
6890 @item gnus-article-display-hook
6891 Set this hook to all the available hiding commands:
6893 (setq gnus-article-display-hook
6894 '(gnus-article-hide-headers gnus-article-hide-signature
6895 gnus-article-hide-citation))
6897 @item gnus-use-full-window
6898 By setting this to @code{nil}, you can make all the windows smaller.
6899 While this doesn't really cut down much generally, it means that you
6900 have to see smaller portions of articles before deciding that you didn't
6901 want to read them anyway.
6902 @item gnus-thread-hide-subtree
6903 If this is non-@code{nil}, all threads in the summary buffer will be
6905 @item gnus-updated-mode-lines
6906 If this is @code{nil}, Gnus will not put information in the buffer mode
6907 lines, which might save some time.
6910 @node Little Disk Space
6911 @section Little Disk Space
6913 The startup files can get rather large, so you may want to cut their
6914 sizes a bit if you are running out of space.
6917 @item gnus-save-newsrc-file
6918 If this is @code{nil}, Gnus will never save @file{.newsrc} - it will
6919 only save @file{.newsrc.eld}. This means that you will not be able to
6920 use any other newsreaders than Gnus.
6921 @item gnus-save-killed-list
6922 If this is @code{nil}, Gnus will not save the list of dead groups. You
6923 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
6924 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
6925 variable to @code{nil}.
6929 @section Slow Machine
6931 If you have a slow machine, or are just really impatient, there are a
6932 few things you can do to make Gnus run faster.
6934 Set@code{gnus-check-new-newsgroups} and
6935 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
6937 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
6938 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
6939 summary buffer faster.
6941 Set @code{gnus-article-display-hook} to @code{nil} to make article
6942 processing a bit faster.
6944 @node Troubleshooting
6945 @chapter Troubleshooting
6946 @cindex troubleshooting
6948 Gnus works @emph{so} well straight out of the box - I can't imagine any
6955 Make sure your computer is switched on.
6957 Make sure that you really load the current Gnus version. If you have
6958 been running @sc{gnus}, you need to exit Emacs and start it up again before
6961 Try doing an @kbd{M-x gnus-version}. If you get something that looks
6962 like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
6963 on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
6964 flee}, you have some old @file{.el} files lying around. Delete these.
6966 Read the help group (@kbd{M h} in the group buffer) for a FAQ and a
6970 If all else fails, report the problem as a bug,
6973 @cindex reporting bugs
6975 @kindex M-x gnus-bug
6977 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
6978 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
6979 me the backtrace. I will fix bugs, but I can only fix them if you send
6980 me a precise description as to how to reproduce the bug.
6982 @c If you just need help, you are better off asking on
6983 @c @samp{gnu.emacs.gnus}.
6988 Well, that's the manual - you can get on with your life now. Keep in
6989 touch. Say hello to your cats from me.
6991 My @strong{ghod} - I just can't stand goodbyes. Sniffle.
6993 Ol' Chuck Reznikoff said it pretty well, so I leave the floor to him:
6998 Not because of victories @*
7001 but for the common sunshine,@*
7003 the largess of the spring.
7006 but for the day's work done@*
7007 as well as I was able;@*
7008 not for a seat upon the dais@*
7009 but at the common table.@*
7013 @chapter A Programmer's Guide to Gnus
7015 It is my hope that other people will figure out smart stuff that Gnus
7016 can do, and that other people will write those smart things as well. To
7017 facilitate that I thought it would be a good idea to describe the inner
7018 workings of Gnus. And some of the not-so-inner workings, while I'm at
7021 You can never expect the internals of a program not to change, but I
7022 will be defining (in some details) the interface between Gnus and its
7023 backends (this is written in stone), the format of the score files
7024 (ditto), data structures (some are less likely to change than others)
7025 and general method of operations.
7028 * Backend Interface:: How Gnus communicates with the servers.
7029 * Score File Syntax:: A BNF definition of the score file standard.
7030 * Headers:: How Gnus stores headers internally.
7031 * Ranges:: A handy format for storing mucho numbers.
7032 * Group Info:: The group info format.
7036 @node Backend Interface
7037 @section Backend Interface
7039 Gnus doesn't know anything about nntp, spools, mail or virtual groups.
7040 It only knows how to talk to @dfn{virtual servers}. A virtual server is
7041 a @dfn{backend} and some @dfn{backend variables}. As examples of the
7042 first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
7043 examples of the latter we have @code{nntp-port-number} and
7044 @code{nnmbox-directory}.
7046 When Gnus asks for information from a backend -- say @code{nntp} -- on
7047 something, it will normally include a virtual server name in the
7048 function parameters. (If not, the backend should use the "current"
7049 virtual server.) For instance, @code{nntp-request-list} takes a virtual
7050 server as its only (optional) parameter. If this virtual server hasn't
7051 been opened, the function should fail.
7053 Note that a virtual server name has no relation to some physical server
7054 name. Take this example:
7058 (nntp-address "ifi.uio.no")
7059 (nntp-port-number 4324))
7062 Here the virtual server name is @samp{"odd-one"} while the name of
7063 the physical server is @samp{"ifi.uio.no"}.
7065 The backends should be able to switch between several virtual servers.
7066 The standard backends implement this by keeping an alist of virtual
7067 server environments that it pulls down/pushes up when needed.
7069 There are two groups of interface functions: @dfn{required functions},
7070 which must be present, and @dfn{optional functions}, which Gnus will
7071 always check whether are present before attempting to call.
7073 All these functions are expected to return data in the buffer
7074 @code{nntp-server-buffer} (@samp{" *nntpd*"}), which is somewhat
7075 unfortunately named, but we'll have to live with it. When I talk about
7076 "resulting data", I always refer to the data in that buffer. When I
7077 talk about "return value", I talk about the function value returned by
7080 Some backends could be said to be @dfn{server-forming} backends, and
7081 some might be said to not be. The latter are backends that generally
7082 only operate on one group at a time, and have no concept of "server" --
7083 they have a group, and they deliver info on that group and nothing more.
7085 In the examples and definitions I will refer to the imaginary backend
7089 * Required Backend Functions:: Functions that must be implemented.
7090 * Optional Backend Functions:: Functions that need not be implemented.
7094 @node Required Backend Functions
7095 @subsection Required Backend Functions
7099 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER)
7101 @var{articles} is either a range of article numbers or a list of
7102 @code{Message-ID}s. Current backends do not fully support either - only
7103 sequences (lists) of article numbers, and most backends do not support
7104 retrieval of @code{Message-ID}s. But they should try for both.
7106 The result data should either be HEADs or NOV lines, and the result
7107 value should either be @code{headers} or @code{nov} to reflect this.
7108 This might later be expanded to @code{various}, which will be a mixture
7109 of HEADs and NOV lines, but this is currently not supported by Gnus.
7111 Here's an example HEAD:
7114 221 1056 Article retrieved.
7115 Path: ifi.uio.no!sturles
7116 From: sturles@@ifi.uio.no (Sturle Sunde)
7117 Newsgroups: ifi.discussion
7118 Subject: Re: Something very droll
7119 Date: 27 Oct 1994 14:02:57 +0100
7120 Organization: Dept. of Informatics, University of Oslo, Norway
7122 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
7123 References: <38jdmq$4qu@@visbur.ifi.uio.no>
7124 NNTP-Posting-Host: holmenkollen.ifi.uio.no
7128 So a @code{headers} return value would imply that there's a number of
7129 these in the data buffer.
7131 Here's a BNF definition of such a buffer:
7135 head = error / valid-head
7136 error-message = [ "4" / "5" ] 2number " " <error message> eol
7137 valid-head = valid-message *header "." eol
7138 valid-message = "221 " <number> " Article retrieved." eol
7142 If the return value is @code{nov}, the data buffer should contain
7143 @dfn{network overview database} lines. These are basically fields
7147 nov-buffer = *nov-line
7148 nov-line = 8*9 [ field <TAB> ] eol
7149 field = <text except TAB>
7152 For a closer explanation what should be in those fields,
7156 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
7158 @var{server} is here the virtual server name. @var{definitions} is a
7159 list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
7161 If the server can't be opened, no error should be signaled. The backend
7162 may then choose to refuse further attempts at connecting to this
7163 server. In fact, it should do so.
7165 If the server is opened already, this function should return a
7166 non-@code{nil} value. There should be no data returned.
7169 @item (nnchoke-close-server &optional SERVER)
7171 Close connection to @var{server} and free all resources connected
7174 There should be no data returned.
7177 @item (nnchoke-request-close)
7179 Close connection to all servers and free all resources that the backend
7180 have reserved. All buffers that have been created by that backend
7181 should be killed. (Not the @code{nntp-server-buffer}, though.)
7183 There should be no data returned.
7186 @item (nnchoke-server-opened &optional SERVER)
7188 This function should return whether @var{server} is opened, and that the
7189 connection to it is still alive. This function should under no
7190 circumstances attempt to reconnect to a server that is has lost
7193 There should be no data returned.
7196 @item (nnchoke-status-message &optional SERVER)
7198 This function should return the last error message from @var{server}.
7200 There should be no data returned.
7203 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
7205 The result data from this function should be the article specified by
7206 @var{article}. This might either be a @code{Message-ID} or a number.
7207 It is optional whether to implement retrieval by @code{Message-ID}, but
7208 it would be nice if that were possible.
7210 If @var{to-buffer} is non-@code{nil}, the result data should be returned
7211 in this buffer instead of the normal data buffer. This is to make it
7212 possible to avoid copying large amounts of data from one buffer to
7213 another, and Gnus mainly request articles to be inserted directly into
7217 @item (nnchoke-open-group GROUP &optional SERVER)
7219 Make @var{group} the current group.
7221 There should be no data returned by this function.
7224 @item (nnchoke-request-group GROUP &optional SERVER)
7226 Get data on @var{group}. This function also has the side effect of
7227 making @var{group} the current group.
7229 Here's an example of some result data and a definition of the same:
7232 211 56 1000 1059 ifi.discussion
7235 The first number is the status, which should be @samp{211}. Next is the
7236 total number of articles in the group, the lowest article number, the
7237 highest article number, and finally the group name. Note that the total
7238 number of articles may be less than one might think while just
7239 considering the highest and lowest article numbers, but some articles
7240 may have been cancelled. Gnus just discards the total-number, so
7241 whether one should take the bother to generate it properly (if that is a
7242 problem) is left as an excercise to the reader.
7245 group-status = [ error / info ] eol
7246 error = [ "4" / "5" ] 2<number> " " <Error message>
7247 info = "211 " 3* [ <number> " " ] <string>
7251 @item (nnchoke-close-group GROUP &optional SERVER)
7253 Close @var{group} and free any resources connected to it. This will be
7254 a no-op on most backends.
7256 There should be no data returned.
7259 @item (nnchoke-request-list &optional SERVER)
7261 Return a list of all groups available on @var{server}. And that means
7264 Here's an example from a server that only carries two groups:
7267 ifi.test 0000002200 0000002000 y
7268 ifi.discussion 3324 3300 n
7271 On each line we have a group name, then the highest article number in
7272 that group, the lowest article number, and finally a flag.
7275 active-file = *active-line
7276 active-line = name " " <number> " " <number> " " flags eol
7278 flags = "n" / "y" / "m" / "x" / "j" / "=" name
7281 The flag says whether the group is read-only (@samp{n}), is moderated
7282 (@samp{m}), is dead (@samp{x}), is aliased to some other group
7283 (@samp{=other-group} or none of the above (@samp{y}).
7286 @item (nnchoke-request-post &optional SERVER)
7288 This function should post the current buffer. It might return whether
7289 the posting was successful or not, but that's not required. If, for
7290 instance, the posting is done asynchronously, it has generally not been
7291 completed by the time this function concludes. In that case, this
7292 function should set up some kind of sentinel to beep the user loud and
7293 clear if the posting could not be completed.
7295 There should be no result data from this function.
7298 @item (nnchoke-request-post-buffer POST GROUP SUBJECT HEADER ARTICLE-BUFFER INFO FOLLOW-TO RESPECT-POSTER)
7300 This function should return a buffer suitable for composing an article
7301 to be posted by @code{nnchoke-request-post}. If @var{post} is
7302 non-@code{nil}, this is not a followup, but a totally new article.
7303 @var{group} is the name of the group to be posted to. @var{subject} is
7304 the subject of the message. @var{article-buffer} is the buffer being
7305 followed up, if that is the case. @var{info} is the group info.
7306 @var{follow-to} is the group that one is supposed to re-direct the
7307 article to. If @var{respect-poster} is non-@code{nil}, the special
7308 @samp{"poster"} value of a @code{Followup-To} header is to be respected.
7310 There should be no result data returned.
7314 @node Optional Backend Functions
7315 @subsection Optional Backend Functions
7319 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
7321 @var{groups} is a list of groups, and this function should request data
7322 on all those groups. How it does it is of no concern to Gnus, but it
7323 should attempt to do this in a speedy fashion.
7325 The return value of this function can be either @code{active} or
7326 @code{group}, which says what the format of the result data is. The
7327 former is in the same format as the data from
7328 @code{nnchoke-request-list}, while the latter is a buffer full of lines
7329 in the same format as @code{nnchoke-request-group} gives.
7332 group-buffer = *active-line / *group-status
7336 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
7338 A Gnus group info (@pxref{Group Info}) is handed to the backend for
7339 alterations. This comes in handy if the backend really carries all the
7340 information (as is the case with virtual an imap groups). This function
7341 may alter the info in any manner it sees fit, and should return the
7342 (altered) group info. This function may alter the group info
7343 destructively, so no copying is needed before boogying.
7345 There should be no result data from this function.
7348 @item (nnchoke-request-scan &optional GROUP SERVER)
7350 This function may be called at any time (by Gnus or anything else) to
7351 request that the backend check for incoming articles, in one way or
7352 another. A mail backend will typically read the spool file or query the
7353 POP server when this function is invoked. The @var{group} doesn't have
7354 to be heeded -- if the backend decides that it is too much work just
7355 scanning for a single group, it may do a total scan of all groups. It
7356 would be nice, however, to keep things local if that's practical.
7358 There should be no result data from this function.
7361 @item (nnchoke-request-asynchronous GROUP &optional SERVER ARTICLES)
7363 This is a request to fetch articles asynchronously later.
7364 @var{articles} is an alist of @var{(article-number line-number)}. One
7365 would generally expect that if one later fetches article number 4, for
7366 instance, some sort of asynchronous fetching of the articles after 4
7367 (which might be 5, 6, 7 or 11, 3, 909 depending on the order in that
7368 alist) would be fetched asynchronouly, but that is left up to the
7369 backend. Gnus doesn't care.
7371 There should be no result data from this function.
7374 @item (nnchoke-request-group-description GROUP &optional SERVER)
7376 The result data from this function should be a description of
7380 description-line = name <TAB> description eol
7382 description = <text>
7385 @item (nnchoke-request-list-newsgroups &optional SERVER)
7387 The result data from this function should be the description of all
7388 groups available on the server.
7391 description-buffer = *description-line
7395 @item (nnchoke-request-newgroups DATE &optional SERVER)
7397 The result data from this function should be all groups that were
7398 created after @samp{date}, which is in normal human-readable date
7399 format. The data should be in the active buffer format.
7402 @item (nnchoke-request-create-groups GROUP &optional SERVER)
7404 This function should create an empty group with name @var{group}.
7406 There should be no return data.
7409 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
7411 This function should run the expiry process on all articles in the
7412 @var{articles} range (which is currently a simple list of article
7413 numbers.) It is left up to the backend to decide how old articles
7414 should be before they are removed by this function. If @var{force} is
7415 non-@code{nil}, all @var{articles} should be deleted, no matter how new
7418 This function should return a list of articles that it did not/was not
7421 There should be no result data returned.
7424 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
7427 This function should move @var{article} (which is a number) from
7428 @var{group} by calling @var{accept-form}.
7430 This function should ready the article in question for moving by
7431 removing any header lines it has added to the article, and generally
7432 should "tidy up" the article. Then it should @code{eval}
7433 @var{accept-form} in the buffer where the "tidy" article is. This will
7434 do the actual copying. If this @code{eval} returns a non-@code{nil}
7435 value, the article should be removed.
7437 If @var{last} is @code{nil}, that means that there is a high likelihood
7438 that there will be more requests issued shortly, so that allows some
7441 There should be no data returned.
7444 @item (nnchoke-request-accept-article GROUP &optional LAST)
7446 This function takes the current buffer and inserts it into @var{group}.
7447 If @var{last} in @code{nil}, that means that there will be more calls to
7448 this function in short order.
7450 There should be no data returned.
7453 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
7455 This function should remove @var{article} (which is a number) from
7456 @var{group} and insert @var{buffer} there instead.
7458 There should be no data returned.
7463 @node Score File Syntax
7464 @section Score File Syntax
7466 Score files are meant to be easily parsable, but yet extremely
7467 mallable. It was decided that something that had the same read syntax
7468 as an Emacs Lisp list would fit that spec.
7470 Here's a typical score file:
7474 ("win95" -10000 nil s)
7481 BNF definition of a score file:
7484 score-file = "" / "(" *element ")"
7485 element = rule / atom
7486 rule = string-rule / number-rule / date-rule
7487 string-rule = "(" quote string-header quote space *string-match ")"
7488 number-rule = "(" quote number-header quote space *number-match ")"
7489 date-rule = "(" quote date-header quote space *date-match ")"
7491 string-header = "subject" / "from" / "references" / "message-id" /
7492 "xref" / "body" / "head" / "all" / "followup"
7493 number-header = "lines" / "chars"
7494 date-header = "date"
7495 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
7496 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
7497 score = "nil" / <integer>
7498 date = "nil" / <natural number>
7499 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
7500 "r" / "regex" / "R" / "Regex" /
7501 "e" / "exact" / "E" / "Exact" /
7502 "f" / "fuzzy" / "F" / "Fuzzy"
7503 number-match = "(" <integer> [ "" / [ space score [ "" /
7504 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
7505 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
7506 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
7507 space date [ "" / [ space date-match-t ] ] ] ] ")"
7508 date-match-t = "nil" / "at" / "before" / "after"
7509 atom = "(" [ required-atom / optional-atom ] ")"
7510 required-atom = mark / expunge / mark-and-expunge / files /
7511 exclude-files / read-only / touched
7512 optional-atom = adapt / local / eval
7513 mark = "mark" space nil-or-number
7514 nil-or-t = "nil" / <integer>
7515 expunge = "expunge" space nil-or-number
7516 mark-and-expunge = "mark-and-expunge" space nil-or-number
7517 files = "files" *[ space <string> ]
7518 exclude-files = "exclude-files" *[ space <string> ]
7519 read-only = "read-only" [ space "nil" / space "t" ]
7520 adapt = "adapt" [ space "nil" / space "t" / space adapt-rule ]
7521 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
7522 local = "local" *[ space "(" <string> space <form> ")" ]
7523 eval = "eval" space <form>
7524 space = *[ " " / <TAB> / <NEWLINE> ]
7527 Any unrecognized elements in a score file should be ignored, but not
7530 As you can see, white space is needed, but the type and amount of white
7531 space is irrelevant. This means that formatting of the score file is
7532 left up to the programmer -- if it's simpler to just spew it all out on
7533 one looong line, then that's ok.
7535 The meaning of the various atoms are explained elsewhere in this
7541 Gnus uses internally a format for storing article headers that
7542 corresponds to the @sc{nov} format in a mysterious fashion. One could
7543 almost suspect that the author looked at the @sc{nov} specification and
7544 just shamelessly @emph{stole} the entire thing, and one would be right.
7546 @dfn{Header} is a severly overloaded term. "Header" is used in RFC1036
7547 to talk about lines in the head of an article (eg., @code{From}). It is
7548 used by many people as a synonym for "head" -- "the header and the
7549 body". (That should be avoided, in my opinion.) And Gnus uses a format
7550 interanally that it calls "header", which is what I'm talking about
7551 here. This is a 9-element vector, basically, with each header (ouch)
7554 These slots are, in order: @code{number}, @code{subject}, @code{from},
7555 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
7556 @code{xref}. There are macros for accessing and setting these slots --
7557 they all have predicatable names beginning with @code{mail-header-} and
7558 @code{mail-header-set-}, respectively.
7560 The @code{xref} slot is really a @code{misc} slot. Any extra info will
7566 @sc{gnus} introduced a concept that I found so useful that I've started
7567 using it a lot and have elaborated on it greatly.
7569 The question is simple: If you have a large amount of objects that are
7570 identified by numbers (say, articles, to take a @emph{wild} example)
7571 that you want to callify as being "included", a normal sequence isn't
7572 very useful. (A 200,000 length sequence is a bit long-winded.)
7574 The solution is as simple as the question: You just collapse the
7578 (1 2 3 4 5 6 10 11 12)
7587 To avoid having those nasty @samp{(13 . 13)} elements to denote a
7588 lonesome object, a @samp{13} is a valid element:
7591 ((1 . 6) 7 (10 . 12))
7594 This means that comparing two ranges to find out whether they are equal
7598 ((1 . 6) 7 8 (10 . 12))
7604 ((1 . 5) (7 . 8) (10 . 12))
7607 are equal. In fact, any non-descending list is a range:
7613 is a perfectly valid range, although a pretty longwinded one. This is
7620 and is equal to the previous range.
7622 Here's a BNF definition of ranges. Of course, one must remember the
7623 semantic requirement that the numbers are non-descending. (Any number
7624 of repetition of the same number is allowed, but apt to disappear in
7628 range = simple-range / normal-range
7629 simple-range = "(" number " . " number ")"
7630 normal-range = "(" start-contents ")"
7631 contents = "" / simple-range *[ " " contents ] /
7632 number *[ " " contents ]
7635 Gnus currently uses ranges to keep track of read articles and article
7636 marks. I plan on implementing a number of range operators in C if The
7637 Powers That Be are willing to let me. (I haven't asked yet, because I
7638 need to do some more thinking on what operators I need to make life
7639 totally range-based without ever having to convert back to normal
7646 Gnus stores all permanent info on groups in a @dfn{group info} list.
7647 This list is from three to six elements (or more) long and exhaustively
7648 describes the group.
7650 Here are two example group infos; one is a very simple group while the
7651 second is a more complex one:
7654 ("no.group" 5 (1 . 54324))
7656 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
7657 ((tick (15 . 19)) (replied 3 6 (19 . 23)))
7659 (auto-expire (to-address "ding@@ifi.uio.no")))
7662 The first element is the group name as Gnus knows the group; the second
7663 is the group level; the third is the read articles in range format; the
7664 fourth is a list of article marks lists; the fifth is the select method;
7665 and the sixth contains the group parameters.
7667 Here's a BNF definition of the group info format:
7670 info = "(" group space level space read
7671 [ "" / [ space marks-list [ "" / [ space method [ "" /
7672 space parameters ] ] ] ] ] ")"
7673 group = quote <string> quote
7674 level = <integer in the range of 1 to inf>
7676 marks-lists = nil / "(" *marks ")"
7677 marks = "(" <string> range ")"
7678 method = "(" <string> *elisp-forms ")"
7679 parameters = "(" *elisp-forms ")"
7682 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
7683 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
7701 @c outline-regexp: "@chap\\|@\\(sub\\)*section\\|@appendix \\|@appendix\\(sub\\)*sec\\|\^L"